cairo_pattern_t: Cairo: A Vector Graphics Library

- - -

cairo_pattern_t

cairo_pattern_t — Sources for drawing

Functions

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-void -	-cairo_pattern_add_color_stop_rgb () -
-void -	-cairo_pattern_add_color_stop_rgba () -
-cairo_status_t -	-cairo_pattern_get_color_stop_count () -
-cairo_status_t -	-cairo_pattern_get_color_stop_rgba () -
-cairo_pattern_t * -	-cairo_pattern_create_rgb () -
-cairo_pattern_t * -	-cairo_pattern_create_rgba () -
-cairo_status_t -	-cairo_pattern_get_rgba () -
-cairo_pattern_t * -	-cairo_pattern_create_for_surface () -
-cairo_status_t -	-cairo_pattern_get_surface () -
-cairo_pattern_t * -	-cairo_pattern_create_linear () -
-cairo_status_t -	-cairo_pattern_get_linear_points () -
-cairo_pattern_t * -	-cairo_pattern_create_radial () -
-cairo_status_t -	-cairo_pattern_get_radial_circles () -
-cairo_pattern_t * -	-cairo_pattern_create_mesh () -
-void -	-cairo_mesh_pattern_begin_patch () -
-void -	-cairo_mesh_pattern_end_patch () -
-void -	-cairo_mesh_pattern_move_to () -
-void -	-cairo_mesh_pattern_line_to () -
-void -	-cairo_mesh_pattern_curve_to () -
-void -	-cairo_mesh_pattern_set_control_point () -
-void -	-cairo_mesh_pattern_set_corner_color_rgb () -
-void -	-cairo_mesh_pattern_set_corner_color_rgba () -
-cairo_status_t -	-cairo_mesh_pattern_get_patch_count () -
-cairo_path_t * -	-cairo_mesh_pattern_get_path () -
-cairo_status_t -	-cairo_mesh_pattern_get_control_point () -
-cairo_status_t -	-cairo_mesh_pattern_get_corner_color_rgba () -
-cairo_pattern_t * -	-cairo_pattern_reference () -
-void -	-cairo_pattern_destroy () -
-cairo_status_t -	-cairo_pattern_status () -
-void -	-cairo_pattern_set_extend () -
-cairo_extend_t -	-cairo_pattern_get_extend () -
-void -	-cairo_pattern_set_filter () -
-cairo_filter_t -	-cairo_pattern_get_filter () -
-void -	-cairo_pattern_set_matrix () -
-void -	-cairo_pattern_get_matrix () -
-cairo_pattern_type_t -	-cairo_pattern_get_type () -
unsigned int -	-cairo_pattern_get_reference_count () -
-cairo_status_t -	-cairo_pattern_set_user_data () -
-void * -	-cairo_pattern_get_user_data () -

Types and Values

---- - - - - - - - - - - - - - - - - - - -

typedef	cairo_pattern_t
enum	cairo_extend_t
enum	cairo_filter_t
enum	cairo_pattern_type_t

Description

cairo_pattern_t 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.

Functions

cairo_pattern_add_color_stop_rgb ()

void
-cairo_pattern_add_color_stop_rgb (cairo_pattern_t *pattern,
-                                  double offset,
-                                  double red,
-                                  double green,
-                                  double blue);

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.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

Since: 1.0

cairo_pattern_add_color_stop_rgba ()

void
-cairo_pattern_add_color_stop_rgba (cairo_pattern_t *pattern,
-                                   double offset,
-                                   double red,
-                                   double green,
-                                   double blue,
-                                   double alpha);

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().

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.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

Since: 1.0

cairo_pattern_get_color_stop_count ()

cairo_status_t
-cairo_pattern_get_color_stop_count (cairo_pattern_t *pattern,
-                                    int *count);

Gets the number of color stops specified in the given gradient -pattern.

Parameters

----- - - - - - - - - - - - - -

pattern	a cairo_pattern_t
count	return value for the number of color stops, or `NULL`

Returns

CAIRO_STATUS_SUCCESS, or -CAIRO_STATUS_PATTERN_TYPE_MISMATCH if pattern -is not a gradient -pattern.

Since: 1.4

cairo_pattern_get_color_stop_rgba ()

cairo_status_t
-cairo_pattern_get_color_stop_rgba (cairo_pattern_t *pattern,
-                                   int index,
-                                   double *offset,
-                                   double *red,
-                                   double *green,
-                                   double *blue,
-                                   double *alpha);

