Reference Images

Reference Manual - Images

This reference manuael is under develoment. More to come later.

Updated for Snowmix 0.4.5.

This is the reference manual for Snowmix for the image commands for loading, inspecting, positioning and overlaying images. See also:

• Reserved Commands overview
• Reference manual for general commands
• Reference manual for command macros
• Reference manual for audio feed commands. See also Audio.
• Reference manual for audio mixer commands. See also Audio.
• Reference manual for audio sink commands. See also Audio.
• Reference manual for feed commands.
• Reference manual for text commands. See also Video Text and Snowmix Tutorials on text.
• Reference manual for image commands.
• Reference manual for shape commands. See the manual page on Shapes.
• Reference manual for placed shapes.
• Reference manual for Cairo Graphics Primitives used in shapes
• Reference manual for virtual feed commands.

Overview

• image load - Load an image.
• image align - Set or list horizontal and vertical alignment of a placed image.
• image alpha - Set or list the alpha for a placed image.
• image anchor - Set or list anchor a placed image.
• image coor - Set or list coordinates for a placed image.
• image clip - Set or list clip parameters for a placed image.
• image filter - Set or list the filter method for mixing/overlaying a placed image.
• image geometry - List the geometry for placed image.
• image image - Set or list the image source (loaded image) of a placed image.
• image matrix - Set or list the Cairo Graphics transformation matrix.
• image move alpha - Set or list animation settings for alpha for a placed image.
• image move clip - Set or list animation settings for clip for a placed image.
• image move coor - Set or list animation settings for coordinates for a placed image.
• image move offset - Set or list animation settings for offset for a placed image.
• image move rotation - Set or list animation settings for rotation for a placed image.
• image move scale - Set or list animation settings for scale for a placed image.
• image name - Set or list the name of a loaded image.
• image overlay - Overlay a placed image.
• image place - Place a loaded image.
• image rotation - Set or list rotation for a placed image.
• image scale - Set or list the scale for a placed image.
• image verbose - Set the verbose level for image commands.
• image write - Write a loaded image to disk as a raw BGRA copy.

Not yet implemented:
- image source - Set or list the source of a placed image.

ANYTHING BELOW HERE IS NOT YET EDITED.

Commands

image align

Name

image align - Set or list horizontal and vertical alignment of a placed image.

Synopsis

image align [<place id> (left | center | right) (top | middle | bottom)]

Description

The image align command is used to set the vertical and horizontal alignment for a placed image. The table below list how the placed image is aligned.

Alignment	Mode	Explanation
left	Hor.	The left side of the placed image is aligned to its coordinates.
center	Hor.	The vertical center of the placed image is aligned to its coordinates.
right	Hor.	The right side of the placed image is aligned to its coordinates.
top	Ver.	The top side of the placed image is aligned to its coordinates.
middle	Ver.	The middle horizontal wise of the placed image is aligned to its coordinates.
bottom	Ver.	The bottom side of the placed image is aligned to its coordinates.

Example

    image align 1 left top
    image align 1 center bottom
    image align 1 middle right
    image align

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image alpha

Name

image alpha - Set or list the alpha for a placed image.

Synopsis

image alpha [<place id> <alpha>]

Description

The image alpha command is used to set the alpha value for a placed image placed with the command image place. When used without any parameters, it will list alpha values for all created placed images. The argument place id identifies the placed image to set the alpha value for. Alpha values are integer or decimal values between 0 and 1. Values given for alpha less than 0 or greater than 1 are silently set to 0 or 1 respectively. The alpha value determines "how strong" a placed image is overlayed when overlay. An alpha value of 1 means the placed image will be overlayed solidly. The closer the alpha value is to zero, the more transparent the overlayed image will appear.

Example

    image alpha 3 0.4
    image alpha

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image anchor

Name

image alpha - Set or list anchor the placed image.

Synopsis

image anchor [<place id> ( n | s | e | w | c | ne | nw | se | sw )]

Description

The image anchor command is used to set the anchor value for a placed image placed with the command image place. When used without any parameters, it will list anchor values for all created placed images. The argument place id identifies the placed image to set the anchor value for. Setting an anchor for a placed image will have the effect that a coordinate pair will be added to the coordinate of the placed image when overlayed. The effect is that with the anchor option, placement of a placed image can be relative to the left or right, top or bottom or center of the system frame upon which the placed images is being mixed into or overlayed on-top of. The table below list which the coordinate pair that will be added for a given anchor option. The width and height referenced in the table are the width and height set with the command system geometry

Option	Name	Coordinate pair to add
n	north	width/2, 0
s	south	width/2, height
e	east	width , height/2
w	west	0 , height/2
c	center	width/2, height/2
ne	north-east	width, 0
nw	north-west	0, 0 (default)
se	south-east	width, height
sw	south-west	0, height

