Reference Cairo Graphics

Reference manual - Cairo Graphics Primitives

Updated for Snowmix 0.4.4

This is the reference manual for Snowmix for the commands belonging to the the Cairo Graphics Primitives used to form shapes. 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

Snowmix supports the following Cairo Graphics Primitives:

    shape arc_cw - create a clockwise arc path for a shape
    shape arc_ccw - create a counter clockwise arc path for a shape
    shape arcrel_cw - create a relativ placed clockwise arc path for a shape
    shape arcrel_ccw - create a relative placed counter clockwise arc path for a shape
    shape clip - clip a region for a shape
    shape closepath - close a path in a shape ie. back to the beginning of the path
    shape curveto - create an absolute spline like path for a shape
    shape curverel - create a relative spline path for a shape
    shape feed - use the frame of a video feed as image in a shape
    shape fill - fill out the path defined in a shape
    shape fill preserve - as shape fill, but preserve the path
    shape filter - set the scaling/overlaying method for an image or a feed
    shape image - use an image in a shape
    shape inshape *) - reference/include a shape in a shape
    shape line width - set the line width of a path when setting a stroke in a shape
    shape line join - set the way lines are joined in a shape
    shape line cap - set the way lines are ended in a shape
    shape lineto - create an absolute line path in a shape
    shape linerel - create a relative line path in a shape
    shape mask pattern - mask with a pattern in a shape
    shape moverel - move relative in a shape
    shape moveto - move absolute in a shape
    shape newpath - begin a new path in a shape
    shape operator - set the operator for graphics operations in a shape
    shape paint - paint in a shape 
    shape pattern radial - set a pattern as a radial pattern
    shape pattern linear - set a pattern as a linear pattern
    shape pattern stoprgb - sets the stop rgb points of a pattern
    shape rectangle - create a rectangle path
    shape recursion *) - sets the number of levels a shape can reference other shapes recursively
    shape restore - restore the graphic context in a shape saved by the shape save command 
    shape rotation - make a rotation in a shape
    shape save - save the graphic context in a shape
    shape scale - make a scaling in a shape
    shape source alphaadd - adds a constant to the alpha level
    shape source alphamul - multiply the alpha level with a constant
    shape source rgb - sets the source colours for a shape to be used by paint, stroke etc.
    shape source rgba - as for shape source rgb, but includes alpha/transparency
    shape source pattern - set a pattern as source for a shape to be used with paint etc.
    shape stroke - draw a line along the path defined in a shape
    shape stroke preserve - as shape stroke, but preserving the path
    shape translate - move the origin of a shape
    shape transform - make a matrix transformation of coordinate system for a shape

The commands corresponds directly to similar named commands described for the 8airo Graphics framework. Please also see the API Reference Manual for details on parameter settings for Cairo Graphics as not all details are decribed here.

*) The commands shape inshape and shape recursion do not have a corresponding Cairo Graphics API function though. The command shape inshape is used to reference to a shape to be included possibly including itself. The command shape recursion is used to control the number of levels a shape can reference into. The commands inshape and recursion can be used to form a possibly uselful loop, if combined with relative movement or other changes for each loop.

Further documentation on Cairo Graphics Primitives is work in progress. However see also the wiki pages on Shapes for many examples on how to use the primitives.

---

