From 0c77f1d9abf5f8dcd931ca1ae5856039daf3e3fc Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 17 Dec 2022 14:10:28 -0500 Subject: [PATCH] [paint] Documentation tweaks --- src/hb-paint.cc | 149 +++++++++++++++++++++++++++++++++++++++++++++++- src/hb-paint.h | 25 ++++++-- 2 files changed, 168 insertions(+), 6 deletions(-) diff --git a/src/hb-paint.cc b/src/hb-paint.cc index 537fccd2c..d2cc04fc7 100644 --- a/src/hb-paint.cc +++ b/src/hb-paint.cc @@ -34,7 +34,12 @@ * @short_description: Glyph painting * @include: hb.h * - * Functions for painting (extracting) glyph color layers. + * Functions for painting glyphs. + * + * The main purpose of these functions is to paint + * (extract) color glyph layers from the COLRv1 table, + * but the API works for drawing ordinary outlines + * and images as well. **/ static void @@ -301,6 +306,21 @@ hb_paint_funcs_is_immutable (hb_paint_funcs_t *funcs) return hb_object_is_immutable (funcs); } +/** + * hb_paint_push_transform: + * @funcs: paint functions + * @paint_data: associated data passed by the caller + * @xx: xx component of the transform matrix + * @yx: yx component of the transform matrix + * @xy: xy component of the transform matrix + * @yy: yy component of the transform matrix + * @dx: dx component of the transform matrix + * @dy: dy component of the transform matrix + * + * Perform a "push-transform" paint operation. + * + * Since: REPLACEME + */ void hb_paint_push_transform (hb_paint_funcs_t *funcs, void *paint_data, float xx, float yx, @@ -310,12 +330,31 @@ hb_paint_push_transform (hb_paint_funcs_t *funcs, void *paint_data, funcs->push_transform (paint_data, xx, yx, xy, yy, dx, dy); } +/** + * hb_paint_pop_transform: + * @funcs: paint functions + * @paint_data: associated data passed by the caller + * + * Perform a "pop-transform" paint operation. + * + * Since: REPLACEME + */ void hb_paint_pop_transform (hb_paint_funcs_t *funcs, void *paint_data) { funcs->pop_transform (paint_data); } +/** + * hb_paint_push_clip_glyph: + * @funcs: paint functions + * @paint_data: associated data passed by the caller + * @glyph: the glyph ID + * + * Perform a "push-clip-glyph" paint operation. + * + * Since: REPLACEME + */ void hb_paint_push_clip_glyph (hb_paint_funcs_t *funcs, void *paint_data, hb_codepoint_t glyph) @@ -323,6 +362,19 @@ hb_paint_push_clip_glyph (hb_paint_funcs_t *funcs, void *paint_data, funcs->push_clip_glyph (paint_data, glyph); } +/** + * hb_paint_push_clip_rect: + * @funcs: paint functions + * @paint_data: associated data passed by the caller + * @xmin: min X for the rectangle + * @ymin: min Y for the rectangle + * @xmax: max X for the rectangle + * @ymax: max Y for the rectangle + * + * Perform a "push-clip-rect" paint operation. + * + * Since: REPLACEME + */ void hb_paint_push_clip_rectangle (hb_paint_funcs_t *funcs, void *paint_data, float xmin, float ymin, float xmax, float ymax) @@ -330,12 +382,32 @@ hb_paint_push_clip_rectangle (hb_paint_funcs_t *funcs, void *paint_data, funcs->push_clip_rectangle (paint_data, xmin, ymin, xmax, ymax); } +/** + * hb_paint_pop_clip: + * @funcs: paint functions + * @paint_data: associated data passed by the caller + * + * Perform a "pop-clip" paint operation. + * + * Since: REPLACEME + */ void hb_paint_pop_clip (hb_paint_funcs_t *funcs, void *paint_data) { funcs->pop_clip (paint_data); } +/** + * hb_paint_color: + * @funcs: paint functions + * @paint_data: associated data passed by the caller + * @color_index: Index of a color in the fonts selected color palette + * @alpha: Alpha to apply in addition + * + * Perform a "color" paint operation. + * + * Since: REPLACEME + */ void hb_paint_color (hb_paint_funcs_t *funcs, void *paint_data, unsigned int color_index, @@ -344,6 +416,16 @@ hb_paint_color (hb_paint_funcs_t *funcs, void *paint_data, funcs->color (paint_data, color_index, alpha); } +/** + * hb_paint_image: + * @funcs: paint functions + * @paint_data: associated data passed by the caller + * @glyph: the glyph ID + * + * Perform a "image" paint operation. + * + * Since: REPLACEME + */ void hb_paint_image (hb_paint_funcs_t *funcs, void *paint_data, hb_blob_t *image, @@ -353,6 +435,22 @@ hb_paint_image (hb_paint_funcs_t *funcs, void *paint_data, funcs->image (paint_data, image, format, extents); } +/** + * hb_paint_linear_gradient: + * @funcs: paint functions + * @paint_data: associated data passed by the caller + * @color_line: Color information for the gradient + * @x0: X coordinate of the first point + * @y0: Y coordinate of the first point + * @x1: X coordinate of the second point + * @y1: Y coordinate of the second point + * @x2: X coordinate of the third point + * @y2: Y coordinate of the third point + * + * Perform a "linear-gradient" paint operation. + * + * Since: REPLACEME + */ void hb_paint_linear_gradient (hb_paint_funcs_t *funcs, void *paint_data, hb_color_line_t *color_line, @@ -363,6 +461,22 @@ hb_paint_linear_gradient (hb_paint_funcs_t *funcs, void *paint_data, funcs->linear_gradient (paint_data, color_line, x0, y0, x1, y1, x2, y2); } +/** + * hb_paint_radial_gradient: + * @funcs: paint functions + * @paint_data: associated data passed by the caller + * @color_line: Color information for the gradient + * @x0: X coordinate of the first circle's center + * @y0: Y coordinate of the first circle's center + * @r0: radius of the first circle + * @x1: X coordinate of the second circle's center + * @y1: Y coordinate of the second circle's center + * @r1: radius of the second circle + * + * Perform a "radial-gradient" paint operation. + * + * Since: REPLACEME + */ void hb_paint_radial_gradient (hb_paint_funcs_t *funcs, void *paint_data, hb_color_line_t *color_line, @@ -372,6 +486,20 @@ hb_paint_radial_gradient (hb_paint_funcs_t *funcs, void *paint_data, funcs->radial_gradient (paint_data, color_line, x0, y0, r0, y1, x1, r1); } +/** + * hb_paint_sweep_gradient: + * @funcs: paint functions + * @paint_data: associated data passed by the caller + * @color_line: Color information for the gradient + * @x0: X coordinate of the circle's center + * @y0: Y coordinate of the circle's center + * @start_angle: the start angle + * @end_angle: the end angle + * + * Perform a "sweep-gradient" paint operation. + * + * Since: REPLACEME + */ void hb_paint_sweep_gradient (hb_paint_funcs_t *funcs, void *paint_data, hb_color_line_t *color_line, @@ -381,12 +509,31 @@ hb_paint_sweep_gradient (hb_paint_funcs_t *funcs, void *paint_data, funcs->sweep_gradient (paint_data, color_line, x0, y0, start_angle, end_angle); } +/** + * hb_paint_push_group: + * @funcs: paint functions + * @paint_data: associated data passed by the caller + * + * Perform a "push-group" paint operation. + * + * Since: REPLACEME + */ void hb_paint_push_group (hb_paint_funcs_t *funcs, void *paint_data) { funcs->push_group (paint_data); } +/** + * hb_paint_pop_group: + * @funcs: paint functions + * @paint_data: associated data passed by the caller + * @mode: the compositing mode to use + * + * Perform a "pop-group" paint operation. + * + * Since: REPLACEME + */ void hb_paint_pop_group (hb_paint_funcs_t *funcs, void *paint_data, hb_paint_composite_mode_t mode) diff --git a/src/hb-paint.h b/src/hb-paint.h index 12539b4de..f253852f3 100644 --- a/src/hb-paint.h +++ b/src/hb-paint.h @@ -39,8 +39,6 @@ HB_BEGIN_DECLS * * Glyph paint callbacks. * - * All the callbacks are necessary. - * * The callbacks assume that the caller maintains a stack * of current transforms, clips and intermediate surfaces, * as evidenced by the pairs of push/pop callbacks. The @@ -58,7 +56,7 @@ HB_BEGIN_DECLS * gradient and composite callbacks are not needed. * * The paint-image callback is only needed for glyphs - * with blobs in the CBDT, sbix or SVG tables. + * with image blobs in the CBDT, sbix or SVG tables. * * Since: REPLACEME **/ @@ -285,6 +283,13 @@ typedef struct hb_color_line_t hb_color_line_t; * Color lines typically have offsets ranging between 0 and 1, * but that is not required. * + * The @color_index can be either an index into one of the fonts + * color palettes, or the special value 0xFFFF, which indicates that + * the foreground color should be used. + * + * in either case, the @alpha value should be applied in addition + * (i.e. multiplied with) the alpha value found in the color. + * * Since: REPLACEME */ typedef struct { @@ -380,8 +385,8 @@ typedef void (*hb_paint_radial_gradient_func_t) (hb_paint_funcs_t *funcs, * @color_line: Color information for the gradient * @x0: X coordinate of the circle's center * @y0: Y coordinate of the circle's center - * @start_angle: the start angle - * @end_angle: the end angle + * @start_angle: the start angle, in radians + * @end_angle: the end angle, in radians * @user_data: user data passed to the hb_font_paint_glyph() call * * A virtual method for the #hb_paint_funcs_t to paint a sweep @@ -404,6 +409,16 @@ typedef void (*hb_paint_sweep_gradient_func_t) (hb_paint_funcs_t *funcs, float end_angle, void *user_data); +/** + * hb_paint_composite_mode_t: + * + * The values of this enumeration describe the compositing modes + * that can be used when combining temporary redirected drawing + * with the backdrop. + * + * See the OpenType spec COLR section (https://learn.microsoft.com/en-us/typography/opentype/spec/colr) + * for details. + */ typedef enum { HB_PAINT_COMPOSITE_MODE_CLEAR, HB_PAINT_COMPOSITE_MODE_SRC,