hb-ot-color: HarfBuzz Manual

hb-ot-color

hb-ot-color — OpenType Color Fonts

Functions

#define	HB_COLOR()
uint8_t	hb_color_get_alpha ()
uint8_t	hb_color_get_blue ()
uint8_t	hb_color_get_green ()
uint8_t	hb_color_get_red ()
hb_bool_t	hb_ot_color_has_layers ()
unsigned int	hb_ot_color_glyph_get_layers ()
hb_bool_t	hb_ot_color_has_palettes ()
unsigned int	hb_ot_color_palette_get_count ()
unsigned int	hb_ot_color_palette_get_colors ()
hb_ot_color_palette_flags_t	hb_ot_color_palette_get_flags ()
hb_ot_name_id_t	hb_ot_color_palette_get_name_id ()
hb_ot_name_id_t	hb_ot_color_palette_color_get_name_id ()
hb_bool_t	hb_ot_color_has_paint ()
hb_bool_t	hb_ot_color_glyph_has_paint ()
hb_bool_t	hb_ot_color_has_png ()
hb_blob_t *	hb_ot_color_glyph_reference_png ()
hb_bool_t	hb_ot_color_has_svg ()
hb_blob_t *	hb_ot_color_glyph_reference_svg ()

Types and Values

typedef	hb_color_t
	hb_ot_color_layer_t
enum	hb_ot_color_palette_flags_t

Includes

#include <hb-ot.h>

Description

Functions for fetching color-font information from OpenType font faces.

HarfBuzz supports COLR/CPAL, sbix, CBDT, and SVG color fonts.

Functions

HB_COLOR()

#define HB_COLOR(b,g,r,a) ((hb_color_t) HB_TAG ((b),(g),(r),(a)))

Constructs an hb_color_t from four integers.

Parameters

b	blue channel value
g	green channel value
r	red channel value
a	alpha channel value

Since: 2.1.0

hb_color_get_alpha ()

uint8_t
hb_color_get_alpha (hb_color_t color);

Fetches the alpha channel of the given color .

Parameters

color

an hb_color_t we are interested in its channels.

Returns

Alpha channel value

Since: 2.1.0

hb_color_get_blue ()

uint8_t
hb_color_get_blue (hb_color_t color);

Fetches the blue channel of the given color .

Parameters

color

an hb_color_t we are interested in its channels.

Returns

Blue channel value

Since: 2.1.0

hb_color_get_green ()

uint8_t
hb_color_get_green (hb_color_t color);

Fetches the green channel of the given color .

Parameters

color

an hb_color_t we are interested in its channels.

Returns

Green channel value

Since: 2.1.0

hb_color_get_red ()

uint8_t
hb_color_get_red (hb_color_t color);

Fetches the red channel of the given color .

Parameters

color

an hb_color_t we are interested in its channels.

Returns

Red channel value

Since: 2.1.0

hb_ot_color_has_layers ()

hb_bool_t
hb_ot_color_has_layers (hb_face_t *face);

Tests whether a face includes a COLR table with data according to COLRv0.

Parameters

face

hb_face_t to work upon

Returns

true if data found, false otherwise

Since: 2.1.0

hb_ot_color_glyph_get_layers ()

unsigned int
hb_ot_color_glyph_get_layers (hb_face_t *face,
                              hb_codepoint_t glyph,
                              unsigned int start_offset,
                              unsigned int *layer_count,
                              hb_ot_color_layer_t *layers);

Fetches a list of all color layers for the specified glyph index in the specified face. The list returned will begin at the offset provided.

Parameters

face	hb_face_t to work upon
glyph	The glyph index to query
start_offset	offset of the first layer to retrieve
layer_count	Input = the maximum number of layers to return; Output = the actual number of layers returned (may be zero).	[inout][optional]
layers	The array of layers found.	[out][array length=layer_count][nullable]

Returns

Total number of layers available for the glyph index queried

Since: 2.1.0

hb_ot_color_has_palettes ()

hb_bool_t
hb_ot_color_has_palettes (hb_face_t *face);

Tests whether a face includes a CPAL color-palette table.

Parameters

face

hb_face_t to work upon

Returns

true if data found, false otherwise

Since: 2.1.0

hb_ot_color_palette_get_count ()

unsigned int
hb_ot_color_palette_get_count (hb_face_t *face);

Fetches the number of color palettes in a face.

Parameters

face

hb_face_t to work upon

Returns

the number of palettes found

Since: 2.1.0

hb_ot_color_palette_get_colors ()

unsigned int
hb_ot_color_palette_get_colors (hb_face_t *face,
                                unsigned int palette_index,
                                unsigned int start_offset,
                                unsigned int *color_count,
                                hb_color_t *colors);

Fetches a list of the colors in a color palette.

After calling this function, colors will be filled with the palette colors. If colors is NULL, the function will just return the number of total colors without storing any actual colors; this can be used for allocating a buffer of suitable size before calling hb_ot_color_palette_get_colors() a second time.

The RGBA values in the palette are unpremultiplied. See the OpenType spec CPAL section for details.

Parameters

face	hb_face_t to work upon
palette_index	the index of the color palette to query
start_offset	offset of the first color to retrieve
color_count	Input = the maximum number of colors to return; Output = the actual number of colors returned (may be zero).	[inout][optional]
colors	The array of hb_color_t records found.	[out][array length=color_count][nullable]

