## Patterns

Patterns — Gradients and filtered sources

## Synopsis

    typedef             cairo_pattern_t;
    void                cairo_pattern_add_color_stop_rgb    (cairo_pattern_t *pattern,
                                                             double offset,
                                                             double red,
                                                             double green,
                                                             double blue);
    void                cairo_pattern_add_color_stop_rgba   (cairo_pattern_t *pattern,
                                                             double offset,
                                                             double red,
                                                             double green,
                                                             double blue,
                                                             double alpha);
    cairo_status_t      cairo_pattern_get_color_stop_count  (cairo_pattern_t *pattern,
                                                             int *count);
    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);
    cairo_pattern_t*    cairo_pattern_create_rgb            (double red,
                                                             double green,
                                                             double blue);
    cairo_pattern_t*    cairo_pattern_create_rgba           (double red,
                                                             double green,
                                                             double blue,
                                                             double alpha);
    cairo_status_t      cairo_pattern_get_rgba              (cairo_pattern_t *pattern,
                                                             double *red,
                                                             double *green,
                                                             double *blue,
                                                             double *alpha);
    cairo_pattern_t*    cairo_pattern_create_for_surface    (cairo_surface_t *surface);
    cairo_status_t      cairo_pattern_get_surface           (cairo_pattern_t *pattern,
                                                             cairo_surface_t **surface);
    cairo_pattern_t*    cairo_pattern_create_linear         (double x0,
                                                             double y0,
                                                             double x1,
                                                             double y1);
    cairo_status_t      cairo_pattern_get_linear_points     (cairo_pattern_t *pattern,
                                                             double *x0,
                                                             double *y0,
                                                             double *x1,
                                                             double *y1);
    cairo_pattern_t*    cairo_pattern_create_radial         (double cx0,
                                                             double cy0,
                                                             double radius0,
                                                             double cx1,
                                                             double cy1,
                                                             double radius1);
    cairo_status_t      cairo_pattern_get_radial_circles    (cairo_pattern_t *pattern,
                                                             double *x0,
                                                             double *y0,
                                                             double *r0,
                                                             double *x1,
                                                             double *y1,
                                                             double *r1);
    cairo_pattern_t*    cairo_pattern_reference             (cairo_pattern_t *pattern);
    void                cairo_pattern_destroy               (cairo_pattern_t *pattern);
    cairo_status_t      cairo_pattern_status                (cairo_pattern_t *pattern);
    enum                cairo_extend_t;
    void                cairo_pattern_set_extend            (cairo_pattern_t *pattern,
                                                             cairo_extend_t extend);
    cairo_extend_t      cairo_pattern_get_extend            (cairo_pattern_t *pattern);
    enum                cairo_filter_t;
    void                cairo_pattern_set_filter            (cairo_pattern_t *pattern,
                                                             cairo_filter_t filter);
    cairo_filter_t      cairo_pattern_get_filter            (cairo_pattern_t *pattern);
    void                cairo_pattern_set_matrix            (cairo_pattern_t *pattern,
                                                             const cairo_matrix_t *matrix);
    void                cairo_pattern_get_matrix            (cairo_pattern_t *pattern,
                                                             cairo_matrix_t *matrix);
    enum                cairo_pattern_type_t;
    cairo_pattern_type_t cairo_pattern_get_type             (cairo_pattern_t *pattern);
    unsigned int        cairo_pattern_get_reference_count   (cairo_pattern_t *pattern);
    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);
    void*               cairo_pattern_get_user_data         (cairo_pattern_t *pattern,
                                                             const cairo_user_data_key_t *key);

## Description

## Details

### 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 vairous 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()`.

### 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`.

`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

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

If two (or more) stops are specified with identical offset values, they will be sorted according to the order in which the stops are added, (stops added earlier will compare less than stops added later). This can be useful for reliably making sharp color transitions instead of the typical blend.

Note: If the pattern is not a gradient pattern, (eg. a linear or radial pattern), then the pattern will be put into an error status with a status of `CAIRO_STATUS_PATTERN_TYPE_MISMATCH`.

`pattern` : | a cairo_pattern_t
`offset` : | an offset in the range [0.0 .. 1.0]
`red` : | red component of color
`green` : | green component of color
`blue` : | blue component of color
`alpha` : | alpha component of color

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

`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` are 0 to 1 less than the number returned by `cairo_pattern_get_color_stop_count()`.

`pattern` : | a cairo_pattern_t
`index` : | index of the stop to return data for
`offset` : | return value for the offset of the stop, or `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.

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

