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