include/harfbuzz/hb-paint.h

0001 /*
0002  * Copyright © 2022 Matthias Clasen
0003  *
0004  *  This is part of HarfBuzz, a text shaping library.
0005  *
0006  * Permission is hereby granted, without written agreement and without
0007  * license or royalty fees, to use, copy, modify, and distribute this
0008  * software and its documentation for any purpose, provided that the
0009  * above copyright notice and the following two paragraphs appear in
0010  * all copies of this software.
0011  *
0012  * IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR
0013  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
0014  * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
0015  * IF THE COPYRIGHT HOLDER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
0016  * DAMAGE.
0017  *
0018  * THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
0019  * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
0020  * FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
0021  * ON AN "AS IS" BASIS, AND THE COPYRIGHT HOLDER HAS NO OBLIGATION TO
0022  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
0023  */
0024
0025 #if !defined(HB_H_IN) && !defined(HB_NO_SINGLE_HEADER_ERROR)
0026 #error "Include <hb.h> instead."
0027 #endif
0028
0029 #ifndef HB_PAINT_H
0030 #define HB_PAINT_H
0031
0032 #include "hb-common.h"
0033
0034 HB_BEGIN_DECLS
0035
0036
0037 /**
0038  * hb_paint_funcs_t:
0039  *
0040  * Glyph paint callbacks.
0041  *
0042  * The callbacks assume that the caller maintains a stack
0043  * of current transforms, clips and intermediate surfaces,
0044  * as evidenced by the pairs of push/pop callbacks. The
0045  * push/pop calls will be properly nested, so it is fine
0046  * to store the different kinds of object on a single stack.
0047  *
0048  * Not all callbacks are required for all kinds of glyphs.
0049  * For rendering COLRv0 or non-color outline glyphs, the
0050  * gradient callbacks are not needed, and the composite
0051  * callback only needs to handle simple alpha compositing
0052  * (#HB_PAINT_COMPOSITE_MODE_SRC_OVER).
0053  *
0054  * The paint-image callback is only needed for glyphs
0055  * with image blobs in the CBDT, sbix or SVG tables.
0056  *
0057  * The custom-palette-color callback is only necessary if
0058  * you want to override colors from the font palette with
0059  * custom colors.
0060  *
0061  * Since: 7.0.0
0062  **/
0063 typedef struct hb_paint_funcs_t hb_paint_funcs_t;
0064
0065 HB_EXTERN hb_paint_funcs_t *
0066 hb_paint_funcs_create (void);
0067
0068 HB_EXTERN hb_paint_funcs_t *
0069 hb_paint_funcs_get_empty (void);
0070
0071 HB_EXTERN hb_paint_funcs_t *
0072 hb_paint_funcs_reference (hb_paint_funcs_t *funcs);
0073
0074 HB_EXTERN void
0075 hb_paint_funcs_destroy (hb_paint_funcs_t *funcs);
0076
0077 HB_EXTERN hb_bool_t
0078 hb_paint_funcs_set_user_data (hb_paint_funcs_t *funcs,
0079                   hb_user_data_key_t *key,
0080                   void *              data,
0081                   hb_destroy_func_t   destroy,
0082                   hb_bool_t           replace);
0083
0084
0085 HB_EXTERN void *
0086 hb_paint_funcs_get_user_data (const hb_paint_funcs_t *funcs,
0087                   hb_user_data_key_t       *key);
0088
0089 HB_EXTERN void
0090 hb_paint_funcs_make_immutable (hb_paint_funcs_t *funcs);
0091
0092 HB_EXTERN hb_bool_t
0093 hb_paint_funcs_is_immutable (hb_paint_funcs_t *funcs);
0094
0095 /**
0096  * hb_paint_push_transform_func_t:
0097  * @funcs: paint functions object
0098  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0099  * @xx: xx component of the transform matrix
0100  * @yx: yx component of the transform matrix
0101  * @xy: xy component of the transform matrix
0102  * @yy: yy component of the transform matrix
0103  * @dx: dx component of the transform matrix
0104  * @dy: dy component of the transform matrix
0105  * @user_data: User data pointer passed to hb_paint_funcs_set_push_transform_func()
0106  *
0107  * A virtual method for the #hb_paint_funcs_t to apply
0108  * a transform to subsequent paint calls.
0109  *
0110  * This transform is applied after the current transform,
0111  * and remains in effect until a matching call to
0112  * the #hb_paint_funcs_pop_transform_func_t vfunc.
0113  *
0114  * Since: 7.0.0
0115  */
0116 typedef void (*hb_paint_push_transform_func_t) (hb_paint_funcs_t *funcs,
0117                                                 void *paint_data,
0118                                                 float xx, float yx,
0119                                                 float xy, float yy,
0120                                                 float dx, float dy,
0121                                                 void *user_data);
0122
0123 /**
0124  * hb_paint_pop_transform_func_t:
0125  * @funcs: paint functions object
0126  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0127  * @user_data: User data pointer passed to hb_paint_funcs_set_pop_transform_func()
0128  *
0129  * A virtual method for the #hb_paint_funcs_t to undo
0130  * the effect of a prior call to the #hb_paint_funcs_push_transform_func_t
0131  * vfunc.
0132  *
0133  * Since: 7.0.0
0134  */
0135 typedef void (*hb_paint_pop_transform_func_t) (hb_paint_funcs_t *funcs,
0136                                                void *paint_data,
0137                                                void *user_data);
0138
0139 /**
0140  * hb_paint_color_glyph_func_t:
0141  * @funcs: paint functions object
0142  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0143  * @glyph: the glyph ID
0144  * @font: the font
0145  * @user_data: User data pointer passed to hb_paint_funcs_set_color_glyph_func()
0146  *
0147  * A virtual method for the #hb_paint_funcs_t to render a color glyph by glyph index.
0148  *
0149  * Return value: %true if the glyph was painted, %false otherwise.
0150  *
0151  * Since: 8.2.0
0152  */
0153 typedef hb_bool_t (*hb_paint_color_glyph_func_t) (hb_paint_funcs_t *funcs,
0154                                                   void *paint_data,
0155                                                   hb_codepoint_t glyph,
0156                                                   hb_font_t *font,
0157                                                   void *user_data);
0158
0159 /**
0160  * hb_paint_push_clip_glyph_func_t:
0161  * @funcs: paint functions object
0162  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0163  * @glyph: the glyph ID
0164  * @font: the font
0165  * @user_data: User data pointer passed to hb_paint_funcs_set_push_clip_glyph_func()
0166  *
0167  * A virtual method for the #hb_paint_funcs_t to clip
0168  * subsequent paint calls to the outline of a glyph.
0169  *
0170  * The coordinates of the glyph outline are interpreted according
0171  * to the current transform.
0172  *
0173  * This clip is applied in addition to the current clip,
0174  * and remains in effect until a matching call to
0175  * the #hb_paint_funcs_pop_clip_func_t vfunc.
0176  *
0177  * Since: 7.0.0
0178  */
0179 typedef void (*hb_paint_push_clip_glyph_func_t) (hb_paint_funcs_t *funcs,
0180                                                  void *paint_data,
0181                                                  hb_codepoint_t glyph,
0182                                                  hb_font_t *font,
0183                                                  void *user_data);
0184
0185 /**
0186  * hb_paint_push_clip_rectangle_func_t:
0187  * @funcs: paint functions object
0188  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0189  * @xmin: min X for the rectangle
0190  * @ymin: min Y for the rectangle
0191  * @xmax: max X for the rectangle
0192  * @ymax: max Y for the rectangle
0193  * @user_data: User data pointer passed to hb_paint_funcs_set_push_clip_rectangle_func()
0194  *
0195  * A virtual method for the #hb_paint_funcs_t to clip
0196  * subsequent paint calls to a rectangle.
0197  *
0198  * The coordinates of the rectangle are interpreted according
0199  * to the current transform.
0200  *
0201  * This clip is applied in addition to the current clip,
0202  * and remains in effect until a matching call to
0203  * the #hb_paint_funcs_pop_clip_func_t vfunc.
0204  *
0205  * Since: 7.0.0
0206  */
0207 typedef void (*hb_paint_push_clip_rectangle_func_t) (hb_paint_funcs_t *funcs,
0208                                                      void *paint_data,
0209                                                      float xmin, float ymin,
0210                                                      float xmax, float ymax,
0211                                                      void *user_data);
0212
0213 /**
0214  * hb_paint_pop_clip_func_t:
0215  * @funcs: paint functions object
0216  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0217  * @user_data: User data pointer passed to hb_paint_funcs_set_pop_clip_func()
0218  *
0219  * A virtual method for the #hb_paint_funcs_t to undo
0220  * the effect of a prior call to the #hb_paint_funcs_push_clip_glyph_func_t
0221  * or #hb_paint_funcs_push_clip_rectangle_func_t vfuncs.
0222  *
0223  * Since: 7.0.0
0224  */
0225 typedef void (*hb_paint_pop_clip_func_t) (hb_paint_funcs_t *funcs,
0226                                           void *paint_data,
0227                                           void *user_data);
0228
0229 /**
0230  * hb_paint_color_func_t:
0231  * @funcs: paint functions object
0232  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0233  * @is_foreground: whether the color is the foreground
0234  * @color: The color to use, unpremultiplied
0235  * @user_data: User data pointer passed to hb_paint_funcs_set_color_func()
0236  *
0237  * A virtual method for the #hb_paint_funcs_t to paint a
0238  * color everywhere within the current clip.
0239  *
0240  * Since: 7.0.0
0241  */
0242 typedef void (*hb_paint_color_func_t) (hb_paint_funcs_t *funcs,
0243                                        void *paint_data,
0244                                        hb_bool_t is_foreground,
0245                                        hb_color_t color,
0246                                        void *user_data);
0247
0248 /**
0249  * HB_PAINT_IMAGE_FORMAT_PNG:
0250  *
0251  * Tag identifying PNG images in #hb_paint_image_func_t callbacks.
0252  *
0253  * Since: 7.0.0
0254  */
0255 #define HB_PAINT_IMAGE_FORMAT_PNG HB_TAG('p','n','g',' ')
0256
0257 /**
0258  * HB_PAINT_IMAGE_FORMAT_SVG:
0259  *
0260  * Tag identifying SVG images in #hb_paint_image_func_t callbacks.
0261  *
0262  * Since: 7.0.0
0263  */
0264 #define HB_PAINT_IMAGE_FORMAT_SVG HB_TAG('s','v','g',' ')
0265
0266 /**
0267  * HB_PAINT_IMAGE_FORMAT_BGRA:
0268  *
0269  * Tag identifying raw pixel-data images in #hb_paint_image_func_t callbacks.
0270  * The data is in BGRA pre-multiplied sRGBA color-space format.
0271  *
0272  * Since: 7.0.0
0273  */
0274 #define HB_PAINT_IMAGE_FORMAT_BGRA HB_TAG('B','G','R','A')
0275
0276 /**
0277  * hb_paint_image_func_t:
0278  * @funcs: paint functions object
0279  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0280  * @image: the image data
0281  * @width: width of the raster image in pixels, or 0
0282  * @height: height of the raster image in pixels, or 0
0283  * @format: the image format as a tag
0284  * @slant: the synthetic slant ratio to be applied to the image during rendering
0285  * @extents: (nullable): glyph extents for desired rendering
0286  * @user_data: User data pointer passed to hb_paint_funcs_set_image_func()
0287  *
0288  * A virtual method for the #hb_paint_funcs_t to paint a glyph image.
0289  *
0290  * This method is called for glyphs with image blobs in the CBDT,
0291  * sbix or SVG tables. The @format identifies the kind of data that
0292  * is contained in @image. Possible values include #HB_PAINT_IMAGE_FORMAT_PNG,
0293  * #HB_PAINT_IMAGE_FORMAT_SVG and #HB_PAINT_IMAGE_FORMAT_BGRA.
0294  *
0295  * The image dimensions and glyph extents are provided if available,
0296  * and should be used to size and position the image.
0297  *
0298  * Return value: Whether the operation was successful.
0299  *
0300  * Since: 7.0.0
0301  */
0302 typedef hb_bool_t (*hb_paint_image_func_t) (hb_paint_funcs_t *funcs,
0303                         void *paint_data,
0304                         hb_blob_t *image,
0305                         unsigned int width,
0306                         unsigned int height,
0307                         hb_tag_t format,
0308                         float slant,
0309                         hb_glyph_extents_t *extents,
0310                         void *user_data);
0311
0312 /**
0313  * hb_color_stop_t:
0314  * @offset: the offset of the color stop
0315  * @is_foreground: whether the color is the foreground
0316  * @color: the color, unpremultiplied
0317  *
0318  * Information about a color stop on a color line.
0319  *
0320  * Color lines typically have offsets ranging between 0 and 1,
0321  * but that is not required.
0322  *
0323  * Note: despite @color being unpremultiplied here, interpolation in
0324  * gradients shall happen in premultiplied space. See the OpenType spec
0325  * [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr)
0326  * section for details.
0327  *
0328  * Since: 7.0.0
0329  */
0330 typedef struct {
0331   float offset;
0332   hb_bool_t is_foreground;
0333   hb_color_t color;
0334 } hb_color_stop_t;
0335
0336 /**
0337  * hb_paint_extend_t:
0338  * @HB_PAINT_EXTEND_PAD: Outside the defined interval,
0339  *   the color of the closest color stop is used.
0340  * @HB_PAINT_EXTEND_REPEAT: The color line is repeated over
0341  *   repeated multiples of the defined interval
0342  * @HB_PAINT_EXTEND_REFLECT: The color line is repeated over
0343  *      repeated intervals, as for the repeat mode.
0344  *      However, in each repeated interval, the ordering of
0345  *      color stops is the reverse of the adjacent interval.
0346  *
0347  * The values of this enumeration determine how color values
0348  * outside the minimum and maximum defined offset on a #hb_color_line_t
0349  * are determined.
0350  *
0351  * See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr)
0352  * section for details.
0353  *
0354  * Since: 7.0.0
0355  */
0356 typedef enum {
0357   HB_PAINT_EXTEND_PAD,
0358   HB_PAINT_EXTEND_REPEAT,
0359   HB_PAINT_EXTEND_REFLECT
0360 } hb_paint_extend_t;
0361
0362 typedef struct hb_color_line_t hb_color_line_t;
0363
0364 /**
0365  * hb_color_line_get_color_stops_func_t:
0366  * @color_line: a #hb_color_line_t object
0367  * @color_line_data: the data accompanying @color_line
0368  * @start: the index of the first color stop to return
0369  * @count: (inout) (optional): Input = the maximum number of feature tags to return;
0370  *     Output = the actual number of feature tags returned (may be zero)
0371  * @color_stops: (out) (array length=count) (optional): Array of #hb_color_stop_t to populate
0372  * @user_data: the data accompanying this method
0373  *
0374  * A virtual method for the #hb_color_line_t to fetch color stops.
0375  *
0376  * Return value: the total number of color stops in @color_line
0377  *
0378  * Since: 7.0.0
0379  */
0380 typedef unsigned int (*hb_color_line_get_color_stops_func_t) (hb_color_line_t *color_line,
0381                                   void *color_line_data,
0382                                   unsigned int start,
0383                                   unsigned int *count,
0384                                   hb_color_stop_t *color_stops,
0385                                   void *user_data);
0386
0387 /**
0388  * hb_color_line_get_extend_func_t:
0389  * @color_line: a #hb_color_line_t object
0390  * @color_line_data: the data accompanying @color_line
0391  * @user_data: the data accompanying this method
0392  *
0393  * A virtual method for the @hb_color_line_t to fetches the extend mode.
0394  *
0395  * Return value: the extend mode of @color_line
0396  *
0397  * Since: 7.0.0
0398  */
0399 typedef hb_paint_extend_t (*hb_color_line_get_extend_func_t) (hb_color_line_t *color_line,
0400                                   void *color_line_data,
0401                                   void *user_data);
0402
0403 /**
0404  * hb_color_line_t:
0405  *
0406  * A struct containing color information for a gradient.
0407  *
0408  * Since: 7.0.0
0409  */
0410 struct hb_color_line_t {
0411   void *data;
0412
0413   hb_color_line_get_color_stops_func_t get_color_stops;
0414   void *get_color_stops_user_data;
0415
0416   hb_color_line_get_extend_func_t get_extend;
0417   void *get_extend_user_data;
0418
0419   void *reserved0;
0420   void *reserved1;
0421   void *reserved2;
0422   void *reserved3;
0423   void *reserved5;
0424   void *reserved6;
0425   void *reserved7;
0426   void *reserved8;
0427 };
0428
0429 HB_EXTERN unsigned int
0430 hb_color_line_get_color_stops (hb_color_line_t *color_line,
0431                                unsigned int start,
0432                                unsigned int *count,
0433                                hb_color_stop_t *color_stops);
0434
0435 HB_EXTERN hb_paint_extend_t
0436 hb_color_line_get_extend (hb_color_line_t *color_line);
0437
0438 /**
0439  * hb_paint_linear_gradient_func_t:
0440  * @funcs: paint functions object
0441  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0442  * @color_line: Color information for the gradient
0443  * @x0: X coordinate of the first point
0444  * @y0: Y coordinate of the first point
0445  * @x1: X coordinate of the second point
0446  * @y1: Y coordinate of the second point
0447  * @x2: X coordinate of the third point
0448  * @y2: Y coordinate of the third point
0449  * @user_data: User data pointer passed to hb_paint_funcs_set_linear_gradient_func()
0450  *
0451  * A virtual method for the #hb_paint_funcs_t to paint a linear
0452  * gradient everywhere within the current clip.
0453  *
0454  * The @color_line object contains information about the colors of the gradients.
0455  * It is only valid for the duration of the callback, you cannot keep it around.
0456  *
0457  * The coordinates of the points are interpreted according
0458  * to the current transform.
0459  *
0460  * See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr)
0461  * section for details on how the points define the direction
0462  * of the gradient, and how to interpret the @color_line.
0463  *
0464  * Since: 7.0.0
0465  */
0466 typedef void (*hb_paint_linear_gradient_func_t) (hb_paint_funcs_t *funcs,
0467                                                  void *paint_data,
0468                                                  hb_color_line_t *color_line,
0469                                                  float x0, float y0,
0470                                                  float x1, float y1,
0471                                                  float x2, float y2,
0472                                                  void *user_data);
0473
0474 /**
0475  * hb_paint_radial_gradient_func_t:
0476  * @funcs: paint functions object
0477  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0478  * @color_line: Color information for the gradient
0479  * @x0: X coordinate of the first circle's center
0480  * @y0: Y coordinate of the first circle's center
0481  * @r0: radius of the first circle
0482  * @x1: X coordinate of the second circle's center
0483  * @y1: Y coordinate of the second circle's center
0484  * @r1: radius of the second circle
0485  * @user_data: User data pointer passed to hb_paint_funcs_set_radial_gradient_func()
0486  *
0487  * A virtual method for the #hb_paint_funcs_t to paint a radial
0488  * gradient everywhere within the current clip.
0489  *
0490  * The @color_line object contains information about the colors of the gradients.
0491  * It is only valid for the duration of the callback, you cannot keep it around.
0492  *
0493  * The coordinates of the points are interpreted according
0494  * to the current transform.
0495  *
0496  * See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr)
0497  * section for details on how the points define the direction
0498  * of the gradient, and how to interpret the @color_line.
0499  *
0500  * Since: 7.0.0
0501  */
0502 typedef void (*hb_paint_radial_gradient_func_t) (hb_paint_funcs_t *funcs,
0503                                                  void *paint_data,
0504                                                  hb_color_line_t *color_line,
0505                                                  float x0, float y0, float r0,
0506                                                  float x1, float y1, float r1,
0507                                                  void *user_data);
0508
0509 /**
0510  * hb_paint_sweep_gradient_func_t:
0511  * @funcs: paint functions object
0512  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0513  * @color_line: Color information for the gradient
0514  * @x0: X coordinate of the circle's center
0515  * @y0: Y coordinate of the circle's center
0516  * @start_angle: the start angle, in radians
0517  * @end_angle: the end angle, in radians
0518  * @user_data: User data pointer passed to hb_paint_funcs_set_sweep_gradient_func()
0519  *
0520  * A virtual method for the #hb_paint_funcs_t to paint a sweep
0521  * gradient everywhere within the current clip.
0522  *
0523  * The @color_line object contains information about the colors of the gradients.
0524  * It is only valid for the duration of the callback, you cannot keep it around.
0525  *
0526  * The coordinates of the points are interpreted according
0527  * to the current transform.
0528  *
0529  * See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr)
0530  * section for details on how the points define the direction
0531  * of the gradient, and how to interpret the @color_line.
0532  *
0533  * Since: 7.0.0
0534  */
0535 typedef void (*hb_paint_sweep_gradient_func_t)  (hb_paint_funcs_t *funcs,
0536                                                  void *paint_data,
0537                                                  hb_color_line_t *color_line,
0538                                                  float x0, float y0,
0539                                                  float start_angle,
0540                                                  float end_angle,
0541                                                  void *user_data);
0542
0543 /**
0544  * hb_paint_composite_mode_t:
0545  * @HB_PAINT_COMPOSITE_MODE_CLEAR: clear destination layer (bounded)
0546  * @HB_PAINT_COMPOSITE_MODE_SRC: replace destination layer (bounded)
0547  * @HB_PAINT_COMPOSITE_MODE_SRC_OVER: draw source layer on top of destination layer
0548  * (bounded)
0549  * @HB_PAINT_COMPOSITE_MODE_SRC_IN: draw source where there was destination content
0550  * (unbounded)
0551  * @HB_PAINT_COMPOSITE_MODE_SRC_OUT: draw source where there was no destination
0552  * content (unbounded)
0553  * @HB_PAINT_COMPOSITE_MODE_SRC_ATOP: draw source on top of destination content and
0554  * only there
0555  * @HB_PAINT_COMPOSITE_MODE_DEST: ignore the source
0556  * @HB_PAINT_COMPOSITE_MODE_DEST_OVER: draw destination on top of source
0557  * @HB_PAINT_COMPOSITE_MODE_DEST_IN: leave destination only where there was
0558  * source content (unbounded)
0559  * @HB_PAINT_COMPOSITE_MODE_DEST_OUT: leave destination only where there was no
0560  * source content
0561  * @HB_PAINT_COMPOSITE_MODE_DEST_ATOP: leave destination on top of source content
0562  * and only there (unbounded)
0563  * @HB_PAINT_COMPOSITE_MODE_XOR: source and destination are shown where there is only
0564  * one of them
0565  * @HB_PAINT_COMPOSITE_MODE_PLUS: source and destination layers are accumulated
0566  * @HB_PAINT_COMPOSITE_MODE_MULTIPLY: source and destination layers are multiplied.
0567  * This causes the result to be at least as dark as the darker inputs.
0568  * @HB_PAINT_COMPOSITE_MODE_SCREEN: source and destination are complemented and
0569  * multiplied. This causes the result to be at least as light as the lighter
0570  * inputs.
0571  * @HB_PAINT_COMPOSITE_MODE_OVERLAY: multiplies or screens, depending on the
0572  * lightness of the destination color.
0573  * @HB_PAINT_COMPOSITE_MODE_DARKEN: replaces the destination with the source if it
0574  * is darker, otherwise keeps the source.
0575  * @HB_PAINT_COMPOSITE_MODE_LIGHTEN: replaces the destination with the source if it
0576  * is lighter, otherwise keeps the source.
0577  * @HB_PAINT_COMPOSITE_MODE_COLOR_DODGE: brightens the destination color to reflect
0578  * the source color.
0579  * @HB_PAINT_COMPOSITE_MODE_COLOR_BURN: darkens the destination color to reflect
0580  * the source color.
0581  * @HB_PAINT_COMPOSITE_MODE_HARD_LIGHT: Multiplies or screens, dependent on source
0582  * color.
0583  * @HB_PAINT_COMPOSITE_MODE_SOFT_LIGHT: Darkens or lightens, dependent on source
0584  * color.
0585  * @HB_PAINT_COMPOSITE_MODE_DIFFERENCE: Takes the difference of the source and
0586  * destination color.
0587  * @HB_PAINT_COMPOSITE_MODE_EXCLUSION: Produces an effect similar to difference, but
0588  * with lower contrast.
0589  * @HB_PAINT_COMPOSITE_MODE_HSL_HUE: Creates a color with the hue of the source
0590  * and the saturation and luminosity of the target.
0591  * @HB_PAINT_COMPOSITE_MODE_HSL_SATURATION: Creates a color with the saturation
0592  * of the source and the hue and luminosity of the target. Painting with
0593  * this mode onto a gray area produces no change.
0594  * @HB_PAINT_COMPOSITE_MODE_HSL_COLOR: Creates a color with the hue and saturation
0595  * of the source and the luminosity of the target. This preserves the gray
0596  * levels of the target and is useful for coloring monochrome images or
0597  * tinting color images.
0598  * @HB_PAINT_COMPOSITE_MODE_HSL_LUMINOSITY: Creates a color with the luminosity of
0599  * the source and the hue and saturation of the target. This produces an
0600  * inverse effect to @HB_PAINT_COMPOSITE_MODE_HSL_COLOR.
0601  *
0602  * The values of this enumeration describe the compositing modes
0603  * that can be used when combining temporary redirected drawing
0604  * with the backdrop.
0605  *
0606  * See the OpenType spec [COLR](https://learn.microsoft.com/en-us/typography/opentype/spec/colr)
0607  * section for details.
0608  *
0609  * Since: 7.0.0
0610  */
0611 typedef enum {
0612   HB_PAINT_COMPOSITE_MODE_CLEAR,
0613   HB_PAINT_COMPOSITE_MODE_SRC,
0614   HB_PAINT_COMPOSITE_MODE_DEST,
0615   HB_PAINT_COMPOSITE_MODE_SRC_OVER,
0616   HB_PAINT_COMPOSITE_MODE_DEST_OVER,
0617   HB_PAINT_COMPOSITE_MODE_SRC_IN,
0618   HB_PAINT_COMPOSITE_MODE_DEST_IN,
0619   HB_PAINT_COMPOSITE_MODE_SRC_OUT,
0620   HB_PAINT_COMPOSITE_MODE_DEST_OUT,
0621   HB_PAINT_COMPOSITE_MODE_SRC_ATOP,
0622   HB_PAINT_COMPOSITE_MODE_DEST_ATOP,
0623   HB_PAINT_COMPOSITE_MODE_XOR,
0624   HB_PAINT_COMPOSITE_MODE_PLUS,
0625   HB_PAINT_COMPOSITE_MODE_SCREEN,
0626   HB_PAINT_COMPOSITE_MODE_OVERLAY,
0627   HB_PAINT_COMPOSITE_MODE_DARKEN,
0628   HB_PAINT_COMPOSITE_MODE_LIGHTEN,
0629   HB_PAINT_COMPOSITE_MODE_COLOR_DODGE,
0630   HB_PAINT_COMPOSITE_MODE_COLOR_BURN,
0631   HB_PAINT_COMPOSITE_MODE_HARD_LIGHT,
0632   HB_PAINT_COMPOSITE_MODE_SOFT_LIGHT,
0633   HB_PAINT_COMPOSITE_MODE_DIFFERENCE,
0634   HB_PAINT_COMPOSITE_MODE_EXCLUSION,
0635   HB_PAINT_COMPOSITE_MODE_MULTIPLY,
0636   HB_PAINT_COMPOSITE_MODE_HSL_HUE,
0637   HB_PAINT_COMPOSITE_MODE_HSL_SATURATION,
0638   HB_PAINT_COMPOSITE_MODE_HSL_COLOR,
0639   HB_PAINT_COMPOSITE_MODE_HSL_LUMINOSITY
0640 } hb_paint_composite_mode_t;
0641
0642 /**
0643  * hb_paint_push_group_func_t:
0644  * @funcs: paint functions object
0645  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0646  * @user_data: User data pointer passed to hb_paint_funcs_set_push_group_func()
0647  *
0648  * A virtual method for the #hb_paint_funcs_t to use
0649  * an intermediate surface for subsequent paint calls.
0650  *
0651  * The drawing will be redirected to an intermediate surface
0652  * until a matching call to the #hb_paint_funcs_pop_group_func_t
0653  * vfunc.
0654  *
0655  * Since: 7.0.0
0656  */
0657 typedef void (*hb_paint_push_group_func_t) (hb_paint_funcs_t *funcs,
0658                                             void *paint_data,
0659                                             void *user_data);
0660
0661 /**
0662  * hb_paint_pop_group_func_t:
0663  * @funcs: paint functions object
0664  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0665  * @mode: the compositing mode to use
0666  * @user_data: User data pointer passed to hb_paint_funcs_set_pop_group_func()
0667  *
0668  * A virtual method for the #hb_paint_funcs_t to undo
0669  * the effect of a prior call to the #hb_paint_funcs_push_group_func_t
0670  * vfunc.
0671  *
0672  * This call stops the redirection to the intermediate surface,
0673  * and then composites it on the previous surface, using the
0674  * compositing mode passed to this call.
0675  *
0676  * Since: 7.0.0
0677  */
0678 typedef void (*hb_paint_pop_group_func_t) (hb_paint_funcs_t *funcs,
0679                                            void *paint_data,
0680                                            hb_paint_composite_mode_t mode,
0681                                            void *user_data);
0682
0683 /**
0684  * hb_paint_custom_palette_color_func_t:
0685  * @funcs: paint functions object
0686  * @paint_data: The data accompanying the paint functions in hb_font_paint_glyph()
0687  * @color_index: the color index
0688  * @color: (out): fetched color
0689  * @user_data: User data pointer passed to hb_paint_funcs_set_pop_group_func()
0690  *
0691  * A virtual method for the #hb_paint_funcs_t to fetch a color from the custom
0692  * color palette.
0693  *
0694  * Custom palette colors override the colors from the fonts selected color
0695  * palette. It is not necessary to override all palette entries; for entries
0696  * that should be taken from the font palette, return `false`.
0697  *
0698  * This function might get called multiple times, but the custom palette is
0699  * expected to remain unchanged for duration of a hb_font_paint_glyph() call.
0700  *
0701  * Return value: `true` if found, `false` otherwise
0702  *
0703  * Since: 7.0.0
0704  */
0705 typedef hb_bool_t (*hb_paint_custom_palette_color_func_t) (hb_paint_funcs_t *funcs,
0706                                                            void *paint_data,
0707                                                            unsigned int color_index,
0708                                                            hb_color_t *color,
0709                                                            void *user_data);
0710
0711
0712 /**
0713  * hb_paint_funcs_set_push_transform_func:
0714  * @funcs: A paint functions struct
0715  * @func: (closure user_data) (destroy destroy) (scope notified): The push-transform callback
0716  * @user_data: Data to pass to @func
0717  * @destroy: (nullable): Function to call when @user_data is no longer needed
0718  *
0719  * Sets the push-transform callback on the paint functions struct.
0720  *
0721  * Since: 7.0.0
0722  */
0723 HB_EXTERN void
0724 hb_paint_funcs_set_push_transform_func (hb_paint_funcs_t               *funcs,
0725                                         hb_paint_push_transform_func_t  func,
0726                                         void                           *user_data,
0727                                         hb_destroy_func_t               destroy);
0728
0729 /**
0730  * hb_paint_funcs_set_pop_transform_func:
0731  * @funcs: A paint functions struct
0732  * @func: (closure user_data) (destroy destroy) (scope notified): The pop-transform callback
0733  * @user_data: Data to pass to @func
0734  * @destroy: (nullable): Function to call when @user_data is no longer needed
0735  *
0736  * Sets the pop-transform callback on the paint functions struct.
0737  *
0738  * Since: 7.0.0
0739  */
0740 HB_EXTERN void
0741 hb_paint_funcs_set_pop_transform_func (hb_paint_funcs_t              *funcs,
0742                                        hb_paint_pop_transform_func_t  func,
0743                                        void                          *user_data,
0744                                        hb_destroy_func_t              destroy);
0745
0746 /**
0747  * hb_paint_funcs_set_color_glyph_func:
0748  * @funcs: A paint functions struct
0749  * @func: (closure user_data) (destroy destroy) (scope notified): The color-glyph callback
0750  * @user_data: Data to pass to @func
0751  * @destroy: (nullable): Function to call when @user_data is no longer needed
0752  *
0753  * Sets the color-glyph callback on the paint functions struct.
0754  *
0755  * Since: 8.2.0
0756  */
0757 HB_EXTERN void
0758 hb_paint_funcs_set_color_glyph_func (hb_paint_funcs_t                *funcs,
0759                      hb_paint_color_glyph_func_t     func,
0760                      void                            *user_data,
0761                      hb_destroy_func_t                destroy);
0762
0763 /**
0764  * hb_paint_funcs_set_push_clip_glyph_func:
0765  * @funcs: A paint functions struct
0766  * @func: (closure user_data) (destroy destroy) (scope notified): The push-clip-glyph callback
0767  * @user_data: Data to pass to @func
0768  * @destroy: (nullable): Function to call when @user_data is no longer needed
0769  *
0770  * Sets the push-clip-glyph callback on the paint functions struct.
0771  *
0772  * Since: 7.0.0
0773  */
0774 HB_EXTERN void
0775 hb_paint_funcs_set_push_clip_glyph_func (hb_paint_funcs_t                *funcs,
0776                                          hb_paint_push_clip_glyph_func_t  func,
0777                                          void                            *user_data,
0778                                          hb_destroy_func_t                destroy);
0779
0780 /**
0781  * hb_paint_funcs_set_push_clip_rectangle_func:
0782  * @funcs: A paint functions struct
0783  * @func: (closure user_data) (destroy destroy) (scope notified): The push-clip-rectangle callback
0784  * @user_data: Data to pass to @func
0785  * @destroy: (nullable): Function to call when @user_data is no longer needed
0786  *
0787  * Sets the push-clip-rect callback on the paint functions struct.
0788  *
0789  * Since: 7.0.0
0790  */
0791 HB_EXTERN void
0792 hb_paint_funcs_set_push_clip_rectangle_func (hb_paint_funcs_t                    *funcs,
0793                                              hb_paint_push_clip_rectangle_func_t  func,
0794                                              void                                *user_data,
0795                                              hb_destroy_func_t                    destroy);
0796
0797 /**
0798  * hb_paint_funcs_set_pop_clip_func:
0799  * @funcs: A paint functions struct
0800  * @func: (closure user_data) (destroy destroy) (scope notified): The pop-clip callback
0801  * @user_data: Data to pass to @func
0802  * @destroy: (nullable): Function to call when @user_data is no longer needed
0803  *
0804  * Sets the pop-clip callback on the paint functions struct.
0805  *
0806  * Since: 7.0.0
0807  */
0808 HB_EXTERN void
0809 hb_paint_funcs_set_pop_clip_func (hb_paint_funcs_t         *funcs,
0810                                   hb_paint_pop_clip_func_t  func,
0811                                   void                     *user_data,
0812                                   hb_destroy_func_t         destroy);
0813
0814 /**
0815  * hb_paint_funcs_set_color_func:
0816  * @funcs: A paint functions struct
0817  * @func: (closure user_data) (destroy destroy) (scope notified): The paint-color callback
0818  * @user_data: Data to pass to @func
0819  * @destroy: (nullable): Function to call when @user_data is no longer needed
0820  *
0821  * Sets the paint-color callback on the paint functions struct.
0822  *
0823  * Since: 7.0.0
0824  */
0825 HB_EXTERN void
0826 hb_paint_funcs_set_color_func (hb_paint_funcs_t      *funcs,
0827                                hb_paint_color_func_t  func,
0828                                void                  *user_data,
0829                                hb_destroy_func_t      destroy);
0830
0831 /**
0832  * hb_paint_funcs_set_image_func:
0833  * @funcs: A paint functions struct
0834  * @func: (closure user_data) (destroy destroy) (scope notified): The paint-image callback
0835  * @user_data: Data to pass to @func
0836  * @destroy: (nullable): Function to call when @user_data is no longer needed
0837  *
0838  * Sets the paint-image callback on the paint functions struct.
0839  *
0840  * Since: 7.0.0
0841  */
0842 HB_EXTERN void
0843 hb_paint_funcs_set_image_func (hb_paint_funcs_t      *funcs,
0844                                hb_paint_image_func_t  func,
0845                                void                  *user_data,
0846                                hb_destroy_func_t      destroy);
0847
0848 /**
0849  * hb_paint_funcs_set_linear_gradient_func:
0850  * @funcs: A paint functions struct
0851  * @func: (closure user_data) (destroy destroy) (scope notified): The linear-gradient callback
0852  * @user_data: Data to pass to @func
0853  * @destroy: (nullable): Function to call when @user_data is no longer needed
0854  *
0855  * Sets the linear-gradient callback on the paint functions struct.
0856  *
0857  * Since: 7.0.0
0858  */
0859 HB_EXTERN void
0860 hb_paint_funcs_set_linear_gradient_func (hb_paint_funcs_t                *funcs,
0861                                          hb_paint_linear_gradient_func_t  func,
0862                                          void                            *user_data,
0863                                          hb_destroy_func_t                destroy);
0864
0865 /**
0866  * hb_paint_funcs_set_radial_gradient_func:
0867  * @funcs: A paint functions struct
0868  * @func: (closure user_data) (destroy destroy) (scope notified): The radial-gradient callback
0869  * @user_data: Data to pass to @func
0870  * @destroy: (nullable): Function to call when @user_data is no longer needed
0871  *
0872  * Sets the radial-gradient callback on the paint functions struct.
0873  *
0874  * Since: 7.0.0
0875  */
0876 HB_EXTERN void
0877 hb_paint_funcs_set_radial_gradient_func (hb_paint_funcs_t                *funcs,
0878                                          hb_paint_radial_gradient_func_t  func,
0879                                          void                            *user_data,
0880                                          hb_destroy_func_t                destroy);
0881
0882 /**
0883  * hb_paint_funcs_set_sweep_gradient_func:
0884  * @funcs: A paint functions struct
0885  * @func: (closure user_data) (destroy destroy) (scope notified): The sweep-gradient callback
0886  * @user_data: Data to pass to @func
0887  * @destroy: (nullable): Function to call when @user_data is no longer needed
0888  *
0889  * Sets the sweep-gradient callback on the paint functions struct.
0890  *
0891  * Since: 7.0.0
0892  */
0893 HB_EXTERN void
0894 hb_paint_funcs_set_sweep_gradient_func (hb_paint_funcs_t               *funcs,
0895                                         hb_paint_sweep_gradient_func_t  func,
0896                                         void                           *user_data,
0897                                         hb_destroy_func_t               destroy);
0898
0899 /**
0900  * hb_paint_funcs_set_push_group_func:
0901  * @funcs: A paint functions struct
0902  * @func: (closure user_data) (destroy destroy) (scope notified): The push-group callback
0903  * @user_data: Data to pass to @func
0904  * @destroy: (nullable): Function to call when @user_data is no longer needed
0905  *
0906  * Sets the push-group callback on the paint functions struct.
0907  *
0908  * Since: 7.0.0
0909  */
0910 HB_EXTERN void
0911 hb_paint_funcs_set_push_group_func (hb_paint_funcs_t           *funcs,
0912                                     hb_paint_push_group_func_t  func,
0913                                     void                       *user_data,
0914                                     hb_destroy_func_t           destroy);
0915
0916 /**
0917  * hb_paint_funcs_set_pop_group_func:
0918  * @funcs: A paint functions struct
0919  * @func: (closure user_data) (destroy destroy) (scope notified): The pop-group callback
0920  * @user_data: Data to pass to @func
0921  * @destroy: (nullable): Function to call when @user_data is no longer needed
0922  *
0923  * Sets the pop-group callback on the paint functions struct.
0924  *
0925  * Since: 7.0.0
0926  */
0927 HB_EXTERN void
0928 hb_paint_funcs_set_pop_group_func (hb_paint_funcs_t          *funcs,
0929                                    hb_paint_pop_group_func_t  func,
0930                                    void                       *user_data,
0931                                    hb_destroy_func_t           destroy);
0932
0933 /**
0934  * hb_paint_funcs_set_custom_palette_color_func:
0935  * @funcs: A paint functions struct
0936  * @func: (closure user_data) (destroy destroy) (scope notified): The custom-palette-color callback
0937  * @user_data: Data to pass to @func
0938  * @destroy: (nullable): Function to call when @user_data is no longer needed
0939  *
0940  * Sets the custom-palette-color callback on the paint functions struct.
0941  *
0942  * Since: 7.0.0
0943  */
0944 HB_EXTERN void
0945 hb_paint_funcs_set_custom_palette_color_func (hb_paint_funcs_t                     *funcs,
0946                                               hb_paint_custom_palette_color_func_t  func,
0947                                               void                                 *user_data,
0948                                               hb_destroy_func_t                     destroy);
0949 /*
0950  * Manual API
0951  */
0952
0953 HB_EXTERN void
0954 hb_paint_push_transform (hb_paint_funcs_t *funcs, void *paint_data,
0955                          float xx, float yx,
0956                          float xy, float yy,
0957                          float dx, float dy);
0958
0959 HB_EXTERN void
0960 hb_paint_pop_transform (hb_paint_funcs_t *funcs, void *paint_data);
0961
0962 HB_EXTERN hb_bool_t
0963 hb_paint_color_glyph (hb_paint_funcs_t *funcs, void *paint_data,
0964                       hb_codepoint_t glyph,
0965                       hb_font_t *font);
0966
0967 HB_EXTERN void
0968 hb_paint_push_clip_glyph (hb_paint_funcs_t *funcs, void *paint_data,
0969                           hb_codepoint_t glyph,
0970                           hb_font_t *font);
0971
0972 HB_EXTERN void
0973 hb_paint_push_clip_rectangle (hb_paint_funcs_t *funcs, void *paint_data,
0974                               float xmin, float ymin,
0975                               float xmax, float ymax);
0976
0977 HB_EXTERN void
0978 hb_paint_pop_clip (hb_paint_funcs_t *funcs, void *paint_data);
0979
0980 HB_EXTERN void
0981 hb_paint_color (hb_paint_funcs_t *funcs, void *paint_data,
0982                 hb_bool_t is_foreground,
0983                 hb_color_t color);
0984
0985 HB_EXTERN void
0986 hb_paint_image (hb_paint_funcs_t *funcs, void *paint_data,
0987                 hb_blob_t *image,
0988                 unsigned int width,
0989                 unsigned int height,
0990                 hb_tag_t format,
0991                 float slant,
0992                 hb_glyph_extents_t *extents);
0993
0994 HB_EXTERN void
0995 hb_paint_linear_gradient (hb_paint_funcs_t *funcs, void *paint_data,
0996                           hb_color_line_t *color_line,
0997                           float x0, float y0,
0998                           float x1, float y1,
0999                           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 */