Quelle  hb-gpu-paint.hh   Sprache: C

/*
 * Copyright (C) 2026  Behdad Esfahbod
 *
 *  This is part of HarfBuzz, a text shaping library.
 *
 * Permission is hereby granted, without written agreement and without
 * license or royalty fees, to use, copy, modify, and distribute this
 * software and its documentation for any purpose, provided that the
 * above copyright notice and the following two paragraphs appear in
 * all copies of this software.
 *
 * IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR
 * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
 * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
 * IF THE COPYRIGHT HOLDER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 *
 * THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND THE COPYRIGHT HOLDER HAS NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 *
 * Author(s): Behdad Esfahbod
 */

#ifndef HB_GPU_PAINT_HH
#define HB_GPU_PAINT_HH

#include "hb.hh"
#include "hb-gpu.h"
#include "hb-geometry.hh"
#include "hb-map.hh"
#include "hb-object.hh"


/*
 * hb_gpu_paint_t encoded-blob design
 * ==================================
 *
 * One blob per glyph.  One quad per glyph.  The fragment shader
 * is the interpreter: it walks a flat op stream per pixel, maintains
 * a small group stack, and composites the result.
 *
 * The encoder turns a COLRv1 paint tree (visited via hb_paint_funcs_t
 * callbacks) into a pre-order op stream plus embedded sub-payloads,
 * all packed into a single RGBA16I blob suitable for
 * hb_blob_t-style upload into the same shared atlas used by the
 * draw renderer.
 *
 * --- Top-level layout --------------------------------------------
 *
 *   [header]
 *   [op stream]          -- variable number of op records
 *   [sub-payloads]       -- clip-glyph Slug draw blobs and
 *                           gradient parameter blobs, referenced
 *                           by intra-blob offsets from the ops
 *
 * Every offset in the blob is a texel index (RGBA16I, 8 bytes per
 * texel) relative to the blob's base address.  The caller uploads
 * the blob at some atlas_base offset and adds that base to the
 * glyph's vertex attribute; the fragment shader sees one absolute
 * atlas offset per glyph and discovers everything else by walking
 * inside.
 *
 * --- Header -------------------------------------------------------
 *
 *   texel 0: (num_ops:i16, reserved:i16, reserved:i16, reserved:i16)
 *   texel 1: (ext_min_x:i16, ext_min_y:i16,
 *             ext_max_x:i16, ext_max_y:i16)   -- in HB_GPU units
 *   texel 2: (ops_offset:i16, reserved:i16,
 *             reserved:i16, reserved:i16)
 *
 * --- Op record ----------------------------------------------------
 *
 * Each op is exactly one RGBA16I texel (4 int16s):
 *
 *   (op_type:i16, op_aux:i16, payload_hi:i16, payload_lo:i16)
 *
 * op_type values:
 *
 *   0  LAYER_SOLID
 *        aux      = flags (bit 0 = is_foreground)
 *        payload  = clip_glyph_offset (texel index)
 *        followed by one extra texel:
 *          (r_q15:i16, g_q15:i16, b_q15:i16, a_q15:i16)
 *        flags bit 0: is_foreground -- use the shader's foreground
 *                     uniform/varying instead of the baked color
 *                     (so runtime foreground changes still work)
 *
 *   1  LAYER_GRADIENT
 *        aux      = gradient subtype  (0=linear, 1=radial, 2=sweep)
 *        payload  = clip_glyph_offset (texel index)
 *        followed by one extra texel:
 *          (grad_offset_hi:i16, grad_offset_lo:i16,
 *           reserved:i16, reserved:i16)
 *
 *   2  PUSH_GROUP
 *        aux      = 0
 *        payload  = 0
 *
 *   3  POP_GROUP
 *        aux      = composite mode, enumerated 0..27 matching
 *                   hb_paint_composite_mode_t
 *        payload  = 0
 *
 * The fragment shader reads the first texel, inspects op_type,
 * and knows from the type whether a trailing texel follows.  Ops
 * are therefore mixed-size but self-delimiting.
 *
 * --- Sub-payload: clip-glyph Slug draw blob ----------------------
 *
 * Exactly the format produced by hb_gpu_draw_encode().  Referenced
 * by LAYER_SOLID and LAYER_GRADIENT.
 *
 * The outline fed into the draw encoder has the enclosing paint
 * transform baked in at CPU encode time.  v1 does not dedup
 * outlines that differ only by translation; v2 may keep the outline
 * in canonical pre-translate space and store a per-op (dx, dy)
 * offset in the aux/payload slots.
 *
 * --- Sub-payload: gradient parameter blob ------------------------
 *
 *   texels 0..2  : inverse affine transform, 6 components as
 *                  q15.16 fixed point (two int16 per component,
 *                  int part then fraction)
 *   texel 3      : (grad_subtype:i16, extend_mode:i16,
 *                   reserved:i16, reserved:i16)
 *   texels 4..N  : subtype-specific params
 *                  linear: (x0, y0, px, py)  -- two texels
 *                          where p is the foot of perpendicular
 *                          from p2 onto the p0..p1 line
 *                  radial: (x0, y0, x1, y1), (r0, r1, _, _)
 *                  sweep:  (x0, y0, start_q14, end_q14)
 *                          angles in q14 fractions of pi
 *   texels ...   : color stops, each one texel:
 *                    (offset_q8<<1 | last_stop_bit,
 *                     palette_index:i16,
 *                     flags:i16,
 *                     alpha_q15:i16)
 *                  flags / alpha_q15 semantics match LAYER_SOLID.
 *                  The last stop is marked by the LSB of
 *                  offset_q8 being 1 (offsets quantized to q8 so
 *                  the bit is free for the marker).
 *
 * --- Shader entry point -----------------------------------------
 *
 *   vec4 hb_gpu_paint (vec2 renderCoord, uint glyphLoc,
 *                      vec4 foreground);
 *
 * Returns premultiplied RGBA.  The caller passes foreground in
 * explicitly; sourcing it from a uniform, a per-quad flat varying,
 * or anywhere else is the caller's decision.
 *
 * Colors are baked into the blob at encode time (as signed Q15
 * RGBA in a single texel per layer).  There is no runtime palette
 * buffer to bind or size.  Palette selection and per-run custom
 * palette overrides are set on the encoder via
 * hb_gpu_paint_set_palette() / hb_gpu_paint_set_custom_palette_color();
 * changing either invalidates previously encoded blobs and requires
 * re-encoding.  The is_foreground flag still routes through the
 * shader's foreground parameter so a dark-mode toggle does not
 * require re-encoding.
 *
 * --- Fragment-shader contract ------------------------------------
 *
 * Per pixel:
 *   acc    = vec4 (0)                    -- transparent
 *   stack  = array<vec4, HB_GPU_PAINT_GROUP_DEPTH>
 *   sp     = 0
 *
 *   for op in ops:
 *     LAYER_SOLID:
 *       cov = hb_gpu_draw (texcoord, clip_glyph_offset)
 *       col = is_foreground ? v_foreground : rgba_q15 / 32767
 *       acc = src_over (col * cov, acc)
 *     LAYER_GRADIENT:
 *       cov = hb_gpu_draw (texcoord, clip_glyph_offset)
 *       col = sample_gradient (texcoord, grad_offset, subtype)
 *       acc = src_over (col * cov, acc)
 *     PUSH_GROUP:
 *       stack[sp++] = acc
 *       acc = vec4 (0)
 *     POP_GROUP:
 *       acc = composite (stack[--sp], acc, composite_mode)
 *
 *   write acc to gl_FragColor
 *
 * HB_GPU_PAINT_GROUP_DEPTH is compile-time fixed at 4.  Encoder
 * validates nesting depth and fails encode if a paint tree exceeds
 * it.  Typical COLRv1 emoji nest 0..2 groups deep.
 *
 * --- Encoder state ----------------------------------------------
 *
 * hb_gpu_paint_t accumulates, during hb_font_paint_glyph_or_fail:
 *
 *   - transform stack (visited push/pop_transform)
 *   - current clip-glyph snapshot captured on push_clip_glyph:
 *       (font, codepoint, transform_at_push)
 *     consumed by the next color / gradient callback to emit a
 *     LAYER_SOLID or LAYER_GRADIENT op
 *   - flat op buffer
 *   - flat sub-payload buffer (bytes; offsets recorded as ops emit)
 *   - scratch hb_gpu_draw_t used to rasterize each clip-glyph
 *     outline under its baked transform
 *   - scratch int16 vector for gradient encoding
 *   - current group depth counter (for validation against
 *     HB_GPU_PAINT_GROUP_DEPTH)
 *   - recycled output blob
 *
 * To preserve palette indices across harfbuzz's paint pipeline
 * (which resolves them to hb_color_t before the color / color-stop
 * callbacks fire), the encoder registers a custom_palette_color
 * callback that returns a sentinel hb_color_t with the palette
 * index embedded.  Downstream color / color-stop callbacks decode
 * the sentinel to recover the index.  Foreground colors are
 * signalled independently by the is_foreground flag that harfbuzz
 * supplies, so the sentinel never collides with a genuine
 * foreground request.
 *
 * On hb_gpu_paint_encode:
 *   - emit header (num_ops, extents, ops_offset)
 *   - emit op stream
 *   - append accumulated sub-payload buffer
 *   - patch any ops that held byte offsets to convert to texel
 *     offsets
 *   - return blob
 *
 * --- Out of scope for v1 ----------------------------------------
 *
 *   - Clip-rectangle paints (push_clip_rectangle / pop_clip).
 *     COLRv1 allows them but they are rare; v1 emits nothing for
 *     them and the caller loses clipping precision.  v2 adds a
 *     RECT_CLIP op with four fixed-point extents.
 *   - Paint images (hb_paint_funcs_set_image_func).  Always
 *     returns unhandled.  Images are better served by a separate
 *     bitmap path.
 */

