cairo_font_options_t

cairo_font_options_t — How a font should be rendered

Functions

Types and Values

Description

The font options specify how fonts should be rendered. Most of the time the font options implied by a surface are just right and do not need any changes, but for pixel-based targets tweaking font options may result in superior output on a particular display.

Functions

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

Since: 1.0


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 .

Parameters

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

Since: 1.0


cairo_font_options_destroy ()

void
cairo_font_options_destroy (cairo_font_options_t *options);

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

Parameters

options

a cairo_font_options_t

 

Since: 1.0


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

Parameters

options

a cairo_font_options_t

 

Since: 1.0


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

Parameters

options

a cairo_font_options_t

 

other

another cairo_font_options_t

 

Since: 1.0


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.

Parameters

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.

Since: 1.0


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.

Parameters

options

a cairo_font_options_t

 

other

another cairo_font_options_t

 

Returns

TRUE if all fields of the two font options objects match. Note that this function will return FALSE if either object is in error.

Since: 1.0


cairo_font_options_set_antialias ()

void
cairo_font_options_set_antialias (cairo_font_options_t *options,
                                  cairo_antialias_t antialias);

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

Parameters

options

a cairo_font_options_t

 

antialias

the new antialiasing mode

 

Since: 1.0


cairo_font_options_get_antialias ()

cairo_antialias_t
cairo_font_options_get_antialias (const cairo_font_options_t *options);

Gets the antialiasing mode for the font options object.

Parameters

options

a cairo_font_options_t

 

Returns

the antialiasing mode

Since: 1.0


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.

Parameters

options

a cairo_font_options_t

 

subpixel_order

the new subpixel order

 

Since: 1.0


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.

Parameters

options

a cairo_font_options_t

 

Returns

the subpixel order for the font options object

Since: 1.0


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.

Parameters

options

a cairo_font_options_t

 

hint_style

the new hint style

 

Since: 1.0


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.

Parameters

options

a cairo_font_options_t

 

Returns

the hint style for the font options object

Since: 1.0


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.

Parameters

options

a cairo_font_options_t

 

hint_metrics

the new metrics hinting mode

 

Since: 1.0


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.

Parameters

options

a cairo_font_options_t

 

Returns

the metrics hinting mode for the font options object

Since: 1.0


cairo_font_options_get_variations ()

const char *
cairo_font_options_get_variations (cairo_font_options_t *options);

Gets the OpenType font variations for the font options object. See cairo_font_options_set_variations() for details about the string format.

Parameters

options

a cairo_font_options_t

 

Returns

the font variations for the font options object. The returned string belongs to the options and must not be modified. It is valid until either the font options object is destroyed or the font variations in this object is modified with cairo_font_options_set_variations().

Since: 1.16


cairo_font_options_set_variations ()

void
cairo_font_options_set_variations (cairo_font_options_t *options,
                                   const char *variations);

Sets the OpenType font variations for the font options object. Font variations are specified as a string with a format that is similar to the CSS font-variation-settings. The string contains a comma-separated list of axis assignments, which each assignment consists of a 4-character axis name and a value, separated by whitespace and optional equals sign.

Examples:

wght=200,wdth=140.5

wght 200 , wdth 140.5

Parameters

options

a cairo_font_options_t

 

variations

the new font variations, or NULL

 

Since: 1.16


cairo_font_options_set_color_mode ()

void
cairo_font_options_set_color_mode (cairo_font_options_t *options,
                                   cairo_color_mode_t color_mode);

Sets the color mode for the font options object. This controls whether color fonts are to be rendered in color or as outlines. See the documentation for cairo_color_mode_t for full details.

Parameters

options

a cairo_font_options_t

 

color_mode

the new color mode

 

Since: 1.18


cairo_font_options_get_color_mode ()

cairo_color_mode_t
cairo_font_options_get_color_mode (const cairo_font_options_t *options);

Gets the color mode for the font options object. See the documentation for cairo_color_mode_t for full details.

Parameters

options

a cairo_font_options_t

 

Returns

the color mode for the font options object

Since: 1.18


cairo_font_options_set_color_palette ()

void
cairo_font_options_set_color_palette (cairo_font_options_t *options,
                                      unsigned int palette_index);

Sets the OpenType font color palette for the font options object. OpenType color fonts with a CPAL table may contain multiple palettes. The default color palette index is CAIRO_COLOR_PALETTE_DEFAULT.

If palette_index is invalid, the default palette is used.

Individual colors within the palette may be overriden with cairo_font_options_set_custom_palette_color().

Parameters

options

a cairo_font_options_t

 

palette_index

the palette index in the CPAL table

 

Since: 1.18


cairo_font_options_get_color_palette ()