Command Syntax Overview

    shape arc_cw <shape id> <x> <y> <radius> <angle from> <angle to>
    shape arc_ccw <shape id> <x> <y> <radius> <angle from> <angle to>
    shape arcrel_cw <shape id> <x> <y> <radius> <angle from> <angle to>
    shape arcrel_ccw <shape id> <x> <y> <radius> <angle from> <angle to>
    shape clip <shape id>
    shape closepath <shape_id>
    shape curveto <shape id> <x1> <y1> <x2> <y2> <x3> <y3>
    shape curverel <shape id> <x1> <y1> <x2> <y2> <x3> <y3>
    shape feed <shape id> <feed id> <x> <y> <scale x> <scale y>
    shape fill <shape id>
    shape fill preserve <shape id>
    shape filter <shape id> (fast | good | best | nearest | bilinear | gaussian)
    shape image <shape id> <image id> <x> <y> <scale_x> <scale_y>
    shape inshape <shape id> <inshape id>
    shape line width <shape id> <width>
    shape line join <shape id> (miter | round | bevel) [<miter limit>]
    shape line cap <shape id> (butt | round | square)
    shape lineto <shape id> <x> <y>
    shape linerel <shape id> <x> <y>
    shape mask pattern <shape_id> <pattern id>
    shape moveentry <shape id> <entry id> [<to entry>]
    shape moverel <shape id> <x> <y>
    shape moveto <shape id> <x> <y>
    shape newpath <shape id>
    shape operator <shape id> (clear | source | over | in | out | atop | dest | dest_over | dest_in | dest_out | dest_atop | xor | add | saturate | multiply | screen | overlay | darken | lighten | dodge | burn | hard | soft | difference | exclusion | hsl_hue | hsl_saturation | hsl_color | hsl_luminosity)
    shape paint <shape id> [<alpha>]
    shape pattern add [<pattern id> [<pattern name>]]
    shape pattern radial <pattern id> <cx0> <cy0> <radius0> <cx1> <cy1> <radius1>
    shape pattern linear <pattern id> <x1> <y1> <x2> <y2>
    shape pattern stoprgb <pattern id> <offset> <red> <green> <blue> [<alpha>]
    shape rectangle <shape id> <x> <y> <width> <height>
    shape recursion <shape id> <level>
    shape restore <shape id>
    shape rotation <shape id> <relative rotation> [<absolute rotation>]
    shape save <shape id>
    shape scale <shape id> <scale x> <scale y>
    shape source alphaadd <shape id> <value>
    shape source alphamul <shape id> <value>
    shape source rgb <shape id> <red> <green> <blue> [<alpha>]
    shape source rgba <shape id> <red> <green> <blue> [<alpha>]
    shape source pattern <shape_id> <pattern id>
    shape stroke <shape id>
    shape stroke preserve <shape id>
    shape translate <shape id> <offset x> <offset y>
    shape transform <shape id> <xx> <yx> <xy> <yy> <x0> <y0>

---

Command reference

shape arc_cw, shape arc_ccw, shape arcrel_cw, shape_arcrel_ccw

Name
shape arc_cw - create a clockwise arc path absolute placed for a shape
shape arc_ccw - create a counter clockwise arc path absolute placed for a shape
shape arcrel_cw - create a clockwise arc path absolute placed for a shape
shape arcrel_ccw - create a counter clockwise arc path absolute placed for a shape

Synopsis
shape arc_cw <shape id> <x> <y> <radius> <angle from> <angle to>
shape arc_ccw <shape id> <x> <y> <radius> <angle from> <angle to>
shape arcrel_cw <shape id> <x> <y> <radius> <angle from> <angle to>
shape arcrel_ccw <shape id> <x> <y> <radius> <angle from> <angle to>

Description
The shape arc_cw, shape arc_ccw, shape arcrel_cw and shape arcrel_ccw are used to add an arc path to a shape either clockwise or counter clockwise. The arc can either be placed absolute using the placed shapes coordinates the shape is used in as origin or relative placed using the current point in the current path as origin. The path in the shape can then be used for clipping (shape clip), or drawing (stroke) or paiting an area (shape paint). The shape id parameter is the id number of the shape given for a preceeding shape add command. The x and y parameter is center of the arc desired. The angle from is the beginning angle describing the arc, the parameter angle to is the ending angle describing the arc. Both angles are in radians. The command supports the keyword PI and fractions of PI as shown in the examples. See also the Cairo Graphics API Equivalent for details on the parameters.

Cairo Graphics API Equivalent
The Cairo Graphics API equivalents are cairo_arc and cairo_arc_negative. See also cairo_get_current_point used to compute a relative placed arcs.

Example

    shape add 1 Arc Example
    shape arc_cw 1 0.0 0.5 0.1 3PI/12
    shape closepath 1
    shape stroke 1

The example list a shape with shape id. It includes an arc with center at 0.0,0.5 and has starting angle at 0.1 and an ending angle at 3PI/12. Further more the shape shape closes the path from whereever it started, usually 0,0 unless otherwise given and the shape ends with a stroke, that will instruct the shape to draw a line along the path.

See also

shape add, shape lineto, shape linerel, shape curveto, shape curverel, shape moveto, shape moverel

