xbintsc 0.5.23 → 0.5.32

package/runtime/ext_gui/paint_clip.cpp

@@ -0,0 +1,268 @@
+/*
+ * xbintsc GUI engine — `clip-path` geometry.
+ *
+ * CSS shapes become one device-space polygon, which is triangulated with ear
+ * clipping (so concave `polygon()` shapes work). The renderer intersects every
+ * convex shape/text/image quad with those triangles; no stencil or shader
+ * change is needed.
+ */
+
+#include "paint_internal.h"
+
+#include <algorithm>
+#include <cmath>
+#include <vector>
+
+namespace xtgui {
+namespace paint_detail {
+
+namespace {
+
+constexpr float kPi = 3.14159265358979323846f;
+
+struct Point {
+  float x = 0.0f;
+  float y = 0.0f;
+};
+
+float resolveX(const Length &length, float base, float em, float vw, float vh) {
+  return resolveLength(length, base, em, vw, vh);
+}
+
+float resolveY(const Length &length, float base, float em, float vw, float vh) {
+  return resolveLength(length, base, em, vw, vh);
+}
+
+void appendPoint(std::vector<Point> *points, const Point &point) {
+  if (!points->empty()) {
+    const Point &last = points->back();
+    if (std::fabs(last.x - point.x) < 0.0001f && std::fabs(last.y - point.y) < 0.0001f) return;
+  }
+  points->push_back(point);
+}
+
+/** Rounded-rectangle outline (used by `inset(... round r)`). */
+void insetOutline(const LayoutBox &box, const XtStyle &style, const ClipPathSpec &clip, float vw,
+                  float vh, std::vector<Point> *points) {
+  float em = style.font_size;
+  float top = resolveY(clip.inset_top, box.height, em, vw, vh);
+  float right = resolveX(clip.inset_right, box.width, em, vw, vh);
+  float bottom = resolveY(clip.inset_bottom, box.height, em, vw, vh);
+  float left = resolveX(clip.inset_left, box.width, em, vw, vh);
+  float x0 = box.x + left;
+  float y0 = box.y + top;
+  float x1 = box.x + box.width - right;
+  float y1 = box.y + box.height - bottom;
+  if (x1 < x0) std::swap(x0, x1);
+  if (y1 < y0) std::swap(y0, y1);
+  if (x1 - x0 <= 0.0f || y1 - y0 <= 0.0f) return;
+  float radius = resolveLength(clip.inset_radius, std::min(x1 - x0, y1 - y0), em, vw, vh);
+  radius = std::max(0.0f, std::min(radius, std::min(x1 - x0, y1 - y0) * 0.5f));
+  if (radius <= 0.0f) {
+    appendPoint(points, {x0, y0});
+    appendPoint(points, {x1, y0});
+    appendPoint(points, {x1, y1});
+    appendPoint(points, {x0, y1});
+    return;
+  }
+  const int segments = 6;
+  /* Clockwise from the top-left corner's start, one quarter arc per corner. */
+  for (int i = 0; i <= segments; i++) {
+    float angle = kPi + (float)i / (float)segments * (kPi * 0.5f);
+    appendPoint(points, {x0 + radius + std::cos(angle) * radius,
+                         y0 + radius + std::sin(angle) * radius});
+  }
+  for (int i = 0; i <= segments; i++) {
+    float angle = kPi * 1.5f + (float)i / (float)segments * (kPi * 0.5f);
+    appendPoint(points, {x1 - radius + std::cos(angle) * radius,
+                         y0 + radius + std::sin(angle) * radius});
+  }
+  for (int i = 0; i <= segments; i++) {
+    float angle = (float)i / (float)segments * (kPi * 0.5f);
+    appendPoint(points, {x1 - radius + std::cos(angle) * radius,
+                         y1 - radius + std::sin(angle) * radius});
+  }
+  for (int i = 0; i <= segments; i++) {
+    float angle = kPi * 0.5f + (float)i / (float)segments * (kPi * 0.5f);
+    appendPoint(points, {x0 + radius + std::cos(angle) * radius,
+                         y1 - radius + std::sin(angle) * radius});
+  }
+}
+
+void ellipseOutline(const LayoutBox &box, const XtStyle &style, const ClipPathSpec &clip, float vw,
+                    float vh, std::vector<Point> *points) {
+  float em = style.font_size;
+  float cx = box.x + resolveX(clip.center_x, box.width, em, vw, vh);
+  float cy = box.y + resolveY(clip.center_y, box.height, em, vw, vh);
+  bool circle = clip.type == ClipPathSpec::Type::Circle;
+  float rx = 0.0f;
+  float ry = 0.0f;
+  if (clip.radius_explicit) {
+    if (circle && clip.radius_x.unit == Unit::Percent) {
+      /* CSS resolves a circle percentage against sqrt(w² + h²) / sqrt(2). */
+      float diagonal = std::sqrt(box.width * box.width + box.height * box.height);
+      rx = ry = diagonal / std::sqrt(2.0f) * clip.radius_x.value / 100.0f;
+    } else {
+      rx = resolveX(clip.radius_x, box.width, em, vw, vh);
+      ry = circle ? rx : resolveY(clip.radius_y, box.height, em, vw, vh);
+    }
+  } else {
+    float left = std::max(0.0f, cx - box.x);
+    float right = std::max(0.0f, box.x + box.width - cx);
+    float top = std::max(0.0f, cy - box.y);
+    float bottom = std::max(0.0f, box.y + box.height - cy);
+    if (circle) {
+      rx = ry = std::min(std::min(left, right), std::min(top, bottom));
+    } else {
+      rx = std::min(left, right);
+      ry = std::min(top, bottom);
+    }
+  }
+  if (rx <= 0.0f || ry <= 0.0f) return;
+  const int segments = 48;
+  for (int i = 0; i < segments; i++) {
+    float angle = (float)i / (float)segments * kPi * 2.0f;
+    appendPoint(points, {cx + std::cos(angle) * rx, cy + std::sin(angle) * ry});
+  }
+}
+
+void polygonOutline(const LayoutBox &box, const XtStyle &style, const ClipPathSpec &clip, float vw,
+                    float vh, std::vector<Point> *points) {
+  float em = style.font_size;
+  for (size_t i = 0; i + 1 < clip.polygon.size(); i += 2) {
+    float x = box.x + resolveX(clip.polygon[i], box.width, em, vw, vh);
+    float y = box.y + resolveY(clip.polygon[i + 1], box.height, em, vw, vh);
+    appendPoint(points, {x, y});
+  }
+}
+
+float cross(const Point &a, const Point &b, const Point &c) {
+  return (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+}
+
+bool pointInTriangle(const Point &p, const Point &a, const Point &b, const Point &c) {
+  float c1 = cross(a, b, p);
+  float c2 = cross(b, c, p);
+  float c3 = cross(c, a, p);
+  const float eps = 0.0001f;
+  bool hasNeg = c1 < -eps || c2 < -eps || c3 < -eps;
+  bool hasPos = c1 > eps || c2 > eps || c3 > eps;
+  return !(hasNeg && hasPos);
+}
+
+/** Ear clipping for a simple polygon; falls back to a fan if it stalls. */
+void triangulate(std::vector<Point> points, std::vector<ClipTriangle> *triangles) {
+  if (points.size() < 3) return;
+  /* Remove a repeated closing point. */
+  if (std::fabs(points.front().x - points.back().x) < 0.0001f &&
+      std::fabs(points.front().y - points.back().y) < 0.0001f)
+    points.pop_back();
+  if (points.size() < 3) return;
+  float area = 0.0f;
+  for (size_t i = 0; i < points.size(); i++) {
+    const Point &a = points[i];
+    const Point &b = points[(i + 1) % points.size()];
+    area += a.x * b.y - b.x * a.y;
+  }
+  if (area < 0.0f) std::reverse(points.begin(), points.end());
+  std::vector<size_t> indices(points.size());
+  for (size_t i = 0; i < indices.size(); i++) indices[i] = i;
+  size_t guard = 0;
+  while (indices.size() > 3 && guard++ < indices.size() * indices.size() + 8) {
+    bool clipped = false;
+    for (size_t i = 0; i < indices.size(); i++) {
+      size_t previous = indices[(i + indices.size() - 1) % indices.size()];
+      size_t current = indices[i];
+      size_t next = indices[(i + 1) % indices.size()];
+      const Point &a = points[previous];
+      const Point &b = points[current];
+      const Point &c = points[next];
+      if (cross(a, b, c) <= 0.0001f) continue;
+      bool contains = false;
+      for (size_t other : indices) {
+        if (other == previous || other == current || other == next) continue;
+        if (pointInTriangle(points[other], a, b, c)) {
+          contains = true;
+          break;
+        }
+      }
+      if (contains) continue;
+      ClipTriangle triangle;
+      triangle.x[0] = a.x;
+      triangle.y[0] = a.y;
+      triangle.x[1] = b.x;
+      triangle.y[1] = b.y;
+      triangle.x[2] = c.x;
+      triangle.y[2] = c.y;
+      triangles->push_back(triangle);
+      indices.erase(indices.begin() + (long)i);
+      clipped = true;
+      break;
+    }
+    if (!clipped) break;
+  }
+  if (indices.size() >= 3) {
+    for (size_t i = 1; i + 1 < indices.size(); i++) {
+      ClipTriangle triangle;
+      triangle.x[0] = points[indices[0]].x;
+      triangle.y[0] = points[indices[0]].y;
+      triangle.x[1] = points[indices[i]].x;
+      triangle.y[1] = points[indices[i]].y;
+      triangle.x[2] = points[indices[i + 1]].x;
+      triangle.y[2] = points[indices[i + 1]].y;
+      triangles->push_back(triangle);
+    }
+  }
+}
+
+}  // namespace
+
+int addClipPathForBox(DisplayList &out, const LayoutBox &box, const XtStyle &style,
+                      float viewportWidth, float viewportHeight) {
+  if (style.clip_path.type == ClipPathSpec::Type::None) return -1;
+  std::vector<Point> points;
+  switch (style.clip_path.type) {
+    case ClipPathSpec::Type::Inset:
+      insetOutline(box, style, style.clip_path, viewportWidth, viewportHeight, &points);
+      break;
+    case ClipPathSpec::Type::Circle:
+    case ClipPathSpec::Type::Ellipse:
+      ellipseOutline(box, style, style.clip_path, viewportWidth, viewportHeight, &points);
+      break;
+    case ClipPathSpec::Type::Polygon:
+      polygonOutline(box, style, style.clip_path, viewportWidth, viewportHeight, &points);
+      break;
+    default:
+      return -1;
+  }
+  /* An empty but valid shape (`inset(50%)`, `circle(0)`) clips everything away;
+   * it must not fall back to "no clip". The paint walk keeps the empty geometry
+   * and the renderer emits no geometry for ops that reference it. */
+  ClipPathGeometry geometry;
+  geometry.points.reserve(points.size() * 2);
+  for (Point &point : points) {
+    float x = point.x;
+    float y = point.y;
+    box.world.apply(point.x, point.y, &x, &y);
+    geometry.points.push_back(x);
+    geometry.points.push_back(y);
+  }
+  if (points.size() >= 3) {
+    std::vector<Point> device;
+    device.reserve(points.size());
+    for (size_t i = 0; i + 1 < geometry.points.size(); i += 2)
+      device.push_back({geometry.points[i], geometry.points[i + 1]});
+    triangulate(device, &geometry.triangles);
+  }
+  out.clip_paths.push_back(std::move(geometry));
+  return (int)(out.clip_paths.size() - 1);
+}
+
+PaintClip addClipPath(PaintClip clip, int index) {
+  if (index < 0) return clip;
+  if (clip.path_count < 2) clip.paths[clip.path_count++] = index;
+  return clip;
+}
+
+}  // namespace paint_detail
+}  // namespace xtgui

package/runtime/ext_gui/paint_effects.cpp

@@ -0,0 +1,324 @@
+/*
+ * xbintsc GUI engine — CSS filter and shadow approximations.
+ *
+ * Colour functions are applied per painted shape (a group would need an
+ * offscreen layer). `blur()` is approximated by spreading nine translucent
+ * copies around the shape, and `drop-shadow()` by a shadow silhouette per box.
+ * Both are deterministic and need no render-target pass, which keeps the
+ * single-pass painter intact; `backdrop-filter` still needs a backdrop snapshot
+ * and is documented as not composited.
+ */
+
+#include "paint_internal.h"
+
+#include <algorithm>
+#include <cmath>
+#include <utility>
+#include <vector>
+
+#include "style_internal.h"
+
+namespace xtgui {
+namespace paint_detail {
+
+namespace {
+
+float clamp01(float value) { return value < 0.0f ? 0.0f : (value > 1.0f ? 1.0f : value); }
+
+Color lerpColor(const Color &from, const Color &to, float amount) {
+  Color out;
+  out.r = from.r + (to.r - from.r) * amount;
+  out.g = from.g + (to.g - from.g) * amount;
+  out.b = from.b + (to.b - from.b) * amount;
+  out.a = from.a + (to.a - from.a) * amount;
+  out.valid = true;
+  return out;
+}
+
+float luminance(const Color &color) {
+  return color.r * 0.2126f + color.g * 0.7152f + color.b * 0.0722f;
+}
+
+Color applySepia(const Color &color, float amount) {
+  Color sepia;
+  sepia.r = color.r * 0.393f + color.g * 0.769f + color.b * 0.189f;
+  sepia.g = color.r * 0.349f + color.g * 0.686f + color.b * 0.168f;
+  sepia.b = color.r * 0.272f + color.g * 0.534f + color.b * 0.131f;
+  sepia.a = color.a;
+  sepia.valid = true;
+  return lerpColor(color, sepia, amount);
+}
+
+Color applySaturate(const Color &color, float amount) {
+  float luma = luminance(color);
+  Color out;
+  out.r = luma + (color.r - luma) * amount;
+  out.g = luma + (color.g - luma) * amount;
+  out.b = luma + (color.b - luma) * amount;
+  out.a = color.a;
+  out.valid = true;
+  return out;
+}
+
+Color applyHueRotate(const Color &color, float degrees) {
+  float radians = degrees * 3.141592653589793f / 180.0f;
+  float c = std::cos(radians);
+  float s = std::sin(radians);
+  Color out;
+  out.r = color.r * (0.213f + c * 0.787f - s * 0.213f) +
+          color.g * (0.715f - c * 0.715f - s * 0.715f) +
+          color.b * (0.072f - c * 0.072f + s * 0.928f);
+  out.g = color.r * (0.213f - c * 0.213f + s * 0.143f) +
+          color.g * (0.715f + c * 0.285f + s * 0.140f) +
+          color.b * (0.072f - c * 0.072f - s * 0.283f);
+  out.b = color.r * (0.213f - c * 0.213f - s * 0.787f) +
+          color.g * (0.715f - c * 0.715f + s * 0.715f) +
+          color.b * (0.072f + c * 0.928f + s * 0.072f);
+  out.a = color.a;
+  out.valid = true;
+  return out;
+}
+
+struct Tap {
+  float dx;
+  float dy;
+};
+constexpr float kBlurTapWeight = 0.12f;
+
+std::vector<Tap> blurTaps(float radius) {
+  if (radius <= 0.0f) return {Tap{0.0f, 0.0f}};
+  std::vector<Tap> taps;
+  for (int y = -1; y <= 1; y++) {
+    for (int x = -1; x <= 1; x++) taps.push_back(Tap{x * radius, y * radius});
+  }
+  return taps;
+}
+
+}  // namespace
+
+float resolveLength(const Length &length, float base, float em, float viewportWidth,
+                    float viewportHeight) {
+  return xt_style_resolve_absolute(length, base, em, 16.0f, viewportWidth, viewportHeight);
+}
+
+FilterChain extendFilter(const FilterChain &parent, const std::vector<FilterOp> &filters,
+                         const XtStyle &style, float viewportWidth, float viewportHeight) {
+  FilterChain chain = parent;
+  /* Drop shadows are silhouettes of one box, never inherited. */
+  chain.shadows.clear();
+  for (const FilterOp &filter : filters) {
+    if (filter.kind == FilterKind::Blur) {
+      float blur = resolveLength(filter.blur, 0.0f, style.font_size, viewportWidth, viewportHeight);
+      if (blur > 0.0f) chain.blur += blur;
+    } else if (filter.kind == FilterKind::DropShadow) {
+      FilterChain::Shadow shadow;
+      shadow.dx = resolveLength(filter.dx, 0.0f, style.font_size, viewportWidth, viewportHeight);
+      shadow.dy = resolveLength(filter.dy, 0.0f, style.font_size, viewportWidth, viewportHeight);
+      shadow.blur =
+          resolveLength(filter.blur, 0.0f, style.font_size, viewportWidth, viewportHeight);
+      shadow.color = filter.has_color ? filter.color : style.color;
+      chain.shadows.push_back(shadow);
+    } else {
+      chain.ops.push_back(filter);
+    }
+  }
+  return chain;
+}
+
+Color filterColor(const FilterChain &chain, Color color) {
+  for (const FilterOp &filter : chain.ops) {
+    switch (filter.kind) {
+      case FilterKind::Brightness:
+        color.r *= filter.amount;
+        color.g *= filter.amount;
+        color.b *= filter.amount;
+        break;
+      case FilterKind::Contrast:
+        color.r = (color.r - 0.5f) * filter.amount + 0.5f;
+        color.g = (color.g - 0.5f) * filter.amount + 0.5f;
+        color.b = (color.b - 0.5f) * filter.amount + 0.5f;
+        break;
+      case FilterKind::Grayscale: {
+        float luma = luminance(color);
+        Color gray{luma, luma, luma, color.a, true};
+        color = lerpColor(color, gray, filter.amount);
+        break;
+      }
+      case FilterKind::Sepia:
+        color = applySepia(color, filter.amount);
+        break;
+      case FilterKind::Invert:
+        color.r = color.r + (1.0f - 2.0f * color.r) * filter.amount;
+        color.g = color.g + (1.0f - 2.0f * color.g) * filter.amount;
+        color.b = color.b + (1.0f - 2.0f * color.b) * filter.amount;
+        break;
+      case FilterKind::Saturate:
+        color = applySaturate(color, filter.amount);
+        break;
+      case FilterKind::HueRotate:
+        color = applyHueRotate(color, filter.amount);
+        break;
+      case FilterKind::Opacity:
+        color.a *= filter.amount;
+        break;
+      default:
+        break;
+    }
+    color.r = clamp01(color.r);
+    color.g = clamp01(color.g);
+    color.b = clamp01(color.b);
+    color.a = clamp01(color.a);
+  }
+  return color;
+}
+
+Color imageTint(const FilterChain &chain) {
+  /* The image shader multiplies the sampled texel by this colour, which can
+   * express brightness and opacity exactly. Other colour functions need a
+   * per-pixel pass; leaving the tint neutral is less wrong than a channel
+   * multiply, so they are skipped for images. */
+  Color tint{1.0f, 1.0f, 1.0f, 1.0f};
+  for (const FilterOp &filter : chain.ops) {
+    if (filter.kind == FilterKind::Brightness) {
+      tint.r *= filter.amount;
+      tint.g *= filter.amount;
+      tint.b *= filter.amount;
+    } else if (filter.kind == FilterKind::Opacity) {
+      tint.a *= filter.amount;
+    }
+  }
+  tint.r = clamp01(tint.r);
+  tint.g = clamp01(tint.g);
+  tint.b = clamp01(tint.b);
+  tint.a = clamp01(tint.a);
+  return tint;
+}
+
+void addRect(DisplayList &out, float x, float y, float width, float height, float radius,
+             const Color &color, const PaintClip &clip, const Matrix2D &transform) {
+  if (width <= 0.0f || height <= 0.0f || color.a <= 0.0f) return;
+  PaintRect rect;
+  rect.x = x;
+  rect.y = y;
+  rect.width = width;
+  rect.height = height;
+  rect.radius = radius;
+  rect.color = color;
+  rect.transform = transform;
+  out.rects.push_back(rect);
+  out.ops.push_back(PaintOp{PaintKind::Rect, (uint32_t)(out.rects.size() - 1), clip});
+}
+
+void addRectFiltered(DisplayList &out, float x, float y, float width, float height, float radius,
+                     const Color &color, const PaintClip &clip, const Matrix2D &transform,
+                     const FilterChain &chain) {
+  Color filtered = filterColor(chain, color);
+  if (filtered.a <= 0.0f) return;
+  if (chain.blur <= 0.0f) {
+    addRect(out, x, y, width, height, radius, filtered, clip, transform);
+    return;
+  }
+  for (const Tap &tap : blurTaps(chain.blur)) {
+    Color copy = filtered;
+    copy.a *= kBlurTapWeight;
+    addRect(out, x + tap.dx, y + tap.dy, width, height, radius, copy, clip, transform);
+  }
+}
+
+void addBoxDropShadows(DisplayList &out, const LayoutBox &box, const XtStyle &style,
+                       const FilterChain &chain, const PaintClip &clip) {
+  if (chain.shadows.empty()) return;
+  for (const FilterChain::Shadow &shadow : chain.shadows) {
+    Color color = filterColor(chain, shadow.color);
+    if (color.a <= 0.0f) continue;
+    std::vector<Tap> taps = blurTaps(shadow.blur);
+    for (const Tap &tap : taps) {
+      Color copy = color;
+      if (shadow.blur > 0.0f) copy.a *= kBlurTapWeight;
+      addRect(out, box.x + shadow.dx + tap.dx, box.y + shadow.dy + tap.dy, box.width, box.height,
+              style.border_radius, copy, clip, box.world);
+    }
+  }
+}
+
+void addTextRun(DisplayList &out, float x, float baseline, float width, float height,
+                const std::string &text, const FontSpec &font, const Color &color,
+                const Matrix2D &transform, const PaintClip &clip, const XtStyle &style,
+                const FilterChain &chain, float viewportWidth, float viewportHeight) {
+  if (text.empty() || color.a <= 0.0f) return;
+  auto emit = [&](float dx, float dy, Color runColor, bool shadow) {
+    if (runColor.a <= 0.0f) return;
+    PaintText run;
+    run.x = x + dx;
+    run.baseline = baseline + dy;
+    run.width = width;
+    run.height = height;
+    run.color = runColor;
+    run.text = text;
+    run.font = font;
+    run.transform = transform;
+    run.shadow = shadow;
+    out.texts.push_back(std::move(run));
+    out.ops.push_back(PaintOp{PaintKind::Text, (uint32_t)(out.texts.size() - 1), clip});
+  };
+
+  /* `filter: drop-shadow()` first (behind the glyphs). */
+  for (const FilterChain::Shadow &shadow : chain.shadows) {
+    Color shadowColor = filterColor(chain, shadow.color);
+    for (const Tap &tap : blurTaps(shadow.blur)) {
+      Color copy = shadowColor;
+      if (shadow.blur > 0.0f) copy.a *= kBlurTapWeight;
+      emit(shadow.dx + tap.dx, shadow.dy + tap.dy, copy, true);
+    }
+  }
+
+  /* `text-shadow`, bottom-most first: CSS paints later layers under earlier
+   * ones, so reverse the declaration list. */
+  for (size_t index = style.text_shadow.size(); index-- > 0;) {
+    const TextShadow &shadow = style.text_shadow[index];
+    float dx = resolveLength(shadow.dx, 0.0f, style.font_size, viewportWidth, viewportHeight);
+    float dy = resolveLength(shadow.dy, 0.0f, style.font_size, viewportWidth, viewportHeight);
+    float blur =
+        resolveLength(shadow.blur, 0.0f, style.font_size, viewportWidth, viewportHeight);
+    Color shadowColor = shadow.has_color ? filterColor(chain, shadow.color) : color;
+    for (const Tap &tap : blurTaps(blur)) {
+      Color copy = shadowColor;
+      if (blur > 0.0f) copy.a *= kBlurTapWeight;
+      emit(dx + tap.dx, dy + tap.dy, copy, true);
+    }
+  }
+
+  /* `filter: blur()` spreads the glyphs themselves. */
+  if (chain.blur > 0.0f) {
+    for (const Tap &tap : blurTaps(chain.blur)) {
+      Color copy = color;
+      copy.a *= kBlurTapWeight;
+      emit(tap.dx, tap.dy, copy, false);
+    }
+    return;
+  }
+  emit(0.0f, 0.0f, color, false);
+}
+
+void addImage(DisplayList &out, PaintImage image, const PaintClip &clip,
+              const FilterChain &chain) {
+  if (image.width <= 0.0f || image.height <= 0.0f) return;
+  image.tint = imageTint(chain);
+  if (image.tint.a <= 0.0f) return;
+  if (chain.blur <= 0.0f) {
+    out.images.push_back(std::move(image));
+    out.ops.push_back(PaintOp{PaintKind::Image, (uint32_t)(out.images.size() - 1), clip});
+    return;
+  }
+  for (const Tap &tap : blurTaps(chain.blur)) {
+    PaintImage copy = image;
+    copy.x += tap.dx;
+    copy.y += tap.dy;
+    copy.tint.a *= kBlurTapWeight;
+    out.images.push_back(std::move(copy));
+    out.ops.push_back(PaintOp{PaintKind::Image, (uint32_t)(out.images.size() - 1), clip});
+  }
+}
+
+}  // namespace paint_detail
+}  // namespace xtgui

package/runtime/ext_gui/paint_internal.h

@@ -0,0 +1,85 @@
+/*
+ * xbintsc GUI engine — shared paint helpers.
+ *
+ * `paint.cpp` owns the tree walk; the background, effect and clip-path
+ * translation units fill in the shapes. They all append through the small
+ * `addRect` / `addText` / `addImage` helpers here so painter order and the
+ * active clip stay consistent.
+ */
+#ifndef XT_GUI_PAINT_INTERNAL_H
+#define XT_GUI_PAINT_INTERNAL_H
+
+#include <string>
+#include <vector>
+
+#include "paint.h"
+#include "style.h"
+
+namespace xtgui {
+namespace paint_detail {
+
+/** A resolved chain of `filter` functions. `filter` applies to the element and
+ * its subtree, so it accumulates down the tree. Only the colour functions are
+ * group-accurate; blur and drop-shadow are approximated per shape (see the
+ * docs). */
+struct FilterChain {
+  std::vector<FilterOp> ops;  // colour functions (and any unknown no-ops)
+  float blur = 0.0f;          // resolved px
+  struct Shadow {
+    float dx = 0.0f;
+    float dy = 0.0f;
+    float blur = 0.0f;
+    Color color;
+  };
+  std::vector<Shadow> shadows;
+
+  bool empty() const { return ops.empty() && blur <= 0.0f && shadows.empty(); }
+};
+
+/** Append `filters` (declared on a box with `style`) to `parent`. */
+FilterChain extendFilter(const FilterChain &parent, const std::vector<FilterOp> &filters,
+                         const XtStyle &style, float viewportWidth, float viewportHeight);
+
+/** Apply the colour half of a filter chain. */
+Color filterColor(const FilterChain &chain, Color color);
+
+/** The multiplicative tint an image shader can carry (brightness/opacity). */
+Color imageTint(const FilterChain &chain);
+
+float resolveLength(const Length &length, float base, float em, float viewportWidth,
+                    float viewportHeight);
+
+/** Append one shape; skips empty geometry and fully transparent colours. */
+void addRect(DisplayList &out, float x, float y, float width, float height, float radius,
+             const Color &color, const PaintClip &clip, const Matrix2D &transform);
+/** Solid rectangle with the chain's blur spread into offset copies. */
+void addRectFiltered(DisplayList &out, float x, float y, float width, float height, float radius,
+                     const Color &color, const PaintClip &clip, const Matrix2D &transform,
+                     const FilterChain &chain);
+/** Add a text run (and its shadows/blur copies) for one laid-out fragment. */
+void addTextRun(DisplayList &out, float x, float baseline, float width, float height,
+                const std::string &text, const FontSpec &font, const Color &color,
+                const Matrix2D &transform, const PaintClip &clip, const XtStyle &style,
+                const FilterChain &chain, float viewportWidth, float viewportHeight);
+void addImage(DisplayList &out, PaintImage image, const PaintClip &clip, const FilterChain &chain);
+
+/** Paint the `background-color` and every `background-image` layer. */
+void paintBackgrounds(DisplayList &out, const LayoutBox &box, const XtStyle &style,
+                      const FilterChain &chain, const PaintClip &clip, float viewportWidth,
+                      float viewportHeight);
+
+/** Append the drop-shadow silhouettes of a box (once, before its content). */
+void addBoxDropShadows(DisplayList &out, const LayoutBox &box, const XtStyle &style,
+                       const FilterChain &chain, const PaintClip &clip);
+
+/** Resolve `clip-path` into a device-space triangulated polygon. */
+int addClipPathForBox(DisplayList &out, const LayoutBox &box, const XtStyle &style,
+                      float viewportWidth, float viewportHeight);
+
+/** Push `index` onto a clip chain (at most two survive). */
+PaintClip addClipPath(PaintClip clip, int index);
+
+}  // namespace paint_detail
+}  // namespace xtgui
+
+#endif /* XT_GUI_PAINT_INTERNAL_H */