Patterns

Patterns are 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 PatternType constructors listed below, or implicitly through Context.set_source_<type>() methods.

class Pattern()

class cairo.Pattern

Pattern is the abstract base class from which all the other pattern classes derive. It cannot be instantiated directly.

get_extend() → Extend

Returns:: the current extend strategy used for drawing the Pattern.

Gets the current extend mode for the Pattern. See cairo.Extend attributes for details on the semantics of each extend strategy.

get_matrix() → Matrix

Returns:: a new Matrix which stores a copy of the Pattern’s transformation matrix

get_filter() → Filter

Returns:: the current filter used for resizing the pattern.

New in version 1.12.0: Used to be a method of SurfacePattern before

set_filter(filter: Filter) → None

Parameters:: filter – a filter describing the filter to use for resizing the pattern

Note that you might want to control filtering even when you do not have an explicit Pattern object, (for example when using Context.set_source_surface()). In these cases, it is convenient to use Context.get_source() to get access to the pattern that cairo creates implicitly. For example:

context.set_source_surface(image, x, y)
context.get_source().set_filter(cairo.FILTER_NEAREST)

New in version 1.12.0: Used to be a method of SurfacePattern before

set_extend(extend: Extend) → None

Parameters:: extend – an extend describing how the area outside of the Pattern will be drawn

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

The default extend mode is cairo.Extend.NONE for SurfacePattern and cairo.Extend.PAD for Gradient Patterns.

set_matrix(matrix: Matrix) → None

Parameters:: matrix – a 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:

matrix = cairo.Matrix(xx=0.5,yy=0.5)
pattern.set_matrix(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 Context.set_source.

get_dither() → Dither

Returns:: the current dithering mode.

Gets the current dithering mode, as set by Pattern.set_dither().

New in version 1.25.0: Only available with cairo 1.18.0+

set_dither(dither: Dither) → None

Parameters:: dither – a Dither describing the new dithering mode

Set the dithering mode of the rasterizer used for drawing shapes. This value is a hint, and a particular backend may or may not support a particular value. At the current time, only pixman is supported.

New in version 1.25.0: Only available with cairo 1.18.0+

class SolidPattern(`Pattern`)

class cairo.SolidPattern(red: float, green: float, blue: float, alpha: float = 1.0)

__init__(red: float, green: float, blue: float, alpha: float = 1.0) → None

Parameters:

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

Creates a new SolidPattern 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.

get_rgba() → Tuple[float, float, float, float]

Returns:: (red, green, blue, alpha) a tuple of float

Gets the solid color for a SolidPattern.

New in version 1.4.

class SurfacePattern(`Pattern`)

class cairo.SurfacePattern(surface: Surface)

__init__(surface: Surface) → None

Parameters:: surface – a cairo Surface

get_surface() → Surface

Returns:: the Surface of the SurfacePattern.

New in version 1.4.

class Gradient(`Pattern`)

class cairo.Gradient

Gradient is an abstract base class from which other Pattern classes derive. It cannot be instantiated directly.

add_color_stop_rgb(offset: float, red: float, green: float, blue: float) → None

Parameters:

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

Adds an opaque color stop to a Gradient pattern. The offset specifies the location along the gradient’s control vector. For example, a LinearGradient’s control vector is from (x0,y0) to (x1,y1) while a RadialGradient’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 Context.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.

add_color_stop_rgba(offset: float, red: float, green: float, blue: float, alpha: float) → None

Parameters:

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

Adds an opaque color stop to a Gradient pattern. The offset specifies the location along the gradient’s control vector. For example, a LinearGradient’s control vector is from (x0,y0) to (x1,y1) while a RadialGradient’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 Context.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.

get_color_stops_rgba() → List[Tuple[float, float, float, float, float]]

Returns:: a list of (offset, red, green, blue, alpha) tuples of float

Gets the color and offset information for all color stops specified in the given gradient pattern.

New in version 1.14.

class LinearGradient(`Gradient`)

class cairo.LinearGradient(x0: float, y0: float, x1: float, y1: float)

__init__(x0: float, y0: float, x1: float, y1: float) → None

Parameters:

x0 – x coordinate of the start point
y0 – y coordinate of the start point
x1 – x coordinate of the end point
y1 – y coordinate of the end point

Create a new LinearGradient along the line defined by (x0, y0) and (x1, y1). Before using the Gradient pattern, a number of color stops should be defined using Gradient.add_color_stop_rgb() or Gradient.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 Pattern.set_matrix()

get_linear_points() → Tuple[float, float, float, float]

Returns:

(x0, y0, x1, y1) - a tuple of float

x0: return value for the x coordinate of the first point
y0: return value for the y coordinate of the first point
x1: return value for the x coordinate of the second point
y1: return value for the y coordinate of the second point

Gets the gradient endpoints for a LinearGradient.

New in version 1.4.

class RadialGradient(`Gradient`)

class cairo.RadialGradient(cx0: float, cy0: float, radius0: float, cx1: float, cy1: float, radius1: float)

__init__(cx0: float, cy0: float, radius0: float, cx1: float, cy1: float, radius1: float) → None

Parameters:

cx0 – x coordinate for the center of the start circle
cy0 – y coordinate for the center of the start circle
radius0 – radius of the start circle
cx1 – x coordinate for the center of the end circle
cy1 – y coordinate for the center of the end circle
radius1 – radius of the end circle

Creates a new RadialGradient pattern 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 Gradient.add_color_stop_rgb() or Gradient.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 Pattern.set_matrix().

get_radial_circles() → Tuple[float, float, float, float, float, float]

Returns:

(x0, y0, r0, x1, y1, r1) - a tuple of float

x0: return value for the x coordinate of the center of the first circle
y0: return value for the y coordinate of the center of the first circle
r0: return value for the radius of the first circle
x1: return value for the x coordinate of the center of the second circle
y1: return value for the y coordinate of the center of the second circle
r1: return value for the radius of the second circle

Gets the Gradient endpoint circles for a RadialGradient, each specified as a center coordinate and a radius.

New in version 1.4.

class MeshPattern(`Pattern`)

class cairo.MeshPattern

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

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

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

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

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

Each patch is constructed by first calling begin_patch(), then move_to() to specify the first point in the patch (C0). Then the sides are specified with calls to curve_to() and line_to().

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

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

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

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

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

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

Additional patches may be added with additional calls to begin_patch()/end_patch().

# Add a Coons patch
pattern = cairo.MeshPattern()
pattern.begin_patch()
pattern.move_to(0, 0)
pattern.curve_to(30, -30, 60, 30, 100, 0)
pattern.curve_to(60, 30, 130, 60, 100, 100)
pattern.curve_to(60, 70, 30, 130, 0, 100)
pattern.curve_to(30, 70, -30, 30, 0, 0)
pattern.set_corner_color_rgb(0, 1, 0, 0)
pattern.set_corner_color_rgb(1, 0, 1, 0)
pattern.set_corner_color_rgb(2, 0, 0, 1)
pattern.set_corner_color_rgb(3, 1, 1, 0)
pattern.end_patch()

# Add a Gouraud-shaded triangle
pattern = cairo.MeshPattern()
pattern.begin_patch()
pattern.move_to(100, 100)
pattern.line_to(130, 130)
pattern.line_to(130, 70)
pattern.set_corner_color_rgb(0, 1, 0, 0)
pattern.set_corner_color_rgb(1, 0, 1, 0)
pattern.set_corner_color_rgb(2, 0, 0, 1)
pattern.end_patch()

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

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

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

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

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

New in version 1.14.

__init__() → None: Create a new mesh pattern.

New in version 1.14.

begin_patch() → None

Raises:: Error –

Begin a patch in a mesh pattern.

After calling this function, the patch shape should be defined with move_to(), line_to() and curve_to().

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

curve_to(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float) → None

Parameters:

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

Raises:

Error –

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

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

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

end_patch() → None

Raises:: Error –

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

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

get_control_point(patch_num: int, point_num: int) → Tuple[float, float]

Parameters:

patch_num – the patch number to return data for
point_num – he control point number to return data for

Returns:

a (x, y) tuple of float - coordinates of the control point

Raises:

Error –

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

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

Valid values for point_num are from 0 to 3 and identify the control points as explained in MeshPattern.

get_corner_color_rgba(patch_num: int, corner_num: int) → Tuple[float, float, float, float]

Parameters:

patch_num – the patch number to return data for
corner_num – the corner number to return data for

Returns:

a (red, green, blue, alpha) tuple of float

Raises:

Error –

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

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

Valid values for corner_num are from 0 to 3 and identify the corners as explained in MeshPattern.

get_patch_count() → int

Returns:: number of patches

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

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

line_to(x: float, y: float) → None

Parameters:

x – the X coordinate of the end of the new line
y – the Y coordinate of the end of the new line

Raises:

Error –

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

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

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

move_to(x: float, y: float) → None

Parameters:

x – the X coordinate of the new position
y – the Y coordinate of the new position

Raises:

Error –

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

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

set_control_point(point_num: int, x: float, y: float) → None

Parameters:

point_num – the control point to set the position for
x – the X coordinate of the control point
y – the Y coordinate of the control point

Raises:

Error –

Set an internal control point of the current patch.

Valid values for point_num are from 0 to 3 and identify the control points as explained in MeshPattern.

set_corner_color_rgb(corner_num: int, red: float, green: float, blue: float) → None

Parameters:

corner_num – the corner to set the color for
red – red component of color
green – green component of color
blue – blue component of color

Raises:

Error –

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

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

Valid values for corner_num are from 0 to 3 and identify the corners as explained in MeshPattern.

set_corner_color_rgba(corner_num: int, red: float, green: float, blue: float, alpha: float) → None

Parameters:

corner_num – the corner to set the color for
red – red component of color
green – green component of color
blue – blue component of color
alpha – alpha component of color

Raises:

Error –

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

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

Valid values for corner_num are from 0 to 3 and identify the corners as explained in MeshPattern.

get_path(patch_num: int) → Path

Parameters:: patch_num – the patch number to return data for
Returns:: the path defining the patch
Raises:: Error –

Gets path defining the patch patch_num for a mesh pattern.

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

class RasterSourcePattern(`Pattern`)

class cairo.RasterSourcePattern(content: Content, width: int, height: int)

The raster source provides the ability to supply arbitrary pixel data whilst rendering. The pixels are queried at the time of rasterisation by means of user callback functions, allowing for the ultimate flexibility. For example, in handling compressed image sources, you may keep a MRU cache of decompressed images and decompress sources on the fly and discard old ones to conserve memory.

For the raster source to be effective, you must at least specify the acquire and release callbacks which are used to retrieve the pixel data for the region of interest and demark when it can be freed afterwards. Other callbacks are provided for when the pattern is copied temporarily during rasterisation, or more permanently as a snapshot in order to keep the pixel data available for printing.

New in version 1.15.

__init__(content: Content, width: int, height: int) → None

Parameters:

content – content type for the pixel data that will be returned. Knowing the content type ahead of time is used for analysing the operation and picking the appropriate rendering path.
width – maximum size of the sample area
height – maximum size of the sample area

Creates a new user pattern for providing pixel data.

Use the setter functions to associate callbacks with the returned pattern.

New in version 1.15.

set_acquire(acquire: Callable[[Surface, RectangleInt], Surface] | None, release: Callable[[Surface], None] | None) → None

Parameters:

acquire (callable) – acquire callback or None to unset it
release (callable) – (optional) release callback or None

Raises:

Error –

Specifies the callbacks used to generate the image surface for a rendering operation (acquire) and the function used to cleanup that surface afterwards.

The acquire callback should create a surface (preferably an image surface created to match the target using Surface.create_similar_image()) that defines at least the region of interest specified by extents. The surface is allowed to be the entire sample area, but if it does contain a subsection of the sample area, the surface extents should be provided by setting the device offset (along with its width and height) using Surface.set_device_offset().

acquire(target, extents)

Parameters:

target (Surface) – the rendering target surface
extents (RectangleInt) – rectangular region of interest in pixels in sample space

Return type:

Surface

This function is called when a pattern is being rendered from. It should create a surface that provides the pixel data for the region of interest as defined by extents, though the surface itself does not have to be limited to that area. For convenience the surface should probably be of image type, created with Surface.create_similar_image() for the target (which enables the number of copies to be reduced during transfer to the device). Another option, might be to return a similar surface to the target for explicit handling by the application of a set of cached sources on the device. The region of sample data provided should be defined using Surface.set_device_offset() to specify the top-left corner of the sample data (along with width and height of the surface).

release(surface)

Parameters:: surface (Surface) – the surface created during acquire

This function is called when the pixel data is no longer being accessed by the pattern for the rendering operation.

New in version 1.15.

get_acquire() → Tuple[Callable[[Surface, RectangleInt], Surface] | None, Callable[[Surface], None] | None]

Returns:: a (acquire, release) tuple of callables or None as set through set_acquire()

Queries the current acquire and release callbacks.

New in version 1.15.

Patterns

class Pattern()

class SolidPattern(Pattern)

class SurfacePattern(Pattern)

class Gradient(Pattern)

class LinearGradient(Gradient)

class RadialGradient(Gradient)

class MeshPattern(Pattern)

class RasterSourcePattern(Pattern)

class SolidPattern(`Pattern`)

class SurfacePattern(`Pattern`)

class Gradient(`Pattern`)

class LinearGradient(`Gradient`)

class RadialGradient(`Gradient`)

class MeshPattern(`Pattern`)

class RasterSourcePattern(`Pattern`)