Fonts

Fonts — Font Handling

Synopsis




typedef     cairo_font_face_t;
typedef     cairo_scaled_font_t;
void        cairo_font_face_reference       (cairo_font_face_t *font_face);
void        cairo_font_face_destroy         (cairo_font_face_t *font_face);
void*       cairo_font_face_get_user_data   (cairo_font_face_t *font_face,
                                             const cairo_user_data_key_t *key);
cairo_status_t cairo_font_face_set_user_data
                                            (cairo_font_face_t *font_face,
                                             const cairo_user_data_key_t *key,
                                             void *user_data,
                                             cairo_destroy_func_t destroy);
cairo_scaled_font_t* cairo_scaled_font_create
                                            (cairo_font_face_t *font_face,
                                             const cairo_matrix_t *font_matrix,
                                             const cairo_matrix_t *ctm,
                                             const cairo_font_options_t *options);
void        cairo_scaled_font_reference     (cairo_scaled_font_t *scaled_font);
void        cairo_scaled_font_destroy       (cairo_scaled_font_t *scaled_font);
            cairo_font_extents_t;
void        cairo_scaled_font_extents       (cairo_scaled_font_t *scaled_font,
                                             cairo_font_extents_t *extents);
            cairo_text_extents_t;
void        cairo_scaled_font_glyph_extents (cairo_scaled_font_t *scaled_font,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs,
                                             cairo_text_extents_t *extents);
typedef     cairo_font_options_t;
cairo_font_options_t* cairo_font_options_create
                                            (void);
cairo_font_options_t* cairo_font_options_copy
                                            (const cairo_font_options_t *original);
void        cairo_font_options_destroy      (cairo_font_options_t *options);
cairo_status_t cairo_font_options_status    (cairo_font_options_t *options);
void        cairo_font_options_merge        (cairo_font_options_t *options,
                                             const cairo_font_options_t *other);
unsigned long cairo_font_options_hash       (const cairo_font_options_t *options);
cairo_bool_t cairo_font_options_equal       (const cairo_font_options_t *options,
                                             const cairo_font_options_t *other);
enum        cairo_antialias_t;
void        cairo_font_options_set_antialias
                                            (cairo_font_options_t *options,
                                             cairo_antialias_t antialias);
cairo_antialias_t cairo_font_options_get_antialias
                                            (const cairo_font_options_t *options);
enum        cairo_subpixel_order_t;
void        cairo_font_options_set_subpixel_order
                                            (cairo_font_options_t *options,
                                             cairo_subpixel_order_t subpixel_order);
cairo_subpixel_order_t cairo_font_options_get_subpixel_order
                                            (const cairo_font_options_t *options);
enum        cairo_hint_style_t;
void        cairo_font_options_set_hint_style
                                            (cairo_font_options_t *options,
                                             cairo_hint_style_t hint_style);
cairo_hint_style_t cairo_font_options_get_hint_style
                                            (const cairo_font_options_t *options);
enum        cairo_hint_metrics_t;
void        cairo_font_options_set_hint_metrics
                                            (cairo_font_options_t *options,
                                             cairo_hint_metrics_t hint_metrics);
cairo_hint_metrics_t cairo_font_options_get_hint_metrics
                                            (const cairo_font_options_t *options);

Description

Details

cairo_font_face_t

typedef struct _cairo_font_face cairo_font_face_t;

A cairo_font_face_t specifies all aspects of a font other than the size or font matrix (a font matrix is used to distort a font by sheering it or scaling it unequally in the two directions) . A font face can be set on a cairo_t by using cairo_set_font_face(); the size and font matrix are set with cairo_set_font_size() and cairo_set_font_matrix().


cairo_scaled_font_t

typedef struct _cairo_scaled_font cairo_scaled_font_t;

A cairo_scaled_font_t is a font scaled to a particular size and device resolution. A cairo_scaled_font_t is most useful for low-level font usage where a library or application wants to cache a reference to a scaled font to speed up the computation of metrics.


cairo_font_face_reference ()

void        cairo_font_face_reference       (cairo_font_face_t *font_face);

Increases the reference count on font_face by one. This prevents font_face from being destroyed until a matching call to cairo_font_face_destroy() is made.

font_face : a cairo_font_face_t, (may be NULL in which case this function does nothing).

cairo_font_face_destroy ()

void        cairo_font_face_destroy         (cairo_font_face_t *font_face);

