Guile-Cairo. version 1.10, updated 23 April Carl Worth Andy Wingo (many others)

Transcription

1 Guile-Cairo version 1.10, updated 23 April 2011 Carl Worth Andy Wingo (many others)

2 This manual is for Guile-Cairo (version 1.10, updated 23 April 2011) Copyright Carl Worth and others Permission is granted to copy, distribute and/or modify this document under the terms of either the GNU Lesser General Public License (LGPL) version 2.1 or the Mozilla Public License (MPL) version 1.1.

3 i Short Contents 1 cairo t Paths Patterns Transformations Regions Text Font Faces Scaled Fonts Font Options FreeType Fonts Win32 Fonts Quartz Fonts User Fonts cairo device t cairo surface t Image Surfaces PDF Surfaces PNG Support PostSipt Surfaces Recording Surfaces SVG Surfaces cairo matrix t Error handling Version Information Types Concept Index Function Index

4 Chapter 1: cairo t 1 1 cairo t The cairo drawing context 1.1 Overview <cairo> is the main object used when drawing with cairo. To draw with cairo, you eate a <cairo>, set the target surface, and drawing options for the <cairo>, eate shapes with functions like cairo-move-to and cairo-line-to, and then draw shapes with cairostroke or cairo-fill. <cairo> s can be pushed to a stack via cairo-save. They may then safely be changed, without loosing the current state. Use cairo-restore to restore to the saved state. 1.2 Usage cairo-eate (target <cairo-surface-t>) ( <cairo-t>) Creates a new <cairo-t> with all graphics state parameters set to default values and with target as a target surface. The target surface should be constructed with a backend-specific function such as cairo-image-surface-eate (or any other cairo_<backend>_surface_eate variant). target target surface for the context a newly allocated <cairo-t>. cairo-save ( <cairo-t>) Makes a copy of the current state of and saves it on an internal stack of saved states for. When cairo-restore is called, will be restored to the saved state. Multiple calls to cairo-save and cairo-restore can be nested; each call to cairo-restore restores the state from the matching paired cairo-save. It isn t necessary to clear all saved states before a <cairo-t> is freed. If the reference count of a <cairo-t> drops to zero in response to a call to cairo-destroy, any saved states will be freed along with the <cairo-t>. a <cairo-t> cairo-restore ( <cairo-t>) Restores to the state saved by a preceding call to cairo-save and removes that state from the stack of saved states. a <cairo-t> cairo-get-target ( <cairo-t>) ( <cairo-surface-t >) Gets the target surface for the cairo context as passed to cairo-eate. This function will always urn a valid pointer, but the result can be a "nil" surface if is already in an error state, (ie. cairo-status!= CAIRO_STATUS_SUCCESS ). A nil surface is indicated by cairo-surface-status!= CAIRO_STATUS_SUCCESS. the target surface. This object is owned by cairo. To keep a reference to it, you must call cairo-surface-reference.

5 Chapter 1: cairo t 2 cairo-push-group ( <cairo-t>) Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to cairo-pop-group or cairopop-group-to-source. These calls provide the result of any drawing to the group as a pattern, (either as an explicit object, or set as the source pattern). This group functionality can be convenient for performing intermediate compositing. One common use of a group is to render objects as opaque within the group, (so that they occlude each other), and then blend the result with translucence onto the destination. Groups can be nested arbitrarily deep by making balanced calls to cairo-pushgroup/cairo-pop-group. Each call pushes/pops the new target group onto/from a stack. The cairo-push-group function calls cairo-save so that any changes to the graphics state will not be visible outside the group, (the pop group functions call cairorestore). By default the intermediate group will have a content type of CAIRO_CONTENT_COLOR_ALPHA. Other content types can be chosen for the group by using cairo-push-group-withcontent instead. As an example, here is how one might fill and stroke a path with translucence, but without any portion of the fill being visible under the stroke: Since 1.2 cairo_push_group (); cairo_set_source (, fill_pattern); cairo_fill_preserve (); cairo_set_source (, stroke_pattern); cairo_stroke (); cairo_pop_group_to_source (); cairo_paint_with_alpha (, alpha); cairo-pop-group ( <cairo-t>) ( <cairo-pattern-t >) Terminates the redirection begun by a call to cairo-push-group or cairo-pushgroup-with-content and urns a new pattern containing the results of all drawing operations performed to the group. The cairo-pop-group function calls cairo-restore, (balancing a call to cairosave by the push group function), so that any changes to the graphics state will not be visible outside the group. Since 1.2 a newly eated (surface) pattern containing the results of all drawing operations performed to the group. The caller owns the urned object and should call cairo-pattern-destroy when finished with it.

6 Chapter 1: cairo t 3 cairo-pop-group-to-source ( <cairo-t>) Terminates the redirection begun by a call to cairo-push-group or cairo-pushgroup-with-content and installs the resulting pattern as the source pattern in the given cairo context. The behavior of this function is equivalent to the sequence of operations: cairo_pattern_t *group = cairo_pop_group (); cairo_set_source (, group); cairo_pattern_destroy (group); but is more convenient as their is no need for a variable to store the short-lived pointer to the pattern. The cairo-pop-group function calls cairo-restore, (balancing a call to cairosave by the push group function), so that any changes to the graphics state will not be visible outside the group. Since 1.2 cairo-get-group-target ( <cairo-t>) ( <cairo-surface-t >) Gets the current destination surface for the context. This is either the original target surface as passed to cairo-eate or the target surface for the current group as started by the most recent call to cairo-push-group or cairo-push-group-withcontent. This function will always urn a valid pointer, but the result can be a "nil" surface if is already in an error state, (ie. cairo-status!= CAIRO_STATUS_SUCCESS ). A nil surface is indicated by cairo-surface-status!= CAIRO_STATUS_SUCCESS. Since 1.2 the target surface. This object is owned by cairo. To keep a reference to it, you must call cairo-surface-reference. cairo-set-source-rgb ( <cairo-t>) (red <double>) (green <double>) (blue <double>) Sets the source pattern within to an opaque color. This opaque color will then be used for any subsequent drawing operation until a new source pattern is set. The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped. The default source pattern is opaque black, (that is, it is equivalent to cairo set source rgb(, 0.0, 0.0, 0.0)). red green blue red component of color green component of color blue component of color

