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 <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 * An optional read-only array of palette name IDs with `num_palettes`
129 * elements, corresponding to entries like 'dark' or 'light' in the
130 * font's '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 * An optional read-only array of palette flags with `num_palettes`
139 * elements. 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 * An optional 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 * Use function @FT_Palette_Select to get the colors associated with a
167 * palette entry.
168 *
169 * @since:
170 * 2.10
171 */
172 typedef struct FT_Palette_Data_ {
173 FT_UShort num_palettes;
174 const FT_UShort* palette_name_ids;
175 const FT_UShort* palette_flags;
176
177 FT_UShort num_palette_entries;
178 const FT_UShort* palette_entry_name_ids;
179
180 } FT_Palette_Data;
181
182
183 /**************************************************************************
184 *
185 * @function:
186 * FT_Palette_Data_Get
187 *
188 * @description:
189 * Retrieve the face's color palette data.
190 *
191 * @input:
192 * face ::
193 * The source face handle.
194 *
195 * @output:
196 * apalette ::
197 * A pointer to an @FT_Palette_Data structure.
198 *
199 * @return:
200 * FreeType error code. 0~means success.
201 *
202 * @note:
203 * All arrays in the returned @FT_Palette_Data structure are read-only.
204 *
205 * This function always returns an error if the config macro
206 * `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.
207 *
208 * @since:
209 * 2.10
210 */
211 FT_EXPORT( FT_Error )
212 FT_Palette_Data_Get( FT_Face face,
213 FT_Palette_Data *apalette );
214
215
216 /**************************************************************************
217 *
218 * @function:
219 * FT_Palette_Select
220 *
221 * @description:
222 * This function has two purposes.
223 *
224 * (1) It activates a palette for rendering color glyphs, and
225 *
226 * (2) it retrieves all (unmodified) color entries of this palette. This
227 * function returns a read-write array, which means that a calling
228 * application can modify the palette entries on demand.
229 *
230 * A corollary of (2) is that calling the function, then modifying some
231 * values, then calling the function again with the same arguments resets
232 * all color entries to the original 'CPAL' values; all user modifications
233 * are lost.
234 *
235 * @input:
236 * face ::
237 * The source face handle.
238 *
239 * palette_index ::
240 * The palette index.
241 *
242 * @output:
243 * apalette ::
244 * An array of color entries for a palette with index `palette_index`,
245 * having `num_palette_entries` elements (as found in the
246 * `FT_Palette_Data` structure). If `apalette` is set to `NULL`, no
247 * array gets returned (and no color entries can be modified).
248 *
249 * In case the font doesn't support color palettes, `NULL` is returned.
250 *
251 * @return:
252 * FreeType error code. 0~means success.
253 *
254 * @note:
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 palette,
293 * and black opaque (BGRA value 0x000000FF) otherwise, including the case
294 * that no palette types are available in the 'CPAL' table.
295 *
296 * This function always returns an error if the config macro
297 * `TT_CONFIG_OPTION_COLOR_LAYERS` is not defined in `ftoption.h`.
298 *
299 * @since:
300 * 2.10
301 */
302 FT_EXPORT( FT_Error )
303 FT_Palette_Set_Foreground_Color( FT_Face face,
304 FT_Color foreground_color );
305
306 /* */
307
308
309 FT_END_HEADER
310
311 #endif /* FTCOLOR_H_ */
312
313
314 /* END */