Decreases the reference count on font_face by one. If the result is zero, then font_face and all associated resources are freed. See cairo_font_face_reference().

font_face : a cairo_font_face_t

cairo_font_face_get_user_data ()

void*       cairo_font_face_get_user_data   (cairo_font_face_t *font_face,
                                             const cairo_user_data_key_t *key);

Return user data previously attached to font_face using the specified key. If no user data has been attached with the given key this function returns NULL.

font_face : a cairo_font_face_t
key : the address of the cairo_user_data_key_t the user data was attached to
Returns : the user data previously attached or NULL.

cairo_font_face_set_user_data ()

cairo_status_t cairo_font_face_set_user_data
                                            (cairo_font_face_t *font_face,
                                             const cairo_user_data_key_t *key,
                                             void *user_data,
                                             cairo_destroy_func_t destroy);

Attach user data to font_face. To remove user data from a font face, call this function with the key that was used to set it and NULL for data.

font_face : a cairo_font_face_t
key : the address of a cairo_user_data_key_t to attach the user data to
user_data : the user data to attach to the font face
destroy : a cairo_destroy_func_t which will be called when the font face is destroyed or when new user data is attached using the same key.
Returns : CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a slot could not be allocated for the user data.

cairo_scaled_font_create ()

cairo_scaled_font_t* cairo_scaled_font_create
                                            (cairo_font_face_t *font_face,
                                             const cairo_matrix_t *font_matrix,
                                             const cairo_matrix_t *ctm,
                                             const cairo_font_options_t *options);

Creates a cairo_scaled_font_t object from a font face and matrices that describe the size of the font and the environment in which it will be used.

font_face : a cairo_font_face_t
font_matrix : font space to user space transformation matrix for the font. In the simplest case of a N point font, this matrix is just a scale by N, but it can also be used to shear the font or stretch it unequally along the two axes. See cairo_set_font_matrix().
ctm : user to device transformation matrix with which the font will be used.
options : options to use when getting metrics for the font and rendering with it.
Returns : a newly created cairo_scaled_font_t. Destroy with cairo_scaled_font_destroy()

cairo_scaled_font_reference ()

void        cairo_scaled_font_reference     (cairo_scaled_font_t *scaled_font);

Increases the reference count on scaled_font by one. This prevents scaled_font from being destroyed until a matching call to cairo_scaled_font_destroy() is made.

scaled_font : a cairo_scaled_font_t, (may be NULL in which case this function does nothing)

cairo_scaled_font_destroy ()

void        cairo_scaled_font_destroy       (cairo_scaled_font_t *scaled_font);

Decreases the reference count on font by one. If the result is zero, then font and all associated resources are freed. See cairo_scaled_font_reference().

scaled_font : a cairo_scaled_font_t

cairo_font_extents_t

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

The cairo_text_extents_t structure stores metric information for a font. Values are given in the current user-space coordinate system.

Because font metrics are in user-space coordinates, they are mostly, but not entirely, independent of 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 ascent; the distance that the font extends above the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the font should align with elements above it.
double descent; the distance that the font extends below the baseline. This value is positive for typical fonts that include portions below the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the the font should align with elements below it.
double height; the recommended vertical distance between baselines when setting consecutive lines of text with the font. This is greater than ascent+descent by a quantity known as the line spacing or external leading. When space is at a premium, most fonts can be set with only a distance of ascent+descent between lines.
double max_x_advance; the maximum distance in the X direction that the the origin is advanced for any glyph in the font.
double max_y_advance; the maximum distance in the Y direction that the the origin is advanced for any glyph in the font. this will be zero for normal fonts used for horizontal writing. (The scripts of East Asia are sometimes written vertically.)

cairo_scaled_font_extents ()

void        cairo_scaled_font_extents       (cairo_scaled_font_t *scaled_font,
                                             cairo_font_extents_t *extents);

Gets the metrics for a cairo_scaled_font_t.

scaled_font : a cairo_scaled_font_t
extents : a cairo_font_extents_t which to store the retrieved extents.

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 are mostly, but not entirely, independent of 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_scaled_font_glyph_extents ()

void        cairo_scaled_font_glyph_extents (cairo_scaled_font_t *scaled_font,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs,
                                             cairo_text_extents_t *extents);

scaled_font :
glyphs :
num_glyphs :
extents :

cairo_font_options_t

typedef struct _cairo_font_options cairo_font_options_t;


