Module org.freedesktop.cairo

Package org.freedesktop.cairo

Class Pattern

java.lang.Object

io.github.jwharm.cairobindings.Proxy

org.freedesktop.cairo.Pattern

Direct Known Subclasses:

Gradient, Mesh, RasterSource, SolidPattern, SurfacePattern

public abstract class Pattern
extends Proxy

Sources for drawing.

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

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

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

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

Since:

1.0

Constructor Summary

Constructors

Constructor	Description
Pattern(MemorySegment address)	Constructor used internally to instantiate a java Pattern object for a native cairo_pattern_t instance

Method Summary

Modifier and Type	Method	Description
void	destroy()	Invokes the cleanup action that is normally invoked during garbage collection.
Dither	getDither()	Gets the current dithering mode, as set by setDither(Dither).
Extend	getExtend()	Gets the current extend mode for a pattern.
Filter	getFilter()	Gets the current filter for a pattern.
void	getMatrix(Matrix matrix)	Stores the pattern's transformation matrix into matrix.
PatternType	getPatternType()	Get the pattern's type.
static org.gnome.glib.Type	getType()	Get the CairoPattern GType
MemorySegment	getUserData(UserDataKey key)	Return user data previously attached to the pattern using the specified key.
void	setDither(Dither dither)	Set the dithering mode of the rasterizer used for drawing shapes.
void	setExtend(Extend extend)	Sets the mode to be used for drawing outside the area of a pattern.
void	setFilter(Filter filter)	Sets the filter to be used for resizing when using this pattern.
void	setMatrix(Matrix matrix)	Sets the pattern's transformation matrix to matrix.
UserDataKey	setUserData(UserDataKey key, MemorySegment userData)	Attach user data to the pattern.
Status	status()	Checks whether an error has previously occurred for this pattern.

Methods inherited from class io.github.jwharm.cairobindings.Proxy

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Pattern

public Pattern(MemorySegment address)

Constructor used internally to instantiate a java Pattern object for a native cairo_pattern_t instance

Parameters:

address - the memory address of the native cairo_pattern_t instance

Method Details

destroy

public void destroy()

Invokes the cleanup action that is normally invoked during garbage collection. If the instance is "owned" by the user, the destroy() function is run to dispose the native instance.

status

public Status status()

Checks whether an error has previously occurred for this pattern.

Returns:

Status.SUCCESS, Status.NO_MEMORY, Status.INVALID_MATRIX, Status.PATTERN_TYPE_MISMATCH, or Status.INVALID_MESH_CONSTRUCTION.

Since:

1.0

setExtend

public void setExtend(Extend extend)

Sets the mode to be used for drawing outside the area of a pattern. See Extend for details on the semantics of each extend strategy.

The default extend mode is Extend.NONE for surface patterns and Extend.PAD for gradient patterns.

Parameters:

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

Since:

1.0

getExtend

public Extend getExtend()

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

Returns:

the current extend strategy used for drawing the pattern.

Since:

1.0

setFilter

public void setFilter(Filter filter)

Sets the filter to be used for resizing when using this pattern. See Filter for details on each filter.

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

 cr.setSourceSurface(image, x, y);
 pattern.setFilter(cr.getSource(), Filter.NEAREST);
 

Parameters:

filter - a Filter describing the filter to use for resizing the pattern

Since:

1.0

getFilter

public Filter getFilter()

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

Returns:

the current filter used for resizing the pattern.

Since:

1.0

setMatrix

public void setMatrix(Matrix 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 matrix = Matrix.createScale(0.5, 0.5);
 pattern.setMatrix(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.setSource(Pattern).

Parameters:

matrix - a Matrix

Since:

1.0

getMatrix

public void getMatrix(Matrix matrix)

Stores the pattern's transformation matrix into matrix.

Parameters:

matrix - return value for the matrix

Since:

1.0

getPatternType

public PatternType getPatternType()

Get the pattern's type. See PatternType for available types.

Returns:

The type of pattern.

Since:

1.2

setUserData

public UserDataKey setUserData(UserDataKey key,
 MemorySegment userData)

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

Parameters:

key - the key to attach the user data to

userData - the user data to attach to the pattern

Returns:

the key

Throws:

NullPointerException - if key is null

Since:

1.4

getUserData

public MemorySegment getUserData(UserDataKey key)

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

The returned memory segment has zero length. It can be resized with MemorySegment.reinterpret(long)^RESTRICTED.

Parameters:

key - the UserDataKey the user data was attached to

Returns:

the user data previously attached or null

Since:

1.4

setDither

public void setDither(Dither dither)

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.

Parameters:

dither - a Dither describing the new dithering mode

Since:

1.18

getDither

public Dither getDither()

Gets the current dithering mode, as set by setDither(Dither).

Returns:

the current dithering mode.

Since:

1.18

getType

public static org.gnome.glib.Type getType()

Get the CairoPattern GType

Returns:

the GType