cairo_t

cairo_t — Drawing contexts.

Synopsis




typedef     cairo_t;
cairo_t*    cairo_create                    (void);
void        cairo_reference                 (cairo_t *cr);
void        cairo_destroy                   (cairo_t *cr);
void        cairo_save                      (cairo_t *cr);
void        cairo_restore                   (cairo_t *cr);
void        cairo_copy                      (cairo_t *dest,
                                             cairo_t *src);
void        cairo_set_target_surface        (cairo_t *cr,
                                             cairo_surface_t *surface);
enum        cairo_format_t;
void        cairo_set_target_image          (cairo_t *cr,
                                             char *data,
                                             cairo_format_t format,
                                             int width,
                                             int height,
                                             int stride);
enum        cairo_operator_t;
void        cairo_set_operator              (cairo_t *cr,
                                             cairo_operator_t op);
void        cairo_set_rgb_color             (cairo_t *cr,
                                             double red,
                                             double green,
                                             double blue);
void        cairo_set_pattern               (cairo_t *cr,
                                             cairo_pattern_t *pattern);
void        cairo_set_alpha                 (cairo_t *cr,
                                             double alpha);
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_concat_matrix             (cairo_t *cr,
                                             cairo_matrix_t *matrix);
void        cairo_set_matrix                (cairo_t *cr,
                                             cairo_matrix_t *matrix);
void        cairo_default_matrix            (cairo_t *cr);
void        cairo_identity_matrix           (cairo_t *cr);
void        cairo_transform_point           (cairo_t *cr,
                                             double *x,
                                             double *y);
void        cairo_transform_distance        (cairo_t *cr,
                                             double *dx,
                                             double *dy);
void        cairo_inverse_transform_point   (cairo_t *cr,
                                             double *x,
                                             double *y);