7 Chapter 1: cairo t 4 cairo-set-source-rgba ( <cairo-t>) (red <double>) (green <double>) (blue <double>) (alpha <double>) Sets the source pattern within to a translucent color. This color will then be used for any subsequent drawing operation until a new source pattern is set. The color and alpha components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped. The default source pattern is opaque black, (that is, it is equivalent to cairo set source rgba(, 0.0, 0.0, 0.0, 1.0)). red green blue alpha red component of color green component of color blue component of color alpha component of color cairo-set-source ( <cairo-t>) (source <cairo-pattern-t>) Sets the source pattern within to source. This pattern will then be used for any subsequent drawing operation until a new source pattern is set. Note: The pattern s transformation matrix will be locked to the user space in effect at the time of cairo-set-source. This means that further modifications of the current transformation matrix will not affect the source pattern. See cairo-pattern-setmatrix. The default source pattern is a solid pattern that is opaque black, (that is, it is equivalent to cairo set source rgb(, 0.0, 0.0, 0.0)). source a <cairo-pattern-t> to be used as the source for subsequent drawing operations. cairo-set-source-surface ( <cairo-t>) (surface <cairo-surface-t>) (x <double>) (y <double>) This is a convenience function for eating a pattern from surface and setting it as the source in with cairo-set-source. The x and y parameters give the user-space coordinate at which the surface origin should appear. (The surface origin is its upper-left corner before any transformation has been applied.) The x and y parameters are negated and then set as translation values in the pattern matrix. Other than the initial translation pattern matrix, as desibed above, all other pattern attributes, (such as its extend mode), are set to the default values as in cairopattern-eate-for-surface. The resulting pattern can be queried with cairoget-source so that these attributes can be modified if desired, (eg. to eate a repeating pattern with cairo-pattern-set-extend). surface a surface to be used to set the source pattern

8 Chapter 1: cairo t 5 x y User-space X coordinate for surface origin User-space Y coordinate for surface origin cairo-get-source ( <cairo-t>) ( <cairo-pattern-t >) Gets the current source pattern for. the current source pattern. This object is owned by cairo. To keep a reference to it, you must call cairo-pattern-reference. cairo-set-antialias ( <cairo-t>) (antialias <cairo-antialias-t>) Set the antialiasing mode of the rasterizer used for drawing shapes. This value is a hint, and a particular backend may or may not support a particular value. At the current time, no backend supports CAIRO_ANTIALIAS_SUBPIXEL when drawing shapes. Note that this option does not affect text rendering, instead see cairo-fontoptions-set-antialias. antialias a <cairo-t> the new antialiasing mode cairo-get-antialias ( <cairo-t>) ( <cairo-antialias-t>) Gets the current shape antialiasing mode, as set by cairo-set-shape-antialias. the current shape antialiasing mode. cairo-set-dash ( <cairo-t>) (dashes <double>) (num-dashes <int>) (offset <double>) Sets the dash pattern to be used by cairo-stroke. A dash pattern is specified by dashes, an array of positive values. Each value provides the length of alternate "on" and "off" portions of the stroke. The offset specifies an offset into the pattern at which the stroke begins. Each "on" segment will have caps applied as if the segment were a separate sub-path. In particular, it is valid to use an "on" length of 0.0 with CAIRO_LINE_CAP_ROUND or CAIRO_LINE_CAP_SQUARE in order to distributed dots or squares along a path. Note: The length values are in user-space units as evaluated at the time of stroking. This is not necessarily the same as the user space at the time of cairo-set-dash. If num-dashes is 0 dashing is disabled. If num-dashes is 1 a symmetric pattern is assumed with alternating on and off portions of the size specified by the single value in dashes. If any value in dashes is negative, or if all values are 0, then will be put into an error state with a status of CAIRO_STATUS_INVALID_DASH.

9 Chapter 1: cairo t 6 dashes an array specifying alternate lengths of on and off stroke portions num-dashes the length of the dashes array offset an offset into the dash pattern at which the stroke should start cairo-get-dash-count ( <cairo-t>) ( <int>) This function urns the length of the dash array in (0 if dashing is not currently in effect). See also cairo-set-dash and cairo-get-dash. Since 1.4 a <cairo-t> the length of the dash array, or 0 if no dash array set. cairo-set-fill-rule ( <cairo-t>) (fill-rule <cairo-fill-rule-t>) Set the current fill rule within the cairo context. The fill rule is used to determine which regions are inside or outside a complex (potentially self-intersecting) path. The current fill rule affects both cairo-fill and cairo-clip. See <cairo-fill-rule-t> for details on the semantics of each available fill rule. The default fill rule is CAIRO_FILL_RULE_WINDING. fill-rule a <cairo-t> a fill rule, specified as a <cairo-fill-rule-t> cairo-get-fill-rule ( <cairo-t>) ( <cairo-fill-rule-t>) Gets the current fill rule, as set by cairo-set-fill-rule. the current fill rule. cairo-set-line-cap ( <cairo-t>) (line-cap <cairo-line-cap-t>) Sets the current line cap style within the cairo context. See <cairo-line-cap-t> for details about how the available line cap styles are drawn. As with the other stroke parameters, the current line cap style is examined by cairostroke, cairo-stroke-extents, and cairo-stroke-to-path, but does not have any effect during path construction. The default line cap style is CAIRO_LINE_CAP_BUTT. line-cap a line cap style cairo-get-line-cap ( <cairo-t>) ( <cairo-line-cap-t>) Gets the current line cap style, as set by cairo-set-line-cap. the current line cap style.