cairo_font_options_create ()

cairo_font_options_t* cairo_font_options_create
                                            (void);

Allocates a new font options object with all options initialized to default values.

Returns : a newly allocated cairo_font_options_t. Free with cairo_font_options_destroy(). This function always returns a valid pointer; if memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with cairo_font_options_status().

cairo_font_options_copy ()

cairo_font_options_t* cairo_font_options_copy
                                            (const cairo_font_options_t *original);

Allocates a new font options object copying the option values from original.

original : a cairo_font_options_t
Returns : a newly allocated cairo_font_options_t. Free with cairo_font_options_destroy(). This function always returns a valid pointer; if memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with cairo_font_options_status().

cairo_font_options_destroy ()

void        cairo_font_options_destroy      (cairo_font_options_t *options);

Destroys a cairo_font_options_t object created with with cairo_font_options_create() or cairo_font_options_copy().

options : a cairo_font_options_t

cairo_font_options_status ()

cairo_status_t cairo_font_options_status    (cairo_font_options_t *options);

Checks whether an error has previously occurred for this font options object

options : a cairo_font_options_t
Returns : CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY

cairo_font_options_merge ()

void        cairo_font_options_merge        (cairo_font_options_t *options,
                                             const cairo_font_options_t *other);

Merges non-default options from other into options, replacing existing values. This operation can be thought of as somewhat similar to compositing other onto options with the operation of CAIRO_OPERATION_OVER.

options : a cairo_font_options_t
other : another cairo_font_options_t

cairo_font_options_hash ()

unsigned long cairo_font_options_hash       (const cairo_font_options_t *options);

Compute a hash for the font options object; this value will be useful when storing an object containing a cairo_font_options_t in a hash table.

options : a cairo_font_options_t
Returns : the hash value for the font options object. The return value can be cast to a 32-bit type if a 32-bit hash value is needed.

cairo_font_options_equal ()

cairo_bool_t cairo_font_options_equal       (const cairo_font_options_t *options,
                                             const cairo_font_options_t *other);

Compares two font options objects for equality.

options : a cairo_font_options_t
other : another cairo_font_options_t
Returns : TRUE if all fields of the two font options objects match

enum cairo_antialias_t

typedef enum _cairo_antialias {
    CAIRO_ANTIALIAS_DEFAULT,
    CAIRO_ANTIALIAS_NONE,
    CAIRO_ANTIALIAS_GRAY,
    CAIRO_ANTIALIAS_SUBPIXEL
} cairo_antialias_t;

Specifies the type of antialiasing to do when rendering text.

CAIRO_ANTIALIAS_DEFAULT Use the default antialiasing for the font subsystem and target device
CAIRO_ANTIALIAS_NONE Do no antialiasing of fonts; use bilevel text
CAIRO_ANTIALIAS_GRAY Perform single-color antialiasing (using shades of gray for black text on a white background, for example).
CAIRO_ANTIALIAS_SUBPIXEL Perform antialiasing by taking advantage of the order of subpixel elements on devices such as LCD panels

cairo_font_options_set_antialias ()

void        cairo_font_options_set_antialias
                                            (cairo_font_options_t *options,
                                             cairo_antialias_t antialias);

Sets the antiliasing mode for the font options object. This specifies the type of antialiasing to do when rendering text.

options : a cairo_font_options_t
antialias : the new antialiasing mode

cairo_font_options_get_antialias ()

cairo_antialias_t cairo_font_options_get_antialias
                                            (const cairo_font_options_t *options);

Gets the antialising mode for the font options object.

options : a cairo_font_options_t
Returns : the antialiasing mode

enum cairo_subpixel_order_t

typedef enum _cairo_subpixel_order {
    CAIRO_SUBPIXEL_ORDER_DEFAULT,
    CAIRO_SUBPIXEL_ORDER_RGB,
    CAIRO_SUBPIXEL_ORDER_BGR,
    CAIRO_SUBPIXEL_ORDER_VRGB,
    CAIRO_SUBPIXEL_ORDER_VBGR
} cairo_subpixel_order_t;

The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of CAIRO_ANTIALIAS_SUBPIXEL.

