[paint] Documentation tweaks

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)

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
+ * @start_angle: the start angle, in radians
- * @end_angle: the end angle
+ * @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,