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