Home | History | Annotate | Line # | Download | only in freetype 
      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 */
    314