Gets the color and offset information at the given index - for a -gradient pattern. Values of index - range from 0 to n-1 -where n is the number returned -by cairo_pattern_get_color_stop_count().

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
index	index of the stop to return data for
offset	return value for the offset of the stop, or `NULL`
red	return value for red component of color, or `NULL`
green	return value for green component of color, or `NULL`
blue	return value for blue component of color, or `NULL`
alpha	return value for alpha component of color, or `NULL`

Returns

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

cairo_pattern_create_rgb ()

cairo_pattern_t *
-cairo_pattern_create_rgb (double red,
-                          double green,
-                          double blue);

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.

Parameters

----- - - - - - - - - - - - - - - - - - -

red	red component of the color
green	green component of the color
blue	blue component of the color

Returns

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().

Since: 1.0

cairo_pattern_create_rgba ()

cairo_pattern_t *
-cairo_pattern_create_rgba (double red,
-                           double green,
-                           double blue,
-                           double alpha);

Creates a new cairo_pattern_t corresponding to a translucent color. -The color components are floating point numbers in the range 0 to

If the values passed in are outside that range, they will be -clamped.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

red	red component of the color
green	green component of the color
blue	blue component of the color
alpha	alpha component of the color

Returns

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().

Since: 1.0

cairo_pattern_get_rgba ()

cairo_status_t
-cairo_pattern_get_rgba (cairo_pattern_t *pattern,
-                        double *red,
-                        double *green,
-                        double *blue,
-                        double *alpha);

Gets the solid color for a solid color pattern.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
red	return value for red component of color, or `NULL`
green	return value for green component of color, or `NULL`
blue	return value for blue component of color, or `NULL`
alpha	return value for alpha component of color, or `NULL`

Returns

CAIRO_STATUS_SUCCESS, or -CAIRO_STATUS_PATTERN_TYPE_MISMATCH if the pattern is not a solid -color pattern.

Since: 1.4

cairo_pattern_create_for_surface ()

cairo_pattern_t *
-cairo_pattern_create_for_surface (cairo_surface_t *surface);

Create a new cairo_pattern_t for the given surface.

Parameters

----- - - - - - -

surface

the surface

Returns

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().

Since: 1.0

cairo_pattern_get_surface ()

cairo_status_t
-cairo_pattern_get_surface (cairo_pattern_t *pattern,
-                           cairo_surface_t **surface);

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.

Parameters

----- - - - - - - - - - - - - -

pattern	a cairo_pattern_t
surface	return value for surface of pattern, or `NULL`

Returns

CAIRO_STATUS_SUCCESS, or -CAIRO_STATUS_PATTERN_TYPE_MISMATCH if the pattern is not a surface -pattern.

Since: 1.4

cairo_pattern_create_linear ()

cairo_pattern_t *
-cairo_pattern_create_linear (double x0,
-                             double y0,
-                             double x1,
-                             double y1);

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().

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

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

Returns

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().

Since: 1.0

cairo_pattern_get_linear_points ()

cairo_status_t
-cairo_pattern_get_linear_points (cairo_pattern_t *pattern,
-                                 double *x0,
-                                 double *y0,
-                                 double *x1,
-                                 double *y1);

Gets the gradient endpoints for a linear gradient.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
x0	return value for the x coordinate of the first point, or `NULL`
y0	return value for the y coordinate of the first point, or `NULL`
x1	return value for the x coordinate of the second point, or `NULL`
y1	return value for the y coordinate of the second point, or `NULL`

Returns

CAIRO_STATUS_SUCCESS, or -CAIRO_STATUS_PATTERN_TYPE_MISMATCH if pattern -is not a linear -gradient pattern.

Since: 1.4

cairo_pattern_create_radial ()

cairo_pattern_t *
-cairo_pattern_create_radial (double cx0,
-                             double cy0,
-                             double radius0,
-                             double cx1,
-                             double cy1,
-                             double radius1);

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().

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

Returns

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().

Since: 1.0

cairo_pattern_get_radial_circles ()