struct hb_gpu_paint_t
{
  hb_object_header_t header;

  /* Persistent configuration (survives hb_gpu_paint_clear). */
  unsigned   palette    = 0;
  hb_map_t  *custom_palette = nullptr;

  /* Current effective affine (stack is grown/shrunk by
   * push_transform / pop_transform callbacks). */
  hb_transform_t<float> cur_transform = {1, 0, 0, 1, 0, 0};
  hb_vector_t<hb_transform_t<float>> transform_stack;

  /* Font scale (set by hb_gpu_paint_glyph()). */
  int x_scale = 0;
  int y_scale = 0;

  /* Accumulator state (cleared by hb_gpu_paint_clear). */

  /* Flat int16 op stream.  Each op is a sequence of i16 words
   * whose total length is determined by the op type (see the
   * design notes at the top of this file). */
  hb_vector_t<int16_t> ops;
  unsigned num_ops = 0;

  /* Clip-glyph Slug sub-blobs collected during paint walk.
   * Referenced by sub_blob_index recorded inside ops;
   * hb_gpu_paint_encode() concatenates them after the op stream and
   * patches the recorded indices into texel offsets. */
  hb_vector_t<hb_blob_t *> sub_blobs;

  /* Nesting depth of push_group / pop_group.  We bail (set
   * `unsupported`) if it exceeds HB_GPU_PAINT_MAX_GROUP_DEPTH,
   * which matches HB_GPU_PAINT_GROUP_DEPTH in the fragment shader. */
  unsigned group_depth = 0;