---

shape feed, shape image

Name
shape feed - use a feed frame in a shape.
shape image - use an image in a shape.

Synopsis

shape feed <shape id> <feed id> <x> <y> <scale_x> <scale_y>
shape image <shape id> <image id> <x> <y> <scale_x> <scale_y>

Description
The shape feed and shape image are used to add a video feed frame or an image to a shape already created with the command shape add. The argument shape id sets the shape the command will be added to. The argument feed id for shape feed and image id for shape image defines the feed or image to be added. The arguments x and y defines the relative placement of the feed frame or image within the shape. The last arguments scale x and scale y sets the scale for the feed frame or image.

Scaling
The scaling arguments controlling the scale of the feed frame or image can either be relative, absolute or no scaling at all as shown in the table below:

Scale	Effect
< 0	Scaling will be relative to whatever scaling the shape has when the shape feed or shape image is executed.
= 0	Scaling will be ignored and the feed frame or image will be scaled to whatever caling the shape has when the shape feed or shape image is executed. This is equivalent to setting scaling to -1
> 0	Scaling is absolute independent of what scale the shape has when the shape feed or shape image is executed.

The scaling of a shape depends on several things. First the shape is scaled accoding to the scale set for the placed shape the shape is used in. Then the shape it self can contain scaling using one or more occurrence of the command shape scale. If a placed shape is scaled to 0.5,0.5 and then the shape of the placed shape contains the command shape scale 0.25 0.25 before the shape feed or shape image command, then the resulting scale of the shape before executing the shape feed or shape image is 0.5 x 0.25 = 0.125. If the feed frame or image is set to scale to -4,-4 then the feed frame or image is scaled relative and will be scaled to 0.5 x 0.25 x 4 = 0.5.

Filter method
By default, when overlay a feed or an image in a shape, the filter method used will be fast. This is usually okay, but there may be a need to do better. If a shape filter command is created right after the shape feed or shape image command, the default filter can be overridden.

Cairo Graphics API Equivalent
The Cairo Graphics API equivalents are cairo_scale, cairo_image_surface_create_for_data, cairo_set_source_surface and cairo_pattern_set_filter

Example

    shape add 21 Shape based feed absolute scaled
    shape feed 21 1 0 0 1 1
    shape paint 21
    shape place 1 21 10 10 1 1

The example defines a shape with id 21. The shape definition 21 adds feed 1 placed at 0,0 and scaled absolute 1,1. It also adds a paint command to the shape ensuring something is shown when overlayed. The command shape place then creates a placed shape id 1 at 10,10 using shape 21 and scale 1,1. The default anchoring for the placed shape is nw meaining at 0,0 and the default alignment is left/top and the default alpha is 1. If placed shape 1 is overlayed, as part of the command macro set with the command ovelay finish, the feed 1 will be placed and overlayed starting from 10,10 in the main mixer frame. If the placed shape 1 is later scaled, then the scaling will not affect the size of the overlayed feed as the scaling in the shape is absolute and not relative. Because there is no filter command in the shape 21 right after the shape feed command, the shape when placed will overlay using the filter method fast

    shape add 22 Shape based image relative scaled
    shape image 22 1 0 0 -1 -1
    shape filter 22 best
    shape paint 22
    shape place 2 22 20 20 1 1

The example defines a shape with id 22. The shape definition 22 adds image 1 placed at 0,0 and scaled relative 1,1 because the scaling value is negative. It also adds a paint command to the shape ensuring something is shown when overlayed. The command shape place then creates a placed shape id 2 at 20,20 using shape 22 and scale 1,1. The default anchoring for the placed shape is nw meaining at 0,0 and the default alignment is left/top and the default alpha is 1. If placed shape 1 is overlayed, as part of the command macro set with the command ovelay finish, the image 1 will be placed and overlayed starting from 20,20 in the main mixer frame. If the placed shape 2 is later scaled, then the scaling will affect the size of the overlayed feed as the scaling in the shape i s relative and not absolute. Because there is a filter command in the shape 22 right after the shape image command, the shape when placed will overlay using this filter method best specified in the example.

See also

shape add, shape scale, shape filter, shape paint, shape place, shape overlay, overlay finish,

More to come