void        cairo_inverse_transform_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_stroke                    (cairo_t *cr);
void        cairo_fill                      (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_init_clip                 (cairo_t *cr);
void        cairo_clip                      (cairo_t *cr);
typedef     cairo_font_t;
            cairo_glyph_t;
            cairo_text_extents_t;
            cairo_font_extents_t;
enum        cairo_font_slant_t;
enum        cairo_font_weight_t;
void        cairo_select_font               (cairo_t *cr,
                                             const char *family,
                                             cairo_font_slant_t slant,
                                             cairo_font_weight_t weight);
void        cairo_scale_font                (cairo_t *cr,
                                             double scale);
void        cairo_transform_font            (cairo_t *cr,
                                             cairo_matrix_t *matrix);
void        cairo_show_text                 (cairo_t *cr,
                                             unsigned char *utf8);
void        cairo_show_glyphs               (cairo_t *cr,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs);
cairo_font_t* cairo_current_font            (cairo_t *cr);
void        cairo_current_font_extents      (cairo_t *cr,
                                             cairo_font_extents_t *extents);
void        cairo_set_font                  (cairo_t *cr,
                                             cairo_font_t *font);
void        cairo_text_extents              (cairo_t *cr,
                                             unsigned 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,
                                             unsigned char *utf8);
void        cairo_glyph_path                (cairo_t *cr,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs);
void        cairo_font_reference            (cairo_font_t *font);
void        cairo_font_destroy              (cairo_font_t *font);
cairo_status_t cairo_font_extents           (cairo_font_t *font,
                                             cairo_matrix_t *font_matrix,
                                             cairo_font_extents_t *extents);
void        cairo_font_glyph_extents        (cairo_font_t *font,
                                             cairo_matrix_t *font_matrix,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs,
                                             cairo_text_extents_t *extents);
void        cairo_show_surface              (cairo_t *cr,
                                             cairo_surface_t *surface,
                                             int width,
                                             int height);
cairo_operator_t cairo_current_operator     (cairo_t *cr);
void        cairo_current_rgb_color         (cairo_t *cr,
                                             double *red,
                                             double *green,
                                             double *blue);
cairo_pattern_t* cairo_current_pattern      (cairo_t *cr);
double      cairo_current_alpha             (cairo_t *cr);
double      cairo_current_tolerance         (cairo_t *cr);
void        cairo_current_point             (cairo_t *cr,
                                             double *x,
                                             double *y);
cairo_fill_rule_t cairo_current_fill_rule   (cairo_t *cr);
double      cairo_current_line_width        (cairo_t *cr);
cairo_line_cap_t cairo_current_line_cap     (cairo_t *cr);
cairo_line_join_t cairo_current_line_join   (cairo_t *cr);
double      cairo_current_miter_limit       (cairo_t *cr);
void        cairo_current_matrix            (cairo_t *cr,
                                             cairo_matrix_t *matrix);
cairo_surface_t* cairo_current_target_surface
                                            (cairo_t *cr);
void        cairo_current_path              (cairo_t *cr,
                                             cairo_move_to_func_t *move_to,
                                             cairo_line_to_func_t *line_to,
                                             cairo_curve_to_func_t *curve_to,
                                             cairo_close_path_func_t *close_path,
                                             void *closure);
void        cairo_current_path_flat         (cairo_t *cr,
                                             cairo_move_to_func_t *move_to,
                                             cairo_line_to_func_t *line_to,
                                             cairo_close_path_func_t *close_path,
                                             void *closure);
enum        cairo_status_t;
cairo_status_t cairo_status                 (cairo_t *cr);
const char* cairo_status_string             (cairo_t *cr);
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
                                            (char *data,
                                             cairo_format_t format,
                                             int width,
                                             int height,
                                             int stride);

Description

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.

Details

cairo_t

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

cairo_t*    cairo_create                    (void);

Creates a new cairo_t with default values. The target surface must be set on the cairo_t with cairo_set_target_surface(), or a backend-specific function like cairo_set_target_image() before drawing with the cairo_t.

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.

cairo_reference ()

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

cairo_destroy ()

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

cr : a cairo_t

cairo_save ()

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

cairo_restore ()

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

cairo_copy ()

void        cairo_copy                      (cairo_t *dest,
                                             cairo_t *src);

This function copies all current state information from src to dest. This includes the current point and path, the target surface, the transformation matrix, and so forth.

The stack of states saved with cairo_save() is not not copied; nor are any saved states on dest cleared. The operation only copies the current state of src to the current state of dest.

dest : a cairo_t
src : another cairo_t

cairo_set_target_surface ()

void        cairo_set_target_surface        (cairo_t *cr,
                                             cairo_surface_t *surface);

Directs output for a cairo_t to a given surface. The surface will be referenced by the cairo_t, so you can immediately call cairo_surface_destroy() on it if you don't need to keep a reference to it around.

cr : a cairo_t
surface : a cairo_surface_t

enum cairo_format_t

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 quanties 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.

cairo_set_target_image ()

void        cairo_set_target_image          (cairo_t *cr,
                                             char *data,
                                             cairo_format_t format,
                                             int width,
                                             int height,
                                             int stride);

Directs output for a cairo_t to an in-memory image. The output buffer must be kept around until the cairo_t is destroyed or set to to have a different target. 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.

cr : a cairo_t
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 eight 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.

enum cairo_operator_t

typedef enum cairo_operator { 
    CAIRO_OPERATOR_CLEAR,
    CAIRO_OPERATOR_SRC,
    CAIRO_OPERATOR_DST,
    CAIRO_OPERATOR_OVER,
    CAIRO_OPERATOR_OVER_REVERSE,
    CAIRO_OPERATOR_IN,
    CAIRO_OPERATOR_IN_REVERSE,
    CAIRO_OPERATOR_OUT,
    CAIRO_OPERATOR_OUT_REVERSE,
    CAIRO_OPERATOR_ATOP,
    CAIRO_OPERATOR_ATOP_REVERSE,
    CAIRO_OPERATOR_XOR,
    CAIRO_OPERATOR_ADD,
    CAIRO_OPERATOR_SATURATE
} cairo_operator_t;


cairo_set_operator ()

void        cairo_set_operator              (cairo_t *cr,
                                             cairo_operator_t op);

cr :
op :

cairo_set_rgb_color ()

void        cairo_set_rgb_color             (cairo_t *cr,
                                             double red,
                                             double green,
                                             double blue);

Sets a constant color for filling and stroking. This replaces any pattern set with cairo_set_pattern(). 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_t
red : red component of color
green : green component of color
blue : blue component of color

cairo_set_pattern ()

void        cairo_set_pattern               (cairo_t *cr,
                                             cairo_pattern_t *pattern);

cr :
pattern :

cairo_set_alpha ()

void        cairo_set_alpha                 (cairo_t *cr,
                                             double alpha);

Sets an overall alpha value used for stroking and filling. This value is multiplied with any alpha value coming from a gradient or image pattern.

cr : a cairo_t
alpha : the alpha value. 0 is transparent, 1 fully opaque. if the value is outside the range 0 to 1, it will be clamped to that range.

cairo_set_tolerance ()

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)