  /* Stack of pending clips.  Each color/gradient op consumes the
   * current state of this stack: the layer is rendered where ALL
   * stacked clips are opaque (intersection).  Capped at depth
   * HB_GPU_PAINT_MAX_CLIP_DEPTH; deeper pushes set `unsupported`.
   * The transform is the one current at push_clip_glyph time --
   * the clip outline is defined in that coord space, a subsequent
   * gradient params callback may run under deeper transforms which
   * we use for the gradient but not the clip outline. */
  struct pending_clip_t
  {
    hb_codepoint_t        glyph;    /* HB_CODEPOINT_INVALID for path clips */
    hb_font_t            *font;     /* borrowed; nullptr for path clips */
    hb_transform_t<float> transform;
    /* Path clips are encoded into a sub-blob at push_clip_path_end
     * time; glyph clips re-encode per consuming layer.  For path
     * clips, sub_blob_index is the pre-baked index and ext_* the
     * captured design-unit extents.  For glyph clips, sub_blob_index
     * is -1 and the ext_* fields are unused. */
    int                   sub_blob_index;
    int                   ext_x0, ext_y0, ext_x1, ext_y1;
  };
  pending_clip_t clip_stack[3];
  unsigned       clip_depth = 0;

  /* Carries the cur_transform captured at push_clip_path_start
   * through to push_clip_path_end, where the encoded clip is
   * committed to clip_stack. */
  hb_transform_t<float> pending_clip_path_transform = {};
  bool                  pending_clip_path = false;

  /* Set when the paint walk emits v1-only callbacks we do not yet
   * support.  hb_gpu_paint_encode() returns NULL in that case. */
  bool unsupported = false;

  /* Extents in font design units, accumulated across layers. */
  int ext_min_x =  0x7fffffff;
  int ext_min_y =  0x7fffffff;
  int ext_max_x = -0x7fffffff;
  int ext_max_y = -0x7fffffff;

  /* Scratch: used to rasterize each clip-glyph outline. */
  hb_gpu_draw_t *scratch_draw = nullptr;

  /* Scratch: color stops fetched per gradient callback. */
  hb_vector_t<hb_color_stop_t> color_stops_scratch;

  /* Recycled output blob. */
  hb_blob_t *recycled_blob = nullptr;

  bool fetch_color_stops (hb_color_line_t *color_line)
  {
    unsigned count = hb_color_line_get_color_stops (color_line, 0, nullptr, nullptr);
    if (unlikely (!count || !color_stops_scratch.resize (count)))
    {
      color_stops_scratch.resize (0);
      return false;
    }
    hb_color_line_get_color_stops (color_line, 0, &count, color_stops_scratch.arrayZ);
    return true;
  }
};


#endif /* HB_GPU_PAINT_HH */