cairo_status_t
-cairo_pattern_get_radial_circles (cairo_pattern_t *pattern,
-                                  double *x0,
-                                  double *y0,
-                                  double *r0,
-                                  double *x1,
-                                  double *y1,
-                                  double *r1);

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

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
x0	return value for the x coordinate of the center of the first circle, or `NULL`
y0	return value for the y coordinate of the center of the first circle, or `NULL`
r0	return value for the radius of the first circle, or `NULL`
x1	return value for the x coordinate of the center of the second circle, or `NULL`
y1	return value for the y coordinate of the center of the second circle, or `NULL`
r1	return value for the radius of the second circle, or `NULL`

Returns

CAIRO_STATUS_SUCCESS, or -CAIRO_STATUS_PATTERN_TYPE_MISMATCH if pattern -is not a radial -gradient pattern.

Since: 1.4

cairo_pattern_create_mesh ()

cairo_pattern_t *
-cairo_pattern_create_mesh (void);

Create a new mesh pattern.

Mesh patterns are tensor-product patch meshes (type 7 shadings in -PDF). Mesh patterns may also be used to create other types of -shadings that are special cases of tensor-product patch meshes such -as Coons patch meshes (type 6 shading in PDF) and Gouraud-shaded -triangle meshes (type 4 and 5 shadings in PDF).

Mesh patterns consist of one or more tensor-product patches, which -should be defined before using the mesh pattern. Using a mesh -pattern with a partially defined patch as source or mask will put -the context in an error status with a status of -CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.

A tensor-product patch is defined by 4 Bézier curves (side 0, 1, 2, -3) and by 4 additional control points (P0, P1, P2, P3) that provide -further control over the patch and complete the definition of the -tensor-product patch. The corner C0 is the first point of the -patch.

Degenerate sides are permitted so straight lines may be used. A -zero length line on one side may be used to create 3 sided patches.

-      C1     Side 1       C2
-       +---------------+
-       |               |
-       |  P1       P2  |
-       |               |
-Side 0 |               | Side 2
-       |               |
-       |               |
-       |  P0       P3  |
-       |               |
-       +---------------+
-     C0     Side 3        C3
-

Each patch is constructed by first calling -cairo_mesh_pattern_begin_patch(), then cairo_mesh_pattern_move_to() -to specify the first point in the patch (C0). Then the sides are -specified with calls to cairo_mesh_pattern_curve_to() and -cairo_mesh_pattern_line_to().

The four additional control points (P0, P1, P2, P3) in a patch can -be specified with cairo_mesh_pattern_set_control_point().

At each corner of the patch (C0, C1, C2, C3) a color may be -specified with cairo_mesh_pattern_set_corner_color_rgb() or -cairo_mesh_pattern_set_corner_color_rgba(). Any corner whose color -is not explicitly specified defaults to transparent black.

A Coons patch is a special case of the tensor-product patch where -the control points are implicitly defined by the sides of the -patch. The default value for any control point not specified is the -implicit value for a Coons patch, i.e. if no control points are -specified the patch is a Coons patch.

A triangle is a special case of the tensor-product patch where the -control points are implicitly defined by the sides of the patch, -all the sides are lines and one of them has length 0, i.e. if the -patch is specified using just 3 lines, it is a triangle. If the -corners connected by the 0-length side have the same color, the -patch is a Gouraud-shaded triangle.

Patches may be oriented differently to the above diagram. For -example the first point could be at the top left. The diagram only -shows the relationship between the sides, corners and control -points. Regardless of where the first point is located, when -specifying colors, corner 0 will always be the first point, corner -1 the point between side 0 and side 1 etc.

Calling cairo_mesh_pattern_end_patch() completes the current -patch. If less than 4 sides have been defined, the first missing -side is defined as a line from the current point to the first point -of the patch (C0) and the other sides are degenerate lines from C0 -to C0. The corners between the added sides will all be coincident -with C0 of the patch and their color will be set to be the same as -the color of C0.

Additional patches may be added with additional calls to -cairo_mesh_pattern_begin_patch()/cairo_mesh_pattern_end_patch().

- - - - - - - -

1
-2
-3
-4
-5
-6
-7
-8
-9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24