enum cairo_fill_rule_t

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.

cairo_set_fill_rule ()

void        cairo_set_fill_rule             (cairo_t *cr,
                                             cairo_fill_rule_t fill_rule);

cr :
fill_rule :

cairo_set_line_width ()

void        cairo_set_line_width            (cairo_t *cr,
                                             double width);

cr :
width :

enum cairo_line_cap_t

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

cairo_set_line_cap ()

void        cairo_set_line_cap              (cairo_t *cr,
                                             cairo_line_cap_t line_cap);

cr :
line_cap :

enum cairo_line_join_t

typedef enum cairo_line_join {
    CAIRO_LINE_JOIN_MITER,
    CAIRO_LINE_JOIN_ROUND,
    CAIRO_LINE_JOIN_BEVEL
} cairo_line_join_t;


cairo_set_line_join ()

void        cairo_set_line_join             (cairo_t *cr,
                                             cairo_line_join_t line_join);

cr :
line_join :

cairo_set_dash ()

void        cairo_set_dash                  (cairo_t *cr,
                                             double *dashes,
                                             int ndash,
                                             double offset);

cr :
dashes :
ndash :
offset :

cairo_set_miter_limit ()

void        cairo_set_miter_limit           (cairo_t *cr,
                                             double limit);

cr :
limit :

cairo_translate ()

void        cairo_translate                 (cairo_t *cr,
                                             double tx,
                                             double ty);

cr :
tx :
ty :

cairo_scale ()

void        cairo_scale                     (cairo_t *cr,
                                             double sx,
                                             double sy);

cr :
sx :
sy :

cairo_rotate ()

void        cairo_rotate                    (cairo_t *cr,
                                             double angle);

cr :
angle :

cairo_concat_matrix ()

void        cairo_concat_matrix             (cairo_t *cr,
                                             cairo_matrix_t *matrix);

cr :
matrix :

cairo_set_matrix ()

void        cairo_set_matrix                (cairo_t *cr,
                                             cairo_matrix_t *matrix);

cr :
matrix :

cairo_default_matrix ()

void        cairo_default_matrix            (cairo_t *cr);

cr :

cairo_identity_matrix ()

void        cairo_identity_matrix           (cairo_t *cr);

cr :

cairo_transform_point ()

void        cairo_transform_point           (cairo_t *cr,
                                             double *x,
                                             double *y);

cr :
x :
y :

cairo_transform_distance ()

void        cairo_transform_distance        (cairo_t *cr,
                                             double *dx,
                                             double *dy);

cr :
dx :
dy :

cairo_inverse_transform_point ()

void        cairo_inverse_transform_point   (cairo_t *cr,
                                             double *x,
                                             double *y);

cr :
x :
y :

cairo_inverse_transform_distance ()

void        cairo_inverse_transform_distance
                                            (cairo_t *cr,
                                             double *dx,
                                             double *dy);

cr :
dx :
dy :

cairo_new_path ()

void        cairo_new_path                  (cairo_t *cr);

cr :

cairo_move_to ()

void        cairo_move_to                   (cairo_t *cr,
                                             double x,
                                             double y);

