Module org.freedesktop.cairo

Package org.freedesktop.cairo

Class Mesh

java.lang.Object

io.github.jwharm.cairobindings.Proxy

org.freedesktop.cairo.Pattern

org.freedesktop.cairo.Mesh

public class Mesh
extends Pattern

A mesh pattern.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
Mesh	beginPatch()	Begin a patch in a mesh pattern.
static Mesh	create()	Create a new mesh pattern.
Mesh	curveTo(double x1, double y1, double x2, double y2, double x3, double y3)	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.
Mesh	endPatch()	Indicates the end of the current patch in a mesh pattern.
Point	getControlPoint(int patchNum, int pointNum)	Gets the control point pointNum of patch patchNum for a mesh pattern.
double[]	getCornerColorRGBA(int patchNum, int cornerNum)	Gets the color information in corner cornerNum of patch patchNum for a mesh pattern.
int	getPatchCount()	Gets the number of patches specified in the given mesh pattern.
Path	getPath(int patchNum)	Gets path defining the patch patchNum for a mesh pattern.
Mesh	lineTo(double x, double y)	Adds a line to the current patch from the current point to position (x, y) in pattern-space coordinates.
Mesh	moveTo(double x, double y)	Define the first point of the current patch in a mesh pattern.
Mesh	setControlPoint(int pointNum, double x, double y)	Set an internal control point of the current patch.
Mesh	setCornerColorRGB(int cornerNum, double red, double green, double blue)	Sets the color of a corner of the current patch in a mesh pattern.
Mesh	setCornerColorRGBA(int cornerNum, double red, double green, double blue, double alpha)	Sets the color of a corner of the current patch in a mesh pattern.

Methods inherited from class org.freedesktop.cairo.Pattern

destroy, getDither, getExtend, getFilter, getMatrix, getPatternType, getType, getUserData, setDither, setExtend, setFilter, setMatrix, setUserData, status

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

Mesh

public Mesh(MemorySegment address)

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

Parameters:

address - the memory address of the native cairo_pattern_t instance

Method Details

create

public static Mesh create()

Create a new mesh pattern.

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 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 beginPatch(), then moveTo(double, double) to specify the first point in the patch (C0). Then the sides are specified with calls to curveTo(double, double, double, double, double, double) and lineTo(double, double)

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

At each corner of the patch (C0, C1, C2, C3) a color may be specified with setCornerColorRGB(int, double, double, double) or setCornerColorRGBA(int, double, double, double, double). 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 endPatch() 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 beginPatch()/endPatch().

 Mesh pattern = Mesh.createMesh();
 
 // Add a Coons patch
 pattern.beginPatch()
        .moveTo(0, 0)
        .curveTo(30, -30, 60, 30, 100, 0)
        .curveTo(60, 30, 130, 60, 100, 100)
        .curveTo(60, 70, 30, 130, 0, 100)
        .curveTo(30, 70, -30, 30, 0, 0)
        .setCornerColorRGB(0, 1, 0, 0)
        .setCornerColorRGB(1, 0, 1, 0)
        .setCornerColorRGB(2, 0, 0, 1)
        .setCornerColorRGB(3, 1, 1, 0)
        .endPatch();
 
 // Add a Gouraud-shaded triangle
 pattern.beginPatch()
        .moveTo(100, 100)
        .lineTo(130, 130)
        .lineTo(130, 70)
        .setCornerColorRGB(0, 1, 0, 0)
        .setCornerColorRGB(1, 0, 1, 0)
        .setCornerColorRGB(2, 0, 0, 1)
        .endPatch();
 

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 1. 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.setMatrix(Matrix).

Returns:

the newly created Mesh

Since:

1.12

beginPatch

public Mesh beginPatch()
                throws IllegalStateException

Begin a patch in a mesh pattern.

After calling this function, the patch shape should be defined with moveTo(double, double), lineTo(double, double) and curveTo(double, double, double, double, double, double).

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

Returns:

the mesh

Throws:

IllegalStateException - If the pattern already has a current patch. See Status.INVALID_MESH_CONSTRUCTION

Since:

1.12

endPatch

public Mesh endPatch()
              throws IllegalStateException

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 lineTo(double, double) was used.

Returns:

the mesh

Throws:

IllegalStateException - If the pattern already has no current patch or the current patch has no current point. See Status.INVALID_MESH_CONSTRUCTION