cairo_pattern_t *pattern = cairo_pattern_create_mesh ();
-
-/* Add a Coons patch */
-cairo_mesh_pattern_begin_patch (pattern);
-cairo_mesh_pattern_move_to (pattern, 0, 0);
-cairo_mesh_pattern_curve_to (pattern, 30, -30,  60,  30, 100, 0);
-cairo_mesh_pattern_curve_to (pattern, 60,  30, 130,  60, 100, 100);
-cairo_mesh_pattern_curve_to (pattern, 60,  70,  30, 130,   0, 100);
-cairo_mesh_pattern_curve_to (pattern, 30,  70, -30,  30,   0, 0);
-cairo_mesh_pattern_set_corner_color_rgb (pattern, 0, 1, 0, 0);
-cairo_mesh_pattern_set_corner_color_rgb (pattern, 1, 0, 1, 0);
-cairo_mesh_pattern_set_corner_color_rgb (pattern, 2, 0, 0, 1);
-cairo_mesh_pattern_set_corner_color_rgb (pattern, 3, 1, 1, 0);
-cairo_mesh_pattern_end_patch (pattern);
-
-/* Add a Gouraud-shaded triangle */
-cairo_mesh_pattern_begin_patch (pattern)
-cairo_mesh_pattern_move_to (pattern, 100, 100);
-cairo_mesh_pattern_line_to (pattern, 130, 130);
-cairo_mesh_pattern_line_to (pattern, 130,  70);
-cairo_mesh_pattern_set_corner_color_rgb (pattern, 0, 1, 0, 0);
-cairo_mesh_pattern_set_corner_color_rgb (pattern, 1, 0, 1, 0);
-cairo_mesh_pattern_set_corner_color_rgb (pattern, 2, 0, 0, 1);
-cairo_mesh_pattern_end_patch (pattern)

- -

When two patches overlap, the last one that has been added is drawn -over the first one.

When a patch folds over itself, points are sorted depending on -their parameter coordinates inside the patch. The v coordinate -ranges from 0 to 1 when moving from side 3 to side 1; the u -coordinate ranges from 0 to 1 when going from side 0 to side

Points with higher v coordinate hide points with lower v -coordinate. When two points have the same v coordinate, the one -with higher u coordinate is above. This means that points nearer to -side 1 are above points nearer to side 3; when this is not -sufficient to decide which point is above (for example when both -points belong to side 1 or side 3) points nearer to side 2 are -above points nearer to side 0.

For a complete definition of tensor-product patches, see the PDF -specification (ISO32000), which describes the parametrization in -detail.

Note: The coordinates are always 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().

Returns

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().

Since: 1.12

cairo_mesh_pattern_begin_patch ()

void
-cairo_mesh_pattern_begin_patch (cairo_pattern_t *pattern);

Begin a patch in a mesh pattern.

After calling this function, the patch shape should be defined with -cairo_mesh_pattern_move_to(), cairo_mesh_pattern_line_to() and -cairo_mesh_pattern_curve_to().

After defining the patch, cairo_mesh_pattern_end_patch() must be -called before using pattern - as a source or mask.

Note: If pattern - is not a mesh pattern then pattern - will be put -into an error status with a status of -CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If pattern - already has a -current patch, it will be put into an error status with a status of -CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.

Parameters

----- - - - - - -

pattern

a cairo_pattern_t

Since: 1.12

cairo_mesh_pattern_end_patch ()

void
-cairo_mesh_pattern_end_patch (cairo_pattern_t *pattern);

Indicates the end of the current patch in a mesh pattern.

If the current patch has less than 4 sides, it is closed with a -straight line from the current point to the first point of the -patch as if cairo_mesh_pattern_line_to() was used.

Note: If pattern - is not a mesh pattern then pattern - will be put -into an error status with a status of -CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If pattern - has no current -patch or the current patch has no current point, pattern - will be -put into an error status with a status of -CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.

Parameters

----- - - - - - -

pattern

a cairo_pattern_t

Since: 1.12

cairo_mesh_pattern_move_to ()

void
-cairo_mesh_pattern_move_to (cairo_pattern_t *pattern,
-                            double x,
-                            double y);

Define the first point of the current patch in a mesh pattern.

After this call the current point will be (x -, y -).

Note: If pattern - is not a mesh pattern then pattern - will be put -into an error status with a status of -CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If pattern - has no current -patch or the current patch already has at least one side, pattern - -will be put into an error status with a status of -CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.

Parameters

----- - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
x	the X coordinate of the new position
y	the Y coordinate of the new position

Since: 1.12

cairo_mesh_pattern_line_to ()

void
-cairo_mesh_pattern_line_to (cairo_pattern_t *pattern,
-                            double x,
-                            double y);

Adds a line to the current patch from the current point to position -(x -, y -) in pattern-space coordinates.

If there is no current point before the call to -cairo_mesh_pattern_line_to() this function will behave as -cairo_mesh_pattern_move_to(pattern -, x -, y -).