10 Chapter 1: cairo t 7 cairo-set-line-join ( <cairo-t>) (line-join <cairo-line-join-t>) Sets the current line join style within the cairo context. See <cairo-line-join-t> for details about how the available line join styles are drawn. As with the other stroke parameters, the current line join style is examined by cairostroke, cairo-stroke-extents, and cairo-stroke-to-path, but does not have any effect during path construction. The default line join style is CAIRO_LINE_JOIN_MITER. line-join a line join style cairo-get-line-join ( <cairo-t>) ( <cairo-line-join-t>) Gets the current line join style, as set by cairo-set-line-join. the current line join style. cairo-set-line-width ( <cairo-t>) (width <double>) Sets the current line width within the cairo context. The line width value specifies the diameter of a pen that is circular in user space, (though device-space pen may be an ellipse in general due to scaling/shear/rotation of the CTM). Note: When the desiption above refers to user space and CTM it refers to the user space and CTM in effect at the time of the stroking operation, not the user space and CTM in effect at the time of the call to cairo-set-line-width. The simplest usage makes both of these spaces identical. That is, if there is no change to the CTM between a call to cairo-set-line-width and the stroking operation, then one can just pass user-space values to cairo-set-line-width and ignore this note. As with the other stroke parameters, the current line width is examined by cairostroke, cairo-stroke-extents, and cairo-stroke-to-path, but does not have any effect during path construction. The default line width value is 2.0. width a <cairo-t> a line width cairo-get-line-width ( <cairo-t>) ( <double>) This function urns the current line width value exactly as set by cairo-set-linewidth. Note that the value is unchanged even if the CTM has changed between the calls to cairo-set-line-width and cairo-get-line-width. the current line width. cairo-set-miter-limit ( <cairo-t>) (limit <double>) Sets the current miter limit within the cairo context.

11 Chapter 1: cairo t 8 If the current line join style is set to CAIRO_LINE_JOIN_MITER (see cairo-set-linejoin), the miter limit is used to determine whether the lines should be joined with a bevel instead of a miter. Cairo divides the length of the miter by the line width. If the result is greater than the miter limit, the style is converted to a bevel. As with the other stroke parameters, the current line miter limit is examined by cairo-stroke, cairo-stroke-extents, and cairo-stroke-to-path, but does not have any effect during path construction. The default miter limit value is 10.0, which will convert joins with interior angles less than 11 degrees to bevels instead of miters. For reference, a miter limit of 2.0 makes the miter cutoff at 60 degrees, and a miter limit of makes the cutoff at 90 degrees. A miter limit for a desired angle can be computed as: miter limit = 1/sin(angle/2) limit miter limit to set cairo-get-miter-limit ( <cairo-t>) ( <double>) Gets the current miter limit, as set by cairo-set-miter-limit. the current miter limit. cairo-set-operator ( <cairo-t>) (op <cairo-operator-t>) Sets the compositing operator to be used for all drawing operations. See <cairooperator-t> for details on the semantics of each available compositing operator. The default operator is CAIRO_OPERATOR_OVER. op a <cairo-t> a compositing operator, specified as a <cairo-operator-t> cairo-get-operator ( <cairo-t>) ( <cairo-operator-t>) Gets the current compositing operator for. the current compositing operator. cairo-set-tolerance ( <cairo-t>) (tolerance <double>) Sets the tolerance used when converting paths into trapezoids. Curved segments of the path will be subdivided until the maximum deviation between the original path and the polygonal approximation is less than tolerance. The default value is 0.1. A larger value will give better performance, a smaller value, better appearance. (Reducing the value from the default value of 0.1 is unlikely to improve appearance significantly.) The accuracy of paths within Cairo is limited by the precision of its internal arithmetic, and the presibed tolerance is restricted to the smallest representable internal value. tolerance a <cairo-t> the tolerance, in device units (typically pixels)

12 Chapter 1: cairo t 9 cairo-get-tolerance ( <cairo-t>) ( <double>) Gets the current tolerance value, as set by cairo-set-tolerance. the current tolerance value. cairo-clip ( <cairo-t>) Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by cairo-fill and according to the current fill rule (see cairo-set-fill-rule). After cairo-clip, the current path will be cleared from the cairo context. The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region. Calling cairo-clip can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling cairo-clip within a cairo-save/cairo-restore pair. The only other means of ineasing the size of the clip region is cairo-reset-clip. cairo-clip-preserve ( <cairo-t>) Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by cairo-fill and according to the current fill rule (see cairo-set-fill-rule). Unlike cairo-clip, cairo-clip-preserve preserves the path within the cairo context. The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region. Calling cairo-clip-preserve can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling cairo-clip-preserve within a cairo-save/cairorestore pair. The only other means of ineasing the size of the clip region is cairoreset-clip. cairo-clip-extents ( <cairo-t>) (x1 <double>) (y1 <double>) (x2 <double>) (y2 <double>) Computes a bounding box in user coordinates covering the area inside the current clip. x1 y1 x2 y2 Since 1.4 left of the resulting extents top of the resulting extents right of the resulting extents bottom of the resulting extents

