Mesh patterns are tensor-product patch meshes (type 7 shadings in PDF). More...

#include <cairomm/mesh_pattern.h>

Inheritance diagram for Cairo::MeshPattern:

Public Member Functions
	MeshPattern (cairo_pattern_t *cobject, bool has_reference=false)
	Create a C++ wrapper for the C instance.

	~MeshPattern () override

void	begin_patch ()
	Begin a patch in a mesh pattern.

void	end_patch ()
	Indicates the end of the current patch in a mesh pattern.

void	move_to (double x, double y)
	Define the first point of the current patch in a mesh pattern.

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

void	curve_to (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.

void	set_control_point (unsigned int point_num, double x, double y)
	Sets an internal control point of the current patch.

void	set_corner_color_rgb (unsigned int corner_num, double red, double green, double blue)
	Sets the color of a corner of the current patch in a mesh pattern.

void	set_corner_color_rgba (unsigned int corner_num, double red, double green, double blue, double alpha)
	Sets the color of a corner of the current patch in a mesh pattern.

unsigned int	get_patch_count () const
	Returns the number of patches specified in the given mesh pattern.

RefPtr< Path >	get_path (unsigned int patch_num) const
	Returns path defining the patch patch_num for the mesh pattern.

void	get_control_point (unsigned int patch_num, unsigned int point_num, double & x, double & y)
	Gets the control point point_num of patch patch_num for a mesh pattern.

void	get_corner_color_rgba (unsigned int patch_num, unsigned int corner_num, double & red, double & green, double & blue, double & alpha)
	Gets the color information in corner corner_num of patch patch_num for a mesh pattern.

Public Member Functions inherited from Cairo::Pattern
	Pattern (cairo_pattern_t *cobject, bool has_reference=false)
	Create a C++ wrapper for the C instance.

	Pattern (const Pattern &)=delete

Pattern &	operator= (const Pattern &)=delete

virtual	~Pattern ()

void	set_matrix (const Matrix &matrix)
	Sets the pattern's transformation matrix to @matrix.

void	get_matrix (Matrix &matrix) const
	Returns the pattern's transformation matrix.

Matrix	get_matrix () const
	Returns the pattern's transformation matrix.

Type	get_type () const
	Returns the type of the pattern.

void	set_extend (Extend extend)
	Sets the mode to be used for drawing outside the area of a pattern.

Extend	get_extend () const
	Gets the current extend mode See Cairo::Extend for details on the semantics of each extend strategy.

cobject *	cobj ()

const cobject *	cobj () const

void	reference () const

void	unreference () const

Static Public Member Functions
static RefPtr< MeshPattern >	create ()
	Creates a new mesh pattern.

Additional Inherited Members
Public Types inherited from Cairo::Pattern
enum class	Type { SOLID = CAIRO_PATTERN_TYPE_SOLID , SURFACE = CAIRO_PATTERN_TYPE_SURFACE , LINEAR = CAIRO_PATTERN_TYPE_LINEAR , RADIAL = CAIRO_PATTERN_TYPE_RADIAL , MESH = CAIRO_PATTERN_TYPE_MESH }
	Type is used to describe the type of a given pattern. More...

enum class	Extend { NONE = CAIRO_EXTEND_NONE , REPEAT = CAIRO_EXTEND_REPEAT , REFLECT = CAIRO_EXTEND_REFLECT , PAD = CAIRO_EXTEND_PAD }
	Cairo::Extend 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). More...

typedef cairo_pattern_t	cobject

Protected Member Functions inherited from Cairo::Pattern
	Pattern ()

Protected Attributes inherited from Cairo::Pattern
cobject *	m_cobject

Detailed Description

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 MeshPattern::begin_patch(), then MeshPattern::move_to() to specify the first point in the patch (C0). Then the sides are specified with calls to MeshPattern::curve_to() and MeshPattern::line_to().

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

At each corner of the patch (C0, C1, C2, C3) a color may be specified with MeshPattern::set_corner_color_rgb() or MeshPattern::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 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 MeshPattern::begin_patch() and MeshPattern::end_patch().

Cairo::RefPtr<Cairo::MeshPattern> pattern = Cairo::MeshPattern::create();
 
// Add a Coons patch
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->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 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.

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

Since cairomm 1.20:

Constructor & Destructor Documentation

◆ MeshPattern()

Cairo::MeshPattern::MeshPattern	(	cairo_pattern_t *	cobject,
		bool	has_reference = `false`
	)

explicit

Create a C++ wrapper for the C instance.

This C++ instance should then be given to a RefPtr.

Parameters

cobject	The C instance.
has_reference	whether we already have a reference. Otherwise, the constructor will take an extra reference.

Since cairomm 1.20:

◆ ~MeshPattern()

Cairo::MeshPattern::~MeshPattern ( )

override

Member Function Documentation

◆ begin_patch()

void Cairo::MeshPattern::begin_patch ( )

Begin a patch in a mesh pattern.

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

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

Exceptions

Cairo::logic_error if the pattern already has a current patch.

Since cairomm 1.20:

◆ create()

static RefPtr< MeshPattern > Cairo::MeshPattern::create ( )

static