Since:

1.12

moveTo

public Mesh moveTo(double x,
 double y)
            throws IllegalStateException

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

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

Parameters:

x - the X coordinate of the new position

y - the Y coordinate of the new position

Returns:

the mesh

Throws:

IllegalStateException - If the pattern has no current patch or the current patch already has at least one side. See Status.INVALID_MESH_CONSTRUCTION

Since:

1.12

lineTo

public Mesh lineTo(double x,
 double y)
            throws IllegalStateException

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 lineTo() this function will behave as moveTo(x, y).

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

Parameters:

x - the X coordinate of the end of the new line

y - the X coordinate of the end of the new line

Returns:

the mesh

Throws:

IllegalStateException - If the pattern has no current patch or the current patch already has 4 sides. See Status.INVALID_MESH_CONSTRUCTION

Since:

1.12

curveTo

public Mesh curveTo(double x1,
 double y1,
 double x2,
 double y2,
 double x3,
 double y3)
             throws IllegalStateException

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 curveTo(), this function will behave as if preceded by a call to moveTo(x, y).

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

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

Returns:

the mesh

Throws:

IllegalStateException - If the pattern has no current patch or the current patch already has 4 sides. See Status.INVALID_MESH_CONSTRUCTION

Since:

1.2

setControlPoint

public Mesh setControlPoint(int pointNum,
 double x,
 double y)
                     throws IllegalStateException

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

Parameters:

pointNum - the control point to set the position for

x - the X coordinate of the control point

y - the Y coordinate of the control point

Returns:

the mesh

Throws:

IllegalStateException - If the pattern has no current patch. See Status.INVALID_MESH_CONSTRUCTION

Since:

1.12

setCornerColorRGB

public Mesh setCornerColorRGB(int cornerNum,
 double red,
 double green,
 double blue)
                       throws IllegalStateException

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.setSourceRGB(double, double, double).

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

Parameters:

cornerNum - the corner to set the color for

red - red component of color

green - green component of color

blue - blue component of color

Returns:

the mesh

Throws:

IllegalStateException - If the pattern has no current patch. See Status.INVALID_MESH_CONSTRUCTION

Since:

1.12

setCornerColorRGBA

public Mesh setCornerColorRGBA(int cornerNum,
 double red,
 double green,
 double blue,
 double alpha)
                        throws IllegalStateException

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.setSourceRGBA(double, double, double, double).

Valid values for cornerNum are from 0 to 3 and identify the corners as explained in create().

Parameters:

cornerNum - 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

Returns:

the mesh

Throws:

IllegalStateException - If the pattern has no current patch. See Status.INVALID_MESH_CONSTRUCTION

Since:

1.12

getPatchCount

public int getPatchCount()

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

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

Returns:

the number patches

Since:

1.12

getPath

public Path getPath(int patchNum)
             throws IndexOutOfBoundsException

Gets path defining the patch patchNum for a mesh pattern.

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

Parameters:

patchNum - the patch number to return data for

Returns:

the path defining the patch, or a path with status CAIRO_STATUS_INVALID_INDEX if patchNum or pointNum is not valid for the pattern

Throws:

IndexOutOfBoundsException - if patchNum is not valid for the pattern. Status.INVALID_INDEX.

Since:

1.12

getControlPoint

public Point getControlPoint(int patchNum,
 int pointNum)
                      throws IndexOutOfBoundsException

Gets the control point pointNum of patch patchNum for a mesh pattern.

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

Valid values for pointNum are from 0 to 3 and identify the control points as explained in create().

Parameters:

patchNum - the patch number to return data for

pointNum - the control point number to return data for

Returns:

a Point object with the x and y coordinates of the control point

Throws:

IndexOutOfBoundsException - if patchNum or pointNum is not valid for the pattern

Since:

1.12

getCornerColorRGBA

public double[] getCornerColorRGBA(int patchNum,
 int cornerNum)
                            throws IndexOutOfBoundsException

Gets the color information in corner cornerNum of patch patchNum for a mesh pattern.

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

Valid values for cornerNum are from 0 to 3 and identify the corners as explained in create().

Parameters:

patchNum - the patch number to return data for

cornerNum - the corner number to return data for

Returns:

a 4-element array with red, green, blue and alpha color components

Throws:

IndexOutOfBoundsException - if patchNum or pointNum is not valid for the pattern

Since:

1.12