13 Chapter 1: cairo t 10 cairo-in-clip ( <cairo-t>) (x <double>) (y <double>) ( <cairo-bool-t>) Tests whether the given point is inside the area that would be visible through the current clip, i.e. the area that would be filled by a cairo-paint operation. See cairo-clip, and cairo-clip-preserve. x y X coordinate of the point to test Y coordinate of the point to test A non-zero value if the point is inside, or zero if outside. Since 1.10 cairo-reset-clip ( <cairo-t>) Reset the current clip region to its original, unrestricted state. That is, set the clip region to an infinitely large shape containing the target surface. Equivalently, if infinity is too hard to grasp, one can imagine the clip region being reset to the exact bounds of the target surface. Note that code meant to be reusable should not call cairo-reset-clip as it will cause results unexpected by higher-level code which calls cairo-clip. Consider using cairo-save and cairo-restore around cairo-clip as a more robust means of temporarily restricting the clip region. cairo-copy-clip-rectangle-list ( <cairo-t>) ( <cairo-rectangle-list-t >) Gets the current clip region as a list of rectangles in user coordinates. Never urns #f. The status in the list may be CAIRO_STATUS_CLIP_NOT_REPRESENTABLE to indicate that the clip region cannot be represented as a list of user-space rectangles. The status may have other values to indicate other errors. the current clip region as a list of rectangles in user coordinates, which should be destroyed using cairo-rectangle-list-destroy. Since 1.4 cairo-fill ( <cairo-t>) A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled). After cairo-fill, the current path will be cleared from the cairo context. See cairo-set-fill-rule and cairo-fillpreserve.

14 Chapter 1: cairo t 11 cairo-fill-preserve ( <cairo-t>) A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled). Unlike cairo-fill, cairo-fillpreserve preserves the path within the cairo context. See cairo-set-fill-rule and cairo-fill. cairo-fill-extents ( <cairo-t>) (x1 <double>) (y1 <double>) (x2 <double>) (y2 <double>) Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a cairo-fill operation given the current path and fill parameters. If the current path is empty, urns an empty rectangle ((0,0), (0,0)). Surface dimensions and clipping are not taken into account. Contrast with cairo-path-extents, which is similar, but urns non-zero extents for some paths with no inked area, (such as a simple line segment). Note that cairo-fill-extents must necessarily do more work to compute the precise inked areas in light of the fill rule, so cairo-path-extents may be more desirable for sake of performance if the non-inked path extents are desired. See cairo-fill, cairo-set-fill-rule and cairo-fill-preserve. x1 y1 x2 y2 left of the resulting extents top of the resulting extents right of the resulting extents bottom of the resulting extents cairo-in-fill ( <cairo-t>) (x <double>) (y <double>) ( <cairo-bool-t>) Tests whether the given point is inside the area that would be affected by a cairofill operation given the current path and filling parameters. Surface dimensions and clipping are not taken into account. See cairo-fill, cairo-set-fill-rule and cairo-fill-preserve. x y X coordinate of the point to test Y coordinate of the point to test A non-zero value if the point is inside, or zero if outside. cairo-mask ( <cairo-t>) (pattern <cairo-pattern-t>) A drawing operator that paints the current source using the alpha channel of pattern as a mask. (Opaque areas of pattern are painted with the source, transparent areas are not painted.) pattern a <cairo-pattern-t>

15 Chapter 1: cairo t 12 cairo-mask-surface ( <cairo-t>) (surface <cairo-surface-t>) (surface-x <double>) (surface-y <double>) A drawing operator that paints the current source using the alpha channel of surface as a mask. (Opaque areas of surface are painted with the source, transparent areas are not painted.) surface surface-x surface-y a <cairo-surface-t> X coordinate at which to place the origin of surface Y coordinate at which to place the origin of surface cairo-paint ( <cairo-t>) A drawing operator that paints the current source everywhere within the current clip region. cairo-paint-with-alpha ( <cairo-t>) (alpha <double>) A drawing operator that paints the current source everywhere within the current clip region using a mask of constant alpha value alpha. The effect is similar to cairopaint, but the drawing is faded out using the alpha value. alpha alpha value, between 0 (transparent) and 1 (opaque) cairo-stroke ( <cairo-t>) A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After cairo-stroke, the current path will be cleared from the cairo context. See cairo-set-line-width, cairo-set-line-join, cairo-set-line-cap, cairo-set-dash, and cairo-stroke-preserve. Note: Degenerate segments and sub-paths are treated specially and provide a useful result. These can result in two different situations: 1. Zero-length "on" segments set in cairo-set-dash. If the cap style is CAIRO_LINE_CAP_ROUND or CAIRO_LINE_CAP_SQUARE then these segments will be drawn as circular dots or squares respectively. In the case of CAIRO_LINE_CAP_SQUARE, the orientation of the squares is determined by the direction of the underlying path. 2. A sub-path eated by cairo-move-to followed by either a cairo-close-path or one or more calls to cairo-line-to to the same coordinate as the cairo-moveto. If the cap style is CAIRO_LINE_CAP_ROUND then these sub-paths will be drawn as circular dots. Note that in the case of CAIRO_LINE_CAP_SQUARE a degenerate sub-path will not be drawn at all, (since the correct orientation is indeterminate). In no case will a cap style of CAIRO_LINE_CAP_BUTT cause anything to be drawn in the case of either degenerate segments or sub-paths.