Creates a new mesh pattern.

Throws an exception on error.

Since cairomm 1.20:

◆ curve_to()

void Cairo::MeshPattern::curve_to	(	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.

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

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

Parameters

x1,y1	the X and Y coordinates of the first control point
x2,y2	the X and Y coordinates of the second control point
x3,y3	the X and Y coordinates of the end of the curve

Exceptions

Cairo::logic_error if pattern has no current patch or the current patch already has 4 sides.

Since cairomm 1.20:

◆ end_patch()

void Cairo::MeshPattern::end_patch ( )

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 MeshPattern::line_to() was used.

Exceptions

Cairo::logic_error if the pattern has no current patch or the current patch has no current point.

Since cairomm 1.20:

◆ get_control_point()

void Cairo::MeshPattern::get_control_point	(	unsigned int	patch_num,
		unsigned int	point_num,
		double &	x,
		double &	y
	)

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

patch_num can range 0 to 1 less than the number returned by get_patch_count().

Valid values for point_num are from 0 to 3 and identify the control points.

Parameters

	patch_num	the patch number to return data for
	point_num	the control point number to return data for
[out]	x,y	return value for the X and Y corrdinates of the control point.

Exceptions

Cairo::logic_error if patch_num or point_num is not valid for the pattern

Since cairomm 1.20:

◆ get_corner_color_rgba()

void Cairo::MeshPattern::get_corner_color_rgba	(	unsigned int	patch_num,
		unsigned int	corner_num,
		double &	red,
		double &	green,
		double &	blue,
		double &	alpha
	)

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

patch_num can range 0 to 1 less than the number returned by get_patch_count().

Valid values for point_num are from 0 to 3 and identify the control points.

Parameters

	patch_num	the patch number to return data for
	corner_num	the corner number to return data for
[out]	red,green,blue,alpha	return value for the red, green, blue and alpha components of the corner color respectively.

Exceptions

Cairo::logic_error if patch_num or point_num is not valid for the pattern

Since cairomm 1.20:

◆ get_patch_count()

unsigned int Cairo::MeshPattern::get_patch_count ( ) const

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

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

Since cairomm 1.20:

◆ get_path()

RefPtr< Path > Cairo::MeshPattern::get_path ( unsigned int patch_num ) const

Returns path defining the patch patch_num for the mesh pattern.

patch_num can range 0 to 1 less than the number returned by get_patch_count().

Parameters

patch_num the patch number to return data for

Exceptions

Cairo::logic_error if patch_num or point_num is not valid for the pattern

Since cairomm 1.20:

◆ line_to()

void Cairo::MeshPattern::line_to	(	double	x,
		double	y
	)

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 MeshPattern::line_to() this function will behave as MeshPattern::move_to(x, y).

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

Parameters

x,y	the X and Y coordinates of the end of the new line

Exceptions

Cairo::logic_error if the pattern has no current patch or the current patch already has 4 sides.

Since cairomm 1.20:

◆ move_to()

void Cairo::MeshPattern::move_to	(	double	x,
		double	y
	)

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

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

Parameters

x,y	the X and Y coordinates of the new position

Exceptions

Cairo::logic_error if the pattern has no current patch or the current patch already has at least one side.

Since cairomm 1.20:

◆ set_control_point()

void Cairo::MeshPattern::set_control_point	(	unsigned int	point_num,
		double	x,
		double	y
	)

Sets an internal control point of the current patch.

Valid values for point_num are from 0 to 3 and identify the control points.

Parameters

point_num	the control point to set the position for
x,y	the X and Y corrdinates of the control point

Exceptions

Cairo::logic_error if point_num is not valid or the pattern has no current patch.

Since cairomm 1.20:

◆ set_corner_color_rgb()

void Cairo::MeshPattern::set_corner_color_rgb	(	unsigned int	corner_num,
		double	red,
		double	green,
		double	blue
	)

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

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

Valid values for corner_num are from 0 to 3 and identify the corners.

Parameters

corner_num	the corner to set the color for
red,green,blue	the red, green and blue components of the color respectively.

Exceptions

Cairo::logic_error if point_num is not valid or the pattern has no current patch.

Since cairomm 1.20:

◆ set_corner_color_rgba()

void Cairo::MeshPattern::set_corner_color_rgba	(	unsigned int	corner_num,
		double	red,
		double	green,
		double	blue,
		double	alpha
	)

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

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

Valid values for corner_num are from 0 to 3 and identify the corners.

Parameters

corner_num	the corner to set the color for
red,green,blue,alpha	the red, green, blue and alpha components of the color respectively.

Exceptions

Cairo::logic_error if point_num is not valid or the pattern has no current patch.

Since cairomm 1.20:

The documentation for this class was generated from the following file:

cairomm/mesh_pattern.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ MeshPattern()

◆ ~MeshPattern()

Member Function Documentation

◆ begin_patch()

◆ create()

◆ curve_to()

◆ end_patch()

◆ get_control_point()

◆ get_corner_color_rgba()

◆ get_patch_count()

◆ get_path()

◆ line_to()

◆ move_to()

◆ set_control_point()

◆ set_corner_color_rgb()

◆ set_corner_color_rgba()