After this call the current point will be (x -, y -).

Note: If pattern - is not a mesh pattern then pattern - will be put -into an error status with a status of -CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If pattern - has no current -patch or the current patch already has 4 sides, pattern - will be -put into an error status with a status of -CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.

Parameters

----- - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
x	the X coordinate of the end of the new line
y	the Y coordinate of the end of the new line

Since: 1.12

cairo_mesh_pattern_curve_to ()

void
-cairo_mesh_pattern_curve_to (cairo_pattern_t *pattern,
-                             double x1,
-                             double y1,
-                             double x2,
-                             double y2,
-                             double x3,
-                             double y3);

Adds a cubic Bézier spline to the current patch from the current -point to position (x3 -, y3 -) in pattern-space coordinates, using -(x1 -, y1 -) and (x2 -, y2 -) as the control points.

If the current patch has no current point before the call to -cairo_mesh_pattern_curve_to(), this function will behave as if -preceded by a call to cairo_mesh_pattern_move_to(pattern -, x1 -, -y1 -).

After this call the current point will be (x3 -, y3 -).

Note: If pattern - is not a mesh pattern then pattern - will be put -into an error status with a status of -CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If pattern - has no current -patch or the current patch already has 4 sides, pattern - will be -put into an error status with a status of -CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
x1	the X coordinate of the first control point
y1	the Y coordinate of the first control point
x2	the X coordinate of the second control point
y2	the Y coordinate of the second control point
x3	the X coordinate of the end of the curve
y3	the Y coordinate of the end of the curve

Since: 1.12

cairo_mesh_pattern_set_control_point ()

void
-cairo_mesh_pattern_set_control_point (cairo_pattern_t *pattern,
-                                      unsigned int point_num,
-                                      double x,
-                                      double y);

Set an internal control point of the current patch.

Valid values for point_num - are from 0 to 3 and identify the -control points as explained in cairo_pattern_create_mesh().

Note: If pattern - is not a mesh pattern then pattern - will be put -into an error status with a status of -CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If point_num - is not valid, -pattern - will be put into an error status with a status of -CAIRO_STATUS_INVALID_INDEX. If pattern - has no current patch, -pattern - will be put into an error status with a status of -CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
point_num	the control point to set the position for
x	the X coordinate of the control point
y	the Y coordinate of the control point

Since: 1.12

cairo_mesh_pattern_set_corner_color_rgb ()

void
-cairo_mesh_pattern_set_corner_color_rgb
-                               (cairo_pattern_t *pattern,
-                                unsigned int corner_num,
-                                double red,
-                                double green,
-                                double blue);

Sets the color of a corner of the current patch in a mesh pattern.

The color is specified in the same way as in cairo_set_source_rgb().

Valid values for corner_num - are from 0 to 3 and identify the -corners as explained in cairo_pattern_create_mesh().

Note: If pattern - is not a mesh pattern then pattern - will be put -into an error status with a status of -CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If corner_num - is not valid, -pattern - will be put into an error status with a status of -CAIRO_STATUS_INVALID_INDEX. If pattern - has no current patch, -pattern - will be put into an error status with a status of -CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
corner_num	the corner to set the color for
red	red component of color
green	green component of color
blue	blue component of color

Since: 1.12

cairo_mesh_pattern_set_corner_color_rgba ()

void
-cairo_mesh_pattern_set_corner_color_rgba
-                               (cairo_pattern_t *pattern,
-                                unsigned int corner_num,
-                                double red,
-                                double green,
-                                double blue,
-                                double alpha);

Sets the color of a corner of the current patch in a mesh pattern.

The color is specified in the same way as in cairo_set_source_rgba().

Valid values for corner_num - are from 0 to 3 and identify the -corners as explained in cairo_pattern_create_mesh().

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
corner_num	the corner to set the color for
red	red component of color
green	green component of color
blue	blue component of color
alpha	alpha component of color

Since: 1.12

cairo_mesh_pattern_get_patch_count ()

cairo_status_t
-cairo_mesh_pattern_get_patch_count (cairo_pattern_t *pattern,
-                                    unsigned int *count);

Gets the number of patches specified in the given mesh pattern.

The number only includes patches which have been finished by -calling cairo_mesh_pattern_end_patch(). For example it will be 0 -during the definition of the first patch.

Parameters

----- - - - - - - - - - - - - -

