1 /**************************************************************************** 2 * 3 * ftcolor.h 4 * 5 * FreeType's glyph color management (specification). 6 * 7 * Copyright 2018 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 96 * the @FT_Palette_Data structure to indicate for which background a 97 * palette 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 106 * dark 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 130 * `name' 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 152 * index have the same function. For example, index~0 might 153 * correspond to string `outline' in the font's `name' table to 154 * indicate that this palette entry is used for outlines, index~1 155 * might correspond to `fill' to indicate the filling color palette 156 * entry, etc. 157 * 158 * An empty entry name ID in the `CPAL' table gets represented as 159 * value 0xFFFF. 160 * 161 * NULL if the font's `CPAL' table doesn't contain appropriate data. 162 * 163 * @note: 164 * Use function @FT_Get_Sfnt_Name to map name IDs and entry name IDs to 165 * name strings. 166 * 167 * @since: 168 * 2.10 169 */ 170 typedef struct FT_Palette_Data_ { 171 FT_UShort num_palettes; 172 const FT_UShort* palette_name_ids; 173 const FT_UShort* palette_flags; 174 175 FT_UShort num_palette_entries; 176 const FT_UShort* palette_entry_name_ids; 177 178 } FT_Palette_Data; 179 180 181 /************************************************************************** 182 * 183 * @function: 184 * FT_Palette_Data_Get 185 * 186 * @description: 187 * Retrieve the face's color palette data. 188 * 189 * @input: 190 * face :: 191 * The source face handle. 192 * 193 * @output: 194 * apalette :: 195 * A pointer to an @FT_Palette_Data structure. 196 * 197 * @return: 198 * FreeType error code. 0~means success. 199 * 200 * @note: 201 * All arrays in the returned @FT_Palette_Data structure are read-only. 202 * 203 * This function always returns an error if the config macro 204 * `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'. 205 * 206 * @since: 207 * 2.10 208 */ 209 FT_EXPORT( FT_Error ) 210 FT_Palette_Data_Get( FT_Face face, 211 FT_Palette_Data *apalette ); 212 213 214 /************************************************************************** 215 * 216 * @function: 217 * FT_Palette_Select 218 * 219 * @description: 220 * This function has two purposes. 221 * 222 * (1) It activates a palette for rendering color glyphs, and 223 * 224 * (2) it retrieves all (unmodified) color entries of this palette. This 225 * function returns a read-write array, which means that a calling 226 * application can modify the palette entries on demand. 227 * 228 * A corollary of (2) is that calling the function, then modifying some 229 * values, then calling the function again with the same arguments resets 230 * all color entries to the original `CPAL' values; all user modifications 231 * are lost. 232 * 233 * @input: 234 * face :: 235 * The source face handle. 236 * 237 * palette_index :: 238 * The palette index. 239 * 240 * @output: 241 * apalette :: 242 * An array of color entries for a palette with index `palette_index'. 243 * If `apalette' is set to NULL, no array gets returned (and no color 244 * 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 number of color entries is given by the `num_palette_entries' 253 * field in the @FT_Palette_Data structure. 254 * 255 * The array pointed to by `apalette_entries' is owned and managed by 256 * FreeType. 257 * 258 * This function always returns an error if the config macro 259 * `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'. 260 * 261 * @since: 262 * 2.10 263 */ 264 FT_EXPORT( FT_Error ) 265 FT_Palette_Select( FT_Face face, 266 FT_UShort palette_index, 267 FT_Color* *apalette ); 268 269 270 /************************************************************************** 271 * 272 * @function: 273 * FT_Palette_Set_Foreground_Color 274 * 275 * @description: 276 * `COLR' uses palette index 0xFFFF to indicate a `text foreground 277 * color'. This function sets this value. 278 * 279 * @input: 280 * face :: 281 * The source face handle. 282 * 283 * foreground_color :: 284 * An `FT_Color' structure to define the text foreground color. 285 * 286 * @return: 287 * FreeType error code. 0~means success. 288 * 289 * @note: 290 * If this function isn't called, the text foreground color is set to 291 * white opaque (BGRA value 0xFFFFFFFF) if 292 * @FT_PALETTE_FOR_DARK_BACKGROUND is present for the current 293 * palette, and black opaque (BGRA value 0x000000FF) otherwise, 294 * including the case that no palette types are available in the `CPAL' 295 * table. 296 * 297 * This function always returns an error if the config macro 298 * `TT_CONFIG_OPTION_COLOR_LAYERS' is not defined in `ftoption.h'. 299 * 300 * @since: 301 * 2.10 302 */ 303 FT_EXPORT( FT_Error ) 304 FT_Palette_Set_Foreground_Color( FT_Face face, 305 FT_Color foreground_color ); 306 307 /* */ 308 309 310 FT_END_HEADER 311 312 #endif /* FTCOLOR_H_ */ 313 314 315 /* END */ 316