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 */