pattern	a cairo_pattern_t
count	return value for the number patches, or `NULL`

Returns

CAIRO_STATUS_SUCCESS, or -CAIRO_STATUS_PATTERN_TYPE_MISMATCH if pattern -is not a mesh -pattern.

Since: 1.12

cairo_mesh_pattern_get_path ()

cairo_path_t *
-cairo_mesh_pattern_get_path (cairo_pattern_t *pattern,
-                             unsigned int patch_num);

Gets path defining the patch patch_num - for a mesh -pattern.

patch_num - can range from 0 to n-1 where n is the number returned by -cairo_mesh_pattern_get_patch_count().

Parameters

----- - - - - - - - - - - - - -

pattern	a cairo_pattern_t
patch_num	the patch number to return data for

Returns

the path defining the patch, or a path with status -CAIRO_STATUS_INVALID_INDEX if patch_num -or point_num -is not -valid for pattern -. If pattern -is not a mesh pattern, a path with -status CAIRO_STATUS_PATTERN_TYPE_MISMATCH is returned.

Since: 1.12

cairo_mesh_pattern_get_control_point ()

cairo_status_t
-cairo_mesh_pattern_get_control_point (cairo_pattern_t *pattern,
-                                      unsigned int patch_num,
-                                      unsigned int point_num,
-                                      double *x,
-                                      double *y);

Gets the control point point_num - of patch patch_num - for a mesh -pattern.

patch_num - can range from 0 to n-1 where n is the number returned by -cairo_mesh_pattern_get_patch_count().

Valid values for point_num - are from 0 to 3 and identify the -control points as explained in cairo_pattern_create_mesh().

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
patch_num	the patch number to return data for
point_num	the control point number to return data for
x	return value for the x coordinate of the control point, or `NULL`
y	return value for the y coordinate of the control point, or `NULL`

Returns

CAIRO_STATUS_SUCCESS, or CAIRO_STATUS_INVALID_INDEX -if patch_num -or point_num -is not valid for pattern -. If pattern -is not a mesh pattern, CAIRO_STATUS_PATTERN_TYPE_MISMATCH is -returned.

Since: 1.12

cairo_mesh_pattern_get_corner_color_rgba ()

cairo_status_t
-cairo_mesh_pattern_get_corner_color_rgba
-                               (cairo_pattern_t *pattern,
-                                unsigned int patch_num,
-                                unsigned int corner_num,
-                                double *red,
-                                double *green,
-                                double *blue,
-                                double *alpha);

Gets the color information in corner corner_num - of patch -patch_num - for a mesh pattern.

patch_num - can range from 0 to n-1 where n is the number returned by -cairo_mesh_pattern_get_patch_count().

Valid values for corner_num - are from 0 to 3 and identify the -corners as explained in cairo_pattern_create_mesh().

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
patch_num	the patch number to return data for
corner_num	the corner number to return data for
red	return value for red component of color, or `NULL`
green	return value for green component of color, or `NULL`
blue	return value for blue component of color, or `NULL`
alpha	return value for alpha component of color, or `NULL`

Returns

CAIRO_STATUS_SUCCESS, or CAIRO_STATUS_INVALID_INDEX -if patch_num -or corner_num -is not valid for pattern -. If -pattern -is not a mesh pattern, CAIRO_STATUS_PATTERN_TYPE_MISMATCH -is returned.

Since: 1.12

cairo_pattern_reference ()

cairo_pattern_t *
-cairo_pattern_reference (cairo_pattern_t *pattern);

Increases the reference count on pattern - by one. This prevents -pattern - from being destroyed until a matching call to -cairo_pattern_destroy() is made.

Use cairo_pattern_get_reference_count() to get the number of -references to a cairo_pattern_t.

Parameters

----- - - - - - -

pattern

a cairo_pattern_t

Returns

the referenced cairo_pattern_t.

Since: 1.0

cairo_pattern_destroy ()

void
-cairo_pattern_destroy (cairo_pattern_t *pattern);

Decreases the reference count on pattern - by one. If the result is -zero, then pattern - and all associated resources are freed. See -cairo_pattern_reference().

Parameters

----- - - - - - -

pattern

a cairo_pattern_t

Since: 1.0

cairo_pattern_status ()

cairo_status_t
-cairo_pattern_status (cairo_pattern_t *pattern);

Checks whether an error has previously occurred for this -pattern.

