include/freetype/ftcolor.h

   1 /****************************************************************************
   2  *
   3  * ftcolor.h
   4  *
   5  *   FreeType's glyph color management (specification).
   6  *
   7  * Copyright (C) 2018-2020 by
   8  * David Turner, Robert Wilhelm, and Werner Lemberg.
   9  *
  10  * This file is part of the FreeType project, and may only be used,
  11  * modified, and distributed under the terms of the FreeType project
  12  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
  13  * this file you indicate that you have read the license and
  14  * understand and accept it fully.
  15  *
  16  */
  17
  18
  19 #ifndef FTCOLOR_H_
  20 #define FTCOLOR_H_
  21
  22 #include <freetype/freetype.h>
  23
  24 #ifdef FREETYPE_H
  25 #error "freetype.h of FreeType 1 has been loaded!"
  26 #error "Please fix the directory search order for header files"
  27 #error "so that freetype.h of FreeType 2 is found first."
  28 #endif
  29
  30
  31 FT_BEGIN_HEADER
  32
  33
  34   /**************************************************************************
  35    *
  36    * @section:
  37    *   color_management
  38    *
  39    * @title:
  40    *   Glyph Color Management
  41    *
  42    * @abstract:
  43    *   Retrieving and manipulating OpenType's 'CPAL' table data.
  44    *
  45    * @description:
  46    *   The functions described here allow access and manipulation of color
  47    *   palette entries in OpenType's 'CPAL' tables.
  48    */
  49
  50
  51   /**************************************************************************
  52    *
  53    * @struct:
  54    *   FT_Color
  55    *
  56    * @description:
  57    *   This structure models a BGRA color value of a 'CPAL' palette entry.
  58    *
  59    *   The used color space is sRGB; the colors are not pre-multiplied, and
  60    *   alpha values must be explicitly set.
  61    *
  62    * @fields:
  63    *   blue ::
  64    *     Blue value.
  65    *
  66    *   green ::
  67    *     Green value.
  68    *
  69    *   red ::
  70    *     Red value.
  71    *
  72    *   alpha ::
  73    *     Alpha value, giving the red, green, and blue color's opacity.
  74    *
  75    * @since:
  76    *   2.10
  77    */
  78   typedef struct  FT_Color_
  79   {
  80     FT_Byte  blue;
  81     FT_Byte  green;
  82     FT_Byte  red;
  83     FT_Byte  alpha;
  84
  85   } FT_Color;
  86
  87
  88   /**************************************************************************
  89    *
  90    * @enum:
  91    *   FT_PALETTE_XXX
  92    *
  93    * @description:
  94    *   A list of bit field constants used in the `palette_flags` array of the
  95    *   @FT_Palette_Data structure to indicate for which background a palette
  96    *   with a given index is usable.
  97    *
  98    * @values:
  99    *   FT_PALETTE_FOR_LIGHT_BACKGROUND ::
 100    *     The palette is appropriate to use when displaying the font on a
 101    *     light background such as white.
 102    *
 103    *   FT_PALETTE_FOR_DARK_BACKGROUND ::
 104    *     The palette is appropriate to use when displaying the font on a dark
 105    *     background such as black.
 106    *
 107    * @since:
 108    *   2.10
 109    */
 110 #define FT_PALETTE_FOR_LIGHT_BACKGROUND  0x01
 111 #define FT_PALETTE_FOR_DARK_BACKGROUND   0x02
 112
 113
 114   /**************************************************************************
 115    *
 116    * @struct:
 117    *   FT_Palette_Data
 118    *
 119    * @description:
 120    *   This structure holds the data of the 'CPAL' table.
 121    *
 122    * @fields:
 123    *   num_palettes ::
 124    *     The number of palettes.
 125    *
 126    *   palette_name_ids ::
 127    *     An optional read-only array of palette name IDs with `num_palettes`
 128    *     elements, corresponding to entries like 'dark' or 'light' in the
 129    *     font's 'name' table.
 130    *
 131    *     An empty name ID in the 'CPAL' table gets represented as value
 132    *     0xFFFF.
 133    *
 134    *     `NULL` if the font's 'CPAL' table doesn't contain appropriate data.
 135    *
 136    *   palette_flags ::
 137    *     An optional read-only array of palette flags with `num_palettes`
 138    *     elements.  Possible values are an ORed combination of
 139    *     @FT_PALETTE_FOR_LIGHT_BACKGROUND and
 140    *     @FT_PALETTE_FOR_DARK_BACKGROUND.
 141    *
 142    *     `NULL` if the font's 'CPAL' table doesn't contain appropriate data.
 143    *
 144    *   num_palette_entries ::
 145    *     The number of entries in a single palette.  All palettes have the
 146    *     same size.
 147    *
 148    *   palette_entry_name_ids ::
 149    *     An optional read-only array of palette entry name IDs with
 150    *     `num_palette_entries`.  In each palette, entries with the same index
 151    *     have the same function.  For example, index~0 might correspond to
 152    *     string 'outline' in the font's 'name' table to indicate that this
 153    *     palette entry is used for outlines, index~1 might correspond to
 154    *     'fill' to indicate the filling color palette entry, etc.
 155    *
 156    *     An empty entry name ID in the 'CPAL' table gets represented as value
 157    *     0xFFFF.
 158    *
 159    *     `NULL` if the font's 'CPAL' table doesn't contain appropriate data.
 160    *
 161    * @note:
 162    *   Use function @FT_Get_Sfnt_Name to map name IDs and entry name IDs to
 163    *   name strings.
 164    *
 165    *   Use function @FT_Palette_Select to get the colors associated with a
 166    *   palette entry.
 167    *
 168    * @since:
 169    *   2.10
 170    */
 171   typedef struct  FT_Palette_Data_ {
 172     FT_UShort         num_palettes;
 173     const FT_UShort*  palette_name_ids;
 174     const FT_UShort*  palette_flags;
 175
 176     FT_UShort         num_palette_entries;
 177     const FT_UShort*  palette_entry_name_ids;
 178
 179   } FT_Palette_Data;
 180
 181
 182   /**************************************************************************
 183    *
 184    * @function:
 185    *   FT_Palette_Data_Get
 186    *
 187    * @description:
 188    *   Retrieve the face's color palette data.
 189    *
 190    * @input:
 191    *   face ::
 192    *     The source face handle.
 193    *
 194    * @output:
 195    *   apalette ::
 196    *     A pointer to an @FT_Palette_Data structure.
 197    *
 198    * @return:
 199    *   FreeType error code.  0~means success.
 200    *
 201    * @note:
 202    *   All arrays in the returned @FT_Palette_Data structure are read-only.
 203    *
 204    *   This function always returns an error if the config macro
 205    *   `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.
 206    *
 207    * @since:
 208    *   2.10
 209    */
 210   FT_EXPORT( FT_Error )
 211   FT_Palette_Data_Get( FT_Face           face,
 212                        FT_Palette_Data  *apalette );
 213
 214
 215   /**************************************************************************
 216    *
 217    * @function:
 218    *   FT_Palette_Select
 219    *
 220    * @description:
 221    *   This function has two purposes.
 222    *
 223    *   (1) It activates a palette for rendering color glyphs, and
 224    *
 225    *   (2) it retrieves all (unmodified) color entries of this palette.  This
 226    *       function returns a read-write array, which means that a calling
 227    *       application can modify the palette entries on demand.
 228    *
 229    * A corollary of (2) is that calling the function, then modifying some
 230    * values, then calling the function again with the same arguments resets
 231    * all color entries to the original 'CPAL' values; all user modifications
 232    * are lost.
 233    *
 234    * @input:
 235    *   face ::
 236    *     The source face handle.
 237    *
 238    *   palette_index ::
 239    *     The palette index.
 240    *
 241    * @output:
 242    *   apalette ::
 243    *     An array of color entries for a palette with index `palette_index`,
 244    *     having `num_palette_entries` elements (as found in the
 245    *     `FT_Palette_Data` structure).  If `apalette` is set to `NULL`, no
 246    *     array gets returned (and no color entries can be modified).
 247    *
 248    *     In case the font doesn't support color palettes, `NULL` is returned.
 249    *
 250    * @return:
 251    *   FreeType error code.  0~means success.
 252    *
 253    * @note:
 254    *   The array pointed to by `apalette_entries` is owned and managed by
 255    *   FreeType.
 256    *
 257    *   This function always returns an error if the config macro
 258    *   `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.
 259    *
 260    * @since:
 261    *   2.10
 262    */
 263   FT_EXPORT( FT_Error )
 264   FT_Palette_Select( FT_Face     face,
 265                      FT_UShort   palette_index,
 266                      FT_Color*  *apalette );
 267
 268
 269   /**************************************************************************
 270    *
 271    * @function:
 272    *   FT_Palette_Set_Foreground_Color
 273    *
 274    * @description:
 275    *   'COLR' uses palette index 0xFFFF to indicate a 'text foreground
 276    *   color'.  This function sets this value.
 277    *
 278    * @input:
 279    *   face ::
 280    *     The source face handle.
 281    *
 282    *   foreground_color ::
 283    *     An `FT_Color` structure to define the text foreground color.
 284    *
 285    * @return:
 286    *   FreeType error code.  0~means success.
 287    *
 288    * @note:
 289    *   If this function isn't called, the text foreground color is set to
 290    *   white opaque (BGRA value 0xFFFFFFFF) if
 291    *   @FT_PALETTE_FOR_DARK_BACKGROUND is present for the current palette,
 292    *   and black opaque (BGRA value 0x000000FF) otherwise, including the case
 293    *   that no palette types are available in the 'CPAL' table.
 294    *
 295    *   This function always returns an error if the config macro
 296    *   `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.
 297    *
 298    * @since:
 299    *   2.10
 300    */
 301   FT_EXPORT( FT_Error )
 302   FT_Palette_Set_Foreground_Color( FT_Face   face,
 303                                    FT_Color  foreground_color );
 304
 305   /* */
 306
 307
 308 FT_END_HEADER
 309
 310 #endif /* FTCOLOR_H_ */
 311
 312
 313 /* END */