1 /*
2 * Copyright © 2022 Matthias Clasen
3 *
4 * This is part of HarfBuzz, a text shaping library.
5 *
6 * Permission is hereby granted, without written agreement and without
7 * license or royalty fees, to use, copy, modify, and distribute this
8 * software and its documentation for any purpose, provided that the
9 * above copyright notice and the following two paragraphs appear in
10 * all copies of this software.
11 *
12 * IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR
13 * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
14 * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
15 * IF THE COPYRIGHT HOLDER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
16 * DAMAGE.
17 *
18 * THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
19 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
20 * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
21 * ON AN "AS IS" BASIS, AND THE COPYRIGHT HOLDER HAS NO OBLIGATION TO
22 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
23 */
24
25 #if !defined(HB_H_IN) && !defined(HB_NO_SINGLE_HEADER_ERROR)
26 #error "Include <hb.h> instead."
27 #endif
28
29 #ifndef HB_PAINT_H
30 #define HB_PAINT_H
31
32 #include "hb-common.h"
33
34 HB_BEGIN_DECLS
35
36
37 /**
38 * hb_paint_funcs_t:
39 *
40 * Glyph paint callbacks.
41 *
42 * The callbacks assume that the caller maintains a stack
43 * of current transforms, clips and intermediate surfaces,
44 * as evidenced by the pairs of push/pop callbacks. The
45 * push/pop calls will be properly nested, so it is fine
46 * to store the different kinds of object on a single stack.
47 *
48 * Not all callbacks are required for all kinds of glyphs.
49 * For rendering COLRv0 or non-color outline glyphs, the
50 * gradient callbacks are not needed, and the composite
51 * callback only needs to handle simple alpha compositing
52 * (#HB_PAINT_COMPOSITE_MODE_SRC_OVER).
53 *
54 * The paint-image callback is only needed for glyphs
55 * with image blobs in the CBDT, sbix or SVG tables.
56 *
57 * The custom-palette-color callback is only necessary if
58 * you want to override colors from the font palette with
59 * custom colors.
60 *
61 * Since: 7.0.0
62 **/
63 typedef struct hb_paint_funcs_t hb_paint_funcs_t;
64
65 HB_EXTERN hb_paint_funcs_t *
66 hb_paint_funcs_create (void);
67
68 HB_EXTERN hb_paint_funcs_t *
69 hb_paint_funcs_get_empty (void);
70
71 HB_EXTERN hb_paint_funcs_t *
72 hb_paint_funcs_reference (hb_paint_funcs_t *funcs);
73
74 HB_EXTERN void
75 hb_paint_funcs_destroy (hb_paint_funcs_t *funcs);
76
77 HB_EXTERN hb_bool_t
78 hb_paint_funcs_set_user_data (hb_paint_funcs_t *funcs,
79 hb_user_data_key_t *key,
80 void * data,
81 hb_destroy_func_t destroy,
82 hb_bool_t replace);
83
84
85 HB_EXTERN void *
86 hb_paint_funcs_get_user_data (const hb_paint_funcs_t *funcs,
87 hb_user_data_key_t *key);
88
89 HB_EXTERN void
90 hb_paint_funcs_make_immutable (hb_paint_funcs_t *funcs);
91
92 HB_EXTERN hb_bool_t
93 hb_paint_funcs_is_immutable (hb_paint_funcs_t *funcs);
94
95 /**
96 * hb_paint_push_transform_func_t:
97 * @funcs: paint functions object
98 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
99 * @xx: xx component of the transform matrix
100 * @yx: yx component of the transform matrix
101 * @xy: xy component of the transform matrix
102 * @yy: yy component of the transform matrix
103 * @dx: dx component of the transform matrix
104 * @dy: dy component of the transform matrix
105 * @user_data: User data pointer passed to hb_paint_funcs_set_push_transform_func()
106 *
107 * A virtual method for the #hb_paint_funcs_t to apply
108 * a transform to subsequent paint calls.
109 *
110 * This transform is applied after the current transform,
111 * and remains in effect until a matching call to
112 * the #hb_paint_funcs_pop_transform_func_t vfunc.
113 *
114 * Since: 7.0.0
115 */
116 typedef void (*hb_paint_push_transform_func_t) (hb_paint_funcs_t *funcs,
117 void *paint_data,
118 float xx, float yx,
119 float xy, float yy,
120 float dx, float dy,
121 void *user_data);
122
123 /**
124 * hb_paint_pop_transform_func_t:
125 * @funcs: paint functions object
126 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
127 * @user_data: User data pointer passed to hb_paint_funcs_set_pop_transform_func()
128 *
129 * A virtual method for the #hb_paint_funcs_t to undo
130 * the effect of a prior call to the #hb_paint_funcs_push_transform_func_t
131 * vfunc.
132 *
133 * Since: 7.0.0
134 */
135 typedef void (*hb_paint_pop_transform_func_t) (hb_paint_funcs_t *funcs,
136 void *paint_data,
137 void *user_data);
138
139 /**
140 * hb_paint_color_glyph_func_t:
141 * @funcs: paint functions object
142 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
143 * @glyph: the glyph ID
144 * @font: the font
145 * @user_data: User data pointer passed to hb_paint_funcs_set_color_glyph_func()
146 *
147 * A virtual method for the #hb_paint_funcs_t to render a color glyph by glyph index.
148 *
149 * Return value: %true if the glyph was painted, %false otherwise.
150 *
151 * Since: 8.2.0
152 */
153 typedef hb_bool_t (*hb_paint_color_glyph_func_t) (hb_paint_funcs_t *funcs,
154 void *paint_data,
155 hb_codepoint_t glyph,
156 hb_font_t *font,
157 void *user_data);
158
159 /**
160 * hb_paint_push_clip_glyph_func_t:
161 * @funcs: paint functions object
162 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
163 * @glyph: the glyph ID
164 * @font: the font
165 * @user_data: User data pointer passed to hb_paint_funcs_set_push_clip_glyph_func()
166 *
167 * A virtual method for the #hb_paint_funcs_t to clip
168 * subsequent paint calls to the outline of a glyph.
169 *
170 * The coordinates of the glyph outline are interpreted according
171 * to the current transform.
172 *
173 * This clip is applied in addition to the current clip,
174 * and remains in effect until a matching call to
175 * the #hb_paint_funcs_pop_clip_func_t vfunc.
176 *
177 * Since: 7.0.0
178 */
179 typedef void (*hb_paint_push_clip_glyph_func_t) (hb_paint_funcs_t *funcs,
180 void *paint_data,
181 hb_codepoint_t glyph,
182 hb_font_t *font,
183 void *user_data);
184
185 /**
186 * hb_paint_push_clip_rectangle_func_t:
187 * @funcs: paint functions object
188 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
189 * @xmin: min X for the rectangle
190 * @ymin: min Y for the rectangle
191 * @xmax: max X for the rectangle
192 * @ymax: max Y for the rectangle
193 * @user_data: User data pointer passed to hb_paint_funcs_set_push_clip_rectangle_func()
194 *
195 * A virtual method for the #hb_paint_funcs_t to clip
196 * subsequent paint calls to a rectangle.
197 *
198 * The coordinates of the rectangle are interpreted according
199 * to the current transform.
200 *
201 * This clip is applied in addition to the current clip,
202 * and remains in effect until a matching call to
203 * the #hb_paint_funcs_pop_clip_func_t vfunc.
204 *
205 * Since: 7.0.0
206 */
207 typedef void (*hb_paint_push_clip_rectangle_func_t) (hb_paint_funcs_t *funcs,
208 void *paint_data,
209 float xmin, float ymin,
210 float xmax, float ymax,
211 void *user_data);
212
213 /**
214 * hb_paint_pop_clip_func_t:
215 * @funcs: paint functions object
216 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
217 * @user_data: User data pointer passed to hb_paint_funcs_set_pop_clip_func()
218 *
219 * A virtual method for the #hb_paint_funcs_t to undo
220 * the effect of a prior call to the #hb_paint_funcs_push_clip_glyph_func_t
221 * or #hb_paint_funcs_push_clip_rectangle_func_t vfuncs.
222 *
223 * Since: 7.0.0
224 */
225 typedef void (*hb_paint_pop_clip_func_t) (hb_paint_funcs_t *funcs,
226 void *paint_data,
227 void *user_data);
228
229 /**
230 * hb_paint_color_func_t:
231 * @funcs: paint functions object
232 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
233 * @is_foreground: whether the color is the foreground
234 * @color: The color to use, unpremultiplied
235 * @user_data: User data pointer passed to hb_paint_funcs_set_color_func()
236 *
237 * A virtual method for the #hb_paint_funcs_t to paint a
238 * color everywhere within the current clip.
239 *
240 * Since: 7.0.0
241 */
242 typedef void (*hb_paint_color_func_t) (hb_paint_funcs_t *funcs,
243 void *paint_data,
244 hb_bool_t is_foreground,
245 hb_color_t color,
246 void *user_data);
247
248 /**
249 * HB_PAINT_IMAGE_FORMAT_PNG:
250 *
251 * Tag identifying PNG images in #hb_paint_image_func_t callbacks.
252 *
253 * Since: 7.0.0
254 */
255 #define HB_PAINT_IMAGE_FORMAT_PNG HB_TAG('p','n','g',' ')
256
257 /**
258 * HB_PAINT_IMAGE_FORMAT_SVG:
259 *
260 * Tag identifying SVG images in #hb_paint_image_func_t callbacks.
261 *
262 * Since: 7.0.0
263 */
264 #define HB_PAINT_IMAGE_FORMAT_SVG HB_TAG('s','v','g',' ')
265
266 /**
267 * HB_PAINT_IMAGE_FORMAT_BGRA:
268 *
269 * Tag identifying raw pixel-data images in #hb_paint_image_func_t callbacks.
270 * The data is in BGRA pre-multiplied sRGBA color-space format.
271 *
272 * Since: 7.0.0
273 */
274 #define HB_PAINT_IMAGE_FORMAT_BGRA HB_TAG('B','G','R','A')
275
276 /**
277 * hb_paint_image_func_t:
278 * @funcs: paint functions object
279 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
280 * @image: the image data
281 * @width: width of the raster image in pixels, or 0
282 * @height: height of the raster image in pixels, or 0
283 * @format: the image format as a tag
284 * @slant: the synthetic slant ratio to be applied to the image during rendering
285 * @extents: (nullable): glyph extents for desired rendering
286 * @user_data: User data pointer passed to hb_paint_funcs_set_image_func()
287 *
288 * A virtual method for the #hb_paint_funcs_t to paint a glyph image.
289 *
290 * This method is called for glyphs with image blobs in the CBDT,
291 * sbix or SVG tables. The @format identifies the kind of data that
292 * is contained in @image. Possible values include #HB_PAINT_IMAGE_FORMAT_PNG,
293 * #HB_PAINT_IMAGE_FORMAT_SVG and #HB_PAINT_IMAGE_FORMAT_BGRA.
294 *
295 * The image dimensions and glyph extents are provided if available,
296 * and should be used to size and position the image.
297 *
298 * Return value: Whether the operation was successful.
299 *
300 * Since: 7.0.0
301 */
302 typedef hb_bool_t (*hb_paint_image_func_t) (hb_paint_funcs_t *funcs,
303 void *paint_data,
304 hb_blob_t *image,
305 unsigned int width,
306 unsigned int height,
307 hb_tag_t format,
308 float slant,
309 hb_glyph_extents_t *extents,
310 void *user_data);
311
312 /**
313 * hb_color_stop_t:
314 * @offset: the offset of the color stop
315 * @is_foreground: whether the color is the foreground
316 * @color: the color, unpremultiplied
317 *
318 * Information about a color stop on a color line.
319 *
320 * Color lines typically have offsets ranging between 0 and 1,
321 * but that is not required.
322 *
323 * Note: despite @color being unpremultiplied here, interpolation in
324 * gradients shall happen in premultiplied space. See the OpenType spec
325 * [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr)
326 * section for details.
327 *
328 * Since: 7.0.0
329 */
330 typedef struct {
331 float offset;
332 hb_bool_t is_foreground;
333 hb_color_t color;
334 } hb_color_stop_t;
335
336 /**
337 * hb_paint_extend_t:
338 * @HB_PAINT_EXTEND_PAD: Outside the defined interval,
339 * the color of the closest color stop is used.
340 * @HB_PAINT_EXTEND_REPEAT: The color line is repeated over
341 * repeated multiples of the defined interval
342 * @HB_PAINT_EXTEND_REFLECT: The color line is repeated over
343 * repeated intervals, as for the repeat mode.
344 * However, in each repeated interval, the ordering of
345 * color stops is the reverse of the adjacent interval.
346 *
347 * The values of this enumeration determine how color values
348 * outside the minimum and maximum defined offset on a #hb_color_line_t
349 * are determined.
350 *
351 * See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr)
352 * section for details.
353 *
354 * Since: 7.0.0
355 */
356 typedef enum {
357 HB_PAINT_EXTEND_PAD,
358 HB_PAINT_EXTEND_REPEAT,
359 HB_PAINT_EXTEND_REFLECT
360 } hb_paint_extend_t;
361
362 typedef struct hb_color_line_t hb_color_line_t;
363
364 /**
365 * hb_color_line_get_color_stops_func_t:
366 * @color_line: a #hb_color_line_t object
367 * @color_line_data: the data accompanying @color_line
368 * @start: the index of the first color stop to return
369 * @count: (inout) (optional): Input = the maximum number of feature tags to return;
370 * Output = the actual number of feature tags returned (may be zero)
371 * @color_stops: (out) (array length=count) (optional): Array of #hb_color_stop_t to populate
372 * @user_data: the data accompanying this method
373 *
374 * A virtual method for the #hb_color_line_t to fetch color stops.
375 *
376 * Return value: the total number of color stops in @color_line
377 *
378 * Since: 7.0.0
379 */
380 typedef unsigned int (*hb_color_line_get_color_stops_func_t) (hb_color_line_t *color_line,
381 void *color_line_data,
382 unsigned int start,
383 unsigned int *count,
384 hb_color_stop_t *color_stops,
385 void *user_data);
386
387 /**
388 * hb_color_line_get_extend_func_t:
389 * @color_line: a #hb_color_line_t object
390 * @color_line_data: the data accompanying @color_line
391 * @user_data: the data accompanying this method
392 *
393 * A virtual method for the @hb_color_line_t to fetches the extend mode.
394 *
395 * Return value: the extend mode of @color_line
396 *
397 * Since: 7.0.0
398 */
399 typedef hb_paint_extend_t (*hb_color_line_get_extend_func_t) (hb_color_line_t *color_line,
400 void *color_line_data,
401 void *user_data);
402
403 /**
404 * hb_color_line_t:
405 *
406 * A struct containing color information for a gradient.
407 *
408 * Since: 7.0.0
409 */
410 struct hb_color_line_t {
411 void *data;
412
413 hb_color_line_get_color_stops_func_t get_color_stops;
414 void *get_color_stops_user_data;
415
416 hb_color_line_get_extend_func_t get_extend;
417 void *get_extend_user_data;
418
419 void *reserved0;
420 void *reserved1;
421 void *reserved2;
422 void *reserved3;
423 void *reserved5;
424 void *reserved6;
425 void *reserved7;
426 void *reserved8;
427 };
428
429 HB_EXTERN unsigned int
430 hb_color_line_get_color_stops (hb_color_line_t *color_line,
431 unsigned int start,
432 unsigned int *count,
433 hb_color_stop_t *color_stops);
434
435 HB_EXTERN hb_paint_extend_t
436 hb_color_line_get_extend (hb_color_line_t *color_line);
437
438 /**
439 * hb_paint_linear_gradient_func_t:
440 * @funcs: paint functions object
441 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
442 * @color_line: Color information for the gradient
443 * @x0: X coordinate of the first point
444 * @y0: Y coordinate of the first point
445 * @x1: X coordinate of the second point
446 * @y1: Y coordinate of the second point
447 * @x2: X coordinate of the third point
448 * @y2: Y coordinate of the third point
449 * @user_data: User data pointer passed to hb_paint_funcs_set_linear_gradient_func()
450 *
451 * A virtual method for the #hb_paint_funcs_t to paint a linear
452 * gradient everywhere within the current clip.
453 *
454 * The @color_line object contains information about the colors of the gradients.
455 * It is only valid for the duration of the callback, you cannot keep it around.
456 *
457 * The coordinates of the points are interpreted according
458 * to the current transform.
459 *
460 * See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr)
461 * section for details on how the points define the direction
462 * of the gradient, and how to interpret the @color_line.
463 *
464 * Since: 7.0.0
465 */
466 typedef void (*hb_paint_linear_gradient_func_t) (hb_paint_funcs_t *funcs,
467 void *paint_data,
468 hb_color_line_t *color_line,
469 float x0, float y0,
470 float x1, float y1,
471 float x2, float y2,
472 void *user_data);
473
474 /**
475 * hb_paint_radial_gradient_func_t:
476 * @funcs: paint functions object
477 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
478 * @color_line: Color information for the gradient
479 * @x0: X coordinate of the first circle's center
480 * @y0: Y coordinate of the first circle's center
481 * @r0: radius of the first circle
482 * @x1: X coordinate of the second circle's center
483 * @y1: Y coordinate of the second circle's center
484 * @r1: radius of the second circle
485 * @user_data: User data pointer passed to hb_paint_funcs_set_radial_gradient_func()
486 *
487 * A virtual method for the #hb_paint_funcs_t to paint a radial
488 * gradient everywhere within the current clip.
489 *
490 * The @color_line object contains information about the colors of the gradients.
491 * It is only valid for the duration of the callback, you cannot keep it around.
492 *
493 * The coordinates of the points are interpreted according
494 * to the current transform.
495 *
496 * See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr)
497 * section for details on how the points define the direction
498 * of the gradient, and how to interpret the @color_line.
499 *
500 * Since: 7.0.0
501 */
502 typedef void (*hb_paint_radial_gradient_func_t) (hb_paint_funcs_t *funcs,
503 void *paint_data,
504 hb_color_line_t *color_line,
505 float x0, float y0, float r0,
506 float x1, float y1, float r1,
507 void *user_data);
508
509 /**
510 * hb_paint_sweep_gradient_func_t:
511 * @funcs: paint functions object
512 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
513 * @color_line: Color information for the gradient
514 * @x0: X coordinate of the circle's center
515 * @y0: Y coordinate of the circle's center
516 * @start_angle: the start angle, in radians
517 * @end_angle: the end angle, in radians
518 * @user_data: User data pointer passed to hb_paint_funcs_set_sweep_gradient_func()
519 *
520 * A virtual method for the #hb_paint_funcs_t to paint a sweep
521 * gradient everywhere within the current clip.
522 *
523 * The @color_line object contains information about the colors of the gradients.
524 * It is only valid for the duration of the callback, you cannot keep it around.
525 *
526 * The coordinates of the points are interpreted according
527 * to the current transform.
528 *
529 * See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr)
530 * section for details on how the points define the direction
531 * of the gradient, and how to interpret the @color_line.
532 *
533 * Since: 7.0.0
534 */
535 typedef void (*hb_paint_sweep_gradient_func_t) (hb_paint_funcs_t *funcs,
536 void *paint_data,
537 hb_color_line_t *color_line,
538 float x0, float y0,
539 float start_angle,
540 float end_angle,
541 void *user_data);
542
543 /**
544 * hb_paint_composite_mode_t:
545 * @HB_PAINT_COMPOSITE_MODE_CLEAR: clear destination layer (bounded)
546 * @HB_PAINT_COMPOSITE_MODE_SRC: replace destination layer (bounded)
547 * @HB_PAINT_COMPOSITE_MODE_SRC_OVER: draw source layer on top of destination layer
548 * (bounded)
549 * @HB_PAINT_COMPOSITE_MODE_SRC_IN: draw source where there was destination content
550 * (unbounded)
551 * @HB_PAINT_COMPOSITE_MODE_SRC_OUT: draw source where there was no destination
552 * content (unbounded)
553 * @HB_PAINT_COMPOSITE_MODE_SRC_ATOP: draw source on top of destination content and
554 * only there
555 * @HB_PAINT_COMPOSITE_MODE_DEST: ignore the source
556 * @HB_PAINT_COMPOSITE_MODE_DEST_OVER: draw destination on top of source
557 * @HB_PAINT_COMPOSITE_MODE_DEST_IN: leave destination only where there was
558 * source content (unbounded)
559 * @HB_PAINT_COMPOSITE_MODE_DEST_OUT: leave destination only where there was no
560 * source content
561 * @HB_PAINT_COMPOSITE_MODE_DEST_ATOP: leave destination on top of source content
562 * and only there (unbounded)
563 * @HB_PAINT_COMPOSITE_MODE_XOR: source and destination are shown where there is only
564 * one of them
565 * @HB_PAINT_COMPOSITE_MODE_PLUS: source and destination layers are accumulated
566 * @HB_PAINT_COMPOSITE_MODE_MULTIPLY: source and destination layers are multiplied.
567 * This causes the result to be at least as dark as the darker inputs.
568 * @HB_PAINT_COMPOSITE_MODE_SCREEN: source and destination are complemented and
569 * multiplied. This causes the result to be at least as light as the lighter
570 * inputs.
571 * @HB_PAINT_COMPOSITE_MODE_OVERLAY: multiplies or screens, depending on the
572 * lightness of the destination color.
573 * @HB_PAINT_COMPOSITE_MODE_DARKEN: replaces the destination with the source if it
574 * is darker, otherwise keeps the source.
575 * @HB_PAINT_COMPOSITE_MODE_LIGHTEN: replaces the destination with the source if it
576 * is lighter, otherwise keeps the source.
577 * @HB_PAINT_COMPOSITE_MODE_COLOR_DODGE: brightens the destination color to reflect
578 * the source color.
579 * @HB_PAINT_COMPOSITE_MODE_COLOR_BURN: darkens the destination color to reflect
580 * the source color.
581 * @HB_PAINT_COMPOSITE_MODE_HARD_LIGHT: Multiplies or screens, dependent on source
582 * color.
583 * @HB_PAINT_COMPOSITE_MODE_SOFT_LIGHT: Darkens or lightens, dependent on source
584 * color.
585 * @HB_PAINT_COMPOSITE_MODE_DIFFERENCE: Takes the difference of the source and
586 * destination color.
587 * @HB_PAINT_COMPOSITE_MODE_EXCLUSION: Produces an effect similar to difference, but
588 * with lower contrast.
589 * @HB_PAINT_COMPOSITE_MODE_HSL_HUE: Creates a color with the hue of the source
590 * and the saturation and luminosity of the target.
591 * @HB_PAINT_COMPOSITE_MODE_HSL_SATURATION: Creates a color with the saturation
592 * of the source and the hue and luminosity of the target. Painting with
593 * this mode onto a gray area produces no change.
594 * @HB_PAINT_COMPOSITE_MODE_HSL_COLOR: Creates a color with the hue and saturation
595 * of the source and the luminosity of the target. This preserves the gray
596 * levels of the target and is useful for coloring monochrome images or
597 * tinting color images.
598 * @HB_PAINT_COMPOSITE_MODE_HSL_LUMINOSITY: Creates a color with the luminosity of
599 * the source and the hue and saturation of the target. This produces an
600 * inverse effect to @HB_PAINT_COMPOSITE_MODE_HSL_COLOR.
601 *
602 * The values of this enumeration describe the compositing modes
603 * that can be used when combining temporary redirected drawing
604 * with the backdrop.
605 *
606 * See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr)
607 * section for details.
608 *
609 * Since: 7.0.0
610 */
611 typedef enum {
612 HB_PAINT_COMPOSITE_MODE_CLEAR,
613 HB_PAINT_COMPOSITE_MODE_SRC,
614 HB_PAINT_COMPOSITE_MODE_DEST,
615 HB_PAINT_COMPOSITE_MODE_SRC_OVER,
616 HB_PAINT_COMPOSITE_MODE_DEST_OVER,
617 HB_PAINT_COMPOSITE_MODE_SRC_IN,
618 HB_PAINT_COMPOSITE_MODE_DEST_IN,
619 HB_PAINT_COMPOSITE_MODE_SRC_OUT,
620 HB_PAINT_COMPOSITE_MODE_DEST_OUT,
621 HB_PAINT_COMPOSITE_MODE_SRC_ATOP,
622 HB_PAINT_COMPOSITE_MODE_DEST_ATOP,
623 HB_PAINT_COMPOSITE_MODE_XOR,
624 HB_PAINT_COMPOSITE_MODE_PLUS,
625 HB_PAINT_COMPOSITE_MODE_SCREEN,
626 HB_PAINT_COMPOSITE_MODE_OVERLAY,
627 HB_PAINT_COMPOSITE_MODE_DARKEN,
628 HB_PAINT_COMPOSITE_MODE_LIGHTEN,
629 HB_PAINT_COMPOSITE_MODE_COLOR_DODGE,
630 HB_PAINT_COMPOSITE_MODE_COLOR_BURN,
631 HB_PAINT_COMPOSITE_MODE_HARD_LIGHT,
632 HB_PAINT_COMPOSITE_MODE_SOFT_LIGHT,
633 HB_PAINT_COMPOSITE_MODE_DIFFERENCE,
634 HB_PAINT_COMPOSITE_MODE_EXCLUSION,
635 HB_PAINT_COMPOSITE_MODE_MULTIPLY,
636 HB_PAINT_COMPOSITE_MODE_HSL_HUE,
637 HB_PAINT_COMPOSITE_MODE_HSL_SATURATION,
638 HB_PAINT_COMPOSITE_MODE_HSL_COLOR,
639 HB_PAINT_COMPOSITE_MODE_HSL_LUMINOSITY
640 } hb_paint_composite_mode_t;
641
642 /**
643 * hb_paint_push_group_func_t:
644 * @funcs: paint functions object
645 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
646 * @user_data: User data pointer passed to hb_paint_funcs_set_push_group_func()
647 *
648 * A virtual method for the #hb_paint_funcs_t to use
649 * an intermediate surface for subsequent paint calls.
650 *
651 * The drawing will be redirected to an intermediate surface
652 * until a matching call to the #hb_paint_funcs_pop_group_func_t
653 * vfunc.
654 *
655 * Since: 7.0.0
656 */
657 typedef void (*hb_paint_push_group_func_t) (hb_paint_funcs_t *funcs,
658 void *paint_data,
659 void *user_data);
660
661 /**
662 * hb_paint_pop_group_func_t:
663 * @funcs: paint functions object
664 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
665 * @mode: the compositing mode to use
666 * @user_data: User data pointer passed to hb_paint_funcs_set_pop_group_func()
667 *
668 * A virtual method for the #hb_paint_funcs_t to undo
669 * the effect of a prior call to the #hb_paint_funcs_push_group_func_t
670 * vfunc.
671 *
672 * This call stops the redirection to the intermediate surface,
673 * and then composites it on the previous surface, using the
674 * compositing mode passed to this call.
675 *
676 * Since: 7.0.0
677 */
678 typedef void (*hb_paint_pop_group_func_t) (hb_paint_funcs_t *funcs,
679 void *paint_data,
680 hb_paint_composite_mode_t mode,
681 void *user_data);
682
683 /**
684 * hb_paint_custom_palette_color_func_t:
685 * @funcs: paint functions object
686 * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
687 * @color_index: the color index
688 * @color: (out): fetched color
689 * @user_data: User data pointer passed to hb_paint_funcs_set_pop_group_func()
690 *
691 * A virtual method for the #hb_paint_funcs_t to fetch a color from the custom
692 * color palette.
693 *
694 * Custom palette colors override the colors from the fonts selected color
695 * palette. It is not necessary to override all palette entries; for entries
696 * that should be taken from the font palette, return `false`.
697 *
698 * This function might get called multiple times, but the custom palette is
699 * expected to remain unchanged for duration of a hb_font_paint_glyph() call.
700 *
701 * Return value: `true` if found, `false` otherwise
702 *
703 * Since: 7.0.0
704 */
705 typedef hb_bool_t (*hb_paint_custom_palette_color_func_t) (hb_paint_funcs_t *funcs,
706 void *paint_data,
707 unsigned int color_index,
708 hb_color_t *color,
709 void *user_data);
710
711
712 /**
713 * hb_paint_funcs_set_push_transform_func:
714 * @funcs: A paint functions struct
715 * @func: (closure user_data) (destroy destroy) (scope notified): The push-transform callback
716 * @user_data: Data to pass to @func
717 * @destroy: (nullable): Function to call when @user_data is no longer needed
718 *
719 * Sets the push-transform callback on the paint functions struct.
720 *
721 * Since: 7.0.0
722 */
723 HB_EXTERN void
724 hb_paint_funcs_set_push_transform_func (hb_paint_funcs_t *funcs,
725 hb_paint_push_transform_func_t func,
726 void *user_data,
727 hb_destroy_func_t destroy);
728
729 /**
730 * hb_paint_funcs_set_pop_transform_func:
731 * @funcs: A paint functions struct
732 * @func: (closure user_data) (destroy destroy) (scope notified): The pop-transform callback
733 * @user_data: Data to pass to @func
734 * @destroy: (nullable): Function to call when @user_data is no longer needed
735 *
736 * Sets the pop-transform callback on the paint functions struct.
737 *
738 * Since: 7.0.0
739 */
740 HB_EXTERN void
741 hb_paint_funcs_set_pop_transform_func (hb_paint_funcs_t *funcs,
742 hb_paint_pop_transform_func_t func,
743 void *user_data,
744 hb_destroy_func_t destroy);
745
746 /**
747 * hb_paint_funcs_set_color_glyph_func:
748 * @funcs: A paint functions struct
749 * @func: (closure user_data) (destroy destroy) (scope notified): The color-glyph callback
750 * @user_data: Data to pass to @func
751 * @destroy: (nullable): Function to call when @user_data is no longer needed
752 *
753 * Sets the color-glyph callback on the paint functions struct.
754 *
755 * Since: 8.2.0
756 */
757 HB_EXTERN void
758 hb_paint_funcs_set_color_glyph_func (hb_paint_funcs_t *funcs,
759 hb_paint_color_glyph_func_t func,
760 void *user_data,
761 hb_destroy_func_t destroy);
762
763 /**
764 * hb_paint_funcs_set_push_clip_glyph_func:
765 * @funcs: A paint functions struct
766 * @func: (closure user_data) (destroy destroy) (scope notified): The push-clip-glyph callback
767 * @user_data: Data to pass to @func
768 * @destroy: (nullable): Function to call when @user_data is no longer needed
769 *
770 * Sets the push-clip-glyph callback on the paint functions struct.
771 *
772 * Since: 7.0.0
773 */
774 HB_EXTERN void
775 hb_paint_funcs_set_push_clip_glyph_func (hb_paint_funcs_t *funcs,
776 hb_paint_push_clip_glyph_func_t func,
777 void *user_data,
778 hb_destroy_func_t destroy);
779
780 /**
781 * hb_paint_funcs_set_push_clip_rectangle_func:
782 * @funcs: A paint functions struct
783 * @func: (closure user_data) (destroy destroy) (scope notified): The push-clip-rectangle callback
784 * @user_data: Data to pass to @func
785 * @destroy: (nullable): Function to call when @user_data is no longer needed
786 *
787 * Sets the push-clip-rect callback on the paint functions struct.
788 *
789 * Since: 7.0.0
790 */
791 HB_EXTERN void
792 hb_paint_funcs_set_push_clip_rectangle_func (hb_paint_funcs_t *funcs,
793 hb_paint_push_clip_rectangle_func_t func,
794 void *user_data,
795 hb_destroy_func_t destroy);
796
797 /**
798 * hb_paint_funcs_set_pop_clip_func:
799 * @funcs: A paint functions struct
800 * @func: (closure user_data) (destroy destroy) (scope notified): The pop-clip callback
801 * @user_data: Data to pass to @func
802 * @destroy: (nullable): Function to call when @user_data is no longer needed
803 *
804 * Sets the pop-clip callback on the paint functions struct.
805 *
806 * Since: 7.0.0
807 */
808 HB_EXTERN void
809 hb_paint_funcs_set_pop_clip_func (hb_paint_funcs_t *funcs,
810 hb_paint_pop_clip_func_t func,
811 void *user_data,
812 hb_destroy_func_t destroy);
813
814 /**
815 * hb_paint_funcs_set_color_func:
816 * @funcs: A paint functions struct
817 * @func: (closure user_data) (destroy destroy) (scope notified): The paint-color callback
818 * @user_data: Data to pass to @func
819 * @destroy: (nullable): Function to call when @user_data is no longer needed
820 *
821 * Sets the paint-color callback on the paint functions struct.
822 *
823 * Since: 7.0.0
824 */
825 HB_EXTERN void
826 hb_paint_funcs_set_color_func (hb_paint_funcs_t *funcs,
827 hb_paint_color_func_t func,
828 void *user_data,
829 hb_destroy_func_t destroy);
830
831 /**
832 * hb_paint_funcs_set_image_func:
833 * @funcs: A paint functions struct
834 * @func: (closure user_data) (destroy destroy) (scope notified): The paint-image callback
835 * @user_data: Data to pass to @func
836 * @destroy: (nullable): Function to call when @user_data is no longer needed
837 *
838 * Sets the paint-image callback on the paint functions struct.
839 *
840 * Since: 7.0.0
841 */
842 HB_EXTERN void
843 hb_paint_funcs_set_image_func (hb_paint_funcs_t *funcs,
844 hb_paint_image_func_t func,
845 void *user_data,
846 hb_destroy_func_t destroy);
847
848 /**
849 * hb_paint_funcs_set_linear_gradient_func:
850 * @funcs: A paint functions struct
851 * @func: (closure user_data) (destroy destroy) (scope notified): The linear-gradient callback
852 * @user_data: Data to pass to @func
853 * @destroy: (nullable): Function to call when @user_data is no longer needed
854 *
855 * Sets the linear-gradient callback on the paint functions struct.
856 *
857 * Since: 7.0.0
858 */
859 HB_EXTERN void
860 hb_paint_funcs_set_linear_gradient_func (hb_paint_funcs_t *funcs,
861 hb_paint_linear_gradient_func_t func,
862 void *user_data,
863 hb_destroy_func_t destroy);
864
865 /**
866 * hb_paint_funcs_set_radial_gradient_func:
867 * @funcs: A paint functions struct
868 * @func: (closure user_data) (destroy destroy) (scope notified): The radial-gradient callback
869 * @user_data: Data to pass to @func
870 * @destroy: (nullable): Function to call when @user_data is no longer needed
871 *
872 * Sets the radial-gradient callback on the paint functions struct.
873 *
874 * Since: 7.0.0
875 */
876 HB_EXTERN void
877 hb_paint_funcs_set_radial_gradient_func (hb_paint_funcs_t *funcs,
878 hb_paint_radial_gradient_func_t func,
879 void *user_data,
880 hb_destroy_func_t destroy);
881
882 /**
883 * hb_paint_funcs_set_sweep_gradient_func:
884 * @funcs: A paint functions struct
885 * @func: (closure user_data) (destroy destroy) (scope notified): The sweep-gradient callback
886 * @user_data: Data to pass to @func
887 * @destroy: (nullable): Function to call when @user_data is no longer needed
888 *
889 * Sets the sweep-gradient callback on the paint functions struct.
890 *
891 * Since: 7.0.0
892 */
893 HB_EXTERN void
894 hb_paint_funcs_set_sweep_gradient_func (hb_paint_funcs_t *funcs,
895 hb_paint_sweep_gradient_func_t func,
896 void *user_data,
897 hb_destroy_func_t destroy);
898
899 /**
900 * hb_paint_funcs_set_push_group_func:
901 * @funcs: A paint functions struct
902 * @func: (closure user_data) (destroy destroy) (scope notified): The push-group callback
903 * @user_data: Data to pass to @func
904 * @destroy: (nullable): Function to call when @user_data is no longer needed
905 *
906 * Sets the push-group callback on the paint functions struct.
907 *
908 * Since: 7.0.0
909 */
910 HB_EXTERN void
911 hb_paint_funcs_set_push_group_func (hb_paint_funcs_t *funcs,
912 hb_paint_push_group_func_t func,
913 void *user_data,
914 hb_destroy_func_t destroy);
915
916 /**
917 * hb_paint_funcs_set_pop_group_func:
918 * @funcs: A paint functions struct
919 * @func: (closure user_data) (destroy destroy) (scope notified): The pop-group callback
920 * @user_data: Data to pass to @func
921 * @destroy: (nullable): Function to call when @user_data is no longer needed
922 *
923 * Sets the pop-group callback on the paint functions struct.
924 *
925 * Since: 7.0.0
926 */
927 HB_EXTERN void
928 hb_paint_funcs_set_pop_group_func (hb_paint_funcs_t *funcs,
929 hb_paint_pop_group_func_t func,
930 void *user_data,
931 hb_destroy_func_t destroy);
932
933 /**
934 * hb_paint_funcs_set_custom_palette_color_func:
935 * @funcs: A paint functions struct
936 * @func: (closure user_data) (destroy destroy) (scope notified): The custom-palette-color callback
937 * @user_data: Data to pass to @func
938 * @destroy: (nullable): Function to call when @user_data is no longer needed
939 *
940 * Sets the custom-palette-color callback on the paint functions struct.
941 *
942 * Since: 7.0.0
943 */
944 HB_EXTERN void
945 hb_paint_funcs_set_custom_palette_color_func (hb_paint_funcs_t *funcs,
946 hb_paint_custom_palette_color_func_t func,
947 void *user_data,
948 hb_destroy_func_t destroy);
949 /*
950 * Manual API
951 */
952
953 HB_EXTERN void
954 hb_paint_push_transform (hb_paint_funcs_t *funcs, void *paint_data,
955 float xx, float yx,
956 float xy, float yy,
957 float dx, float dy);
958
959 HB_EXTERN void
960 hb_paint_pop_transform (hb_paint_funcs_t *funcs, void *paint_data);
961
962 HB_EXTERN hb_bool_t
963 hb_paint_color_glyph (hb_paint_funcs_t *funcs, void *paint_data,
964 hb_codepoint_t glyph,
965 hb_font_t *font);
966
967 HB_EXTERN void
968 hb_paint_push_clip_glyph (hb_paint_funcs_t *funcs, void *paint_data,
969 hb_codepoint_t glyph,
970 hb_font_t *font);
971
972 HB_EXTERN void
973 hb_paint_push_clip_rectangle (hb_paint_funcs_t *funcs, void *paint_data,
974 float xmin, float ymin,
975 float xmax, float ymax);
976
977 HB_EXTERN void
978 hb_paint_pop_clip (hb_paint_funcs_t *funcs, void *paint_data);
979
980 HB_EXTERN void
981 hb_paint_color (hb_paint_funcs_t *funcs, void *paint_data,
982 hb_bool_t is_foreground,
983 hb_color_t color);
984
985 HB_EXTERN void
986 hb_paint_image (hb_paint_funcs_t *funcs, void *paint_data,
987 hb_blob_t *image,
988 unsigned int width,
989 unsigned int height,
990 hb_tag_t format,
991 float slant,
992 hb_glyph_extents_t *extents);
993
994 HB_EXTERN void
995 hb_paint_linear_gradient (hb_paint_funcs_t *funcs, void *paint_data,
996 hb_color_line_t *color_line,
997 float x0, float y0,
998 float x1, float y1,
999 float x2, float y2);
1000
1001 HB_EXTERN void
1002 hb_paint_radial_gradient (hb_paint_funcs_t *funcs, void *paint_data,
1003 hb_color_line_t *color_line,
1004 float x0, float y0,
1005 float r0,
1006 float x1, float y1,
1007 float r1);
1008
1009 HB_EXTERN void
1010 hb_paint_sweep_gradient (hb_paint_funcs_t *funcs, void *paint_data,
1011 hb_color_line_t *color_line,
1012 float x0, float y0,
1013 float start_angle, float end_angle);
1014
1015 HB_EXTERN void
1016 hb_paint_push_group (hb_paint_funcs_t *funcs, void *paint_data);
1017
1018 HB_EXTERN void
1019 hb_paint_pop_group (hb_paint_funcs_t *funcs, void *paint_data,
1020 hb_paint_composite_mode_t mode);
1021
1022 HB_EXTERN hb_bool_t
1023 hb_paint_custom_palette_color (hb_paint_funcs_t *funcs, void *paint_data,
1024 unsigned int color_index,
1025 hb_color_t *color);
1026
1027 HB_END_DECLS
1028
1029 #endif /* HB_PAINT_H */