Returns

the total number of colors in the palette

Since: 2.1.0

hb_ot_color_palette_get_flags ()

hb_ot_color_palette_flags_t
hb_ot_color_palette_get_flags (hb_face_t *face,
                               unsigned int palette_index);

Fetches the flags defined for a color palette.

Parameters

face	hb_face_t to work upon
palette_index	The index of the color palette

Returns

the hb_ot_color_palette_flags_t of the requested color palette

Since: 2.1.0

hb_ot_color_palette_get_name_id ()

hb_ot_name_id_t
hb_ot_color_palette_get_name_id (hb_face_t *face,
                                 unsigned int palette_index);

Fetches the name table Name ID that provides display names for a CPAL color palette.

Palette display names can be generic (e.g., "Default") or provide specific, themed names (e.g., "Spring", "Summer", "Fall", and "Winter").

Parameters

face	hb_face_t to work upon
palette_index	The index of the color palette

Returns

the Named ID found for the palette. If the requested palette has no name the result is HB_OT_NAME_ID_INVALID.

Since: 2.1.0

hb_ot_color_palette_color_get_name_id ()

hb_ot_name_id_t
hb_ot_color_palette_color_get_name_id (hb_face_t *face,
                                       unsigned int color_index);

Fetches the name table Name ID that provides display names for the specified color in a face's CPAL color palette.

Display names can be generic (e.g., "Background") or specific (e.g., "Eye color").

Parameters

face	hb_face_t to work upon
color_index	The index of the color

Returns

the Name ID found for the color.

Since: 2.1.0

hb_ot_color_has_paint ()

hb_bool_t
hb_ot_color_has_paint (hb_face_t *face);

Tests where a face includes a COLR table with data according to COLRv1.

Parameters

face

hb_face_t to work upon

Returns

true if data found, false otherwise

Since: 7.0.0

hb_ot_color_glyph_has_paint ()

hb_bool_t
hb_ot_color_glyph_has_paint (hb_face_t *face,
                             hb_codepoint_t glyph);

Tests where a face includes COLRv1 paint data for glyph .

Parameters

face	hb_face_t to work upon
glyph	The glyph index to query

Returns

true if data found, false otherwise

Since: 7.0.0

hb_ot_color_has_png ()

hb_bool_t
hb_ot_color_has_png (hb_face_t *face);

Tests whether a face has PNG glyph images (either in CBDT or sbix tables).

Parameters

face

hb_face_t to work upon

Returns

true if data found, false otherwise

Since: 2.1.0

hb_ot_color_glyph_reference_png ()

hb_blob_t *
hb_ot_color_glyph_reference_png (hb_font_t *font,
                                 hb_codepoint_t glyph);

Fetches the PNG image for a glyph. This function takes a font object, not a face object, as input. To get an optimally sized PNG blob, the PPEM values must be set on the font object. If PPEM is unset, the blob returned will be the largest PNG available.

If the glyph has no PNG image, the singleton empty blob is returned.

Parameters

font	hb_font_t to work upon
glyph	a glyph index

Returns

An hb_blob_t containing the PNG image for the glyph, if available.

[transfer full]

Since: 2.1.0

hb_ot_color_has_svg ()

hb_bool_t
hb_ot_color_has_svg (hb_face_t *face);

Tests whether a face includes any SVG glyph images.

Parameters

face

hb_face_t to work upon.

Returns

true if data found, false otherwise.

Since: 2.1.0

hb_ot_color_glyph_reference_svg ()

hb_blob_t *
hb_ot_color_glyph_reference_svg (hb_face_t *face,
                                 hb_codepoint_t glyph);

Fetches the SVG document for a glyph. The blob may be either plain text or gzip-encoded.

If the glyph has no SVG document, the singleton empty blob is returned.

Parameters

face	hb_face_t to work upon
glyph	a svg glyph index

Returns

An hb_blob_t containing the SVG document of the glyph, if available.

[transfer full]

Since: 2.1.0

Types and Values

hb_color_t

typedef uint32_t hb_color_t;

Data type for holding color values. Colors are eight bits per channel RGB plus alpha transparency.

Since: 2.1.0

hb_ot_color_layer_t

typedef struct {
  hb_codepoint_t glyph;
  unsigned int   color_index;
} hb_ot_color_layer_t;

Pairs of glyph and color index.

A color index of 0xFFFF does not refer to a palette color, but indicates that the foreground color should be used.

Members

hb_codepoint_t `glyph`;	the glyph ID of the layer
unsigned int `color_index`;	the palette color index of the layer

Since: 2.1.0

enum hb_ot_color_palette_flags_t

Flags that describe the properties of color palette.

Members

HB_OT_COLOR_PALETTE_FLAG_DEFAULT	Default indicating that there is nothing special to note about a color palette.
HB_OT_COLOR_PALETTE_FLAG_USABLE_WITH_LIGHT_BACKGROUND	Flag indicating that the color palette is appropriate to use when displaying the font on a light background such as white.
HB_OT_COLOR_PALETTE_FLAG_USABLE_WITH_DARK_BACKGROUND	Flag indicating that the color palette is appropriate to use when displaying the font on a dark background such as black.

Since: 2.1.0