Example

    image anchor 3 se
    image anchor

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source, system geometry

image coor

Name

image coor - Set or list a placed image's coordinate.

Synopsis

image coor [<place id> <x> <y>]

Description

The image coor command is used to set the coordinate value for a placed image placed with the command image place. When used without any parameters, it will list coordinate values for all placed images. The argument place id identifies the placed image to set the coordinate value for. Coordinate values are integer values between -2 to the power of 31 minus 1 and 2 to the power of 31 minus 1. Default value is 0,0 when a placed image is created. The origin (0,0) of the Snowmix coordinate system is in the top left corner of the system geometry frame defined by the command system geometry. Positive X is to the right and positive Y is down.

Example

    image coor 3 300 400
    image coor

The first example will set the coordinates for placed image 3 to 300,400.

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source, system geometry

image clip

Name

image clip - Set or list clip parameters for placed image.

Synopsis

image coor [<place id> <clip w> <clip h> <src_x> <src_y>]

Description

The image clip command is used to set the clip value for a placed image created with the command image add. The clip value determines how much of the placed image's source is overlayed when the placed image is overlayed. When used without any parameters, it will list clip values for all placed images. The argument place id identifies the placed image to set the clip parameters for. Clip parameters positive integers between 0 and 2 to the power of 31 minus 1. Default values are zero and as such nothing will be shown when overlayed. The parameters clip_w and clip_h sets the width and height of the clip. The parameters clip_x and clip_y sets the offset of the source within the clip. If you are setting clip_w = 320 and clip_h = 240 and the source has a geometry of 640x480 and if you set set clip_x = 100 and clip_y = 50 and assuming the scale of the placed image is set to 1,1, then the placed image, when overlayed, will clip out from the source an image with the geometry 320x240 and clip is starting from column 100 and row 50 of the source.

Example

    image clip 3 320 240 100 50
    image clip

The first example will clip an image with the geometry 320x240 and it will clip from the source's 100'th column and 50'th row.

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source.

image filter

Name

image filter - Set or list the filter method for mixing/overlaying the placed image.

Synopsis

image filter [<place id> (fast | good | best | nearest | bilinear | gaussian)]

Description

The command image filter is used to set or list which method is used to possibly scale and overlay a placed image. When used without any parameters, it will list filter values for all created placed images. The argument place id identifies the placed image to set the filter parameter for.

Default filter method is fast. How and how well each filter method performs on a specific hardware/software platform depends on how the Cairo Graphic Library has been implemented and how well it is supported in hardware.

WARNING: Any filter setting not being fast or nearest will make the overlaying of that placed image, if scaled 30-50, times slower compared to the fast method. This can be detrimental to running Snowmix if the hardware on which Snowmix is running is not fast enough.

Example

    image filter 3 best
    image filter

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image geometry

Name

image geometry - List the geometry for placed image.

Synopsis

image geometry [<place id> <clip w> <clip h> <src_x> <src_y>]

Description

The image clip command is used to list the geometry for a placed image created with the command image add. When used without any parameters, it will list geometries for all placed images. The optional argument place id identifies the placed image to list.

Example

    image geometry 3
    image clip

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image load

Name

image load - Load an image from file or delete loaded image or list loaded images

Synopsis

image load [<image id> <file name>]

Description

The image load command, when given without any parameters will list loaded images. If given with the image id parameter and a valid file name identifying a PNG file, Snowmix will load the image into loaded images identified by the argument image id. The image id is a positive integer greater than or equal to 0 and less than the maximum number of images Snowmix can hold. This number is by default 32, but can be changed using the command maxplaces before the first image command is issued. When loading the image, a previous loaded image with the same image id, if any, will be deleted. If the command is issued with only the image id as argument, the loaded image with that image id, if loaded, will be deleted.

Example

    image load 1 ../images/CS_logo-white-64x64.png
    image load 1
    image load

The first command loads the image into an image holder with the image id 1. The second command deletes the loaded image and the third command lists loaded images

See also
maxplaces, image help, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image name

Name

image name - Set or list name for loaded image or images.

Synopsis

image name [<image id> [<iname>]]

Description

The image name command is used to set or list the name for loaded images. Used without arguments, the command list the name of all loaded images where this command has been used to set the name for the image. By defualt no name exist. Used with one argument, the image id, the name of that loaded image is deleted. Used with both the image id and a name argument, the name is set as name for the loaded image.

Example

     image name 3 My Loasded Image no 3

In the above example, the name for the loaded image 3 is set to "Loaded Image no 3".

See also

image load

image place

Name

image place - Set (place) an image.

Synopsis

image place [<place id> [<image id> <x> <y> [(n | s | e | w | c | ne | nw | se | sw)] [(left | center | right) (top | middle | bottom)]]]

