| /**************************************************************************** |
| * |
| * 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 <ft2build.h> |
| #include FT_FREETYPE_H |
| |
| #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 */ |
