/**************************************************************************** * * ftcolor.h * * FreeType's glyph color management (specification). * * Copyright (C) 2018-2020 by * David Turner, Robert Wilhelm, and Werner Lemberg. * * This file is part of the FreeType project, and may only be used, * modified, and distributed under the terms of the FreeType project * license, LICENSE.TXT. By continuing to use, modify, or distribute * this file you indicate that you have read the license and * understand and accept it fully. * */ #ifndef FTCOLOR_H_ #define FTCOLOR_H_ #include #ifdef FREETYPE_H #error "freetype.h of FreeType 1 has been loaded!" #error "Please fix the directory search order for header files" #error "so that freetype.h of FreeType 2 is found first." #endif FT_BEGIN_HEADER /************************************************************************** * * @section: * color_management * * @title: * Glyph Color Management * * @abstract: * Retrieving and manipulating OpenType's 'CPAL' table data. * * @description: * The functions described here allow access and manipulation of color * palette entries in OpenType's 'CPAL' tables. */ /************************************************************************** * * @struct: * FT_Color * * @description: * 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 */ typedef struct FT_Color_ { FT_Byte blue; FT_Byte green; FT_Byte red; FT_Byte alpha; } FT_Color; /************************************************************************** * * @enum: * FT_PALETTE_XXX * * @description: * 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 */ #define FT_PALETTE_FOR_LIGHT_BACKGROUND 0x01 #define FT_PALETTE_FOR_DARK_BACKGROUND 0x02 /************************************************************************** * * @struct: * FT_Palette_Data * * @description: * 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 */ 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; /************************************************************************** * * @function: * FT_Palette_Data_Get * * @description: * 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_EXPORT( FT_Error ) FT_Palette_Data_Get( FT_Face face, FT_Palette_Data *apalette ); /************************************************************************** * * @function: * FT_Palette_Select * * @description: * 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_EXPORT( FT_Error ) FT_Palette_Select( FT_Face face, FT_UShort palette_index, FT_Color* *apalette ); /************************************************************************** * * @function: * FT_Palette_Set_Foreground_Color * * @description: * '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 */ FT_EXPORT( FT_Error ) FT_Palette_Set_Foreground_Color( FT_Face face, FT_Color foreground_color ); /* */ FT_END_HEADER #endif /* FTCOLOR_H_ */ /* END */