Description

The image place command is used to place an image loaded with the command image load. When used without any parameters, the command will list all placed images. The argument place id identifies the identifies the place holder to use for placing an image. to place. When used only with the argument place id, the command will delete the placed image, if it exist. The optional arguments image id identifies the loaded image to place. The optional argument x and y is the coordinate to place the image. See command image coor for more on a virtual feeds coordinates. The optional argument 'n', 's' etc is the anchor parameter for the image. Default value if omitted is 'nw'. See the command image anchor for more information. The argument 'left', 'center' etc. is the alignment for the placed image. The default value is 'top' and 'left' if omitted. See the command image align for more information about alignment for placed images.

Example

    image place 2 3 -1 0 ne right top
    image place 2
    image place

The first example will create a placed image with id 2 and it will use loaded image 3. It will anchor the image to north-east and align the image top and right side to the coordinate. Anchoring the image to north-east will add system width and 0 to the coordinates. The result is that the image will be placed in the top right side of the sysem mixer frame when overlayed.

The second example deletes the placed image 2. The third example lists the placed images.

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image move alpha

Name

image move alpha - Set or list animation settings for alpha for virtual feed.

Synopsis

image move alpha [<place id> <delta alpha> <steps>]

Description

The image move alpha command is used to set the delta alpha value and steps for animation of the alpha value for a placed image loaded. When used without any parameters, it will list alpha animation values for all placed images. The argument place id identifies the placed image to set the animation alpha values for. When set, the placed image's alpha value will be added the delta alpha value for every frame for as many frames the steps parameter indicates. delta alpha is an integer or decimal value and the steps parameter must be a positive integer between 0 and 2 to the power of 32 minus 1. This command will not change the placed image's alpha value beyond 1.0 or below 0.0.

Example

    image move alpha 3 0.01 100
    image move alpha

If the alpha value of placed image is 0, then over the next 100 frames, the alpha value will be increased in steps of 0.01 per frame to 1.0 after 100 frames.

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image move coor

Name

image move coor - Set or list animation settings for coordinates for virtual feed.

Synopsis

image move coor [<place id> <delta x> <delta y> <steps x> <steps y>]

Description

The image move coor command is used to set the delta coordinate values and steps for animation of the coordinate value for a placed image created with the command image add. When used without any parameters, it will list coordinate animation values for all created placed images. The argument place id identifies the placed image to set the animation coordinate values for. When set, the placed image's coordinate value will be added the delta x and delta y value for every frame for as many frames the steps x and steps y parameter indicates. delta x and delta y must be integer values larger than 2 to the power of 31 and lower than 2 to the power of 32. The steps x and steps y parameters must be a positive integer between 0 and 2 to the power of 32 minus 1. The number of steps can be set individually for X and for Y. Using nummerical very large values for either steps or delta coor will eventually cause overflow for the 32 bit signed variables holding the coordinates for each placed image. See command image coor for more information setting coordinates for placed images.

Example

    image move coor 3 2 -4 100 50 
    image move coor

The above example will for placed image 3 add 2 to the placed image's X coordinate for the next 100 frames and -4 to the feed's Y coordinate for the next 50 frames.

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image move clip

Name

image move clip - Set or list animation settings for coordinates for placed image.

Synopsis

image move clip [<place id> <delta clip x> <delta clip y> <delta clip w> <delta clip h> <steps x> <steps y> <steps w> <steps h>]

Description

The image move clip command is used to set the delta clip values and steps for animation of the clip values for a placed image created with the command image add. When used without any parameters, it will list clip animation values for all placed images. The argument place id identifies the placed image to set the animation clip values for. When set, the placed image's clip value will be added the delta clip x, delta clip y, delta clip w and delta clip h value for every frame for as many frames the steps x, steps y, steps w and steps h parameter indicates. The delta clip parameters must be integer values larger than 2 to the power of 31 and lower than 2 to the power of 32. The step parameters must be a positive integer between 0 and 2 to the power of 32 minus 1. The number of steps can be set individually for each clip parameter. Using nummerical very large values for either steps or delta clip will eventually cause overflow for the 32 bit unsigned variables holding the clip values for each placed image. See command image clip for more information setting clip parameters for placed images.

Example

    image move clip 3 2 1 1 1 100 100 100 100
    image move clip

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image move offset

Name

image move offset - Set or list animation settings for offset for placed image.

Synopsis

image move offset [<place id> <delta offsey x> <delta offset y> <steps x> <steps y>]

Description