unsigned int
cairo_font_options_get_color_palette (const cairo_font_options_t *options);

Gets the current OpenType color font palette for the font options object.

Parameters

options

a cairo_font_options_t

 

Returns

the palette index

Since: 1.18


cairo_font_options_set_custom_palette_color ()

void
cairo_font_options_set_custom_palette_color
                               (cairo_font_options_t *options,
                                unsigned int index,
                                double red,
                                double green,
                                double blue,
                                double alpha);

Sets a custom palette color for the font options object. This overrides the palette color at the specified color index. This override is independent of the selected palette index and will remain in place even if cairo_font_options_set_color_palette() is called to change the palette index.

It is only possible to override color indexes already in the font palette.

Parameters

options

a cairo_font_options_t

 

index

the index of the color to set

 

red

red component of color

 

green

green component of color

 

blue

blue component of color

 

alpha

alpha component of color

 

Since: 1.18


cairo_font_options_get_custom_palette_color ()

cairo_status_t
cairo_font_options_get_custom_palette_color
                               (cairo_font_options_t *options,
                                unsigned int index,
                                double *red,
                                double *green,
                                double *blue,
                                double *alpha);

Gets the custom palette color for the color index for the font options object.

Parameters

options

a cairo_font_options_t

 

index

the index of the color to get

 

red

return location for red component of color

 

green

return location for green component of color

 

blue

return location for blue component of color

 

alpha

return location for alpha component of color

 

Returns

CAIRO_STATUS_SUCCESS if a custom palette color is returned, CAIRO_STATUS_INVALID_INDEX if no custom color exists for the color index.

Since: 1.18

Types and Values

cairo_font_options_t

typedef struct _cairo_font_options cairo_font_options_t;

An opaque structure holding all options that are used when rendering fonts.

Individual features of a cairo_font_options_t can be set or accessed using functions named cairo_font_options_set_feature_name() and cairo_font_options_get_feature_name(), like cairo_font_options_set_antialias() and cairo_font_options_get_antialias().

New features may be added to a cairo_font_options_t in the future. For this reason, cairo_font_options_copy(), cairo_font_options_equal(), cairo_font_options_merge(), and cairo_font_options_hash() should be used to copy, check for equality, merge, or compute a hash value of cairo_font_options_t objects.

Since: 1.0


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

Members

CAIRO_SUBPIXEL_ORDER_DEFAULT

Use the default subpixel order for for the target device, since 1.0

 

CAIRO_SUBPIXEL_ORDER_RGB

Subpixel elements are arranged horizontally with red at the left, since 1.0

 

CAIRO_SUBPIXEL_ORDER_BGR

Subpixel elements are arranged horizontally with blue at the left, since 1.0

 

CAIRO_SUBPIXEL_ORDER_VRGB

Subpixel elements are arranged vertically with red at the top, since 1.0

 

CAIRO_SUBPIXEL_ORDER_VBGR

Subpixel elements are arranged vertically with blue at the top, since 1.0

 

Since: 1.0


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

New entries may be added in future versions.

Members

CAIRO_HINT_STYLE_DEFAULT

Use the default hint style for font backend and target device, since 1.0

 

CAIRO_HINT_STYLE_NONE

Do not hint outlines, since 1.0

 

CAIRO_HINT_STYLE_SLIGHT

Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes, since 1.0

 

CAIRO_HINT_STYLE_MEDIUM

Hint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast, since 1.0

 

CAIRO_HINT_STYLE_FULL

Hint outlines to maximize contrast, since 1.0

 

Since: 1.0


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

Members

CAIRO_HINT_METRICS_DEFAULT

Hint metrics in the default manner for the font backend and target device, since 1.0

 

CAIRO_HINT_METRICS_OFF

Do not hint font metrics, since 1.0

 

CAIRO_HINT_METRICS_ON

Hint font metrics, since 1.0

 

Since: 1.0


enum cairo_color_mode_t

Specifies if color fonts are to be rendered using the color glyphs or outline glyphs. Glyphs that do not have a color presentation, and non-color fonts are not affected by this font option.

Members

CAIRO_COLOR_MODE_DEFAULT

Use the default color mode for font backend and target device, since 1.18.

 

CAIRO_COLOR_MODE_NO_COLOR

Disable rendering color glyphs. Glyphs are always rendered as outline glyphs, since 1.18.

 

CAIRO_COLOR_MODE_COLOR

Enable rendering color glyphs. If the font contains a color presentation for a glyph, and when supported by the font backend, the glyph will be rendered in color, since 1.18.

 

Since: 1.18


CAIRO_COLOR_PALETTE_DEFAULT

#define CAIRO_COLOR_PALETTE_DEFAULT 0

The default color palette index.

Since: 1.18

See Also

cairo_scaled_font_t