![]() |
![]() |
![]() |
Cairo: A Vector Graphics Library | ![]() |
---|
cairo_tcairo_t — Drawing contexts. |
typedef cairo_t; cairo_t* cairo_create (cairo_surface_t *target); void cairo_reference (cairo_t *cr); void cairo_destroy (cairo_t *cr); void cairo_save (cairo_t *cr); void cairo_restore (cairo_t *cr); enum cairo_content_t; #define CAIRO_CONTENT_VALID (content) enum cairo_format_t; #define CAIRO_FORMAT_VALID (format) enum cairo_operator_t; void cairo_set_operator (cairo_t *cr, cairo_operator_t op); void cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue); void cairo_set_source_rgba (cairo_t *cr, double red, double green, double blue, double alpha); void cairo_set_source (cairo_t *cr, cairo_pattern_t *source); void cairo_set_source_surface (cairo_t *cr, cairo_surface_t *surface, double x, double y); void cairo_set_tolerance (cairo_t *cr, double tolerance); enum cairo_fill_rule_t; void cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule); void cairo_set_line_width (cairo_t *cr, double width); enum cairo_line_cap_t; void cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap); enum cairo_line_join_t; void cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join); void cairo_set_dash (cairo_t *cr, double *dashes, int ndash, double offset); void cairo_set_miter_limit (cairo_t *cr, double limit); void cairo_translate (cairo_t *cr, double tx, double ty); void cairo_scale (cairo_t *cr, double sx, double sy); void cairo_rotate (cairo_t *cr, double angle); void cairo_transform (cairo_t *cr, const cairo_matrix_t *matrix); void cairo_set_matrix (cairo_t *cr, const cairo_matrix_t *matrix); void cairo_identity_matrix (cairo_t *cr); void cairo_user_to_device (cairo_t *cr, double *x, double *y); void cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy); void cairo_device_to_user (cairo_t *cr, double *x, double *y); void cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy); void cairo_new_path (cairo_t *cr); void cairo_move_to (cairo_t *cr, double x, double y); void cairo_line_to (cairo_t *cr, double x, double y); void cairo_curve_to (cairo_t *cr, double x1, double y1, double x2, double y2, double x3, double y3); void cairo_arc (cairo_t *cr, double xc, double yc, double radius, double angle1, double angle2); void cairo_arc_negative (cairo_t *cr, double xc, double yc, double radius, double angle1, double angle2); void cairo_rel_move_to (cairo_t *cr, double dx, double dy); void cairo_rel_line_to (cairo_t *cr, double dx, double dy); void cairo_rel_curve_to (cairo_t *cr, double dx1, double dy1, double dx2, double dy2, double dx3, double dy3); void cairo_rectangle (cairo_t *cr, double x, double y, double width, double height); void cairo_close_path (cairo_t *cr); void cairo_paint (cairo_t *cr); void cairo_paint_with_alpha (cairo_t *cr, double alpha); void cairo_mask (cairo_t *cr, cairo_pattern_t *pattern); void cairo_mask_surface (cairo_t *cr, cairo_surface_t *surface, double surface_x, double surface_y); void cairo_stroke (cairo_t *cr); void cairo_stroke_preserve (cairo_t *cr); void cairo_fill (cairo_t *cr); void cairo_fill_preserve (cairo_t *cr); void cairo_copy_page (cairo_t *cr); void cairo_show_page (cairo_t *cr); cairo_bool_t cairo_in_stroke (cairo_t *cr, double x, double y); cairo_bool_t cairo_in_fill (cairo_t *cr, double x, double y); typedef cairo_bool_t; void cairo_stroke_extents (cairo_t *cr, double *x1, double *y1, double *x2, double *y2); void cairo_fill_extents (cairo_t *cr, double *x1, double *y1, double *x2, double *y2); void cairo_clip (cairo_t *cr); void cairo_clip_preserve (cairo_t *cr); void cairo_reset_clip (cairo_t *cr); cairo_glyph_t; enum cairo_font_slant_t; enum cairo_font_weight_t; void cairo_select_font_face (cairo_t *cr, const char *family, cairo_font_slant_t slant, cairo_font_weight_t weight); void cairo_set_font_size (cairo_t *cr, double size); void cairo_set_font_matrix (cairo_t *cr, const cairo_matrix_t *matrix); void cairo_get_font_matrix (cairo_t *cr, cairo_matrix_t *matrix); void cairo_set_font_options (cairo_t *cr, const cairo_font_options_t *options); void cairo_get_font_options (cairo_t *cr, cairo_font_options_t *options); void cairo_show_text (cairo_t *cr, const char *utf8); void cairo_show_glyphs (cairo_t *cr, cairo_glyph_t *glyphs, int num_glyphs); cairo_font_face_t* cairo_get_font_face (cairo_t *cr); void cairo_font_extents (cairo_t *cr, cairo_font_extents_t *extents); void cairo_set_font_face (cairo_t *cr, cairo_font_face_t *font_face); void cairo_text_extents (cairo_t *cr, const char *utf8, cairo_text_extents_t *extents); void cairo_glyph_extents (cairo_t *cr, cairo_glyph_t *glyphs, int num_glyphs, cairo_text_extents_t *extents); void cairo_text_path (cairo_t *cr, const char *utf8); void cairo_glyph_path (cairo_t *cr, cairo_glyph_t *glyphs, int num_glyphs); cairo_operator_t cairo_get_operator (cairo_t *cr); cairo_pattern_t* cairo_get_source (cairo_t *cr); double cairo_get_tolerance (cairo_t *cr); void cairo_get_current_point (cairo_t *cr, double *x, double *y); cairo_fill_rule_t cairo_get_fill_rule (cairo_t *cr); double cairo_get_line_width (cairo_t *cr); cairo_line_cap_t cairo_get_line_cap (cairo_t *cr); cairo_line_join_t cairo_get_line_join (cairo_t *cr); double cairo_get_miter_limit (cairo_t *cr); void cairo_get_matrix (cairo_t *cr, cairo_matrix_t *matrix); cairo_surface_t* cairo_get_target (cairo_t *cr); cairo_path_t* cairo_copy_path (cairo_t *cr); cairo_path_t* cairo_copy_path_flat (cairo_t *cr); void cairo_append_path (cairo_t *cr, cairo_path_t *path); enum cairo_path_data_type_t; cairo_path_t; void cairo_path_destroy (cairo_path_t *path); enum cairo_status_t; cairo_status_t cairo_status (cairo_t *cr); #define cairo_status_string const char* cairo_status_to_string (cairo_status_t status); enum cairo_filter_t; cairo_surface_t* cairo_image_surface_create (cairo_format_t format, int width, int height); cairo_surface_t* cairo_image_surface_create_for_data (unsigned char *data, cairo_format_t format, int width, int height, int stride); int cairo_image_surface_get_width (cairo_surface_t *surface); int cairo_image_surface_get_height (cairo_surface_t *surface); void (*cairo_destroy_func_t) (void *data); cairo_user_data_key_t; cairo_status_t (*cairo_read_func_t) (void *closure, unsigned char *data, unsigned int length); cairo_status_t (*cairo_write_func_t) (void *closure, unsigned char *data, unsigned int length);
cairo_t is the main object used when drawing with Cairo. To
draw with Cairo, you create a cairo_t, set the target surface,
and drawing options for the cairo_t, create shapes with
functions like cairo_move_to()
and cairo_line_to()
, and then
draw ships with cairo_stroke()
or cairo_fill()
.
cairo_t's can be pushed to a stack via cairo_save()
.
They may then safely be changed, without loosing the current state.
Use cairo_restore()
to restore to the saved state.
typedef struct _cairo cairo_t;
A cairo_t contains the current state of the rendering device, including coordinates of yet to be drawn shapes.
cairo_t* cairo_create (cairo_surface_t *target);
Creates a new cairo_t with all graphics state parameters set to
default values and with target
as a target surface. The target
surface should be constructed with a backend-specific function such
as cairo_image_surface_create (or any other
cairo_<backend>_surface_create variant).
This function references target
, so you can immediately
call cairo_surface_destroy()
on it if you don't need to
maintain a separate reference to it.
Note that there are restrictions on using the same surface in
multiple contexts at the same time. If, after creating cr_a
with
surface
you also create cr_b
with the same surface, you must
ensure that cr_b
has finished using surface
before resuming use
of cr_a
. Currently, the only way time at which this is guaranteed
is when the the last reference to cr_b
is released with
cairo_destroy()
. (XXX: We need to add a cairo_finish()
call to
provide a way to achieve this explicitly). See also the
CAIRO_STATUS_BAD_NESTING
status.
target : |
target surface for the context |
Returns : | a newly allocated cairo_t with a reference
count of 1. The initial reference count should be released
with cairo_destroy() when you are done using the cairo_t.
This function never returns NULL . If memory cannot be
allocated, a special cairo_t object will be returned on
which cairo_status() returns CAIRO_STATUS_NO_MEMORY .
You can use this object normally, but no drawing will
be done.
|
void cairo_reference (cairo_t *cr);
Increases the reference count on cr
by one. This prevents
cr
from being destroyed until a matching call to cairo_destroy()
is made.
cr : |
a cairo_t |
void cairo_destroy (cairo_t *cr);
Decreases the reference count on cr
by one. If the result
is zero, then cr
and all associated resources are freed.
See cairo_reference()
.
cr : |
a cairo_t |
void cairo_save (cairo_t *cr);
Makes a copy of the current state of cr
and saves it
on an internal stack of saved states for cr
. When
cairo_restore()
is called, cr
will be restored to
the saved state. Multiple calls to cairo_save()
and
cairo_restore()
can be nested; each call to cairo_restore()
restores the state from the matching paired cairo_save()
.
It isn't necessary to clear all saved states before
a cairo_t is freed. If the reference count of a cairo_t
drops to zero in response to a call to cairo_destroy()
,
any saved states will be freed along with the cairo_t.
cr : |
a cairo_t |
void cairo_restore (cairo_t *cr);
Restores cr
to the state saved by a preceding call to
cairo_save()
and removes that state from the stack of
saved states.
cr : |
a cairo_t |
typedef enum _cairo_content { CAIRO_CONTENT_COLOR = 0x1000, CAIRO_CONTENT_ALPHA = 0x2000, CAIRO_CONTENT_COLOR_ALPHA = 0x3000 } cairo_content_t;
cairo_content_t
is used to describe the content that a surface will
contain, whether color information, alpha information (translucence
vs. opacity), or both.
Note: The large values here are designed to keep cairo_content_t values distinct from cairo_format_t values so that the implementation can detect the error if users confuse the two types.
CAIRO_CONTENT_COLOR |
The surface will hold color content only. |
CAIRO_CONTENT_ALPHA |
The surface will hold alpha content only. |
CAIRO_CONTENT_COLOR_ALPHA |
The surface will hold color and alpha content. |
typedef enum _cairo_format { CAIRO_FORMAT_ARGB32, CAIRO_FORMAT_RGB24, CAIRO_FORMAT_A8, CAIRO_FORMAT_A1 } cairo_format_t;
cairo_format_t is used to identify the memory format of image data.
CAIRO_FORMAT_ARGB32 |
each pixel is a 32-bit quantity, with alpha in the upper 8 bits, then red, then green, then blue. The 32-bit quantities are stored native-endian. Pre-multiplied alpha is used. (That is, 50% transparent red is 0x80800000, not 0x80ff0000.) |
CAIRO_FORMAT_RGB24 |
each pixel is a 32-bit quantity, with the upper 8 bits unused. Red, Green, and Blue are stored in the remaining 24 bits in that order. |
CAIRO_FORMAT_A8 |
each pixel is a 8-bit quantity holding an alpha value. |
CAIRO_FORMAT_A1 |
each pixel is a 1-bit quantity holding an alpha value. Pixels are packed together into 32-bit quantities. The ordering of the bits matches the endianess of the platform. On a big-endian machine, the first pixel is in the uppermost bit, on a little-endian machine the first pixel is in the least-significant bit. |
typedef enum _cairo_operator { CAIRO_OPERATOR_CLEAR, CAIRO_OPERATOR_SOURCE, CAIRO_OPERATOR_OVER, CAIRO_OPERATOR_IN, CAIRO_OPERATOR_OUT, CAIRO_OPERATOR_ATOP, CAIRO_OPERATOR_DEST, CAIRO_OPERATOR_DEST_OVER, CAIRO_OPERATOR_DEST_IN, CAIRO_OPERATOR_DEST_OUT, CAIRO_OPERATOR_DEST_ATOP, CAIRO_OPERATOR_XOR, CAIRO_OPERATOR_ADD, CAIRO_OPERATOR_SATURATE } cairo_operator_t;
void cairo_set_operator (cairo_t *cr, cairo_operator_t op);
Sets the compositing operator to be used for all drawing operations. See cairo_operator_t for details on the semantics of each available drawing operator.
XXX: I'd also like to direct the reader's attention to some (not-yet-written) section on cairo's imaging model. How would I do that if such a section existed? (cworth).
cr : |
a cairo_t |
op : |
a compositing operator, specified as a cairo_operator_t |
void cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue);
Sets the source pattern within cr
to an opaque color. This opaque
color will then be used for any subsequent drawing operation until
a new source pattern is set.
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.
cr : |
a cairo context |
red : |
red component of color |
green : |
green component of color |
blue : |
blue component of color |
void cairo_set_source_rgba (cairo_t *cr, double red, double green, double blue, double alpha);
Sets the source pattern within cr
to a translucent color. This
color will then be used for any subsequent drawing operation until
a new source pattern is set.
The color and alpha components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped.
cr : |
a cairo context |
red : |
red component of color |
green : |
green component of color |
blue : |
blue component of color |
alpha : |
alpha component of color |
void cairo_set_source (cairo_t *cr, cairo_pattern_t *source);
Sets the source pattern within cr
to source
. This pattern
will then be used for any subsequent drawing operation until a new
source pattern is set.
XXX: I'd also like to direct the reader's attention to some (not-yet-written) section on cairo's imaging model. How would I do that if such a section existed? (cworth).
cr : |
a cairo context |
source : |
a cairo_pattern_t to be used as the source for subsequent drawing operations. |
void cairo_set_source_surface (cairo_t *cr, cairo_surface_t *surface, double x, double y);
This is a convenience function for creating a pattern from surface
and setting it as the source in cr
with cairo_set_source()
.
The x
and y
parameters give the user-space coordinate at which
the surface origin should appear. (The surface origin is its
upper-left corner before any transformation has been applied.) The
x
and y
patterns are negated and then set as translation values
in the pattern matrix.
Other than the initial translation pattern matrix, as described
above, all other pattern attributes, (such as its extend mode), are
set to the default values as in cairo_pattern_create_for_surface.
The resulting pattern can be queried with cairo_get_source()
so
that these attributes can be modified if desired, (eg. to create a
repeating pattern with cairo_pattern_set_extend()
).
cr : |
a cairo context |
surface : |
a surface to be used to set the source pattern |
x : |
User-space X coordinate for surface origin |
y : |
User-space Y coordinate for surface origin |
void cairo_set_tolerance (cairo_t *cr, double tolerance);
Sets the tolerance used when converting paths into trapezoids.
Curved segments of the path will be subdivided until the maximum
deviation between the original path and the polygonal approximation
is less than tolerance
. The default value is 0.1. A larger
value will give better performance, a smaller value, better
appearance. (Reducing the value from the default value of 0.1
is unlikely to improve appearance significantly.)
cr : |
a cairo_t |
tolerance : |
the tolerance, in device units (typically pixels) |
typedef enum _cairo_fill_rule { CAIRO_FILL_RULE_WINDING, CAIRO_FILL_RULE_EVEN_ODD } cairo_fill_rule_t;
cairo_fill_rule_t is used to select how paths are filled. For both fill rules, whether or not a point is included in the fill is determined by taking a ray from that point to infinity and looking at intersections with the path. The ray can be in any direction, as long as it doesn't pass through the end point of a segment or have a tricky intersection such as intersecting tangent to the path. (Note that filling is not actually implemented in this way. This is just a description of the rule that is applied.)
CAIRO_FILL_RULE_WINDING |
If the path crosses the ray from left-to-right, counts +1. If the path crosses the ray from right to left, counts -1. (Left and right are determined from the perspective of looking along the ray from the starting point.) If the total count is non-zero, the point will be filled. |
CAIRO_FILL_RULE_EVEN_ODD |
Counts the total number of intersections, without regard to the orientation of the contour. If the total number of intersections is odd, the point will be filled. |
void cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule);
Set the current fill rule within the cairo context. The fill rule is used to determine which regions are inside or outside a complex (potentially self-intersecting) path. The current fill rule affects both cairo_fill and cairo_clip. See cairo_fill_rule_t for details on the semantics of each available fill rule.
cr : |
a cairo_t |
fill_rule : |
a fill rule, specified as a cairo_fill_rule_t |
void cairo_set_line_width (cairo_t *cr, double width);
Sets the current line width within the cairo context. The line width specifies the diameter of a pen that is circular in user-space.
As with the other stroke parameters, the current line cap style is
examined by cairo_stroke()
, cairo_stroke_extents()
, and
cairo_stroke_to_path()
, but does not have any effect during path
construction.
cr : |
a cairo_t |
width : |
a line width, as a user-space value |
typedef enum _cairo_line_cap { CAIRO_LINE_CAP_BUTT, CAIRO_LINE_CAP_ROUND, CAIRO_LINE_CAP_SQUARE } cairo_line_cap_t;
enumeration for style of line-endings
CAIRO_LINE_CAP_BUTT |
start(stop) the line exactly at the start(end) point |
CAIRO_LINE_CAP_ROUND |
use a round ending, the center of the circle is the end point |
CAIRO_LINE_CAP_SQUARE |
use squared ending, the center of the square is the end point |
void cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap);
Sets the current line cap style within the cairo context. See cairo_line_cap_t for details about how the available line cap styles are drawn.
As with the other stroke parameters, the current line cap style is
examined by cairo_stroke()
, cairo_stroke_extents()
, and
cairo_stroke_to_path()
, but does not have any effect during path
construction.
cr : |
a cairo context, as a cairo_t |
line_cap : |
a line cap style, as a cairo_line_cap_t |
typedef enum _cairo_line_join { CAIRO_LINE_JOIN_MITER, CAIRO_LINE_JOIN_ROUND, CAIRO_LINE_JOIN_BEVEL } cairo_line_join_t;
void cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join);
Sets the current line join style within the cairo context. See cairo_line_join_t for details about how the available line join styles are drawn.
As with the other stroke parameters, the current line join style is
examined by cairo_stroke()
, cairo_stroke_extents()
, and
cairo_stroke_to_path()
, but does not have any effect during path
construction.
cr : |
a cairo context, as a cairo_t |
line_join : |
a line joint style, as a cairo_line_join_t |
void cairo_set_dash (cairo_t *cr, double *dashes, int ndash, double offset);
cr : |
|
dashes : |
|
ndash : |
|
offset : |
void cairo_translate (cairo_t *cr, double tx, double ty);
Modifies the current transformation matrix (CTM) by translating the
user-space origin by (tx
, ty
). This offset is interpreted as a
user-space coordinate according to the CTM in place before the new
call to cairo_translate. In other words, the translation of the
user-space origin takes place after any existing transformation.
cr : |
a cairo context |
tx : |
amount to translate in the X direction |
ty : |
amount to translate in the Y direction |
void cairo_scale (cairo_t *cr, double sx, double sy);
Modifies the current transformation matrix (CTM) by scaling the X
and Y user-space axes by sx
and sy
respectively. The scaling of
the axes takes place after any existing transformation of user
space.
cr : |
a cairo context |
sx : |
scale factor for the X dimension |
sy : |
scale factor for the Y dimension |
void cairo_rotate (cairo_t *cr, double angle);
Modifies the current transformation matrix (CTM) by rotating the
user-space axes by angle
radians. The rotation of the axes takes
places after any existing transformation of user space. The
rotation direction for positive angles is from the positive X axis
toward the positive Y axis.
cr : |
a cairo context |
angle : |
angle (in radians) by which the user-space axes will be rotated |
void cairo_transform (cairo_t *cr, const cairo_matrix_t *matrix);
Modifies the current transformation matrix (CTM) by applying
matrix
as an additional transformation. The new transformation of
user space takes place after any existing transformation.
cr : |
a cairo context |
matrix : |
a transformation to be applied to the user-space axes |
void cairo_set_matrix (cairo_t *cr, const cairo_matrix_t *matrix);
Modifies the current transformation matrix (CTM) by setting it
equal to matrix
.
cr : |
a cairo context |
matrix : |
a transformation matrix from user space to device space |
void cairo_identity_matrix (cairo_t *cr);
Resets the current transformation matrix (CTM) by setting it equal to the identity matrix. That is, the user-space and device-space axes will be aligned and one user-space unit will transform to one device-space unit.
cr : |
a cairo context |
void cairo_user_to_device (cairo_t *cr, double *x, double *y);
Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).
cr : |
a cairo context |
x : |
X value of coordinate (in/out parameter) |
y : |
Y value of coordinate (in/out parameter) |
void cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy);
Transform a distance vector from user space to device space. This
function is similar to cairo_user_to_device()
except that the
translation components of the CTM will be ignored when transforming
(dx
,dy
).
cr : |
a cairo context |
dx : |
X component of a distance vector (in/out parameter) |
dy : |
Y component of a distance vector (in/out parameter) |
void cairo_device_to_user (cairo_t *cr, double *x, double *y);
Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix (CTM).
cr : |
a cairo |
x : |
X value of coordinate (in/out parameter) |
y : |
Y value of coordinate (in/out parameter) |
void cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy);
Transform a distance vector from device space to user space. This
function is similar to cairo_device_to_user()
except that the
translation components of the inverse CTM will be ignored when
transforming (dx
,dy
).
cr : |
a cairo context |
dx : |
X component of a distance vector (in/out parameter) |
dy : |
Y component of a distance vector (in/out parameter) |
void cairo_curve_to (cairo_t *cr, double x1, double y1, double x2, double y2, double x3, double y3);
cr : |
|
x1 : |
|
y1 : |
|
x2 : |
|
y2 : |
|
x3 : |
|
y3 : |
void cairo_arc (cairo_t *cr, double xc, double yc, double radius, double angle1, double angle2);
Adds an arc from angle1
to angle2
to the current path. If there
is a current point, that point is connected to the start of the arc
by a straight line segment. Angles are measured in radians with an
angle of 0 along the X axis and an angle of M_PI
radians (90
degrees) along the Y axis, so with the default transformation
matrix, positive angles are clockwise. (To convert from degrees to
radians, use degrees * (M_PI / 180.)
.) This
function gives the arc in the direction of increasing angle; see
cairo_arc_negative()
to get the arc in the direction of decreasing
angle.
A full arc is drawn as a circle. To make an oval arc, you can scale
the current transformation matrix by different amounts in the X and
Y directions. For example, to draw a full oval in the box given
by x
, y
, width
, height
:
cairo_save (cr); cairo_translate (x + width / 2., y + height / 2.); cairo_scale (1. / (height / 2.), 1. / (width / 2.)); cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI); cairo_restore (cr);
cr : |
a cairo context |
xc : |
X position of the center of the arc |
yc : |
Y position of the center of the arc |
radius : |
the radius of the arc |
angle1 : |
the start angle, in radians |
angle2 : |
the end angle, in radians |
void cairo_arc_negative (cairo_t *cr, double xc, double yc, double radius, double angle1, double angle2);
Adds an arc from angle1
to angle2
to the current path. The
function behaves identically to cairo_arc()
except that instead of
giving the arc in the direction of increasing angle, it gives
the arc in the direction of decreasing angle.
cr : |
a cairo context |
xc : |
X position of the center of the arc |
yc : |
Y position of the center of the arc |
radius : |
the radius of the arc |
angle1 : |
the start angle, in radians |
angle2 : |
the end angle, in radians |
void cairo_rel_curve_to (cairo_t *cr, double dx1, double dy1, double dx2, double dy2, double dx3, double dy3);
cr : |
|
dx1 : |
|
dy1 : |
|
dx2 : |
|
dy2 : |
|
dx3 : |
|
dy3 : |
void cairo_rectangle (cairo_t *cr, double x, double y, double width, double height);
cr : |
|
x : |
|
y : |
|
width : |
|
height : |
void cairo_paint (cairo_t *cr);
A drawing operator that paints the current source everywhere within the current clip region.
cr : |
a cairo context |
void cairo_paint_with_alpha (cairo_t *cr, double alpha);
A drawing operator that paints the current source everywhere within
the current clip region using a mask of constant alpha value
alpha
. The effect is similar to cairo_paint()
, but the drawing
is faded out using the alpha value.
cr : |
a cairo context |
alpha : |
alpha value, between 0 (transparent) and 1 (opaque) |
void cairo_mask (cairo_t *cr, cairo_pattern_t *pattern);
A drawing operator that paints the current source
using the alpha channel of pattern
as a mask. (Opaque
areas of mask
are painted with the source, transparent
areas are not painted.)
cr : |
a cairo context |
pattern : |
a cairo_pattern_t |
void cairo_mask_surface (cairo_t *cr, cairo_surface_t *surface, double surface_x, double surface_y);
A drawing operator that paints the current source
using the alpha channel of surface
as a mask. (Opaque
areas of surface
are painted with the source, transparent
areas are not painted.)
cr : |
a cairo context |
surface : |
a cairo_surface_t |
surface_x : |
X coordinate at which to place the origin of surface
|
surface_y : |
Y coordinate at which to place the origin of surface
|
void cairo_stroke (cairo_t *cr);
A drawing operator that strokes the current path according to the
current line width, line join, line cap, and dash settings. After
cairo_stroke, the current path will be cleared from the cairo
context. See cairo_set_line_width()
, cairo_set_line_join()
,
cairo_set_line_cap()
, cairo_set_dash()
, and
cairo_stroke_preserve()
.
cr : |
a cairo context |
void cairo_stroke_preserve (cairo_t *cr);
A drawing operator that strokes the current path according to the
current line width, line join, line cap, and dash settings. Unlike
cairo_stroke()
, cairo_stroke_preserve preserves the path within the
cairo context.
See cairo_set_line_width()
, cairo_set_line_join()
,
cairo_set_line_cap()
, cairo_set_dash()
, and
cairo_stroke_preserve()
.
cr : |
a cairo context |
void cairo_fill (cairo_t *cr);
A drawing operator that fills the current path according to the
current fill rule. After cairo_fill, the current path will be
cleared from the cairo context. See cairo_set_fill_rule()
and
cairo_fill_preserve()
.
cr : |
a cairo context |
void cairo_fill_preserve (cairo_t *cr);
A drawing operator that fills the current path according to the
current fill rule. Unlike cairo_fill()
, cairo_fill_preserve
preserves the path within the cairo context.
See cairo_set_fill_rule()
and cairo_fill()
.
cr : |
a cairo context |
cairo_bool_t cairo_in_stroke (cairo_t *cr, double x, double y);
cr : |
|
x : |
|
y : |
|
Returns : |
cairo_bool_t cairo_in_fill (cairo_t *cr, double x, double y);
cr : |
|
x : |
|
y : |
|
Returns : |
typedef int cairo_bool_t;
cairo_bool_t is used for boolean values. Returns of type cairo_bool_t will always be either 0 or 1, but testing against these values explicitly is not encouraged; just use the value as a boolean condition.
if (cairo_in_stroke (cr, x, y)) { /* do something */ }
void cairo_stroke_extents (cairo_t *cr, double *x1, double *y1, double *x2, double *y2);
cr : |
|
x1 : |
|
y1 : |
|
x2 : |
|
y2 : |
void cairo_fill_extents (cairo_t *cr, double *x1, double *y1, double *x2, double *y2);
cr : |
|
x1 : |
|
y1 : |
|
x2 : |
|
y2 : |
void cairo_clip (cairo_t *cr);
Establishes a new clip region by intersecting the current clip
region with the current path as it would be filled by cairo_fill()
and according to the current fill rule (see cairo_set_fill_rule()
).
After cairo_clip, the current path will be cleared from the cairo context.
The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region.
Calling cairo_clip()
can only make the clip region smaller, never
larger. But the current clip is part of the graphics state, so a
temporary restriction of the clip region can be achieved by
calling cairo_clip()
within a cairo_save()
/cairo_restore()
pair. The only other means of increasing the size of the clip
region is cairo_reset_clip()
.
cr : |
a cairo context |
void cairo_clip_preserve (cairo_t *cr);
Establishes a new clip region by intersecting the current clip
region with the current path as it would be filled by cairo_fill()
and according to the current fill rule (see cairo_set_fill_rule()
).
Unlike cairo_clip()
, cairo_clip_preserve preserves the path within
the cairo context.
The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region.
Calling cairo_clip()
can only make the clip region smaller, never
larger. But the current clip is part of the graphics state, so a
temporary restriction of the clip region can be achieved by
calling cairo_clip()
within a cairo_save()
/cairo_restore()
pair. The only other means of increasing the size of the clip
region is cairo_reset_clip()
.
cr : |
a cairo context |
void cairo_reset_clip (cairo_t *cr);
Reset the current clip region to its original, unrestricted state. That is, set the clip region to an infinitely large shape containing the target surface. Equivalently, if infinity is too hard to grasp, one can imagine the clip region being reset to the exact bounds of the target surface.
Note that code meant to be reusable should not call
cairo_reset_clip()
as it will cause results unexpected by
higher-level code which calls cairo_clip()
. Consider using
cairo_save()
and cairo_restore()
around cairo_clip()
as a more
robust means of temporarily restricting the clip region.
cr : |
a cairo context |
typedef struct { unsigned long index; double x; double y; } cairo_glyph_t;
The cairo_glyph_t structure holds information about a single glyph when drawing or measuring text. A font is (in simple terms) a collection of shapes used to draw text. A glyph is one of these shapes. There can be multiple glyphs for a single character (alternates to be used in different contexts, for example), or a glyph can be a ligature of multiple characters. Cairo doesn't expose any way of converting input text into glyphs, so in order to use the Cairo interfaces that take arrays of glyphs, you must directly access the appropriate underlying font system.
Note that the offsets given by x
and y
are not cumulative. When
drawing or measuring text, each glyph is individually positioned
with respect to the overall origin
unsigned long index ; |
glyph index in the font. The exact interpretation of the glyph index depends on the font technology being used. |
double x ; |
the offset in the X direction between the origin used for drawing or measuring the string and the origin of this glyph. |
double y ; |
the offset in the Y direction between the origin used for drawing or measuring the string and the origin of this glyph. |
typedef enum _cairo_font_slant { CAIRO_FONT_SLANT_NORMAL, CAIRO_FONT_SLANT_ITALIC, CAIRO_FONT_SLANT_OBLIQUE } cairo_font_slant_t;
typedef enum _cairo_font_weight { CAIRO_FONT_WEIGHT_NORMAL, CAIRO_FONT_WEIGHT_BOLD } cairo_font_weight_t;
void cairo_select_font_face (cairo_t *cr, const char *family, cairo_font_slant_t slant, cairo_font_weight_t weight);
Selects a family and style of font from a simplified description as a family name, slant and weight. This function is meant to be used only for applications with simple font needs: Cairo doesn't provide for operations such as listing all available fonts on the system, and it is expected that most applications will need to use a more comprehensive font handling and text layout library in addition to Cairo.
cr : |
a cairo_t |
family : |
a font family name, encoded in UTF-8 |
slant : |
the slant for the font |
weight : |
the weight for the font |
void cairo_set_font_size (cairo_t *cr, double size);
Sets the current font matrix to a scale by a factor of size
, replacing
any font matrix previously set with cairo_set_font_size()
or
cairo_set_font_matrix()
. This results in a font size of size
user space
units. (More precisely, this matrix will result in the font's
em-square being a size
by size
square in user space.)
cr : |
a cairo_t |
size : |
the new font size, in user space units |
void cairo_set_font_matrix (cairo_t *cr, const cairo_matrix_t *matrix);
Sets the current font matrix to matrix
. The font matrix gives a
transformation from the design space of the font (in this space,
the em-square is 1 unit by 1 unit) to user space. Normally, a
simple scale is used (see cairo_set_font_size()
), but a more
complex font matrix can be used to shear the font
or stretch it unequally along the two axes
cr : |
a cairo_t |
matrix : |
a cairo_matrix_t describing a transform to be applied to the current font. |
void cairo_get_font_matrix (cairo_t *cr, cairo_matrix_t *matrix);
Stores the current font matrix into matrix
. See
cairo_set_font_matrix()
.
cr : |
a cairo_t |
matrix : |
return value for the matrix |
void cairo_set_font_options (cairo_t *cr, const cairo_font_options_t *options);
Sets a set of custom font rendering options for the cairo_t.
Rendering options are derived by merging these options with the
options derived from underlying surface; if the value in options
has a default value (like CAIRO_ANTIALIAS_DEFAULT
), then the value
from the surface is used.
cr : |
a cairo_t |
options : |
font options to use |
void cairo_get_font_options (cairo_t *cr, cairo_font_options_t *options);
Retrieves font rendering options set via cairo_set_font_options.
Note that the returned options do not include any options derived
from the underlying surface; they are literally the options
passed to cairo_set_font_options()
.
cr : |
a cairo_t |
options : |
a cairo_font_options_t object into which to store the retrieved options. All existing values are overwritten |
void cairo_show_glyphs (cairo_t *cr, cairo_glyph_t *glyphs, int num_glyphs);
cr : |
|
glyphs : |
|
num_glyphs : |
cairo_font_face_t* cairo_get_font_face (cairo_t *cr);
Gets the current font face for a cairo_t.
cr : |
a cairo_t |
Returns : | the current font object. Can return NULL
on out-of-memory or if the context is already in
an error state. This object is owned by cairo. To keep
a reference to it, you must call cairo_font_face_reference() .
|
void cairo_font_extents (cairo_t *cr, cairo_font_extents_t *extents);
Gets the font extents for the currently selected font.
cr : |
a cairo_t |
extents : |
a cairo_font_extents_t object into which the results will be stored. |
void cairo_set_font_face (cairo_t *cr, cairo_font_face_t *font_face);
Replaces the current cairo_font_face_t object in the cairo_t with
font_face
. The replaced font face in the cairo_t will be
destroyed if there are no other references to it.
cr : |
a cairo_t |
font_face : |
a cairo_font_face_t, or NULL to restore to the default font
|
void cairo_text_extents (cairo_t *cr, const char *utf8, cairo_text_extents_t *extents);
Gets the extents for a string of text. The extents describe a user-space rectangle that encloses the "inked" portion of the text, (as it would be drawn by cairo_show_text). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by cairo_show_text.
Note that whitespace characters do not directly contribute to the size of the rectangle (extents.width and extents.height). They do contribute indirectly by changing the position of non-whitespace characters. In particular, trailing whitespace characters are likely to not affect the size of the rectangle, though they will affect the x_advance and y_advance values.
cr : |
a cairo_t |
utf8 : |
a string of text, encoded in utf-8 |
extents : |
a cairo_text_extents_t object into which the results will be stored. |
void cairo_glyph_extents (cairo_t *cr, cairo_glyph_t *glyphs, int num_glyphs, cairo_text_extents_t *extents);
Gets the extents for an array of glyphs. The extents describe a user-space rectangle that encloses the "inked" portion of the glyphs, (as they would be drawn by cairo_show_glyphs). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by cairo_show_glyphs.
Note that whitespace glyphs do not contribute to the size of the rectangle (extents.width and extents.height).
cr : |
a cairo_t |
glyphs : |
an array of cairo_glyph_t objects |
num_glyphs : |
the number of elements in glyphs
|
extents : |
a cairo_text_extents_t object into which the results will be stored |
void cairo_glyph_path (cairo_t *cr, cairo_glyph_t *glyphs, int num_glyphs);
cr : |
|
glyphs : |
|
num_glyphs : |
cairo_operator_t cairo_get_operator (cairo_t *cr);
Gets the current compositing operator for a cairo context.
cr : |
a cairo context |
Returns : | the current compositing operator. |
cairo_pattern_t* cairo_get_source (cairo_t *cr);
Gets the current source pattern for cr
.
cr : |
a cairo context |
Returns : | the current source pattern. This object is owned by
cairo. To keep a reference to it, you must call
cairo_pattern_reference() .
|
double cairo_get_tolerance (cairo_t *cr);
Gets the current tolerance value, as set by cairo_set_tolerance()
.
cr : |
a cairo context |
Returns : | the current tolerance value. |
void cairo_get_current_point (cairo_t *cr, double *x, double *y);
Gets the current point of the current path, which is conceptually the final point reached by the path so far.
The current point is returned in the user-space coordinate
system. If there is no defined current point then x
and y
will
both be set to 0.0.
Most path construction functions alter the current point. See the following for details on how they affect the current point:
cairo_new_path()
, cairo_move_to()
, cairo_line_to()
,
cairo_curve_to()
, cairo_arc()
, cairo_rel_move_to()
,
cairo_rel_line_to()
, cairo_rel_curve_to()
, cairo_arc()
,
cairo_text_path()
, cairo_stroke_to_path()
cr : |
a cairo context |
x : |
return value for X coordinate of the current point |
y : |
return value for Y coordinate of the current point |
cairo_fill_rule_t cairo_get_fill_rule (cairo_t *cr);
Gets the current fill rule, as set by cairo_set_fill_rule()
.
cr : |
a cairo context |
Returns : | the current fill rule. |
double cairo_get_line_width (cairo_t *cr);
Gets the current line width, as set by cairo_set_line_width()
.
cr : |
a cairo context |
Returns : | the current line width, in user-space units. |
cairo_line_cap_t cairo_get_line_cap (cairo_t *cr);
Gets the current line cap style, as set by cairo_set_line_cap()
.
cr : |
a cairo context |
Returns : | the current line cap style. |
cairo_line_join_t cairo_get_line_join (cairo_t *cr);
Gets the current line join style, as set by cairo_set_line_join()
.
cr : |
a cairo context |
Returns : | the current line join style. |
double cairo_get_miter_limit (cairo_t *cr);
Gets the current miter limit, as set by cairo_set_miter_limit()
.
cr : |
a cairo context |
Returns : | the current miter limit. |
void cairo_get_matrix (cairo_t *cr, cairo_matrix_t *matrix);
Stores the current transformation matrix (CTM) into matrix
.
cr : |
a cairo context |
matrix : |
return value for the matrix |
cairo_surface_t* cairo_get_target (cairo_t *cr);
Gets the target surface for the cairo context as passed to
cairo_create()
.
cr : |
a cairo context |
Returns : | the target surface. This object is owned by cairo. To
keep a reference to it, you must call cairo_surface_reference() .
This function will always return a valid pointer, but the result
can be a "nil" surface if cr is already in an error state,
(ie. cairo_status(cr) != CAIRO_STATUS_SUCCESS). A nil surface is
indicated by cairo_surface_status(surface) != CAIRO_STATUS_SUCCESS.
|
cairo_path_t* cairo_copy_path (cairo_t *cr);
Creates a copy of the current path and returns it to the user as a cairo_path_t. See cairo_path_data_t for hints on how to iterate over the returned data structure.
cr : |
a cairo context |
Returns : | the copy of the current path. The caller owns the
returned object and should call cairo_path_destroy() when finished
with it.
This function will always return a valid pointer, but the result
will have no data, (data==NULL and num_data==0), if either of the
following conditions hold:
1) If there is insufficient memory to copy the path.
2) If cr is already in an error state.
In either case, path->status will be set to CAIRO_STATUS_NO_MEMORY,
(regardless of what the error status in cr might have been).
|
cairo_path_t* cairo_copy_path_flat (cairo_t *cr);
Gets a flattened copy of the current path and returns it to the user as a cairo_path_t. See cairo_path_data_t for hints on how to iterate over the returned data structure.
This function is like cairo_copy_path()
except that any curves
in the path will be approximated with piecewise-linear
approximations, (accurate to within the current tolerance
value). That is, the result is guaranteed to not have any elements
of type CAIRO_PATH_CURVE_TO which will instead be replaced by a
series of CAIRO_PATH_LINE_TO elements.
cr : |
a cairo context |
Returns : | the copy of the current path. The caller owns the
returned object and should call cairo_path_destroy() when finished
with it.
This function will always return a valid pointer, but the result
will have no data, (data==NULL and num_data==0), if either of the
following conditions hold:
1) If there is insufficient memory to copy the path. In this case
path->status will be set to CAIRO_STATUS_NO_MEMORY.
2) If cr is already in an error state. In this case path->status
will contain the same status that would be returned by
cairo_status(cr).
|
void cairo_append_path (cairo_t *cr, cairo_path_t *path);
Append the path
onto the current path. The path
may be either the
return value from one of cairo_copy_path()
or
cairo_copy_path_flat()
or it may be constructed manually. See
cairo_path_t for details on how the path data structure should be
initialized, and note that path->status must be initialized to
CAIRO_STATUS_SUCCESS.
cr : |
a cairo context |
path : |
path to be appended |
typedef enum _cairo_path_data_type { CAIRO_PATH_MOVE_TO, CAIRO_PATH_LINE_TO, CAIRO_PATH_CURVE_TO, CAIRO_PATH_CLOSE_PATH } cairo_path_data_type_t;
typedef struct { cairo_status_t status; cairo_path_data_t *data; int num_data; } cairo_path_t;
A data structure for holding a path. This data structure serves as
the return value for cairo_copy_path_data()
and
cairo_copy_path_data_flat()
as well the input value for
cairo_append_path()
.
See cairo_path_data_t for hints on how to iterate over the actual data within the path.
The num_data member gives the number of elements in the data array. This number is larger than the number of independent path portions (MOVE_TO, LINE_TO, CURVE_TO, CLOSE_PATH), since the data includes both headers and coordinates for each portion.
cairo_status_t status ; |
the current error status |
cairo_path_data_t *data ; |
the elements in the path |
int num_data ; |
the number of elements in the data array |
void cairo_path_destroy (cairo_path_t *path);
Immediately releases all memory associated with path
. After a call
to cairo_path_destroy()
the path
pointer is no longer valid and
should not be used further.
NOTE: cairo_path_destroy function should only be called with a pointer to a cairo_path_t returned by a cairo function. Any path that is created manually (ie. outside of cairo) should be destroyed manually as well.
path : |
a path to destroy which was previously returned by either cairo_copy_path or cairo_copy_path_flat. |
typedef enum _cairo_status { CAIRO_STATUS_SUCCESS = 0, CAIRO_STATUS_NO_MEMORY, CAIRO_STATUS_INVALID_RESTORE, CAIRO_STATUS_INVALID_POP_GROUP, CAIRO_STATUS_NO_CURRENT_POINT, CAIRO_STATUS_INVALID_MATRIX, CAIRO_STATUS_INVALID_STATUS, CAIRO_STATUS_NULL_POINTER, CAIRO_STATUS_INVALID_STRING, CAIRO_STATUS_INVALID_PATH_DATA, CAIRO_STATUS_READ_ERROR, CAIRO_STATUS_WRITE_ERROR, CAIRO_STATUS_SURFACE_FINISHED, CAIRO_STATUS_SURFACE_TYPE_MISMATCH, CAIRO_STATUS_PATTERN_TYPE_MISMATCH, CAIRO_STATUS_INVALID_CONTENT, CAIRO_STATUS_INVALID_FORMAT, CAIRO_STATUS_INVALID_VISUAL, CAIRO_STATUS_FILE_NOT_FOUND } cairo_status_t;
cairo_status_t is used to indicate errors that can occur when
using Cairo. In some cases it is returned directly by functions.
but when using cairo_t, the last error, if any, is stored in
the context and can be retrieved with cairo_status()
.
CAIRO_STATUS_SUCCESS |
no error has occurred |
CAIRO_STATUS_NO_MEMORY |
out of memory |
CAIRO_STATUS_INVALID_RESTORE |
cairo_restore without matching cairo_save |
CAIRO_STATUS_INVALID_POP_GROUP |
no saved group to pop |
CAIRO_STATUS_NO_CURRENT_POINT |
no current point defined |
CAIRO_STATUS_INVALID_MATRIX |
invalid matrix (not invertible) |
CAIRO_STATUS_INVALID_STATUS |
invalid value for an input cairo_status_t |
CAIRO_STATUS_NULL_POINTER |
NULL pointer |
CAIRO_STATUS_INVALID_STRING |
input string not valid UTF-8 |
CAIRO_STATUS_INVALID_PATH_DATA |
input path data not valid |
CAIRO_STATUS_READ_ERROR |
error while reading from input stream |
CAIRO_STATUS_WRITE_ERROR |
error while writing to output stream |
CAIRO_STATUS_SURFACE_FINISHED |
target surface has been finished |
CAIRO_STATUS_SURFACE_TYPE_MISMATCH |
the surface type is not appropriate for the operation |
CAIRO_STATUS_PATTERN_TYPE_MISMATCH |
the pattern type is not appropriate for the operation |
CAIRO_STATUS_INVALID_CONTENT |
invalid value for an input cairo_content_t |
CAIRO_STATUS_INVALID_FORMAT |
invalid value for an input cairo_format_t |
CAIRO_STATUS_INVALID_VISUAL |
invalid value for an input Visual* |
CAIRO_STATUS_FILE_NOT_FOUND |
file not found |
#define cairo_status_string cairo_status_string_DEPRECATED_BY_cairo_status_AND_cairo_status_to_string
const char* cairo_status_to_string (cairo_status_t status);
status : |
|
Returns : |
typedef enum _cairo_filter { CAIRO_FILTER_FAST, CAIRO_FILTER_GOOD, CAIRO_FILTER_BEST, CAIRO_FILTER_NEAREST, CAIRO_FILTER_BILINEAR, CAIRO_FILTER_GAUSSIAN } cairo_filter_t;
cairo_surface_t* cairo_image_surface_create (cairo_format_t format, int width, int height);
Creates an image surface of the specified format and
dimensions. The initial contents of the surface is undefined; you
must explicitely clear the buffer, using, for example,
cairo_rectangle()
and cairo_fill()
if you want it cleared.
format : |
format of pixels in the surface to create |
width : |
width of the surface, in pixels |
height : |
height of the surface, in pixels |
Returns : | the newly created surface, or NULL if it couldn't
be created because of lack of memory
|
cairo_surface_t* cairo_image_surface_create_for_data (unsigned char *data, cairo_format_t format, int width, int height, int stride);
Creates an image surface for the provided pixel data. The output
buffer must be kept around until the cairo_surface_t is destroyed
or cairo_surface_finish()
is called on the surface. The initial
contents of buffer
will be used as the inital image contents; you
must explicitely clear the buffer, using, for example,
cairo_rectangle()
and cairo_fill()
if you want it cleared.
data : |
a pointer to a buffer supplied by the application in which to write contents. |
format : |
the format of pixels in the buffer |
width : |
the width of the image to be stored in the buffer |
height : |
the height of the image to be stored in the buffer |
stride : |
the number of bytes between the start of rows
in the buffer. Having this be specified separate from width
allows for padding at the end of rows, or for writing
to a subportion of a larger image.
|
Returns : | the newly created surface, or NULL if it couldn't
be created because of lack of memory
|
int cairo_image_surface_get_width (cairo_surface_t *surface);
Get the width of the image surface in pixels.
surface : |
a cairo_image_surface_t |
Returns : | the width of the surface in pixels. |
int cairo_image_surface_get_height (cairo_surface_t *surface);
Get the height of the image surface in pixels.
surface : |
a cairo_image_surface_t |
Returns : | the height of the surface in pixels. |
void (*cairo_destroy_func_t) (void *data);
cairo_destroy_func_t the type of function which is called when a data element is destroyed. It is passed the pointer to the data element and should free any memory and resources allocated for it.
data : |
The data element being destroyed. |
typedef struct { int unused; } cairo_user_data_key_t;
cairo_user_data_key_t is used for attaching user data to cairo data structures. The actual contents of the struct is never used, and there is no need to initialize the object; only the unique address of a cairo_data_key_t object is used. Typically, you would just use the address of a static cairo_data_key_t object.
int unused ; |
not used; ignore. |
cairo_status_t (*cairo_read_func_t) (void *closure, unsigned char *data, unsigned int length);
cairo_read_func_t is the type of function which is called when a backend needs to read data from an intput stream. It is passed the closure which was specified by the user at the time the read function was registered, the buffer to read the data into and the length of the data in bytes. The read function should return CAIRO_STATUS_SUCCESS if all the data was successfully read, CAIRO_STATUS_READ_ERROR otherwise.
closure : |
the input closure |
data : |
the buffer into which to read the data |
length : |
the amount of data to read |
Returns : | the status code of the read operation |
cairo_status_t (*cairo_write_func_t) (void *closure, unsigned char *data, unsigned int length);
cairo_write_func_t is the type of function which is called when a backend needs to write data to an output stream. It is passed the closure which was specified by the user at the time the write function was registered, the data to write and the length of the data in bytes. The write function should return CAIRO_STATUS_SUCCESS if all the data was successfully written, CAIRO_STATUS_WRITE_ERROR otherwise.
closure : |
the output closure |
data : |
the buffer containing the data to write |
length : |
the amount of data to write |
Returns : | the status code of the write operation |
<< Part 2. Reference | cairo_surface_t >> |