Parameters

----- - - - - - -

pattern

a cairo_pattern_t

Returns

CAIRO_STATUS_SUCCESS, CAIRO_STATUS_NO_MEMORY, -CAIRO_STATUS_INVALID_MATRIX, CAIRO_STATUS_PATTERN_TYPE_MISMATCH, -or CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.

Since: 1.0

cairo_pattern_set_extend ()

void
-cairo_pattern_set_extend (cairo_pattern_t *pattern,
-                          cairo_extend_t extend);

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.

Parameters

----- - - - - - - - - - - - - -

pattern	a cairo_pattern_t
extend	a cairo_extend_t describing how the area outside of the -pattern will be drawn

Since: 1.0

cairo_pattern_get_extend ()

cairo_extend_t
-cairo_pattern_get_extend (cairo_pattern_t *pattern);

Gets the current extend mode for a pattern. See cairo_extend_t -for details on the semantics of each extend strategy.

Parameters

----- - - - - - -

pattern

a cairo_pattern_t

Returns

the current extend strategy used for drawing the -pattern.

Since: 1.0

cairo_pattern_set_filter ()

void
-cairo_pattern_set_filter (cairo_pattern_t *pattern,
-                          cairo_filter_t filter);

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:

- - - - - - - -

1 -2	cairo_set_source_surface (cr, image, x, y); -cairo_pattern_set_filter (cairo_get_source (cr), CAIRO_FILTER_NEAREST);

- -

Parameters

----- - - - - - - - - - - - - -

pattern	a cairo_pattern_t
filter	a cairo_filter_t describing the filter to use for resizing -the pattern

Since: 1.0

cairo_pattern_get_filter ()

cairo_filter_t
-cairo_pattern_get_filter (cairo_pattern_t *pattern);

Gets the current filter for a pattern. See cairo_filter_t -for details on each filter.

Parameters

----- - - - - - -

pattern

a cairo_pattern_t

Returns

the current filter used for resizing the pattern.

Since: 1.0

cairo_pattern_set_matrix ()

void
-cairo_pattern_set_matrix (cairo_pattern_t *pattern,
-                          const cairo_matrix_t *matrix);

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:

- - - - - - - -

1 -2	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().

Parameters

----- - - - - - - - - - - - - -

pattern	a cairo_pattern_t
matrix	a cairo_matrix_t

Since: 1.0

cairo_pattern_get_matrix ()

void
-cairo_pattern_get_matrix (cairo_pattern_t *pattern,
-                          cairo_matrix_t *matrix);

Stores the pattern's transformation matrix into matrix -.

Parameters

----- - - - - - - - - - - - - -

pattern	a cairo_pattern_t
matrix	return value for the matrix

Since: 1.0

cairo_pattern_get_type ()

cairo_pattern_type_t
-cairo_pattern_get_type (cairo_pattern_t *pattern);

Get the pattern's type. See cairo_pattern_type_t for available -types.

Parameters

----- - - - - - -

pattern

a cairo_pattern_t

Returns

The type of pattern -.

Since: 1.2

cairo_pattern_get_reference_count ()

unsigned int
-cairo_pattern_get_reference_count (cairo_pattern_t *pattern);

Returns the current reference count of pattern -.

Parameters

----- - - - - - -

pattern

a cairo_pattern_t

Returns

the current reference count of pattern -. If the -object is a nil object, 0 will be returned.

Since: 1.4

cairo_pattern_set_user_data ()

cairo_status_t
-cairo_pattern_set_user_data (cairo_pattern_t *pattern,
-                             const cairo_user_data_key_t *key,
-                             void *user_data,
-                             cairo_destroy_func_t destroy);

Attach user data to pattern -. To remove user data from a surface, -call this function with the key that was used to set it and NULL -for data -.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

pattern	a cairo_pattern_t
key	the address of a cairo_user_data_key_t to attach the user data to
user_data	the user data to attach to the cairo_pattern_t
destroy	a cairo_destroy_func_t which will be called when the -cairo_t is destroyed or when new user data is attached using the -same key.

Returns

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a -slot could not be allocated for the user data.

Since: 1.4

cairo_pattern_get_user_data ()

void *
-cairo_pattern_get_user_data (cairo_pattern_t *pattern,
-                             const cairo_user_data_key_t *key);

Return user data previously attached to pattern - using the -specified key. If no user data has been attached with the given -key this function returns NULL.