16 Chapter 1: cairo t 13 cairo-stroke-preserve ( <cairo-t>) A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. Unlike cairo-stroke, cairo-stroke-preserve preserves the path within the cairo context. See cairo-set-line-width, cairo-set-line-join, cairo-set-line-cap, cairoset-dash, and cairo-stroke-preserve. cairo-stroke-extents ( <cairo-t>) (x1 <double>) (y1 <double>) (x2 <double>) (y2 <double>) Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a cairo-stroke operation given the current path and stroke parameters. If the current path is empty, urns an empty rectangle ((0,0), (0,0)). Surface dimensions and clipping are not taken into account. Note that if the line width is set to exactly zero, then cairo-stroke-extents will urn an empty rectangle. Contrast with cairo-path-extents which can be used to compute the non-empty bounds as the line width approaches zero. Note that cairo-stroke-extents must necessarily do more work to compute the precise inked areas in light of the stroke parameters, so cairo-path-extents may be more desirable for sake of performance if non-inked path extents are desired. See cairo-stroke, cairo-set-line-width, cairo-set-line-join, cairo-setline-cap, cairo-set-dash, and cairo-stroke-preserve. x1 y1 x2 y2 left of the resulting extents top of the resulting extents right of the resulting extents bottom of the resulting extents cairo-in-stroke ( <cairo-t>) (x <double>) (y <double>) ( <cairo-bool-t>) Tests whether the given point is inside the area that would be affected by a cairostroke operation given the current path and stroking parameters. Surface dimensions and clipping are not taken into account. See cairo-stroke, cairo-set-line-width, cairo-set-line-join, cairo-setline-cap, cairo-set-dash, and cairo-stroke-preserve. x y X coordinate of the point to test Y coordinate of the point to test A non-zero value if the point is inside, or zero if outside.

17 Chapter 1: cairo t 14 cairo-copy-page ( <cairo-t>) Emits the current page for backends that support multiple pages, but doesn t clear it, so, the contents of the current page will be ained for the next page too. Use cairo-show-page if you want to get an empty page after the emission. This is a convenience function that simply calls cairo-surface-copy-page on s target. cairo-show-page ( <cairo-t>) Emits and clears the current page for backends that support multiple pages. Use cairo-copy-page if you don t want to clear the page. This is a convenience function that simply calls cairo-surface-show-page on s target.