CAIRO_SUBPIXEL_ORDER_DEFAULT Use the default subpixel order for for the target device
CAIRO_SUBPIXEL_ORDER_RGB Subpixel elements are arranged horizontally with red at the left
CAIRO_SUBPIXEL_ORDER_BGR Subpixel elements are arranged horizontally with blue at the left
CAIRO_SUBPIXEL_ORDER_VRGB Subpixel elements are arranged vertically with red at the top
CAIRO_SUBPIXEL_ORDER_VBGR Subpixel elements are arranged vertically with blue at the top

cairo_font_options_set_subpixel_order ()

void        cairo_font_options_set_subpixel_order
                                            (cairo_font_options_t *options,
                                             cairo_subpixel_order_t subpixel_order);

Sets the subpixel order for the font options object. The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of CAIRO_ANTIALIAS_SUBPIXEL. See the documentation for cairo_subpixel_order_t for full details.

options : a cairo_font_options_t
subpixel_order : the new subpixel order

cairo_font_options_get_subpixel_order ()

cairo_subpixel_order_t cairo_font_options_get_subpixel_order
                                            (const cairo_font_options_t *options);

Gets the subpixel order for the font options object. See the documentation for cairo_subpixel_order_t for full details.

options : a cairo_font_options_t
Returns : the subpixel order for the font options object

enum cairo_hint_style_t

typedef enum _cairo_hint_style {
    CAIRO_HINT_STYLE_DEFAULT,
    CAIRO_HINT_STYLE_NONE,
    CAIRO_HINT_STYLE_SLIGHT,
    CAIRO_HINT_STYLE_MEDIUM,
    CAIRO_HINT_STYLE_FULL
} cairo_hint_style_t;

Specifies the type of hinting to do on font outlines. Hinting is the process of fitting outlines to the pixel grid in order to improve the appearance of the result. Since hinting outlines involves distorting them, it also reduces the faithfulness to the original outline shapes. Not all of the outline hinting styles are supported by all font backends.

CAIRO_HINT_STYLE_DEFAULT Use the default hint style for for font backend and target device
CAIRO_HINT_STYLE_NONE Do not hint outlines
CAIRO_HINT_STYLE_SLIGHT Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes.
CAIRO_HINT_STYLE_MEDIUM Hint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast
CAIRO_HINT_STYLE_FULL Hint outlines to maximize contrast

cairo_font_options_set_hint_style ()

void        cairo_font_options_set_hint_style
                                            (cairo_font_options_t *options,
                                             cairo_hint_style_t hint_style);

Sets the hint style for font outlines for the font options object. This controls whether to fit font outlines to the pixel grid, and if so, whether to optimize for fidelity or contrast. See the documentation for cairo_hint_style_t for full details.

options : a cairo_font_options_t
hint_style : the new hint style

cairo_font_options_get_hint_style ()

cairo_hint_style_t cairo_font_options_get_hint_style
                                            (const cairo_font_options_t *options);

Gets the hint style for font outlines for the font options object. See the documentation for cairo_hint_style_t for full details.

options : a cairo_font_options_t
Returns : the hint style for the font options object

enum cairo_hint_metrics_t

typedef enum _cairo_hint_metrics {
    CAIRO_HINT_METRICS_DEFAULT,
    CAIRO_HINT_METRICS_OFF,
    CAIRO_HINT_METRICS_ON
} cairo_hint_metrics_t;

Specifies whether to hint font metrics; hinting font metrics means quantizing them so that they are integer values in device space. Doing this improves the consistency of letter and line spacing, however it also means that text will be laid out differently at different zoom factors.

CAIRO_HINT_METRICS_DEFAULT Hint metrics in the default manner for the font backend and target device
CAIRO_HINT_METRICS_OFF Do not hint font metrics
CAIRO_HINT_METRICS_ON Hint font metrics

cairo_font_options_set_hint_metrics ()

void        cairo_font_options_set_hint_metrics
                                            (cairo_font_options_t *options,
                                             cairo_hint_metrics_t hint_metrics);

Sets the metrics hinting mode for the font options object. This controls whether metrics are quantized to integer values in device units. See the documentation for cairo_hint_metrics_t for full details.

options : a cairo_font_options_t
hint_metrics : the new metrics hinting mode

cairo_font_options_get_hint_metrics ()

cairo_hint_metrics_t cairo_font_options_get_hint_metrics
                                            (const cairo_font_options_t *options);

Gets the metrics hinting mode for the font options object. See the documentation for cairo_hint_metrics_t for full details.

options : a cairo_font_options_t
Returns : the metrics hinting mode for the font options object