The image move offset command is used to set the delta offset values and steps for animation of the offset values for a placed image. When used without any parameters, it will list offset animation values for all created placed images. The argument place id identifies the placed image to set the animation offset values for. When set, the placed image's offset values will be added the delta offset x and delta offset y value for every frame for as many frames the steps x and steps y parameter indicates. delta offset x and delta offset y must be integer values larger than 2 to the power of 31 and lower than 2 to the power of 32. The steps x and steps y parameters must be a positive integer between 0 and 2 to the power of 32 minus 1. The number of steps can be set individually for offset X and for offset Y. Using nummerical very large values for either steps or delta offset will eventually cause overflow for the 32 bit signed variables holding the offset for each placed image. See command image offset for more information setting offset for placed images.

Example

    image move offset 3 2 -4 100 50 
    image move offset

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image move rotation

Name

image move rotation - Set or list animation settings for rotation for placed image.

Synopsis

image move rotation [<place id> <delta rotation> <steps>]

Description

The image move rotation command is used to set the delta rotation value in radians and steps for animation of the rotation value for a placed image. When used without any parameters, it will list rotation animation values for all created placed images. The argument place id identifies the placed image to set the animation rotation values for. When set, the placed image's rotation value will be added the delta rotation value for every frame for as many frames the steps parameter indicates. delta rotation is an integer or decimal value and the steps parameter must be a positive integer between 0 and 2 to the power of 32 minus 1. This command will not change the placed image's rotation value beyond plus/minus 2PI.

Example

    image move rotation 3 1PI/50 100
    image move rotation 3 0.01570796326794896619 100
    image move rotation

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image move scale

Name

image move scale - Set or list animation settings for scale for placed image.

Synopsis

image move scale [<place id> <delta scale x> <delta scale y> <steps x> <steps y>]

Description

The image move scale command is used to set the delta scale values and steps for animation of the scale values for a placed image. When used without any parameters, it will list scale animation values for all placed images. The argument place id identifies the placed image to set the animation scale values for. When set, the placed image's scale values will be added the delta x and delta y value for every frame for as many frames the steps x and steps y parameter indicates. delta scale x and delta scale y are decimal values. The steps x and steps y parameters must be a positive integer between 0 and 2 to the power of 32 minus 1. The number of steps can be set individually for scaling X and for scaling Y. See command image scale for more information setting scale for placed images. The command will not change the placed image's scale value below 0.0.

Example

    image move scale 3 0.01 0.02 100 30
    image move scale

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image overlay

Name

image overlay - Overlay placed images.

Synopsis

image overlay <id list>
<id list> = \&lt;place id> | <place id>..<place id> | all | end | <place id>..end) [<id list>]

Description

The image overlay command, when executed as part of the command macro set with the command overlay finish. The command will take a list of id as specified in the syntax. The command has no effect when not executed as part of the command macro set with the command overlay finish.

Example

    image overlay 1..4 6..end
    image overlay all
    image overlay 2..4 1 25..end

See also

image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source, overlay finish

image rotation

Name

image rotation - Set or list the rotation for a placed image.

Synopsis

image rotation [<place id> <rotation>]

Description

The image rotation command is used to set the rotation value in radians for a placed image. When used without any parameters, it will list rotation values for all created placed images. The argument place id identifies the placed image to set the rotation value for. Rotation values are integer or decimal values. Snowmix will normalize the rotation to be between -2PI and +2PI. The rotation value can also be specified as fractions of PI.

Example

    image rotation 3 0.3125
    image rotation -1PI/16
    image rotation 2PI/32
    image rotation

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source

image scale

Name

image scale - Set or list the scale of a placed image.

Synopsis

image scale [<place id> <scale x> <scale y>]

Description

The image scale command is used to set the scale values for a placed image. When used without any parameters, it will list scale values for all created placed images. The argument place id identifies the placed image to set the scale values for. Scale values are integer or decimal values. A scale of 0 will prevent overlay of the placed image as it will be infinitesimal small.

Example

    image scale 3 1.090909 1.0
    image scale 3 0.5 0.5
    image coor

The first example will is scale placed image 1.090909 times along the X axis and leave the feed unchanged along the Y axis. This would be useful when overlaying a feed with a 704x576 geometry and a pixel aspect ratio of 12/11 = 1.090909.......

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source.

image source

Name

image source - Set or list the source of a placed image.

Synopsis

image source [(feed | image) <place id> (<feed id> | <image id>)]

Description

The image source command is used to set the source value for a placed image. When used without any parameters, it will list the sources for all placed images. The argument place id identifies the placed image to set the source for. Sources can either be an already created feed or an already loaded image.

Example

    image source feed 3 2
    image source image 4 12
    image source

The first example sets the source of placed image 3 to be feed 2. The second example sets the source of placed image 4 to be image id 12 (the id is the image load id and not the placed id of an image).

See also
image add, image align, image clip, image coor, image filter, image place rect, image move alpha, image move clip, image move coor, image move offset, image move rotation, image move scale, image overlay, image rotation, image scale, image source, feed add, image load.