cr :
x :
y :

cairo_line_to ()

void        cairo_line_to                   (cairo_t *cr,
                                             double x,
                                             double y);

cr :
x :
y :

cairo_curve_to ()

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 :

cairo_arc ()

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

cairo_arc_negative ()

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

cairo_rel_move_to ()

void        cairo_rel_move_to               (cairo_t *cr,
                                             double dx,
                                             double dy);

cr :
dx :
dy :

cairo_rel_line_to ()

void        cairo_rel_line_to               (cairo_t *cr,
                                             double dx,
                                             double dy);

cr :
dx :
dy :

cairo_rel_curve_to ()

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 :

cairo_rectangle ()

void        cairo_rectangle                 (cairo_t *cr,
                                             double x,
                                             double y,
                                             double width,
                                             double height);

cr :
x :
y :
width :
height :

cairo_close_path ()

void        cairo_close_path                (cairo_t *cr);

cr :

cairo_stroke ()

void        cairo_stroke                    (cairo_t *cr);

cr :

cairo_fill ()

void        cairo_fill                      (cairo_t *cr);

cr :

cairo_copy_page ()

void        cairo_copy_page                 (cairo_t *cr);

cr :

cairo_show_page ()

void        cairo_show_page                 (cairo_t *cr);

cr :

cairo_in_stroke ()

cairo_bool_t cairo_in_stroke                (cairo_t *cr,
                                             double x,
                                             double y);

cr :
x :
y :
Returns :

cairo_in_fill ()

cairo_bool_t cairo_in_fill                  (cairo_t *cr,
                                             double x,
                                             double y);

cr :
x :
y :
Returns :

cairo_bool_t

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 explicitely is not encouraged; just use the value as a boolean condition.

 if (cairo_in_stroke (cr, x, y)) {
     /* do something */
 }


cairo_stroke_extents ()

void        cairo_stroke_extents            (cairo_t *cr,
                                             double *x1,
                                             double *y1,
                                             double *x2,
                                             double *y2);

cr :
x1 :
y1 :
x2 :
y2 :

cairo_fill_extents ()

void        cairo_fill_extents              (cairo_t *cr,
                                             double *x1,
                                             double *y1,
                                             double *x2,
                                             double *y2);

cr :
x1 :
y1 :
x2 :
y2 :

cairo_init_clip ()

void        cairo_init_clip                 (cairo_t *cr);

cr :

cairo_clip ()

void        cairo_clip                      (cairo_t *cr);

cr :

cairo_font_t

typedef struct _cairo_font cairo_font_t;

A cairo_font_t is a font scaled to a particular size and device resolution. A font can be set on a cairo_t by using cairo_set_font() assuming that the current transformation and target surface of the cairo_t match that for which the cairo_font_t was created. The effect of using a mismatched cairo_font_t will be incorrect font metrics.


cairo_glyph_t

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.

cairo_text_extents_t

typedef struct {
    double x_bearing;
    double y_bearing;
    double width;
    double height;
    double x_advance;
    double y_advance;
} cairo_text_extents_t;

The cairo_text_extents_t< structure stores the extents of a single glyph or a string of glyphs in user-space coordinates. Because text extents are in user-space coordinates, they don't scale along with the current transformation matrix. If you call cairo_scale(cr, 2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged.

double x_bearing; the horizontal distance from the origin to the leftmost part of the glyphs as drawn. Positive if the glyphs lie entirely to the right of the origin.
double y_bearing; the vertical distance from the origin to the topmost part of the glyphs as drawn. Positive only if the glyphs lie completely below the origin; will usually be negative.
double width; width of the glyphs as drawn
double height; height of the glyphs as drawn
double x_advance;distance to advance in the X direction after drawing these glyphs
double y_advance; distance to advance in the Y direction after drawing these glyphs. Will typically be zero except for vertical text layout as found in East-Asian languages.

cairo_font_extents_t

typedef struct {
    double ascent;
    double descent;
    double height;
    double max_x_advance;
    double max_y_advance;
} cairo_font_extents_t;


