module Pattern:`sig`

..`end`

Paint (and also mask and brush) with which cairo draws and
associated function.

`type ``[< `Gradient | `Linear | `Radial | `Solid | `Surface ]`

t

This 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 functions,
of the form `Cairo.Pattern.create_type`

or implicitly through
`Cairo.set_source_*`

functions.

type`any =`

`[ `Gradient | `Linear | `Radial | `Solid | `Surface ] t`

`Cairo.Group.pop`

and `Cairo.get_source`

retrieve patterns
whose properties we do not know. In this case, we can only
assume the pattern has potentially all properties and the
functions below may raise an exception if it turns out that
the needed property is not present.`val add_color_stop_rgb : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface > `Gradient ]`

t -> ?ofs:float -> float -> float -> float -> unit

Adds an opaque color stop to a gradient pattern. The offset

`ofs`

specifies the location along the gradient's control
vector (default: `0.0`

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

`val add_color_stop_rgba : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface > `Gradient ]`

t -> ?ofs:float -> float -> float -> float -> float -> unit

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.

`val get_color_stop_count : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface > `Gradient ]`

t -> int

Return the number of color stops specified in the given
gradient pattern.

`val get_color_stop_rgba : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface > `Gradient ]`

t -> idx:int -> float * float * float * float * float

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

**Returns** (offset, red, green, blue, alpha)

`Cairo.Pattern.get_color_stop_count`

.`val create_rgb : ``r:float -> g:float -> b:float -> [ `Solid ] t`

Creates a new

`Cairo.Pattern.t`

corresponding to an opaque
color. The color components are floating point numbers in the
range 0 to 1. If the values passed in are outside that range,
they will be clamped.`val create_rgba : ``r:float -> g:float -> b:float -> a:float -> [ `Solid ] t`

Creates a new

`Cairo.Pattern.t`

corresponding to a
translucent color. The color components are floating point
numbers in the range 0 to 1. If the values passed in are
outside that range, they will be clamped.`val get_rgba : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface > `Solid ]`

t -> float * float * float * float

Return the solid color for a solid color pattern.

**Returns** (red, green, blue, alpha)

`val create_for_surface : ``Cairo.Surface.t -> [ `Surface ] t`

Create a new

`Cairo.Pattern.t`

for the given surface.`val get_surface : ``[ `Surface ] t -> Cairo.Surface.t`

Gets the surface of a surface pattern.

`val create_linear : ``x0:float ->`

y0:float -> x1:float -> y1:float -> [ `Gradient | `Linear ] t

Create a new linear gradient

`Cairo.Pattern.t`

along the
line defined by (x0, y0) and (x1, y1). Before using the
gradient pattern, a number of color stops should be defined
using `Cairo.Pattern.add_color_stop_rgb`

or
`Cairo.Pattern.add_color_stop_rgba`

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

.

`val get_linear_points : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface > `Gradient `Linear ]`

t -> float * float * float * float

Gets the gradient endpoints for a linear gradient.

**Returns** (x0, y0, x1, y1).

`val create_radial : ``x0:float ->`

y0:float ->

r0:float ->

x1:float -> y1:float -> r1:float -> [ `Gradient | `Radial ] t

Creates a new radial gradient

`Cairo.Pattern.t`

between the
two circles defined by (cx0, cy0, radius0) and (cx1, cy1,
radius1). Before using the gradient pattern, a number of color
stops should be defined using `Cairo.Pattern.add_color_stop_rgb`

or
`Cairo.Pattern.add_color_stop_rgba`

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

.

`val get_radial_circles : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface > `Gradient `Radial ]`

t -> float * float * float * float * float * float

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

**Returns** (x0, y0, r0, x1, y1, r1).

`type `

extend =

`|` |
`NONE` |
`(*` | pixels outside of the source pattern are fully transparent. | `*)` |

`|` |
`REPEAT` |
`(*` | the pattern is tiled by repeating. | `*)` |

`|` |
`REFLECT` |
`(*` | the pattern is tiled by reflecting at the edges. | `*)` |

`|` |
`PAD` |
`(*` | pixels outside of the pattern copy the closest pixel from the source. | `*)` |

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

`val set_extend : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface ] t ->`

extend -> unit

Sets the mode to be used for drawing outside the area of a
pattern. See

`Cairo.Pattern.extend`

for details on the
semantics of each extend strategy.
The default extend mode is `NONE`

for surface patterns and
`PAD`

for gradient patterns.

`val get_extend : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface ] t ->`

extend

Gets the current extend mode for a pattern. See

`Cairo.Pattern.extend`

for details on the semantics of each
extend strategy.`type `

filter =

`|` |
`FAST` |
`(*` | A high-performance filter, with quality similar to NEAREST | `*)` |

`|` |
`GOOD` |
`(*` | A reasonable-performance filter, with quality similar to BILINEAR | `*)` |

`|` |
`BEST` |
`(*` | The highest-quality available, performance may not be suitable for interactive use. | `*)` |

`|` |
`NEAREST` |
`(*` | Nearest-neighbor filtering | `*)` |

`|` |
`BILINEAR` |
`(*` | Linear interpolation in two dimensions | `*)` |

This 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.`val set_filter : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface ] t ->`

filter -> unit

Sets the filter to be used for resizing when using this
pattern. See

`Cairo.Pattern.filter`

for details on each
filter.
Note that you might want to control filtering even when you do
not have an explicit `Cairo.Pattern.t`

value (for example
when using `Cairo.set_source_surface`

). In these cases, it
is convenient to use `Cairo.get_source`

to get access to the
pattern that cairo creates implicitly. For example:

` Cairo.set_source_surface cr image x y;`

Cairo.Pattern.set_filter (Cairo.get_source cr) Cairo.Pattern.NEAREST;

`val get_filter : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface ] t ->`

filter

Gets the current filter for a pattern. See

`Cairo.Pattern.filter`

for details on each filter.`val set_matrix : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface ] t ->`

Cairo.Matrix.t -> unit

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:

` let matrix = Cairo.Matrix.init_scale 0.5 0.5 in`

Cairo.Pattern.set_matrix pattern matrix;

`val get_matrix : ``[< `Gradient | `Linear | `Radial | `Solid | `Surface ] t ->`

Cairo.Matrix.t

Returns the pattern's transformation matrix.