### 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 1. If the values passed in are outside that range, they will be clamped.

`red` : | red component of the color
`green` : | green component of the color
`blue` : | blue component of the color
`alpha` : | alpha component of the color
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()`.

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

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

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

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

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

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

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

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

Note: The coordinates here are in pattern space. For a new pattern, pattern space is identical to user space, but the relationship between the spaces can be changed with `cairo_pattern_set_matrix()`.

`cx0` : | x coordinate for the center of the start circle
`cy0` : | y coordinate for the center of the start circle
`radius0` : | radius of the start circle
`cx1` : | x coordinate for the center of the end circle
`cy1` : | y coordinate for the center of the end circle
`radius1` : | radius of the end circle
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()`.

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

`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_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.

The number of references to a cairo_pattern_t can be get using `cairo_pattern_get_reference_count()`.

`pattern` : | a cairo_pattern_t
Returns : | the referenced cairo_pattern_t.

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

`pattern` : | a cairo_pattern_t

### cairo_pattern_status ()

    cairo_status_t      cairo_pattern_status                (cairo_pattern_t *pattern);

Checks whether an error has previously occurred for this pattern.

`pattern` : | a cairo_pattern_t
Returns : | `CAIRO_STATUS_SUCCESS`, `CAIRO_STATUS_NO_MEMORY`, or `CAIRO_STATUS_PATTERN_TYPE_MISMATCH`.

### enum cairo_extend_t

    typedef enum _cairo_extend {
        CAIRO_EXTEND_NONE,
        CAIRO_EXTEND_REPEAT,
        CAIRO_EXTEND_REFLECT,
        CAIRO_EXTEND_PAD
    } cairo_extend_t;

cairo_extend_t is used to describe how the area outside of a pattern will be drawn.

New entries may be added in future versions.

`CAIRO_EXTEND_NONE` | pixels outside of the source pattern are fully transparent
`CAIRO_EXTEND_REPEAT` | the pattern is tiled by repeating
`CAIRO_EXTEND_REFLECT` | the pattern is tiled by reflecting at the edges (not implemented for surface patterns currently)
`CAIRO_EXTEND_PAD` | pixels outside of the pattern copy the closest pixel from the source (Since 1.2; not implemented for surface patterns currently)

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

`pattern` : | a cairo_pattern_t
`extend` : | a cairo_extend_t describing how the area outside of the pattern will be drawn

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

`pattern` : | a cairo_pattern_t
Returns : | the current extend strategy used for drawing the pattern.

### enum cairo_filter_t

    typedef enum _cairo_filter {
        CAIRO_FILTER_FAST,
        CAIRO_FILTER_GOOD,
        CAIRO_FILTER_BEST,
        CAIRO_FILTER_NEAREST,
        CAIRO_FILTER_BILINEAR,
        CAIRO_FILTER_GAUSSIAN
    } cairo_filter_t;

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

`pattern` : | a cairo_pattern_t
`filter` : | a cairo_filter_t describing the filter to use for resizing the pattern

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

`pattern` : | a cairo_pattern_t
Returns : | the current filter used for resizing the pattern.

### 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:

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

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

Also, please note the discussion of the user-space locking semantics of `cairo_set_source()`.

`pattern` : | a cairo_pattern_t
`matrix` : | a cairo_matrix_t

### 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`.

`pattern` : | a cairo_pattern_t
`matrix` : | return value for the matrix

### enum cairo_pattern_type_t

    typedef enum _cairo_pattern_type {
        CAIRO_PATTERN_TYPE_SOLID,
        CAIRO_PATTERN_TYPE_SURFACE,
        CAIRO_PATTERN_TYPE_LINEAR,
        CAIRO_PATTERN_TYPE_RADIAL
    } 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 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.

`CAIRO_PATTERN_TYPE_SOLID` | The pattern is a solid (uniform) color. It may be opaque or translucent.
`CAIRO_PATTERN_TYPE_SURFACE` | The pattern is a based on a surface (an image).
`CAIRO_PATTERN_TYPE_LINEAR` | The pattern is a linear gradient.
`CAIRO_PATTERN_TYPE_RADIAL` | The pattern is a radial gradient.

Since 1.2

### cairo_pattern_get_type ()

    cairo_pattern_type_t cairo_pattern_get_type             (cairo_pattern_t *pattern);

This function returns the type a pattern. See cairo_pattern_type_t for available types.

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

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

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

`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