18 Chapter 2: Paths 15 2 Paths Creating paths and manipulating path data 2.1 Overview Paths are the most basic drawing tools and are primarily used to implicitly generate simple masks. 2.2 Usage cairo-copy-path ( <cairo-t>) ( <cairo-path-t >) Creates a copy of the current path and urns it to the user as a <cairo-patht>. See <cairo-path-data-t> for hints on how to iterate over the urned data structure. This function will always urn a valid pointer, but the result will have no data ( data== #f and num_data==0 ), if either of the following conditions hold: 1. If there is insufficient memory to copy the path. In this case path->status will be set to CAIRO_STATUS_NO_MEMORY. 2. If is already in an error state. In this case path->status will contain the same status that would be urned by cairo-status. the copy of the current path. The caller owns the urned object and should call cairo-path-destroy when finished with it. cairo-copy-path-flat ( <cairo-t>) ( <cairo-path-t >) Gets a flattened copy of the current path and urns it to the user as a <cairopath-t>. See <cairo-path-data-t> for hints on how to iterate over the urned data structure. This function is like cairo-copy-path except that any curves in the path will be approximated with piecewise-linear approximations, (accurate to within the current tolerance value). That is, the result is guaranteed to not have any elements of type CAIRO_PATH_CURVE_TO which will instead be replaced by a series of CAIRO_PATH_LINE_TO elements. This function will always urn a valid pointer, but the result will have no data ( data== #f and num_data==0 ), if either of the following conditions hold: 1. If there is insufficient memory to copy the path. In this case path->status will be set to CAIRO_STATUS_NO_MEMORY. 2. If is already in an error state. In this case path->status will contain the same status that would be urned by cairo-status. the copy of the current path. The caller owns the urned object and should call cairo-path-destroy when finished with it.

19 Chapter 2: Paths 16 cairo-append-path ( <cairo-t>) (path <cairo-path-t>) Append the path onto the current path. The path may be either the urn value from one of cairo-copy-path or cairo-copy-path-flat or it may be constructed manually. See <cairo-path-t> for details on how the path data structure should be initialized, and note that path->status must be initialized to CAIRO_STATUS_SUCCESS. path path to be appended See cairo-get- cairo-has-current-point ( <cairo-t>) ( <cairo-bool-t>) Returns whether a current point is defined on the current path. current-point for details on the current point. whether a current point is defined. Since 1.6 cairo-get-current-point ( <cairo-t>) (x <double>) (y <double>) Gets the current point of the current path, which is conceptually the final point reached by the path so far. The current point is urned in the user-space coordinate system. If there is no defined current point or if is in an error status, x and y will both be set to 0.0. It is possible to check this in advance with cairo-has-current-point. Most path construction functions alter the current point. See the following for details on how they affect the current point: cairo-new-path, cairo-new-sub-path, cairo-append-path, cairo-close-path, cairo-move-to, cairo-line-to, cairo-curve-to, cairo-rel-move-to, cairo-rel-line-to, cairo-rel-curve-to, cairo-arc, cairo-arc-negative, cairo-rectangle, cairo-text-path, cairo-glyph-path, cairo-stroke-to-path. Some functions use and alter the current point but do not otherwise change current path: cairo-show-text. Some functions unset the current path and as a result, current point: cairo-fill, cairo-stroke. x y urn value for X coordinate of the current point urn value for Y coordinate of the current point cairo-new-path ( <cairo-t>) Clears the current path. After this call there will be no path and no current point.

20 Chapter 2: Paths 17 cairo-new-sub-path ( <cairo-t>) Begin a new sub-path. Note that the existing path is not affected. After this call there will be no current point. In many cases, this call is not needed since new sub-paths are frequently started with cairo-move-to. A call to cairo-new-sub-path is particularly useful when beginning a new sub-path with one of the cairo-arc calls. This makes things easier as it is no longer necessary to manually compute the arc s initial coordinates for a call to cairo-move-to. Since 1.2 cairo-close-path ( <cairo-t>) Adds a line segment to the path from the current point to the beginning of the current sub-path, (the most recent point passed to cairo-move-to), and closes this sub-path. After this call the current point will be at the joined endpoint of the sub-path. The behavior of cairo-close-path is distinct from simply calling cairo-line-to with the equivalent coordinate in the case of stroking. When a closed sub-path is stroked, there are no caps on the ends of the sub-path. Instead, there is a line join connecting the final and initial segments of the sub-path. If there is no current point before the call to cairo-close-path, this function will have no effect. Note: As of cairo version any call to cairo-close-path will place an explicit MOVE TO element into the path immediately after the CLOSE PATH element, (which can be seen in cairo-copy-path for example). This can simplify path processing in some cases as it may not be necessary to save the "last move to point" during processing as the MOVE TO immediately after the CLOSE PATH will provide that point. cairo-arc ( <cairo-t>) (xc <double>) (yc <double>) (radius <double>) (angle1 <double>) (angle2 <double>) Adds a circular arc of the given radius to the current path. The arc is centered at (xc, yc), begins at angle1 and proceeds in the direction of ineasing angles to end at angle2. If angle2 is less than angle1 it will be progressively ineased by 2*M PI until it is greater than angle1. If there is a current point, an initial line segment will be added to the path to connect the current point to the beginning of the arc. If this initial line is undesired, it can be avoided by calling cairo-new-sub-path before calling cairo-arc. Angles are measured in radians. An angle of 0.0 is in the direction of the positive X axis (in user space). An angle of M_PI /2.0 radians (90 degrees) is in the direction of the positive Y axis (in user space). Angles inease in the direction from the positive X axis toward the positive Y axis. So with the default transformation matrix, angles inease in a clockwise direction. (To convert from degrees to radians, use degrees * (M_PI / 180.).)

21 Chapter 2: Paths 18 This function gives the arc in the direction of ineasing angles; see cairo-arcnegative to get the arc in the direction of deeasing angles. The arc is circular in user space. To achieve an elliptical arc, you can scale the current transformation matrix by different amounts in the X and Y directions. For example, to draw an ellipse in the box given by x, y, width, height: xc yc radius angle1 angle2 cairo_save (); cairo_translate (, x + width / 2., y + height / 2.); cairo_scale (, width / 2., height / 2.); cairo_arc (, 0., 0., 1., 0., 2 * M_PI); cairo_restore (); X position of the center of the arc Y position of the center of the arc the radius of the arc the start angle, in radians the end angle, in radians cairo-arc-negative ( <cairo-t>) (xc <double>) (yc <double>) (radius <double>) (angle1 <double>) (angle2 <double>) Adds a circular arc of the given radius to the current path. The arc is centered at (xc, yc), begins at angle1 and proceeds in the direction of deeasing angles to end at angle2. If angle2 is greater than angle1 it will be progressively deeased by 2*M PI until it is less than angle1. See cairo-arc for more details. This function differs only in the direction of the arc between the two angles. xc yc radius angle1 angle2 X position of the center of the arc Y position of the center of the arc the radius of the arc the start angle, in radians the end angle, in radians cairo-curve-to ( <cairo-t>) (x1 <double>) (y1 <double>) (x2 <double>) (y2 <double>) (x3 <double>) (y3 <double>) Adds a cubic Bzier spline to the path from the current point to position (x3, y3) in user-space coordinates, using (x1, y1) and (x2, y2) as the control points. After this call the current point will be (x3, y3). If there is no current point before the call to cairo-curve-to this function will behave as if preceded by a call to cairo move to(, x1, y1).

22 Chapter 2: Paths 19 x1 y1 x2 y2 x3 y3 the X coordinate of the first control point the Y coordinate of the first control point the X coordinate of the second control point the Y coordinate of the second control point the X coordinate of the end of the curve the Y coordinate of the end of the curve cairo-line-to ( <cairo-t>) (x <double>) (y <double>) Adds a line to the path from the current point to position (x, y) in user-space coordinates. After this call the current point will be (x, y). If there is no current point before the call to cairo-line-to this function will behave as cairo move to(, x, y). x y the X coordinate of the end of the new line the Y coordinate of the end of the new line cairo-move-to ( <cairo-t>) (x <double>) (y <double>) Begin a new sub-path. After this call the current point will be (x, y). x y the X coordinate of the new position the Y coordinate of the new position cairo-rectangle ( <cairo-t>) (x <double>) (y <double>) (width <double>) (height <double>) Adds a closed sub-path rectangle of the given size to the current path at position (x, y) in user-space coordinates. This function is logically equivalent to: cairo_move_to (, x, y); cairo_rel_line_to (, width, 0); cairo_rel_line_to (, 0, height); cairo_rel_line_to (, -width, 0); cairo_close_path (); x y width height the X coordinate of the top left corner of the rectangle the Y coordinate to the top left corner of the rectangle the width of the rectangle the height of the rectangle

23 Chapter 2: Paths 20 cairo-glyph-path ( <cairo-t>) (glyphs <cairo-glyph-t>) (num-glyphs <int>) Adds closed paths for the glyphs to the current path. The generated path if filled, achieves an effect similar to that of cairo-show-glyphs. glyphs array of glyphs to show num-glyphs number of glyphs to show cairo-text-path ( <cairo-t>) (utf8 <char>) Adds closed paths for text to the current path. The generated path if filled, achieves an effect similar to that of cairo-show-text. Text conversion and positioning is done similar to cairo-show-text. Like cairo-show-text, After this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for chaining multiple calls to to cairo-text-path without having to set current point in between. Note: The cairo-text-path function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See cairo-glyph-path for the "real" text path API in cairo. utf8 a NUL-terminated string of text encoded in UTF-8, or #f cairo-rel-curve-to ( <cairo-t>) (dx1 <double>) (dy1 <double>) (dx2 <double>) (dy2 <double>) (dx3 <double>) (dy3 <double>) Relative-coordinate version of cairo-curve-to. All offsets are relative to the current point. Adds a cubic Bzier spline to the path from the current point to a point offset from the current point by (dx3, dy3), using points offset by (dx1, dy1) and (dx2, dy2) as the control points. After this call the current point will be offset by (dx3, dy3). Given a current point of (x, y), cairo rel curve to(, dx1, dy1, dx2, dy2, dx3, dy3) is logically equivalent to cairo curve to(, x+dx1, y+dy1, x+dx2, y+dy2, x+dx3, y+dy3). It is an error to call this function with no current point. Doing so will cause to shutdown with a status of CAIRO_STATUS_NO_CURRENT_POINT. dx1 dy1 dx2 the X offset to the first control point the Y offset to the first control point the X offset to the second control point

24 Chapter 2: Paths 21 dy2 dx3 dy3 the Y offset to the second control point the X offset to the end of the curve the Y offset to the end of the curve cairo-rel-line-to ( <cairo-t>) (dx <double>) (dy <double>) Relative-coordinate version of cairo-line-to. Adds a line to the path from the current point to a point that is offset from the current point by (dx, dy) in user space. After this call the current point will be offset by (dx, dy). Given a current point of (x, y), cairo rel line to(, dx, dy) is logically equivalent to cairo line to(, x + dx, y + dy). It is an error to call this function with no current point. Doing so will cause to shutdown with a status of CAIRO_STATUS_NO_CURRENT_POINT. dx dy the X offset to the end of the new line the Y offset to the end of the new line cairo-rel-move-to ( <cairo-t>) (dx <double>) (dy <double>) Begin a new sub-path. After this call the current point will offset by (x, y). Given a current point of (x, y), cairo rel move to(, dx, dy) is logically equivalent to cairo move to(, x + dx, y + dy). It is an error to call this function with no current point. Doing so will cause to shutdown with a status of CAIRO_STATUS_NO_CURRENT_POINT. dx dy the X offset the Y offset cairo-path-extents ( <cairo-t>) (x1 <double>) (y1 <double>) (x2 <double>) (y2 <double>) Computes a bounding box in user-space coordinates covering the points on the current path. If the current path is empty, urns an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule, surface dimensions and clipping are not taken into account. Contrast with cairo-fill-extents and cairo-stroke-extents which urn the extents of only the area that would be "inked" by the corresponding drawing operations. The result of cairo-path-extents is defined as equivalent to the limit of cairostroke-extents with CAIRO_LINE_CAP_ROUND as the line width approaches 0.0, (but never reaching the empty-rectangle urned by cairo-stroke-extents for a line width of 0.0). Specifically, this means that zero-area sub-paths such as cairo-move-to;cairo-lineto segments, (even degenerate cases where the coordinates to both calls are identical), will be considered as contributing to the extents. However, a lone cairo-move-to will not contribute to the results of cairo-path-extents.

25 Chapter 2: Paths 22 x1 y1 x2 y2 Since 1.6 left of the resulting extents top of the resulting extents right of the resulting extents bottom of the resulting extents

26 Chapter 3: Patterns 23 3 Patterns Sources for drawing 3.1 Overview <cairo-pattern> is the paint with which cairo draws. The primary use of patterns is as the source for all cairo drawing operations, although they can also be used as masks, that is, as the brush too. A cairo pattern is eated by using one of the many constructors, of the form cairo pattern eate type() or implicitly through cairo set source type() functions. 3.2 Usage cairo-pattern-add-color-stop-rgb (pattern <cairo-pattern-t>) (offset <double>) (red <double>) (green <double>) (blue <double>) Adds an opaque color stop to a gradient pattern. The offset specifies the location along the gradient s control vector. For example, a linear gradient s control vector is from (x0,y0) to (x1,y1) while a radial gradient s control vector is from any point on the start circle to the corresponding point on the end circle. The color is specified in the same way as in cairo-set-source-rgb. If two (or more) stops are specified with identical offset values, they will be sorted according to the order in which the stops are added, (stops added earlier will compare less than stops added later). This can be useful for reliably making sharp color transitions instead of the typical blend. Note: If the pattern is not a gradient pattern, (eg. a linear or radial pattern), then the pattern will be put into an error status with a status of CAIRO_STATUS_PATTERN_TYPE_MISMATCH. pattern a <cairo-pattern-t> offset an offset in the range [ ] red green blue red component of color green component of color blue component of color cairo-pattern-add-color-stop-rgba (pattern <cairo-pattern-t>) (offset <double>) (red <double>) (green <double>) (blue <double>) (alpha <double>) Adds a translucent color stop to a gradient pattern. The offset specifies the location along the gradient s control vector. For example, a linear gradient s control vector is from (x0,y0) to (x1,y1) while a radial gradient s control vector is from any point on the start circle to the corresponding point on the end circle. The color is specified in the same way as in cairo-set-source-rgba.

27 Chapter 3: Patterns 24 If two (or more) stops are specified with identical offset values, they will be sorted according to the order in which the stops are added, (stops added earlier will compare less than stops added later). This can be useful for reliably making sharp color transitions instead of the typical blend. Note: If the pattern is not a gradient pattern, (eg. a linear or radial pattern), then the pattern will be put into an error status with a status of CAIRO_STATUS_PATTERN_TYPE_MISMATCH. pattern a <cairo-pattern-t> offset an offset in the range [ ] red green blue alpha red component of color green component of color blue component of color alpha component of color cairo-pattern-get-color-stop-rgba (pattern <cairo-pattern-t>) (index <int>) ( <cairo-status-t>) (offset <double>) (red <double>) (green <double>) (blue <double>) (alpha <double>) Gets the color and offset information at the given index for a gradient pattern. Values of index are 0 to 1 less than the number urned by cairo-pattern-get-colorstop-count. pattern index offset red green blue alpha Since 1.4 a <cairo-pattern-t> index of the stop to urn data for urn value for the offset of the stop, or #f urn value for red component of color, or #f urn value for green component of color, or #f urn value for blue component of color, or #f urn value for alpha component of color, or #f CAIRO_STATUS_SUCCESS, or CAIRO_STATUS_INVALID_INDEX if index is not valid for the given pattern. If the pattern is not a gradient pattern, CAIRO_STATUS_PATTERN_TYPE_MISMATCH is urned. cairo-pattern-eate-rgb (red <double>) (green <double>) (blue <double>) ( <cairo-pattern-t >) Creates a new <cairo-pattern-t> corresponding to an opaque color. The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped. red green red component of the color green component of the color

28 Chapter 3: Patterns 25 blue blue component of the color the newly eated <cairo-pattern-t> if successful, or an error pattern in case of no memory. The caller owns the urned object and should call cairo-pattern-destroy when finished with it. This function will always urn a valid pointer, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use cairopattern-status. cairo-pattern-eate-rgba (red <double>) (green <double>) (blue <double>) (alpha <double>) ( <cairo-pattern-t >) Creates a new <cairo-pattern-t> corresponding to a translucent color. The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped. red green blue alpha red component of the color green component of the color blue component of the color alpha component of the color the newly eated <cairo-pattern-t> if successful, or an error pattern in case of no memory. The caller owns the urned object and should call cairo-pattern-destroy when finished with it. This function will always urn a valid pointer, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use cairopattern-status. cairo-pattern-get-rgba (pattern <cairo-pattern-t>) ( <cairo-status-t>) (red <double>) (green <double>) (blue <double>) (alpha <double>) Gets the solid color for a solid color pattern. pattern red green blue alpha Since 1.4 a <cairo-pattern-t> urn value for red component of color, or #f urn value for green component of color, or #f urn value for blue component of color, or #f urn value for alpha component of color, or #f CAIRO_STATUS_SUCCESS, or CAIRO_STATUS_PATTERN_TYPE_MISMATCH if the pattern is not a solid color pattern. cairo-pattern-eate-for-surface (surface <cairo-surface-t>) ( <cairo-pattern-t >) Create a new <cairo-pattern-t> for the given surface. surface the surface

29 Chapter 3: Patterns 26 the newly eated <cairo-pattern-t> if successful, or an error pattern in case of no memory. The caller owns the urned object and should call cairo-pattern-destroy when finished with it. This function will always urn a valid pointer, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use cairopattern-status. cairo-pattern-get-surface (pattern <cairo-pattern-t>) ( <cairo-status-t>) (surface <cairo-surface-t*>) Gets the surface of a surface pattern. The reference urned in surface is owned by the pattern; the caller should call cairo-surface-reference if the surface is to be ained. pattern surface Since 1.4 a <cairo-pattern-t> urn value for surface of pattern, or #f CAIRO_STATUS_SUCCESS, or CAIRO_STATUS_PATTERN_TYPE_MISMATCH if the pattern is not a surface pattern. cairo-pattern-eate-linear (x0 <double>) (y0 <double>) (x1 <double>) (y1 <double>) ( <cairo-pattern-t >) Create a new linear gradient <cairo-pattern-t> along the line defined by (x0, y0) and (x1, y1). Before using the gradient pattern, a number of color stops should be defined using cairo-pattern-add-color-stop-rgb or cairo-pattern-add-colorstop-rgba. Note: The coordinates here are in pattern space. For a new pattern, pattern space is identical to user space, but the relationship between the spaces can be changed with cairo-pattern-set-matrix. x0 y0 x1 y1 x coordinate of the start point y coordinate of the start point x coordinate of the end point y coordinate of the end point the newly eated <cairo-pattern-t> if successful, or an error pattern in case of no memory. The caller owns the urned object and should call cairo-pattern-destroy when finished with it. This function will always urn a valid pointer, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use cairopattern-status. cairo-pattern-get-linear-points (pattern <cairo-pattern-t>) ( <cairo-status-t>) (x0 <double>) (y0 <double>) (x1 <double>) (y1 <double>) Gets the gradient endpoints for a linear gradient. pattern a <cairo-pattern-t>