Skip to content

FreeType » Docs » Extended API » Glyph Color Management

# Glyph Color Management

## Synopsis

The functions described here allow access and manipulation of color palette entries in OpenType's ‘CPAL’ tables.

## FT_Color

Defined in FT_COLOR_H (freetype/ftcolor.h).

      typedef struct  FT_Color_
      {
        FT_Byte  blue;
        FT_Byte  green;
        FT_Byte  red;
        FT_Byte  alpha;

      } FT_Color;

This structure models a BGRA color value of a ‘CPAL’ palette entry.

The used color space is sRGB; the colors are not pre-multiplied, and alpha values must be explicitly set.

#### fields

blue | Blue value.
green | Green value.
red | Red value.
alpha | Alpha value, giving the red, green, and blue color's opacity.

#### since

2.10

## FT_PALETTE_XXX

Defined in FT_COLOR_H (freetype/ftcolor.h).

    #define FT_PALETTE_FOR_LIGHT_BACKGROUND  0x01
    #define FT_PALETTE_FOR_DARK_BACKGROUND   0x02

A list of bit field constants used in the `palette_flags` array of the `FT_Palette_Data` structure to indicate for which background a palette with a given index is usable.

#### values

FT_PALETTE_FOR_LIGHT_BACKGROUND | The palette is appropriate to use when displaying the font on a light background such as white.
FT_PALETTE_FOR_DARK_BACKGROUND | The palette is appropriate to use when displaying the font on a dark background such as black.

#### since

2.10

## FT_Palette_Data

Defined in FT_COLOR_H (freetype/ftcolor.h).

      typedef struct  FT_Palette_Data_ {
        FT_UShort         num_palettes;
        const FT_UShort*  palette_name_ids;
        const FT_UShort*  palette_flags;

        FT_UShort         num_palette_entries;
        const FT_UShort*  palette_entry_name_ids;

      } FT_Palette_Data;

This structure holds the data of the ‘CPAL’ table.

#### fields

num_palettes | The number of palettes.
palette_name_ids | An optional read-only array of palette name IDs with `num_palettes` elements, corresponding to entries like ‘dark’ or ‘light’ in the font's ‘name’ table. An empty name ID in the ‘CPAL’ table gets represented as value 0xFFFF. `NULL` if the font's ‘CPAL’ table doesn't contain appropriate data.
palette_flags | An optional read-only array of palette flags with `num_palettes` elements. Possible values are an ORed combination of `FT_PALETTE_FOR_LIGHT_BACKGROUND` and `FT_PALETTE_FOR_DARK_BACKGROUND`. `NULL` if the font's ‘CPAL’ table doesn't contain appropriate data.
num_palette_entries | The number of entries in a single palette. All palettes have the same size.

palette_entry_name_ids

An optional read-only array of palette entry name IDs with `num_palette_entries`. In each palette, entries with the same index have the same function. For example, index 0 might correspond to string ‘outline’ in the font's ‘name’ table to indicate that this palette entry is used for outlines, index 1 might correspond to ‘fill’ to indicate the filling color palette entry, etc.

An empty entry name ID in the ‘CPAL’ table gets represented as value 0xFFFF.

`NULL` if the font's ‘CPAL’ table doesn't contain appropriate data.

#### note

Use function `FT_Get_Sfnt_Name` to map name IDs and entry name IDs to name strings.

Use function `FT_Palette_Select` to get the colors associated with a palette entry.

#### since

2.10

## FT_Palette_Data_Get

Defined in FT_COLOR_H (freetype/ftcolor.h).

      FT_EXPORT( FT_Error )
      FT_Palette_Data_Get( FT_Face           face,
                           FT_Palette_Data  *apalette );

Retrieve the face's color palette data.

#### input

face | The source face handle.

#### output

apalette | A pointer to an `FT_Palette_Data` structure.

#### return

FreeType error code. 0 means success.

#### note

All arrays in the returned `FT_Palette_Data` structure are read-only.

This function always returns an error if the config macro `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.

#### since

2.10

## FT_Palette_Select

Defined in FT_COLOR_H (freetype/ftcolor.h).

      FT_EXPORT( FT_Error )
      FT_Palette_Select( FT_Face     face,
                         FT_UShort   palette_index,
                         FT_Color*  *apalette );

This function has two purposes.

(1) It activates a palette for rendering color glyphs, and

(2) it retrieves all (unmodified) color entries of this palette. This function returns a read-write array, which means that a calling application can modify the palette entries on demand.

A corollary of (2) is that calling the function, then modifying some values, then calling the function again with the same arguments resets all color entries to the original ‘CPAL’ values; all user modifications are lost.

#### input

face | The source face handle.
palette_index | The palette index.

#### output

apalette | An array of color entries for a palette with index `palette_index`, having `num_palette_entries` elements (as found in the `FT_Palette_Data` structure). If `apalette` is set to `NULL`, no array gets returned (and no color entries can be modified). In case the font doesn't support color palettes, `NULL` is returned.

#### return

FreeType error code. 0 means success.

#### note

The array pointed to by `apalette_entries` is owned and managed by FreeType.

This function always returns an error if the config macro `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.

#### since

2.10

## FT_Palette_Set_Foreground_Color

Defined in FT_COLOR_H (freetype/ftcolor.h).

      FT_EXPORT( FT_Error )
      FT_Palette_Set_Foreground_Color( FT_Face   face,
                                       FT_Color  foreground_color );

‘COLR’ uses palette index 0xFFFF to indicate a ‘text foreground color’. This function sets this value.

#### input

face | The source face handle.
foreground_color | An `FT_Color` structure to define the text foreground color.

#### return

FreeType error code. 0 means success.

#### note

If this function isn't called, the text foreground color is set to white opaque (BGRA value 0xFFFFFFFF) if `FT_PALETTE_FOR_DARK_BACKGROUND` is present for the current palette, and black opaque (BGRA value 0x000000FF) otherwise, including the case that no palette types are available in the ‘CPAL’ table.

This function always returns an error if the config macro `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.

#### since

2.10