enum cairo_font_slant_t

typedef enum cairo_font_slant {
  CAIRO_FONT_SLANT_NORMAL,
  CAIRO_FONT_SLANT_ITALIC,
  CAIRO_FONT_SLANT_OBLIQUE
} cairo_font_slant_t;


enum cairo_font_weight_t

typedef enum cairo_font_weight {
  CAIRO_FONT_WEIGHT_NORMAL,
  CAIRO_FONT_WEIGHT_BOLD
} cairo_font_weight_t;


cairo_select_font ()

void        cairo_select_font               (cairo_t *cr,
                                             const char *family,
                                             cairo_font_slant_t slant,
                                             cairo_font_weight_t weight);

cr :
family :
slant :
weight :

cairo_scale_font ()

void        cairo_scale_font                (cairo_t *cr,
                                             double scale);

cr :
scale :

cairo_transform_font ()

void        cairo_transform_font            (cairo_t *cr,
                                             cairo_matrix_t *matrix);

cr :
matrix :

cairo_show_text ()

void        cairo_show_text                 (cairo_t *cr,
                                             unsigned char *utf8);

cr :
utf8 :

cairo_show_glyphs ()

void        cairo_show_glyphs               (cairo_t *cr,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs);

cr :
glyphs :
num_glyphs :

cairo_current_font ()

cairo_font_t* cairo_current_font            (cairo_t *cr);

Gets the current font object for a cairo_t. If there is no current font object, because the font parameters, transform, or target surface has been changed since a font was last used, a font object will be created and stored in in the 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_reference().

cairo_current_font_extents ()

void        cairo_current_font_extents      (cairo_t *cr,
                                             cairo_font_extents_t *extents);

cr :
extents :

cairo_set_font ()

void        cairo_set_font                  (cairo_t *cr,
                                             cairo_font_t *font);

Replaces the current cairo_font_t object in the cairo_t with font. The replaced font in the cairo_t will be destroyed if there are no other references to it. Since a cairo_font_t is specific to a particular output device and size, changing the transformation, font transformation, or target surfaces of a cairo_t will clear any previously set font. Setting the font using cairo_set_font() is exclusive with the simple font selection API provided by cairo_select_font(). The size and transformation set by cairo_scale_font() and cairo_transform_font() are ignored unless they were taken into account when creating font.

cr : a cairo_t
font : a cairo_font_t, or NULL to unset any previously set font.

cairo_text_extents ()

void        cairo_text_extents              (cairo_t *cr,
                                             unsigned char *utf8,
                                             cairo_text_extents_t *extents);

cr :
utf8 :
extents :

cairo_glyph_extents ()

void        cairo_glyph_extents             (cairo_t *cr,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs,
                                             cairo_text_extents_t *extents);

cr :
glyphs :
num_glyphs :
extents :

cairo_text_path ()

void        cairo_text_path                 (cairo_t *cr,
                                             unsigned char *utf8);

cr :
utf8 :

cairo_glyph_path ()

void        cairo_glyph_path                (cairo_t *cr,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs);

cr :
glyphs :
num_glyphs :

cairo_font_reference ()

void        cairo_font_reference            (cairo_font_t *font);

font :

cairo_font_destroy ()

void        cairo_font_destroy              (cairo_font_t *font);

font :

cairo_font_extents ()

cairo_status_t cairo_font_extents           (cairo_font_t *font,
                                             cairo_matrix_t *font_matrix,
                                             cairo_font_extents_t *extents);

Gets the metrics for a cairo_font_t.

font : a cairo_font_t
font_matrix : the font transformation for which this font was created. (See cairo_transform_font()). This is needed properly convert the metrics from the font into user space.
extents : a cairo_font_extents_t which to store the retrieved extents.
Returns : CAIRO_STATUS_SUCCESS on success. Otherwise, an error such as CAIRO_STATUS_NO_MEMORY.

cairo_font_glyph_extents ()

void        cairo_font_glyph_extents        (cairo_font_t *font,
                                             cairo_matrix_t *font_matrix,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs,
                                             cairo_text_extents_t *extents);

