| jpayne@68: Top jpayne@68: | jpayne@68: |
jpayne@68: |
jpayne@68: |
jpayne@68: |
jpayne@68:
jpayne@68: cairo_pattern_tjpayne@68:cairo_pattern_t — Sources for drawing jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_add_color_stop_rgb () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_add_color_stop_rgba () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_get_color_stop_count () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_get_color_stop_rgba () jpayne@68: | jpayne@68:
| jpayne@68: cairo_pattern_t * jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_create_rgb () jpayne@68: | jpayne@68:
| jpayne@68: cairo_pattern_t * jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_create_rgba () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_get_rgba () jpayne@68: | jpayne@68:
| jpayne@68: cairo_pattern_t * jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_create_for_surface () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_get_surface () jpayne@68: | jpayne@68:
| jpayne@68: cairo_pattern_t * jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_create_linear () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_get_linear_points () jpayne@68: | jpayne@68:
| jpayne@68: cairo_pattern_t * jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_create_radial () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_get_radial_circles () jpayne@68: | jpayne@68:
| jpayne@68: cairo_pattern_t * jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_create_mesh () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_mesh_pattern_begin_patch () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_mesh_pattern_end_patch () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_mesh_pattern_move_to () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_mesh_pattern_line_to () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_mesh_pattern_curve_to () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_mesh_pattern_set_control_point () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_mesh_pattern_set_corner_color_rgb () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_mesh_pattern_set_corner_color_rgba () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_mesh_pattern_get_patch_count () jpayne@68: | jpayne@68:
| jpayne@68: cairo_path_t * jpayne@68: | jpayne@68:jpayne@68: cairo_mesh_pattern_get_path () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_mesh_pattern_get_control_point () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_mesh_pattern_get_corner_color_rgba () jpayne@68: | jpayne@68:
| jpayne@68: cairo_pattern_t * jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_reference () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_destroy () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_status () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_set_extend () jpayne@68: | jpayne@68:
| jpayne@68: cairo_extend_t jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_get_extend () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_set_filter () jpayne@68: | jpayne@68:
| jpayne@68: cairo_filter_t jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_get_filter () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_set_matrix () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_get_matrix () jpayne@68: | jpayne@68:
| jpayne@68: cairo_pattern_type_t jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_get_type () jpayne@68: | jpayne@68:
| unsigned int jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_get_reference_count () jpayne@68: | jpayne@68:
| jpayne@68: cairo_status_t jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_set_user_data () jpayne@68: | jpayne@68:
| jpayne@68: void * jpayne@68: | jpayne@68:jpayne@68: cairo_pattern_get_user_data () jpayne@68: | jpayne@68:
| typedef | jpayne@68:cairo_pattern_t | jpayne@68:
| enum | jpayne@68:cairo_extend_t | jpayne@68:
| enum | jpayne@68:cairo_filter_t | jpayne@68:
| enum | jpayne@68:cairo_pattern_type_t | jpayne@68:
cairo_pattern_t is the paint with which cairo draws. jpayne@68: The primary use of patterns is as the source for all cairo drawing jpayne@68: operations, although they can also be used as masks, that is, as the jpayne@68: brush too.
jpayne@68:A cairo pattern is created by using one of the many constructors,
jpayne@68: of the form
jpayne@68: cairo_pattern_create_type()
jpayne@68: or implicitly through
jpayne@68: cairo_set_source_type()
jpayne@68: functions.
void jpayne@68: cairo_pattern_add_color_stop_rgb (jpayne@68:cairo_pattern_t *pattern, jpayne@68:double offset, jpayne@68:double red, jpayne@68:double green, jpayne@68:double blue);
Adds an opaque color stop to a gradient pattern. The offset jpayne@68: specifies the location along the gradient's control vector. For jpayne@68: example, a linear gradient's control vector is from (x0,y0) to jpayne@68: (x1,y1) while a radial gradient's control vector is from any point jpayne@68: on the start circle to the corresponding point on the end circle.
jpayne@68: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, jpayne@68: they will be sorted according to the order in which the stops are jpayne@68: added, (stops added earlier will compare less than stops added jpayne@68: later). This can be useful for reliably making sharp color jpayne@68: transitions instead of the typical blend.
jpayne@68:Note: If the pattern is not a gradient pattern, (eg. a linear or
jpayne@68: radial pattern), then the pattern will be put into an error status
jpayne@68: with a status of CAIRO_STATUS_PATTERN_TYPE_MISMATCH.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
offset |
jpayne@68: an offset in the range [0.0 .. 1.0] |
jpayne@68: jpayne@68: |
red |
jpayne@68: red component of color |
jpayne@68: jpayne@68: |
green |
jpayne@68: green component of color |
jpayne@68: jpayne@68: |
blue |
jpayne@68: blue component of color |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_pattern_add_color_stop_rgba (jpayne@68:cairo_pattern_t *pattern, jpayne@68:double offset, jpayne@68:double red, jpayne@68:double green, jpayne@68:double blue, jpayne@68:double alpha);
Adds a translucent color stop to a gradient pattern. The offset jpayne@68: specifies the location along the gradient's control vector. For jpayne@68: example, a linear gradient's control vector is from (x0,y0) to jpayne@68: (x1,y1) while a radial gradient's control vector is from any point jpayne@68: on the start circle to the corresponding point on the end circle.
jpayne@68: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, jpayne@68: they will be sorted according to the order in which the stops are jpayne@68: added, (stops added earlier will compare less than stops added jpayne@68: later). This can be useful for reliably making sharp color jpayne@68: transitions instead of the typical blend.
jpayne@68:Note: If the pattern is not a gradient pattern, (eg. a linear or
jpayne@68: radial pattern), then the pattern will be put into an error status
jpayne@68: with a status of CAIRO_STATUS_PATTERN_TYPE_MISMATCH.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
offset |
jpayne@68: an offset in the range [0.0 .. 1.0] |
jpayne@68: jpayne@68: |
red |
jpayne@68: red component of color |
jpayne@68: jpayne@68: |
green |
jpayne@68: green component of color |
jpayne@68: jpayne@68: |
blue |
jpayne@68: blue component of color |
jpayne@68: jpayne@68: |
alpha |
jpayne@68: alpha component of color |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_status_t jpayne@68: cairo_pattern_get_color_stop_count (jpayne@68:cairo_pattern_t *pattern, jpayne@68:int *count);
Gets the number of color stops specified in the given gradient jpayne@68: pattern.
jpayne@68:pattern |
jpayne@68: jpayne@68: | jpayne@68: |
count |
jpayne@68: return value for the number of color stops, or |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS, or
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH if pattern
jpayne@68: is not a gradient
jpayne@68: pattern.
Since: 1.4
jpayne@68:cairo_status_t jpayne@68: cairo_pattern_get_color_stop_rgba (jpayne@68:cairo_pattern_t *pattern, jpayne@68:int index, jpayne@68:double *offset, jpayne@68:double *red, jpayne@68:double *green, jpayne@68:double *blue, jpayne@68:double *alpha);
Gets the color and offset information at the given index
jpayne@68: for a
jpayne@68: gradient pattern. Values of index
jpayne@68: range from 0 to n-1
jpayne@68: where n is the number returned
jpayne@68: by cairo_pattern_get_color_stop_count().
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
index |
jpayne@68: index of the stop to return data for |
jpayne@68: jpayne@68: |
offset |
jpayne@68: return value for the offset of the stop, or |
jpayne@68: jpayne@68: |
red |
jpayne@68: return value for red component of color, or |
jpayne@68: jpayne@68: |
green |
jpayne@68: return value for green component of color, or |
jpayne@68: jpayne@68: |
blue |
jpayne@68: return value for blue component of color, or |
jpayne@68: jpayne@68: |
alpha |
jpayne@68: return value for alpha component of color, or |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS, or CAIRO_STATUS_INVALID_INDEX
jpayne@68: if index
jpayne@68: is not valid for the given pattern. If the pattern is
jpayne@68: not a gradient pattern, CAIRO_STATUS_PATTERN_TYPE_MISMATCH is
jpayne@68: returned.
Since: 1.4
jpayne@68:cairo_pattern_t * jpayne@68: cairo_pattern_create_rgb (jpayne@68:double red, jpayne@68:double green, jpayne@68:double blue);
Creates a new cairo_pattern_t corresponding to an opaque color. The jpayne@68: color components are floating point numbers in the range 0 to 1. jpayne@68: If the values passed in are outside that range, they will be jpayne@68: clamped.
jpayne@68:red |
jpayne@68: red component of the color |
jpayne@68: jpayne@68: |
green |
jpayne@68: green component of the color |
jpayne@68: jpayne@68: |
blue |
jpayne@68: blue component of the color |
jpayne@68: jpayne@68: |
the newly created cairo_pattern_t if successful, or
jpayne@68: an error pattern in case of no memory. The caller owns the
jpayne@68: returned object and should call cairo_pattern_destroy() when
jpayne@68: finished with it.
This function will always return a valid pointer, but if an error
jpayne@68: occurred the pattern status will be set to an error. To inspect
jpayne@68: the status of a pattern use cairo_pattern_status().
Since: 1.0
jpayne@68:cairo_pattern_t * jpayne@68: cairo_pattern_create_rgba (jpayne@68:double red, jpayne@68:double green, jpayne@68:double blue, jpayne@68:double alpha);
Creates a new cairo_pattern_t corresponding to a translucent color. jpayne@68: The color components are floating point numbers in the range 0 to
jpayne@68:If the values passed in are outside that range, they will be jpayne@68: clamped.
red |
jpayne@68: red component of the color |
jpayne@68: jpayne@68: |
green |
jpayne@68: green component of the color |
jpayne@68: jpayne@68: |
blue |
jpayne@68: blue component of the color |
jpayne@68: jpayne@68: |
alpha |
jpayne@68: alpha component of the color |
jpayne@68: jpayne@68: |
the newly created cairo_pattern_t if successful, or
jpayne@68: an error pattern in case of no memory. The caller owns the
jpayne@68: returned object and should call cairo_pattern_destroy() when
jpayne@68: finished with it.
This function will always return a valid pointer, but if an error
jpayne@68: occurred the pattern status will be set to an error. To inspect
jpayne@68: the status of a pattern use cairo_pattern_status().
Since: 1.0
jpayne@68:cairo_status_t jpayne@68: cairo_pattern_get_rgba (jpayne@68:cairo_pattern_t *pattern, jpayne@68:double *red, jpayne@68:double *green, jpayne@68:double *blue, jpayne@68:double *alpha);
Gets the solid color for a solid color pattern.
jpayne@68:pattern |
jpayne@68: jpayne@68: | jpayne@68: |
red |
jpayne@68: return value for red component of color, or |
jpayne@68: jpayne@68: |
green |
jpayne@68: return value for green component of color, or |
jpayne@68: jpayne@68: |
blue |
jpayne@68: return value for blue component of color, or |
jpayne@68: jpayne@68: |
alpha |
jpayne@68: return value for alpha component of color, or |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS, or
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH if the pattern is not a solid
jpayne@68: color pattern.
Since: 1.4
jpayne@68:cairo_pattern_t *
jpayne@68: cairo_pattern_create_for_surface (cairo_surface_t *surface);
jpayne@68: Create a new cairo_pattern_t for the given surface.
jpayne@68:surface |
jpayne@68: the surface |
jpayne@68: jpayne@68: |
the newly created cairo_pattern_t if successful, or
jpayne@68: an error pattern in case of no memory. The caller owns the
jpayne@68: returned object and should call cairo_pattern_destroy() when
jpayne@68: finished with it.
This function will always return a valid pointer, but if an error
jpayne@68: occurred the pattern status will be set to an error. To inspect
jpayne@68: the status of a pattern use cairo_pattern_status().
Since: 1.0
jpayne@68:cairo_status_t jpayne@68: cairo_pattern_get_surface (jpayne@68:cairo_pattern_t *pattern, jpayne@68:cairo_surface_t **surface);
Gets the surface of a surface pattern. The reference returned in
jpayne@68: surface
jpayne@68: is owned by the pattern; the caller should call
jpayne@68: cairo_surface_reference() if the surface is to be retained.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
surface |
jpayne@68: return value for surface of pattern, or |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS, or
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH if the pattern is not a surface
jpayne@68: pattern.
Since: 1.4
jpayne@68:cairo_pattern_t * jpayne@68: cairo_pattern_create_linear (jpayne@68:double x0, jpayne@68:double y0, jpayne@68:double x1, jpayne@68:double y1);
Create a new linear gradient cairo_pattern_t along the line defined
jpayne@68: by (x0, y0) and (x1, y1). Before using the gradient pattern, a
jpayne@68: number of color stops should be defined using
jpayne@68: cairo_pattern_add_color_stop_rgb() or
jpayne@68: cairo_pattern_add_color_stop_rgba().
Note: The coordinates here are in pattern space. For a new pattern,
jpayne@68: pattern space is identical to user space, but the relationship
jpayne@68: between the spaces can be changed with cairo_pattern_set_matrix().
x0 |
jpayne@68: x coordinate of the start point |
jpayne@68: jpayne@68: |
y0 |
jpayne@68: y coordinate of the start point |
jpayne@68: jpayne@68: |
x1 |
jpayne@68: x coordinate of the end point |
jpayne@68: jpayne@68: |
y1 |
jpayne@68: y coordinate of the end point |
jpayne@68: jpayne@68: |
the newly created cairo_pattern_t if successful, or
jpayne@68: an error pattern in case of no memory. The caller owns the
jpayne@68: returned object and should call cairo_pattern_destroy() when
jpayne@68: finished with it.
This function will always return a valid pointer, but if an error
jpayne@68: occurred the pattern status will be set to an error. To inspect
jpayne@68: the status of a pattern use cairo_pattern_status().
Since: 1.0
jpayne@68:cairo_status_t jpayne@68: cairo_pattern_get_linear_points (jpayne@68:cairo_pattern_t *pattern, jpayne@68:double *x0, jpayne@68:double *y0, jpayne@68:double *x1, jpayne@68:double *y1);
Gets the gradient endpoints for a linear gradient.
jpayne@68:pattern |
jpayne@68: jpayne@68: | jpayne@68: |
x0 |
jpayne@68: return value for the x coordinate of the first point, or |
jpayne@68: jpayne@68: |
y0 |
jpayne@68: return value for the y coordinate of the first point, or |
jpayne@68: jpayne@68: |
x1 |
jpayne@68: return value for the x coordinate of the second point, or |
jpayne@68: jpayne@68: |
y1 |
jpayne@68: return value for the y coordinate of the second point, or |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS, or
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH if pattern
jpayne@68: is not a linear
jpayne@68: gradient pattern.
Since: 1.4
jpayne@68:cairo_pattern_t * jpayne@68: cairo_pattern_create_radial (jpayne@68:double cx0, jpayne@68:double cy0, jpayne@68:double radius0, jpayne@68:double cx1, jpayne@68:double cy1, jpayne@68:double radius1);
Creates a new radial gradient cairo_pattern_t between the two
jpayne@68: circles defined by (cx0, cy0, radius0) and (cx1, cy1, radius1). Before using the
jpayne@68: gradient pattern, a number of color stops should be defined using
jpayne@68: cairo_pattern_add_color_stop_rgb() or
jpayne@68: cairo_pattern_add_color_stop_rgba().
Note: The coordinates here are in pattern space. For a new pattern,
jpayne@68: pattern space is identical to user space, but the relationship
jpayne@68: between the spaces can be changed with cairo_pattern_set_matrix().
cx0 |
jpayne@68: x coordinate for the center of the start circle |
jpayne@68: jpayne@68: |
cy0 |
jpayne@68: y coordinate for the center of the start circle |
jpayne@68: jpayne@68: |
radius0 |
jpayne@68: radius of the start circle |
jpayne@68: jpayne@68: |
cx1 |
jpayne@68: x coordinate for the center of the end circle |
jpayne@68: jpayne@68: |
cy1 |
jpayne@68: y coordinate for the center of the end circle |
jpayne@68: jpayne@68: |
radius1 |
jpayne@68: radius of the end circle |
jpayne@68: jpayne@68: |
the newly created cairo_pattern_t if successful, or
jpayne@68: an error pattern in case of no memory. The caller owns the
jpayne@68: returned object and should call cairo_pattern_destroy() when
jpayne@68: finished with it.
This function will always return a valid pointer, but if an error
jpayne@68: occurred the pattern status will be set to an error. To inspect
jpayne@68: the status of a pattern use cairo_pattern_status().
Since: 1.0
jpayne@68:cairo_status_t jpayne@68: cairo_pattern_get_radial_circles (jpayne@68:cairo_pattern_t *pattern, jpayne@68:double *x0, jpayne@68:double *y0, jpayne@68:double *r0, jpayne@68:double *x1, jpayne@68:double *y1, jpayne@68:double *r1);
Gets the gradient endpoint circles for a radial gradient, each jpayne@68: specified as a center coordinate and a radius.
jpayne@68:pattern |
jpayne@68: jpayne@68: | jpayne@68: |
x0 |
jpayne@68: return value for the x coordinate of the center of the first circle, or |
jpayne@68: jpayne@68: |
y0 |
jpayne@68: return value for the y coordinate of the center of the first circle, or |
jpayne@68: jpayne@68: |
r0 |
jpayne@68: return value for the radius of the first circle, or |
jpayne@68: jpayne@68: |
x1 |
jpayne@68: return value for the x coordinate of the center of the second circle, or |
jpayne@68: jpayne@68: |
y1 |
jpayne@68: return value for the y coordinate of the center of the second circle, or |
jpayne@68: jpayne@68: |
r1 |
jpayne@68: return value for the radius of the second circle, or |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS, or
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH if pattern
jpayne@68: is not a radial
jpayne@68: gradient pattern.
Since: 1.4
jpayne@68:cairo_pattern_t *
jpayne@68: cairo_pattern_create_mesh (void);
jpayne@68: Create a new mesh pattern.
jpayne@68:Mesh patterns are tensor-product patch meshes (type 7 shadings in jpayne@68: PDF). Mesh patterns may also be used to create other types of jpayne@68: shadings that are special cases of tensor-product patch meshes such jpayne@68: as Coons patch meshes (type 6 shading in PDF) and Gouraud-shaded jpayne@68: triangle meshes (type 4 and 5 shadings in PDF).
jpayne@68:Mesh patterns consist of one or more tensor-product patches, which
jpayne@68: should be defined before using the mesh pattern. Using a mesh
jpayne@68: pattern with a partially defined patch as source or mask will put
jpayne@68: the context in an error status with a status of
jpayne@68: CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.
A tensor-product patch is defined by 4 Bézier curves (side 0, 1, 2, jpayne@68: 3) and by 4 additional control points (P0, P1, P2, P3) that provide jpayne@68: further control over the patch and complete the definition of the jpayne@68: tensor-product patch. The corner C0 is the first point of the jpayne@68: patch.
jpayne@68:Degenerate sides are permitted so straight lines may be used. A jpayne@68: zero length line on one side may be used to create 3 sided patches.
jpayne@68:jpayne@68: C1 Side 1 C2 jpayne@68: +---------------+ jpayne@68: | | jpayne@68: | P1 P2 | jpayne@68: | | jpayne@68: Side 0 | | Side 2 jpayne@68: | | jpayne@68: | | jpayne@68: | P0 P3 | jpayne@68: | | jpayne@68: +---------------+ jpayne@68: C0 Side 3 C3 jpayne@68:
Each patch is constructed by first calling
jpayne@68: cairo_mesh_pattern_begin_patch(), then cairo_mesh_pattern_move_to()
jpayne@68: to specify the first point in the patch (C0). Then the sides are
jpayne@68: specified with calls to cairo_mesh_pattern_curve_to() and
jpayne@68: cairo_mesh_pattern_line_to().
The four additional control points (P0, P1, P2, P3) in a patch can
jpayne@68: be specified with cairo_mesh_pattern_set_control_point().
At each corner of the patch (C0, C1, C2, C3) a color may be
jpayne@68: specified with cairo_mesh_pattern_set_corner_color_rgb() or
jpayne@68: cairo_mesh_pattern_set_corner_color_rgba(). Any corner whose color
jpayne@68: is not explicitly specified defaults to transparent black.
A Coons patch is a special case of the tensor-product patch where jpayne@68: the control points are implicitly defined by the sides of the jpayne@68: patch. The default value for any control point not specified is the jpayne@68: implicit value for a Coons patch, i.e. if no control points are jpayne@68: specified the patch is a Coons patch.
jpayne@68:A triangle is a special case of the tensor-product patch where the jpayne@68: control points are implicitly defined by the sides of the patch, jpayne@68: all the sides are lines and one of them has length 0, i.e. if the jpayne@68: patch is specified using just 3 lines, it is a triangle. If the jpayne@68: corners connected by the 0-length side have the same color, the jpayne@68: patch is a Gouraud-shaded triangle.
jpayne@68:Patches may be oriented differently to the above diagram. For jpayne@68: example the first point could be at the top left. The diagram only jpayne@68: shows the relationship between the sides, corners and control jpayne@68: points. Regardless of where the first point is located, when jpayne@68: specifying colors, corner 0 will always be the first point, corner jpayne@68: 1 the point between side 0 and side 1 etc.
jpayne@68:Calling cairo_mesh_pattern_end_patch() completes the current
jpayne@68: patch. If less than 4 sides have been defined, the first missing
jpayne@68: side is defined as a line from the current point to the first point
jpayne@68: of the patch (C0) and the other sides are degenerate lines from C0
jpayne@68: to C0. The corners between the added sides will all be coincident
jpayne@68: with C0 of the patch and their color will be set to be the same as
jpayne@68: the color of C0.
Additional patches may be added with additional calls to
jpayne@68: cairo_mesh_pattern_begin_patch()/cairo_mesh_pattern_end_patch().
1 jpayne@68: 2 jpayne@68: 3 jpayne@68: 4 jpayne@68: 5 jpayne@68: 6 jpayne@68: 7 jpayne@68: 8 jpayne@68: 9 jpayne@68: 10 jpayne@68: 11 jpayne@68: 12 jpayne@68: 13 jpayne@68: 14 jpayne@68: 15 jpayne@68: 16 jpayne@68: 17 jpayne@68: 18 jpayne@68: 19 jpayne@68: 20 jpayne@68: 21 jpayne@68: 22 jpayne@68: 23 jpayne@68: 24 |
jpayne@68: cairo_pattern_t *pattern = cairo_pattern_create_mesh (); jpayne@68: jpayne@68: /* Add a Coons patch */ jpayne@68: cairo_mesh_pattern_begin_patch (pattern); jpayne@68: cairo_mesh_pattern_move_to (pattern, 0, 0); jpayne@68: cairo_mesh_pattern_curve_to (pattern, 30, -30, 60, 30, 100, 0); jpayne@68: cairo_mesh_pattern_curve_to (pattern, 60, 30, 130, 60, 100, 100); jpayne@68: cairo_mesh_pattern_curve_to (pattern, 60, 70, 30, 130, 0, 100); jpayne@68: cairo_mesh_pattern_curve_to (pattern, 30, 70, -30, 30, 0, 0); jpayne@68: cairo_mesh_pattern_set_corner_color_rgb (pattern, 0, 1, 0, 0); jpayne@68: cairo_mesh_pattern_set_corner_color_rgb (pattern, 1, 0, 1, 0); jpayne@68: cairo_mesh_pattern_set_corner_color_rgb (pattern, 2, 0, 0, 1); jpayne@68: cairo_mesh_pattern_set_corner_color_rgb (pattern, 3, 1, 1, 0); jpayne@68: cairo_mesh_pattern_end_patch (pattern); jpayne@68: jpayne@68: /* Add a Gouraud-shaded triangle */ jpayne@68: cairo_mesh_pattern_begin_patch (pattern) jpayne@68: cairo_mesh_pattern_move_to (pattern, 100, 100); jpayne@68: cairo_mesh_pattern_line_to (pattern, 130, 130); jpayne@68: cairo_mesh_pattern_line_to (pattern, 130, 70); jpayne@68: cairo_mesh_pattern_set_corner_color_rgb (pattern, 0, 1, 0, 0); jpayne@68: cairo_mesh_pattern_set_corner_color_rgb (pattern, 1, 0, 1, 0); jpayne@68: cairo_mesh_pattern_set_corner_color_rgb (pattern, 2, 0, 0, 1); jpayne@68: cairo_mesh_pattern_end_patch (pattern) |
jpayne@68:
When two patches overlap, the last one that has been added is drawn jpayne@68: over the first one.
jpayne@68:When a patch folds over itself, points are sorted depending on jpayne@68: their parameter coordinates inside the patch. The v coordinate jpayne@68: ranges from 0 to 1 when moving from side 3 to side 1; the u jpayne@68: coordinate ranges from 0 to 1 when going from side 0 to side
jpayne@68:Points with higher v coordinate hide points with lower v jpayne@68: coordinate. When two points have the same v coordinate, the one jpayne@68: with higher u coordinate is above. This means that points nearer to jpayne@68: side 1 are above points nearer to side 3; when this is not jpayne@68: sufficient to decide which point is above (for example when both jpayne@68: points belong to side 1 or side 3) points nearer to side 2 are jpayne@68: above points nearer to side 0.
For a complete definition of tensor-product patches, see the PDF jpayne@68: specification (ISO32000), which describes the parametrization in jpayne@68: detail.
jpayne@68:Note: The coordinates are always in pattern space. For a new
jpayne@68: pattern, pattern space is identical to user space, but the
jpayne@68: relationship between the spaces can be changed with
jpayne@68: cairo_pattern_set_matrix().
the newly created cairo_pattern_t if successful, or
jpayne@68: an error pattern in case of no memory. The caller owns the returned
jpayne@68: object and should call cairo_pattern_destroy() when finished with
jpayne@68: it.
This function will always return a valid pointer, but if an error
jpayne@68: occurred the pattern status will be set to an error. To inspect the
jpayne@68: status of a pattern use cairo_pattern_status().
Since: 1.12
jpayne@68:void
jpayne@68: cairo_mesh_pattern_begin_patch (cairo_pattern_t *pattern);
jpayne@68: Begin a patch in a mesh pattern.
jpayne@68:After calling this function, the patch shape should be defined with
jpayne@68: cairo_mesh_pattern_move_to(), cairo_mesh_pattern_line_to() and
jpayne@68: cairo_mesh_pattern_curve_to().
After defining the patch, cairo_mesh_pattern_end_patch() must be
jpayne@68: called before using pattern
jpayne@68: as a source or mask.
Note: If pattern
jpayne@68: is not a mesh pattern then pattern
jpayne@68: will be put
jpayne@68: into an error status with a status of
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If pattern
jpayne@68: already has a
jpayne@68: current patch, it will be put into an error status with a status of
jpayne@68: CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.12
jpayne@68:void
jpayne@68: cairo_mesh_pattern_end_patch (cairo_pattern_t *pattern);
jpayne@68: Indicates the end of the current patch in a mesh pattern.
jpayne@68:If the current patch has less than 4 sides, it is closed with a
jpayne@68: straight line from the current point to the first point of the
jpayne@68: patch as if cairo_mesh_pattern_line_to() was used.
Note: If pattern
jpayne@68: is not a mesh pattern then pattern
jpayne@68: will be put
jpayne@68: into an error status with a status of
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If pattern
jpayne@68: has no current
jpayne@68: patch or the current patch has no current point, pattern
jpayne@68: will be
jpayne@68: put into an error status with a status of
jpayne@68: CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.12
jpayne@68:void jpayne@68: cairo_mesh_pattern_move_to (jpayne@68:cairo_pattern_t *pattern, jpayne@68:double x, jpayne@68:double y);
Define the first point of the current patch in a mesh pattern.
jpayne@68:After this call the current point will be (x
jpayne@68: , y
jpayne@68: ).
Note: If pattern
jpayne@68: is not a mesh pattern then pattern
jpayne@68: will be put
jpayne@68: into an error status with a status of
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If pattern
jpayne@68: has no current
jpayne@68: patch or the current patch already has at least one side, pattern
jpayne@68:
jpayne@68: will be put into an error status with a status of
jpayne@68: CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
x |
jpayne@68: the X coordinate of the new position |
jpayne@68: jpayne@68: |
y |
jpayne@68: the Y coordinate of the new position |
jpayne@68: jpayne@68: |
Since: 1.12
jpayne@68:void jpayne@68: cairo_mesh_pattern_line_to (jpayne@68:cairo_pattern_t *pattern, jpayne@68:double x, jpayne@68:double y);
Adds a line to the current patch from the current point to position
jpayne@68: (x
jpayne@68: , y
jpayne@68: ) in pattern-space coordinates.
If there is no current point before the call to
jpayne@68: cairo_mesh_pattern_line_to() this function will behave as
jpayne@68: cairo_mesh_pattern_move_to(pattern
jpayne@68: , x
jpayne@68: , y
jpayne@68: ).
After this call the current point will be (x
jpayne@68: , y
jpayne@68: ).
Note: If pattern
jpayne@68: is not a mesh pattern then pattern
jpayne@68: will be put
jpayne@68: into an error status with a status of
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If pattern
jpayne@68: has no current
jpayne@68: patch or the current patch already has 4 sides, pattern
jpayne@68: will be
jpayne@68: put into an error status with a status of
jpayne@68: CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
x |
jpayne@68: the X coordinate of the end of the new line |
jpayne@68: jpayne@68: |
y |
jpayne@68: the Y coordinate of the end of the new line |
jpayne@68: jpayne@68: |
Since: 1.12
jpayne@68:void jpayne@68: cairo_mesh_pattern_curve_to (jpayne@68:cairo_pattern_t *pattern, jpayne@68:double x1, jpayne@68:double y1, jpayne@68:double x2, jpayne@68:double y2, jpayne@68:double x3, jpayne@68:double y3);
Adds a cubic Bézier spline to the current patch from the current
jpayne@68: point to position (x3
jpayne@68: , y3
jpayne@68: ) in pattern-space coordinates, using
jpayne@68: (x1
jpayne@68: , y1
jpayne@68: ) and (x2
jpayne@68: , y2
jpayne@68: ) as the control points.
If the current patch has no current point before the call to
jpayne@68: cairo_mesh_pattern_curve_to(), this function will behave as if
jpayne@68: preceded by a call to cairo_mesh_pattern_move_to(pattern
jpayne@68: , x1
jpayne@68: ,
jpayne@68: y1
jpayne@68: ).
After this call the current point will be (x3
jpayne@68: , y3
jpayne@68: ).
Note: If pattern
jpayne@68: is not a mesh pattern then pattern
jpayne@68: will be put
jpayne@68: into an error status with a status of
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If pattern
jpayne@68: has no current
jpayne@68: patch or the current patch already has 4 sides, pattern
jpayne@68: will be
jpayne@68: put into an error status with a status of
jpayne@68: CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
x1 |
jpayne@68: the X coordinate of the first control point |
jpayne@68: jpayne@68: |
y1 |
jpayne@68: the Y coordinate of the first control point |
jpayne@68: jpayne@68: |
x2 |
jpayne@68: the X coordinate of the second control point |
jpayne@68: jpayne@68: |
y2 |
jpayne@68: the Y coordinate of the second control point |
jpayne@68: jpayne@68: |
x3 |
jpayne@68: the X coordinate of the end of the curve |
jpayne@68: jpayne@68: |
y3 |
jpayne@68: the Y coordinate of the end of the curve |
jpayne@68: jpayne@68: |
Since: 1.12
jpayne@68:void jpayne@68: cairo_mesh_pattern_set_control_point (jpayne@68:cairo_pattern_t *pattern, jpayne@68:unsigned int point_num, jpayne@68:double x, jpayne@68:double y);
Set an internal control point of the current patch.
jpayne@68:Valid values for point_num
jpayne@68: are from 0 to 3 and identify the
jpayne@68: control points as explained in cairo_pattern_create_mesh().
Note: If pattern
jpayne@68: is not a mesh pattern then pattern
jpayne@68: will be put
jpayne@68: into an error status with a status of
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If point_num
jpayne@68: is not valid,
jpayne@68: pattern
jpayne@68: will be put into an error status with a status of
jpayne@68: CAIRO_STATUS_INVALID_INDEX. If pattern
jpayne@68: has no current patch,
jpayne@68: pattern
jpayne@68: will be put into an error status with a status of
jpayne@68: CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
point_num |
jpayne@68: the control point to set the position for |
jpayne@68: jpayne@68: |
x |
jpayne@68: the X coordinate of the control point |
jpayne@68: jpayne@68: |
y |
jpayne@68: the Y coordinate of the control point |
jpayne@68: jpayne@68: |
Since: 1.12
jpayne@68:void jpayne@68: cairo_mesh_pattern_set_corner_color_rgb jpayne@68: (jpayne@68:cairo_pattern_t *pattern, jpayne@68:unsigned int corner_num, jpayne@68:double red, jpayne@68:double green, jpayne@68:double blue);
Sets the color of a corner of the current patch in a mesh pattern.
jpayne@68:The color is specified in the same way as in cairo_set_source_rgb().
Valid values for corner_num
jpayne@68: are from 0 to 3 and identify the
jpayne@68: corners as explained in cairo_pattern_create_mesh().
Note: If pattern
jpayne@68: is not a mesh pattern then pattern
jpayne@68: will be put
jpayne@68: into an error status with a status of
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If corner_num
jpayne@68: is not valid,
jpayne@68: pattern
jpayne@68: will be put into an error status with a status of
jpayne@68: CAIRO_STATUS_INVALID_INDEX. If pattern
jpayne@68: has no current patch,
jpayne@68: pattern
jpayne@68: will be put into an error status with a status of
jpayne@68: CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
corner_num |
jpayne@68: the corner to set the color for |
jpayne@68: jpayne@68: |
red |
jpayne@68: red component of color |
jpayne@68: jpayne@68: |
green |
jpayne@68: green component of color |
jpayne@68: jpayne@68: |
blue |
jpayne@68: blue component of color |
jpayne@68: jpayne@68: |
Since: 1.12
jpayne@68:void jpayne@68: cairo_mesh_pattern_set_corner_color_rgba jpayne@68: (jpayne@68:cairo_pattern_t *pattern, jpayne@68:unsigned int corner_num, jpayne@68:double red, jpayne@68:double green, jpayne@68:double blue, jpayne@68:double alpha);
Sets the color of a corner of the current patch in a mesh pattern.
jpayne@68:The color is specified in the same way as in cairo_set_source_rgba().
Valid values for corner_num
jpayne@68: are from 0 to 3 and identify the
jpayne@68: corners as explained in cairo_pattern_create_mesh().
Note: If pattern
jpayne@68: is not a mesh pattern then pattern
jpayne@68: will be put
jpayne@68: into an error status with a status of
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH. If corner_num
jpayne@68: is not valid,
jpayne@68: pattern
jpayne@68: will be put into an error status with a status of
jpayne@68: CAIRO_STATUS_INVALID_INDEX. If pattern
jpayne@68: has no current patch,
jpayne@68: pattern
jpayne@68: will be put into an error status with a status of
jpayne@68: CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
corner_num |
jpayne@68: the corner to set the color for |
jpayne@68: jpayne@68: |
red |
jpayne@68: red component of color |
jpayne@68: jpayne@68: |
green |
jpayne@68: green component of color |
jpayne@68: jpayne@68: |
blue |
jpayne@68: blue component of color |
jpayne@68: jpayne@68: |
alpha |
jpayne@68: alpha component of color |
jpayne@68: jpayne@68: |
Since: 1.12
jpayne@68:cairo_status_t jpayne@68: cairo_mesh_pattern_get_patch_count (jpayne@68:cairo_pattern_t *pattern, jpayne@68:unsigned int *count);
Gets the number of patches specified in the given mesh pattern.
jpayne@68:The number only includes patches which have been finished by
jpayne@68: calling cairo_mesh_pattern_end_patch(). For example it will be 0
jpayne@68: during the definition of the first patch.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
count |
jpayne@68: return value for the number patches, or |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS, or
jpayne@68: CAIRO_STATUS_PATTERN_TYPE_MISMATCH if pattern
jpayne@68: is not a mesh
jpayne@68: pattern.
Since: 1.12
jpayne@68:cairo_path_t * jpayne@68: cairo_mesh_pattern_get_path (jpayne@68:cairo_pattern_t *pattern, jpayne@68:unsigned int patch_num);
Gets path defining the patch patch_num
jpayne@68: for a mesh
jpayne@68: pattern.
patch_num
jpayne@68: can range from 0 to n-1 where n is the number returned by
jpayne@68: cairo_mesh_pattern_get_patch_count().
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
patch_num |
jpayne@68: the patch number to return data for |
jpayne@68: jpayne@68: |
the path defining the patch, or a path with status
jpayne@68: CAIRO_STATUS_INVALID_INDEX if patch_num
jpayne@68: or point_num
jpayne@68: is not
jpayne@68: valid for pattern
jpayne@68: . If pattern
jpayne@68: is not a mesh pattern, a path with
jpayne@68: status CAIRO_STATUS_PATTERN_TYPE_MISMATCH is returned.
Since: 1.12
jpayne@68:cairo_status_t jpayne@68: cairo_mesh_pattern_get_control_point (jpayne@68:cairo_pattern_t *pattern, jpayne@68:unsigned int patch_num, jpayne@68:unsigned int point_num, jpayne@68:double *x, jpayne@68:double *y);
Gets the control point point_num
jpayne@68: of patch patch_num
jpayne@68: for a mesh
jpayne@68: pattern.
patch_num
jpayne@68: can range from 0 to n-1 where n is the number returned by
jpayne@68: cairo_mesh_pattern_get_patch_count().
Valid values for point_num
jpayne@68: are from 0 to 3 and identify the
jpayne@68: control points as explained in cairo_pattern_create_mesh().
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
patch_num |
jpayne@68: the patch number to return data for |
jpayne@68: jpayne@68: |
point_num |
jpayne@68: the control point number to return data for |
jpayne@68: jpayne@68: |
x |
jpayne@68: return value for the x coordinate of the control point, or |
jpayne@68: jpayne@68: |
y |
jpayne@68: return value for the y coordinate of the control point, or |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS, or CAIRO_STATUS_INVALID_INDEX
jpayne@68: if patch_num
jpayne@68: or point_num
jpayne@68: is not valid for pattern
jpayne@68: . If pattern
jpayne@68: is not a mesh pattern, CAIRO_STATUS_PATTERN_TYPE_MISMATCH is
jpayne@68: returned.
Since: 1.12
jpayne@68:cairo_status_t jpayne@68: cairo_mesh_pattern_get_corner_color_rgba jpayne@68: (jpayne@68:cairo_pattern_t *pattern, jpayne@68:unsigned int patch_num, jpayne@68:unsigned int corner_num, jpayne@68:double *red, jpayne@68:double *green, jpayne@68:double *blue, jpayne@68:double *alpha);
Gets the color information in corner corner_num
jpayne@68: of patch
jpayne@68: patch_num
jpayne@68: for a mesh pattern.
patch_num
jpayne@68: can range from 0 to n-1 where n is the number returned by
jpayne@68: cairo_mesh_pattern_get_patch_count().
Valid values for corner_num
jpayne@68: are from 0 to 3 and identify the
jpayne@68: corners as explained in cairo_pattern_create_mesh().
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
patch_num |
jpayne@68: the patch number to return data for |
jpayne@68: jpayne@68: |
corner_num |
jpayne@68: the corner number to return data for |
jpayne@68: jpayne@68: |
red |
jpayne@68: return value for red component of color, or |
jpayne@68: jpayne@68: |
green |
jpayne@68: return value for green component of color, or |
jpayne@68: jpayne@68: |
blue |
jpayne@68: return value for blue component of color, or |
jpayne@68: jpayne@68: |
alpha |
jpayne@68: return value for alpha component of color, or |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS, or CAIRO_STATUS_INVALID_INDEX
jpayne@68: if patch_num
jpayne@68: or corner_num
jpayne@68: is not valid for pattern
jpayne@68: . If
jpayne@68: pattern
jpayne@68: is not a mesh pattern, CAIRO_STATUS_PATTERN_TYPE_MISMATCH
jpayne@68: is returned.
Since: 1.12
jpayne@68:cairo_pattern_t *
jpayne@68: cairo_pattern_reference (cairo_pattern_t *pattern);
jpayne@68: Increases the reference count on pattern
jpayne@68: by one. This prevents
jpayne@68: pattern
jpayne@68: from being destroyed until a matching call to
jpayne@68: cairo_pattern_destroy() is made.
Use cairo_pattern_get_reference_count() to get the number of
jpayne@68: references to a cairo_pattern_t.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.0
jpayne@68:void
jpayne@68: cairo_pattern_destroy (cairo_pattern_t *pattern);
jpayne@68: Decreases the reference count on pattern
jpayne@68: by one. If the result is
jpayne@68: zero, then pattern
jpayne@68: and all associated resources are freed. See
jpayne@68: cairo_pattern_reference().
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.0
jpayne@68:cairo_status_t
jpayne@68: cairo_pattern_status (cairo_pattern_t *pattern);
jpayne@68: Checks whether an error has previously occurred for this jpayne@68: pattern.
jpayne@68:pattern |
jpayne@68: jpayne@68: | jpayne@68: |
CAIRO_STATUS_SUCCESS, CAIRO_STATUS_NO_MEMORY,
jpayne@68: CAIRO_STATUS_INVALID_MATRIX, CAIRO_STATUS_PATTERN_TYPE_MISMATCH,
jpayne@68: or CAIRO_STATUS_INVALID_MESH_CONSTRUCTION.
Since: 1.0
jpayne@68:void jpayne@68: cairo_pattern_set_extend (jpayne@68:cairo_pattern_t *pattern, jpayne@68:cairo_extend_t extend);
Sets the mode to be used for drawing outside the area of a pattern. jpayne@68: See cairo_extend_t for details on the semantics of each extend jpayne@68: strategy.
jpayne@68:The default extend mode is CAIRO_EXTEND_NONE for surface patterns
jpayne@68: and CAIRO_EXTEND_PAD for gradient patterns.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
extend |
jpayne@68: a cairo_extend_t describing how the area outside of the jpayne@68: pattern will be drawn |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_extend_t
jpayne@68: cairo_pattern_get_extend (cairo_pattern_t *pattern);
jpayne@68: Gets the current extend mode for a pattern. See cairo_extend_t jpayne@68: for details on the semantics of each extend strategy.
jpayne@68:pattern |
jpayne@68: jpayne@68: | jpayne@68: |
the current extend strategy used for drawing the jpayne@68: pattern.
jpayne@68:Since: 1.0
jpayne@68:void jpayne@68: cairo_pattern_set_filter (jpayne@68:cairo_pattern_t *pattern, jpayne@68:cairo_filter_t filter);
Sets the filter to be used for resizing when using this pattern. jpayne@68: See cairo_filter_t for details on each filter.
jpayne@68:Note that you might want to control filtering even when you do not
jpayne@68: have an explicit cairo_pattern_t object, (for example when using
jpayne@68: cairo_set_source_surface()). In these cases, it is convenient to
jpayne@68: use cairo_get_source() to get access to the pattern that cairo
jpayne@68: creates implicitly. For example:
1 jpayne@68: 2 |
jpayne@68: cairo_set_source_surface (cr, image, x, y); jpayne@68: cairo_pattern_set_filter (cairo_get_source (cr), CAIRO_FILTER_NEAREST); |
jpayne@68:
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
filter |
jpayne@68: a cairo_filter_t describing the filter to use for resizing jpayne@68: the pattern |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_filter_t
jpayne@68: cairo_pattern_get_filter (cairo_pattern_t *pattern);
jpayne@68: Gets the current filter for a pattern. See cairo_filter_t jpayne@68: for details on each filter.
jpayne@68:pattern |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_pattern_set_matrix (jpayne@68:cairo_pattern_t *pattern, jpayne@68:const cairo_matrix_t *matrix);
Sets the pattern's transformation matrix to matrix
jpayne@68: . This matrix is
jpayne@68: a transformation from user space to pattern space.
When a pattern is first created it always has the identity matrix jpayne@68: for its transformation matrix, which means that pattern space is jpayne@68: initially identical to user space.
jpayne@68:Important: Please note that the direction of this transformation jpayne@68: matrix is from user space to pattern space. This means that if you jpayne@68: imagine the flow from a pattern to user space (and on to device jpayne@68: space), then coordinates in that flow will be transformed by the jpayne@68: inverse of the pattern matrix.
jpayne@68:For example, if you want to make a pattern appear twice as large as jpayne@68: it does by default the correct code to use is:
jpayne@68:1 jpayne@68: 2 |
jpayne@68: cairo_matrix_init_scale (&matrix, 0.5, 0.5); jpayne@68: cairo_pattern_set_matrix (pattern, &matrix); |
jpayne@68:
Meanwhile, using values of 2.0 rather than 0.5 in the code above jpayne@68: would cause the pattern to appear at half of its default size.
jpayne@68:Also, please note the discussion of the user-space locking
jpayne@68: semantics of cairo_set_source().
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
matrix |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_pattern_get_matrix (jpayne@68:cairo_pattern_t *pattern, jpayne@68:cairo_matrix_t *matrix);
Stores the pattern's transformation matrix into matrix
jpayne@68: .
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
matrix |
jpayne@68: return value for the matrix |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_pattern_type_t
jpayne@68: cairo_pattern_get_type (cairo_pattern_t *pattern);
jpayne@68: Get the pattern's type. See cairo_pattern_type_t for available jpayne@68: types.
jpayne@68:pattern |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.2
jpayne@68:unsigned int
jpayne@68: cairo_pattern_get_reference_count (cairo_pattern_t *pattern);
jpayne@68: Returns the current reference count of pattern
jpayne@68: .
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
the current reference count of pattern
jpayne@68: . If the
jpayne@68: object is a nil object, 0 will be returned.
Since: 1.4
jpayne@68:cairo_status_t jpayne@68: cairo_pattern_set_user_data (jpayne@68:cairo_pattern_t *pattern, jpayne@68:const cairo_user_data_key_t *key, jpayne@68:void *user_data, jpayne@68:cairo_destroy_func_t destroy);
Attach user data to pattern
jpayne@68: . To remove user data from a surface,
jpayne@68: call this function with the key that was used to set it and NULL
jpayne@68: for data
jpayne@68: .
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
key |
jpayne@68: the address of a cairo_user_data_key_t to attach the user data to |
jpayne@68: jpayne@68: |
user_data |
jpayne@68: the user data to attach to the cairo_pattern_t |
jpayne@68: jpayne@68: |
destroy |
jpayne@68: a cairo_destroy_func_t which will be called when the jpayne@68: cairo_t is destroyed or when new user data is attached using the jpayne@68: same key. |
jpayne@68: jpayne@68: |
CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a
jpayne@68: slot could not be allocated for the user data.
Since: 1.4
jpayne@68:void * jpayne@68: cairo_pattern_get_user_data (jpayne@68:cairo_pattern_t *pattern, jpayne@68:const cairo_user_data_key_t *key);
Return user data previously attached to pattern
jpayne@68: using the
jpayne@68: specified key. If no user data has been attached with the given
jpayne@68: key this function returns NULL.
pattern |
jpayne@68: jpayne@68: | jpayne@68: |
key |
jpayne@68: the address of the cairo_user_data_key_t the user data was jpayne@68: attached to |
jpayne@68: jpayne@68: |
Since: 1.4
jpayne@68:typedef struct _cairo_pattern cairo_pattern_t; jpayne@68:jpayne@68:
A cairo_pattern_t represents a source when drawing onto a
jpayne@68: surface. There are different subtypes of cairo_pattern_t,
jpayne@68: for different types of sources; for example,
jpayne@68: cairo_pattern_create_rgb() creates a pattern for a solid
jpayne@68: opaque color.
Other than various
jpayne@68: cairo_pattern_create_type()
jpayne@68: functions, some of the pattern types can be implicitly created using various
jpayne@68: cairo_set_source_type() functions;
jpayne@68: 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
jpayne@68: cairo_pattern_reference() and cairo_pattern_destroy().
Since: 1.0
jpayne@68:cairo_extend_t is used to describe how pattern color/alpha will be jpayne@68: determined for areas "outside" the pattern's natural area, (for jpayne@68: example, outside the surface bounds or outside the gradient jpayne@68: geometry).
jpayne@68:Mesh patterns are not affected by the extend mode.
jpayne@68:The default extend mode is CAIRO_EXTEND_NONE for surface patterns
jpayne@68: and CAIRO_EXTEND_PAD for gradient patterns.
New entries may be added in future versions.
jpayne@68:| jpayne@68: |
jpayne@68: pixels outside of the source pattern jpayne@68: are fully transparent (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: the pattern is tiled by repeating (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: the pattern is tiled by reflecting jpayne@68: at the edges (Since 1.0; but only implemented for surface patterns since 1.6) jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: pixels outside of the pattern copy jpayne@68: the closest pixel from the source (Since 1.2; but only jpayne@68: implemented for surface patterns since 1.6) jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_filter_t is used to indicate what filtering should be
jpayne@68: applied when reading pixel values from patterns. See
jpayne@68: cairo_pattern_set_filter() for indicating the desired filter to be
jpayne@68: used with a particular pattern.
| jpayne@68: |
jpayne@68: A high-performance filter, with quality similar
jpayne@68: to |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: A reasonable-performance filter, with quality
jpayne@68: similar to |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The highest-quality available, performance may jpayne@68: not be suitable for interactive use. (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: Nearest-neighbor filtering (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: Linear interpolation in two dimensions (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: This filter value is currently jpayne@68: unimplemented, and should not be used in current code. (Since 1.0) jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_pattern_type_t is used to describe the type of a given pattern.
jpayne@68:The type of a pattern is determined by the function used to create
jpayne@68: it. The cairo_pattern_create_rgb() and cairo_pattern_create_rgba()
jpayne@68: functions create SOLID patterns. The remaining
jpayne@68: cairo_pattern_create functions map to pattern types in obvious
jpayne@68: 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
jpayne@68: type, (though trying to change the extend or filter for a solid
jpayne@68: pattern will have no effect). A notable exception is
jpayne@68: cairo_pattern_add_color_stop_rgb() and
jpayne@68: cairo_pattern_add_color_stop_rgba() which must only be called with
jpayne@68: gradient patterns (either LINEAR or RADIAL). Otherwise the pattern
jpayne@68: will be shutdown and put into an error state.
New entries may be added in future versions.
jpayne@68:| jpayne@68: |
jpayne@68: The pattern is a solid (uniform) jpayne@68: color. It may be opaque or translucent, since 1.2. jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The pattern is a based on a surface (an image), since 1.2. jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The pattern is a linear gradient, since 1.2. jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The pattern is a radial gradient, since 1.2. jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The pattern is a mesh, since 1.12. jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: The pattern is a user pattern providing raster data, since 1.12. jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68: