cairo-pattern-create-mesh ()

The newly created cairo-pattern-t instance if successful, or an error pattern in case of no memory. The caller owns the returned object and should call the 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 the function cairo-pattern-status.

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 :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 the function cairo-mesh-pattern-begin-patch, then the function cairo-mesh-pattern-move-to to specify the first point in the patch (C0). Then the sides are specified with calls to the functions cairo-mesh-pattern-curve-to and cairo-mesh-pattern-line-to.

The four additional control points (P0, P1, P2, P3) in a patch can be specified with the function cairo-mesh-pattern-set-control-point.

At each corner of the patch (C0, C1, C2, C3) a color may be specified with the functions cairo-mesh-pattern-set-corner-color-rgb or cairo-mesh-pattern-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 the function cairo-mesh-pattern-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 the functions cairo-mesh-pattern-begin-patch/cairo-mesh-pattern-end-patch.

cairo_pattern_t *pattern = cairo_pattern_create_mesh ();


/* Add a Coons patch */
cairo_mesh_pattern_begin_patch (pattern);
cairo_mesh_pattern_move_to (pattern, 0, 0);
cairo_mesh_pattern_curve_to (pattern, 30, -30,  60,  30, 100, 0);
cairo_mesh_pattern_curve_to (pattern, 60,  30, 130,  60, 100, 100);
cairo_mesh_pattern_curve_to (pattern, 60,  70,  30, 130,   0, 100);
cairo_mesh_pattern_curve_to (pattern, 30,  70, -30,  30,   0, 0);
cairo_mesh_pattern_set_corner_color_rgb (pattern, 0, 1, 0, 0);
cairo_mesh_pattern_set_corner_color_rgb (pattern, 1, 0, 1, 0);
cairo_mesh_pattern_set_corner_color_rgb (pattern, 2, 0, 0, 1);
cairo_mesh_pattern_set_corner_color_rgb (pattern, 3, 1, 1, 0);
cairo_mesh_pattern_end_patch (pattern);


/* Add a Gouraud-shaded triangle */
cairo_mesh_pattern_begin_patch (pattern)
cairo_mesh_pattern_move_to (pattern, 100, 100);
cairo_mesh_pattern_line_to (pattern, 130, 130);
cairo_mesh_pattern_line_to (pattern, 130,  70);
cairo_mesh_pattern_set_corner_color_rgb (pattern, 0, 1, 0, 0);
cairo_mesh_pattern_set_corner_color_rgb (pattern, 1, 0, 1, 0);
cairo_mesh_pattern_set_corner_color_rgb (pattern, 2, 0, 0, 1);
cairo_mesh_pattern_end_patch (pattern)  

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 2. 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. 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 the function cairo-pattern-set-matrix.