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