cairo_font_glyph_extents() gets the overall metrics for a string of glyphs. The X and Y offsets in glyphs are taken from an origin of 0,0.

font : a cairo_font_t
font_matrix : the font transformation for which this font was created. (See cairo_transform_font()). This is needed properly convert the metrics from the font into user space.
glyphs : an array of glyph IDs with X and Y offsets.
num_glyphs : the number of glyphs in the glyphs array
extents : a cairo_text_extents_t which to store the retrieved extents.

cairo_show_surface ()

void        cairo_show_surface              (cairo_t *cr,
                                             cairo_surface_t *surface,
                                             int width,
                                             int height);

cr :
surface :
width :
height :

cairo_current_operator ()

cairo_operator_t cairo_current_operator     (cairo_t *cr);

cr :
Returns :

cairo_current_rgb_color ()

void        cairo_current_rgb_color         (cairo_t *cr,
                                             double *red,
                                             double *green,
                                             double *blue);

cr :
red :
green :
blue :

cairo_current_pattern ()

cairo_pattern_t* cairo_current_pattern      (cairo_t *cr);

cr :
Returns :

cairo_current_alpha ()

double      cairo_current_alpha             (cairo_t *cr);

cr :
Returns :

cairo_current_tolerance ()

double      cairo_current_tolerance         (cairo_t *cr);

cr :
Returns :

cairo_current_point ()

void        cairo_current_point             (cairo_t *cr,
                                             double *x,
                                             double *y);

cr :
x :
y :

cairo_current_fill_rule ()

cairo_fill_rule_t cairo_current_fill_rule   (cairo_t *cr);

cr :
Returns :

cairo_current_line_width ()

double      cairo_current_line_width        (cairo_t *cr);

cr :
Returns :

cairo_current_line_cap ()

cairo_line_cap_t cairo_current_line_cap     (cairo_t *cr);

cr :
Returns :

cairo_current_line_join ()

cairo_line_join_t cairo_current_line_join   (cairo_t *cr);

cr :
Returns :

cairo_current_miter_limit ()

double      cairo_current_miter_limit       (cairo_t *cr);

cr :
Returns :

cairo_current_matrix ()

void        cairo_current_matrix            (cairo_t *cr,
                                             cairo_matrix_t *matrix);

cr :
matrix :

cairo_current_target_surface ()

cairo_surface_t* cairo_current_target_surface
                                            (cairo_t *cr);

cr :
Returns :

cairo_current_path ()

void        cairo_current_path              (cairo_t *cr,
                                             cairo_move_to_func_t *move_to,
                                             cairo_line_to_func_t *line_to,
                                             cairo_curve_to_func_t *curve_to,
                                             cairo_close_path_func_t *close_path,
                                             void *closure);

cr :
move_to :
line_to :
curve_to :
close_path :
closure :

cairo_current_path_flat ()

void        cairo_current_path_flat         (cairo_t *cr,
                                             cairo_move_to_func_t *move_to,
                                             cairo_line_to_func_t *line_to,
                                             cairo_close_path_func_t *close_path,
                                             void *closure);

cr :
move_to :
line_to :
close_path :
closure :

enum cairo_status_t

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_NO_TARGET_SURFACE,
    CAIRO_STATUS_NULL_POINTER,
    CAIRO_STATUS_INVALID_STRING
} cairo_status_t;


cairo_status ()

cairo_status_t cairo_status                 (cairo_t *cr);

cr :
Returns :

cairo_status_string ()

const char* cairo_status_string             (cairo_t *cr);

cr :
Returns :

enum cairo_filter_t

typedef enum {
    CAIRO_FILTER_FAST,
    CAIRO_FILTER_GOOD,
    CAIRO_FILTER_BEST,
    CAIRO_FILTER_NEAREST,
    CAIRO_FILTER_BILINEAR,
    CAIRO_FILTER_GAUSSIAN
} cairo_filter_t;


cairo_image_surface_create ()

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

cairo_surface_t* cairo_image_surface_create_for_data
                                            (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