| /**************************************************************************** |
| * |
| * ftcolor.h |
| * |
| * FreeType's glyph color management (specification). |
| * |
| * Copyright 2018 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 :: |
| * A 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 :: |
| * A 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 :: |
| * A 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. |
| * |
| * @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'. |
| * 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 number of color entries is given by the `num_palette_entries' |
| * field in the @FT_Palette_Data structure. |
| * |
| * 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 */ |
