Next: , Previous: Paths, Up: Top


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 created by using one of the many constructors, of the form cairo_pattern_create_type() or implicitly through cairo_set_source_type() functions.

3.2 Usage

— Function: 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 [0.0 .. 1.0]
red
red component of color
green
green component of color
blue
blue component of color
— Function: 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.

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 [0.0 .. 1.0]
red
red component of color
green
green component of color
blue
blue component of color
alpha
alpha component of color
— Function: cairo-pattern-get-color-stop-rgba (pattern <cairo-pattern-t>) (index <int>) ⇒  (ret <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 returned by cairo-pattern-get-color-stop-count.

pattern
a <cairo-pattern-t>
index
index of the stop to return data for
offset
return value for the offset of the stop, or ‘#f
red
return value for red component of color, or ‘#f
green
return value for green component of color, or ‘#f
blue
return value for blue component of color, or ‘#f
alpha
return value for alpha component of color, or ‘#f
ret
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 returned.

Since 1.4

— Function: cairo-pattern-create-rgb (red <double>) (green <double>) (blue <double>) ⇒  (ret <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
red component of the color
green
green component of the color
blue
blue component of the color
ret
the newly created <cairo-pattern-t> if successful, or an error pattern in case of no memory. The caller owns the returned object and should call cairo-pattern-destroy when finished with it. This function will always return 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 cairo-pattern-status.
— Function: cairo-pattern-create-rgba (red <double>) (green <double>) (blue <double>) (alpha <double>) ⇒  (ret <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
red component of the color
green
green component of the color
blue
blue component of the color
alpha
alpha component of the color
ret
the newly created <cairo-pattern-t> if successful, or an error pattern in case of no memory. The caller owns the returned object and should call cairo-pattern-destroy when finished with it. This function will always return 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 cairo-pattern-status.
— Function: cairo-pattern-get-rgba (pattern <cairo-pattern-t>) ⇒  (ret <cairo-status-t>) (red <double>) (green <double>) (blue <double>) (alpha <double>)

Gets the solid color for a solid color pattern.

pattern
a <cairo-pattern-t>
red
return value for red component of color, or ‘#f
green
return value for green component of color, or ‘#f
blue
return value for blue component of color, or ‘#f
alpha
return value for alpha component of color, or ‘#f
ret
CAIRO_STATUS_SUCCESS’, or ‘CAIRO_STATUS_PATTERN_TYPE_MISMATCH’ if the pattern is not a solid color pattern.

Since 1.4

— Function: cairo-pattern-create-for-surface (surface <cairo-surface-t>) ⇒  (ret <cairo-pattern-t >)

Create a new <cairo-pattern-t> for the given surface.

surface
the surface
ret
the newly created <cairo-pattern-t> if successful, or an error pattern in case of no memory. The caller owns the returned object and should call cairo-pattern-destroy when finished with it. This function will always return 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 cairo-pattern-status.
— Function: cairo-pattern-get-surface (pattern <cairo-pattern-t>) ⇒  (ret <cairo-status-t>) (surface <cairo-surface-t*>)

Gets the surface of a surface pattern. The reference returned in surface is owned by the pattern; the caller should call cairo-surface-reference if the surface is to be retained.

pattern
a <cairo-pattern-t>
surface
return value for surface of pattern, or ‘#f
ret
CAIRO_STATUS_SUCCESS’, or ‘CAIRO_STATUS_PATTERN_TYPE_MISMATCH’ if the pattern is not a surface pattern.

Since 1.4

— Function: cairo-pattern-create-linear (x0 <double>) (y0 <double>) (x1 <double>) (y1 <double>) ⇒  (ret <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-color-stop-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
x coordinate of the start point
y0
y coordinate of the start point
x1
x coordinate of the end point
y1
y coordinate of the end point
ret
the newly created <cairo-pattern-t> if successful, or an error pattern in case of no memory. The caller owns the returned object and should call cairo-pattern-destroy when finished with it. This function will always return 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 cairo-pattern-status.
— Function: cairo-pattern-get-linear-points (pattern <cairo-pattern-t>) ⇒  (ret <cairo-status-t>) (x0 <double>) (y0 <double>) (x1 <double>) (y1 <double>)

Gets the gradient endpoints for a linear gradient.

pattern
a <cairo-pattern-t>
x0
return value for the x coordinate of the first point, or ‘#f
y0
return value for the y coordinate of the first point, or ‘#f
x1
return value for the x coordinate of the second point, or ‘#f
y1
return value for the y coordinate of the second point, or ‘#f
ret
CAIRO_STATUS_SUCCESS’, or ‘CAIRO_STATUS_PATTERN_TYPE_MISMATCH’ if pattern is not a linear gradient pattern.

Since 1.4

— Function: cairo-pattern-create-radial (cx0 <double>) (cy0 <double>) (radius0 <double>) (cx1 <double>) (cy1 <double>) (radius1 <double>) ⇒  (ret <cairo-pattern-t >)

Creates a new radial gradient <cairo-pattern-t> between the two circles defined by (cx0, cy0, radius0) and (cx1, cy1, radius1). Before using the gradient pattern, a number of color stops should be defined using cairo-pattern-add-color-stop-rgb or cairo-pattern-add-color-stop-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.

cx0
x coordinate for the center of the start circle
cy0
y coordinate for the center of the start circle
radius0
radius of the start circle
cx1
x coordinate for the center of the end circle
cy1
y coordinate for the center of the end circle
radius1
radius of the end circle
ret
the newly created <cairo-pattern-t> if successful, or an error pattern in case of no memory. The caller owns the returned object and should call cairo-pattern-destroy when finished with it. This function will always return 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 cairo-pattern-status.
— Function: cairo-pattern-get-radial-circles (pattern <cairo-pattern-t>) ⇒  (ret <cairo-status-t>) (x0 <double>) (y0 <double>) (r0 <double>) (x1 <double>) (y1 <double>) (r1 <double>)

Gets the gradient endpoint circles for a radial gradient, each specified as a center coordinate and a radius.

pattern
a <cairo-pattern-t>
x0
return value for the x coordinate of the center of the first circle, or ‘#f
y0
return value for the y coordinate of the center of the first circle, or ‘#f
r0
return value for the radius of the first circle, or ‘#f
x1
return value for the x coordinate of the center of the second circle, or ‘#f
y1
return value for the y coordinate of the center of the second circle, or ‘#f
r1
return value for the radius of the second circle, or ‘#f
ret
CAIRO_STATUS_SUCCESS’, or ‘CAIRO_STATUS_PATTERN_TYPE_MISMATCH’ if pattern is not a radial gradient pattern.

Since 1.4

— Function: cairo-pattern-set-extend (pattern <cairo-pattern-t>) (extend <cairo-extend-t>)

Sets the mode to be used for drawing outside the area of a pattern. See <cairo-extend-t> for details on the semantics of each extend strategy.

The default extend mode is ‘CAIRO_EXTEND_NONE’ for surface patterns and ‘CAIRO_EXTEND_PAD’ for gradient patterns.

pattern
a <cairo-pattern-t>
extend
a <cairo-extend-t> describing how the area outside of the pattern will be drawn
— Function: cairo-pattern-get-extend (pattern <cairo-pattern-t>) ⇒  (ret <cairo-extend-t>)

Gets the current extend mode for a pattern. See <cairo-extend-t> for details on the semantics of each extend strategy.

pattern
a <cairo-pattern-t>
ret
the current extend strategy used for drawing the pattern.
— Function: cairo-pattern-set-filter (pattern <cairo-pattern-t>) (filter <cairo-filter-t>)

Sets the filter to be used for resizing when using this pattern. See <cairo-filter-t> for details on each filter.

* Note that you might want to control filtering even when you do not have an explicit <cairo-pattern-t> object, (for example when using cairo-set-source-surface). In these cases, it is convenient to use cairo-get-source to get access to the pattern that cairo creates implicitly. For example:

          
          cairo_set_source_surface (cr, image, x, y);
          cairo_pattern_set_filter (cairo_get_source (cr), CAIRO_FILTER_NEAREST);
pattern
a <cairo-pattern-t>
filter
a <cairo-filter-t> describing the filter to use for resizing the pattern
— Function: cairo-pattern-get-filter (pattern <cairo-pattern-t>) ⇒  (ret <cairo-filter-t>)

Gets the current filter for a pattern. See <cairo-filter-t> for details on each filter.

pattern
a <cairo-pattern-t>
ret
the current filter used for resizing the pattern.
— Function: cairo-pattern-set-matrix (pattern <cairo-pattern-t>) (matrix <cairo-matrix-t>)

Sets the pattern's transformation matrix to matrix. This matrix is a transformation from user space to pattern space.

When a pattern is first created it always has the identity matrix for its transformation matrix, which means that pattern space is initially identical to user space.

Important: Please note that the direction of this transformation matrix is from user space to pattern space. This means that if you imagine the flow from a pattern to user space (and on to device space), then coordinates in that flow will be transformed by the inverse of the pattern matrix.

For example, if you want to make a pattern appear twice as large as it does by default the correct code to use is:

          
          cairo_matrix_init_scale (&matrix, 0.5, 0.5);
          cairo_pattern_set_matrix (pattern, &matrix);

Meanwhile, using values of 2.0 rather than 0.5 in the code above would cause the pattern to appear at half of its default size.

Also, please note the discussion of the user-space locking semantics of cairo-set-source.

pattern
a <cairo-pattern-t>
matrix
a <cairo-matrix-t>
— Function: cairo-pattern-get-matrix (pattern <cairo-pattern-t>) (matrix <cairo-matrix-t>)

Stores the pattern's transformation matrix into matrix.

pattern
a <cairo-pattern-t>
matrix
return value for the matrix
— Function: cairo-pattern-get-type (pattern <cairo-pattern-t>) ⇒  (ret <cairo-pattern-type-t>)

This function returns the type a pattern. See <cairo-pattern-type-t> for available types.

pattern
a <cairo-pattern-t>
ret
The type of pattern.

Since 1.2