Parameters

----- - - - - - - - - - - - - -

pattern	a cairo_pattern_t
key	the address of the cairo_user_data_key_t the user data was -attached to

Returns

the user data previously attached or NULL.

Since: 1.4

Types and Values

cairo_pattern_t

typedef struct _cairo_pattern cairo_pattern_t;
-

A cairo_pattern_t represents a source when drawing onto a -surface. There are different subtypes of cairo_pattern_t, -for different types of sources; for example, -cairo_pattern_create_rgb() creates a pattern for a solid -opaque color.

Other than various -cairo_pattern_create_type() -functions, some of the pattern types can be implicitly created using various -cairo_set_source_type() functions; -for example cairo_set_source_rgb().

The type of a pattern can be queried with cairo_pattern_get_type().

Memory management of cairo_pattern_t is done with -cairo_pattern_reference() and cairo_pattern_destroy().

Since: 1.0

enum cairo_extend_t

cairo_extend_t is used to describe how pattern color/alpha will be -determined for areas "outside" the pattern's natural area, (for -example, outside the surface bounds or outside the gradient -geometry).

Mesh patterns are not affected by the extend mode.

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

New entries may be added in future versions.

Members

----- - - - - - - - - - - - - - - - - - - - - - - -

CAIRO_EXTEND_NONE	- pixels outside of the source pattern - are fully transparent (Since 1.0) -
CAIRO_EXTEND_REPEAT	- the pattern is tiled by repeating (Since 1.0) -
CAIRO_EXTEND_REFLECT	- the pattern is tiled by reflecting - at the edges (Since 1.0; but only implemented for surface patterns since 1.6) -
CAIRO_EXTEND_PAD	- pixels outside of the pattern copy - the closest pixel from the source (Since 1.2; but only - implemented for surface patterns since 1.6) -

Since: 1.0

enum cairo_filter_t

cairo_filter_t is used to indicate what filtering should be -applied when reading pixel values from patterns. See -cairo_pattern_set_filter() for indicating the desired filter to be -used with a particular pattern.

Members

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

CAIRO_FILTER_FAST	- A high-performance filter, with quality similar - to `CAIRO_FILTER_NEAREST` (Since 1.0) -
CAIRO_FILTER_GOOD	- A reasonable-performance filter, with quality - similar to `CAIRO_FILTER_BILINEAR` (Since 1.0) -
CAIRO_FILTER_BEST	- The highest-quality available, performance may - not be suitable for interactive use. (Since 1.0) -
CAIRO_FILTER_NEAREST	- Nearest-neighbor filtering (Since 1.0) -
CAIRO_FILTER_BILINEAR	- Linear interpolation in two dimensions (Since 1.0) -
CAIRO_FILTER_GAUSSIAN	- This filter value is currently - unimplemented, and should not be used in current code. (Since 1.0) -

Since: 1.0

enum cairo_pattern_type_t

cairo_pattern_type_t is used to describe the type of a given pattern.

The type of a pattern is determined by the function used to create -it. The cairo_pattern_create_rgb() and cairo_pattern_create_rgba() -functions create SOLID patterns. The remaining -cairo_pattern_create functions map to pattern types in obvious -ways.

The pattern type can be queried with cairo_pattern_get_type()

Most cairo_pattern_t functions can be called with a pattern of any -type, (though trying to change the extend or filter for a solid -pattern will have no effect). A notable exception is -cairo_pattern_add_color_stop_rgb() and -cairo_pattern_add_color_stop_rgba() which must only be called with -gradient patterns (either LINEAR or RADIAL). Otherwise the pattern -will be shutdown and put into an error state.

New entries may be added in future versions.

Members

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

CAIRO_PATTERN_TYPE_SOLID	- The pattern is a solid (uniform) -color. It may be opaque or translucent, since 1.2. -
CAIRO_PATTERN_TYPE_SURFACE	- The pattern is a based on a surface (an image), since 1.2. -
CAIRO_PATTERN_TYPE_LINEAR	- The pattern is a linear gradient, since 1.2. -
CAIRO_PATTERN_TYPE_RADIAL	- The pattern is a radial gradient, since 1.2. -
CAIRO_PATTERN_TYPE_MESH	- The pattern is a mesh, since 1.12. -
CAIRO_PATTERN_TYPE_RASTER_SOURCE	- The pattern is a user pattern providing raster data, since 1.12. -

Since: 1.2