xbintsc 0.5.41 → 0.5.43

package/runtime/ext_gui/paint_background.cpp

@@ -1,17 +1,22 @@
 /*
  * xbintsc GUI engine — background layer painting.
  *
- * The renderer has one rounded-rectangle pipeline and no gradient shader, so a
- * gradient is emitted as a run of solid bands: 18 strips for a linear gradient
- * and 32 concentric ellipses for a radial one. Radial ellipses use the shape
- * pipeline's transform slot (a unit circle scaled to the ellipse radii), which
- * keeps the distance-field antialiasing intact.
+ * `background-color` is one rounded rectangle and a `background-image` layer is
+ * a gradient or an image. A linear gradient is emitted as a run of solid bands
+ * (18 strips, 64 while repeating). A radial gradient is emitted as a single
+ * `PaintGradient` that the renderer rasterises per pixel
+ * (`renderer_gradient.cpp`): stacking translucent radial bands composites their
+ * alpha once per band, which turns a vignette whose stops fade to `transparent`
+ * into an opaque disc.
  */
 
 #include "paint_internal.h"
 
 #include <algorithm>
 #include <cmath>
+#include <cstdio>
+#include <memory>
+#include <string>
 #include <vector>
 
 namespace xtgui {
@@ -19,28 +24,112 @@ namespace paint_detail {
 
 namespace {
 
-Color gradientColorAt(const BackgroundLayer &layer, float t) {
-  const std::vector<BackgroundGradientStop> &stops = layer.stops;
+/** Blend two stops in premultiplied alpha, as CSS specifies, and convert the
+ * result back to the straight alpha both pipelines blend. Without it a
+ * `transparent` stop (rgba(0,0,0,0)) drags the ramp towards black, so a
+ * `transparent -> white` gradient fades through grey. */
+Color mixGradientStops(const Color &from, const Color &to, float amount) {
+  float alpha = from.a + (to.a - from.a) * amount;
+  Color out;
+  out.a = alpha;
+  if (alpha > 0.00001f) {
+    out.r = (from.r * from.a + (to.r * to.a - from.r * from.a) * amount) / alpha;
+    out.g = (from.g * from.a + (to.g * to.a - from.g * from.a) * amount) / alpha;
+    out.b = (from.b * from.a + (to.b * to.a - from.b * from.a) * amount) / alpha;
+  } else {
+    out.r = from.r;
+    out.g = from.g;
+    out.b = from.b;
+  }
+  out.valid = true;
+  return out;
+}
+
+}  // namespace
+
+Color gradientColorAt(const std::vector<GradientStop> &stops, bool repeating, float period,
+                      float t) {
   if (stops.empty()) return Color();
+  /* A repeating gradient restarts its stop pattern at the last stop's offset. */
+  if (repeating) {
+    if (period <= 0.00001f) return stops.back().color;
+    t -= std::floor(t / period) * period;
+  }
   if (t <= stops.front().offset) return stops.front().color;
   if (t >= stops.back().offset) return stops.back().color;
   for (size_t i = 1; i < stops.size(); i++) {
     if (t > stops[i].offset) continue;
     float span = stops[i].offset - stops[i - 1].offset;
     float u = span > 0.00001f ? (t - stops[i - 1].offset) / span : 0.0f;
-    Color a = stops[i - 1].color;
-    Color b = stops[i].color;
-    Color out;
-    out.r = a.r + (b.r - a.r) * u;
-    out.g = a.g + (b.g - a.g) * u;
-    out.b = a.b + (b.b - a.b) * u;
-    out.a = a.a + (b.a - a.a) * u;
-    out.valid = true;
-    return out;
+    return mixGradientStops(stops[i - 1].color, stops[i].color, u);
   }
   return stops.back().color;
 }
 
+namespace {
+
+/** Resolve the declaration's percentage/length offsets against the gradient
+ * line, then distribute the omitted (`Unit::Auto`) ones between their
+ * neighbours. The last explicit stop is preserved: for a normal gradient it
+ * holds that colour, and for a repeating one it defines the period. */
+std::vector<GradientStop> resolveStops(const BackgroundLayer &layer, float line_length,
+                                       const XtStyle &style, float viewportWidth,
+                                       float viewportHeight) {
+  std::vector<GradientStop> stops;
+  for (const BackgroundGradientStop &stop : layer.stops) {
+    GradientStop resolved;
+    resolved.color = stop.color;
+    resolved.offset = -1.0f;
+    if (stop.offset.unit == Unit::Percent) {
+      resolved.offset = stop.offset.value / 100.0f;
+    } else if (stop.offset.unit != Unit::Auto && stop.offset.unit != Unit::Invalid &&
+               stop.offset.unit != Unit::None) {
+      float pixels = resolveLength(stop.offset, 0.0f, style.font_size, viewportWidth,
+                                   viewportHeight);
+      resolved.offset = line_length > 0.00001f ? pixels / line_length : 0.0f;
+    }
+    stops.push_back(resolved);
+  }
+  if (stops.empty()) return stops;
+
+  /* Explicit offsets are non-decreasing, as in CSS. */
+  float last = -1.0f;
+  for (GradientStop &stop : stops) {
+    if (stop.offset < 0.0f) continue;
+    if (stop.offset < last) stop.offset = last;
+    last = stop.offset;
+  }
+
+  /* Fill implicit offsets by distributing them between their neighbours. */
+  size_t i = 0;
+  while (i < stops.size()) {
+    if (stops[i].offset >= 0.0f) {
+      i++;
+      continue;
+    }
+    size_t j = i;
+    while (j < stops.size() && stops[j].offset < 0.0f) j++;
+    float before = (i == 0) ? 0.0f : stops[i - 1].offset;
+    float after = (j >= stops.size()) ? 1.0f : stops[j].offset;
+    size_t count = j - i;
+    for (size_t k = 0; k < count; k++) {
+      float offset = 0.0f;
+      if (i == 0 && j >= stops.size()) {
+        offset = count > 1 ? (float)k / (float)(count - 1) : 0.0f;
+      } else if (i == 0) {
+        offset = after * (float)k / (float)count;
+      } else if (j >= stops.size()) {
+        offset = before + (1.0f - before) * (float)(k + 1) / (float)count;
+      } else {
+        offset = before + (after - before) * (float)(k + 1) / (float)(count + 1);
+      }
+      stops[i + k].offset = offset;
+    }
+    i = j;
+  }
+  return stops;
+}
+
 /** Intersect `clip` with the box's border box (backgrounds never paint outside
  * it, even when the box is not an overflow container). */
 PaintClip boxClip(const PaintClip &clip, const LayoutBox &box) {
@@ -75,17 +164,25 @@ PaintClip boxClip(const PaintClip &clip, const LayoutBox &box) {
   return out;
 }
 
-void paintLinear(const LayoutBox &box, const BackgroundLayer &layer, const FilterChain &chain,
-                 const PaintClip &clip, DisplayList &out) {
+void paintLinear(const LayoutBox &box, const XtStyle &style, const BackgroundLayer &layer,
+                 const FilterChain &chain, const PaintClip &clip, float viewportWidth,
+                 float viewportHeight, DisplayList &out) {
   if (layer.stops.size() < 2 || box.width <= 0.0f || box.height <= 0.0f) return;
-  const int strips = 18;
+  /* Repeating patterns need more samples than one gradient ramp: a 10%
+   * stripe is only two bands at the old 18-strip resolution. */
+  const int strips = layer.repeating ? 64 : 18;
   bool horizontal = (layer.angle > 80.0f && layer.angle < 100.0f) ||
                     (layer.angle > 260.0f && layer.angle < 280.0f);
   bool reverse = (layer.angle > 260.0f && layer.angle < 280.0f) || layer.angle < 10.0f ||
                  layer.angle > 350.0f;
+  const float line_length = horizontal ? box.width : box.height;
+  std::vector<GradientStop> stops = resolveStops(layer, line_length, style, viewportWidth,
+                                                 viewportHeight);
+  if (stops.size() < 2) return;
+  const float period = stops.back().offset;
   for (int i = 0; i < strips; i++) {
     float t = ((float)i + 0.5f) / (float)strips;
-    Color color = gradientColorAt(layer, reverse ? 1.0f - t : t);
+    Color color = gradientColorAt(stops, layer.repeating, period, reverse ? 1.0f - t : t);
     color = filterColor(chain, color);
     if (color.a <= 0.0f) continue;
     if (horizontal) {
@@ -98,6 +195,18 @@ void paintLinear(const LayoutBox &box, const BackgroundLayer &layer, const Filte
   }
 }
 
+/** Radii of a keyword-sized ellipse: it keeps the box's aspect ratio and is
+ * scaled until it meets the corner at `(px, py)` from the centre, so the 100%
+ * stop lands on that corner as it does in CSS. Taking the side distances instead
+ * left the corners of a `farthest-corner` gradient unpainted. */
+void cornerEllipseRadii(float width, float height, float px, float py, float *rx, float *ry) {
+  float x = 2.0f * px / width;
+  float y = 2.0f * py / height;
+  float scale = std::sqrt(x * x + y * y);
+  *rx = scale * width * 0.5f;
+  *ry = scale * height * 0.5f;
+}
+
 /** Default radii for `closest-side` / `farthest-side` / corner keywords. */
 void radialRadii(const LayoutBox &box, const BackgroundLayer &layer, const XtStyle &style,
                  float viewportWidth, float viewportHeight, float *cx, float *cy, float *rx,
@@ -151,31 +260,45 @@ void radialRadii(const LayoutBox &box, const BackgroundLayer &layer, const XtSty
     *rx = *ry = radius;
   } else {
     switch (layer.size) {
-      case RadialSize::ClosestCorner:
       case RadialSize::ClosestSide:
         *rx = std::min(left, right);
         *ry = std::min(top, bottom);
         break;
       case RadialSize::FarthestSide:
-      case RadialSize::FarthestCorner:
-      default:
         *rx = std::max(left, right);
         *ry = std::max(top, bottom);
         break;
+      case RadialSize::ClosestCorner:
+        cornerEllipseRadii(box.width, box.height, std::min(left, right), std::min(top, bottom), rx,
+                           ry);
+        break;
+      case RadialSize::FarthestCorner:
+      default:
+        cornerEllipseRadii(box.width, box.height, std::max(left, right), std::max(top, bottom), rx,
+                           ry);
+        break;
     }
   }
   *cx = centerX;
   *cy = centerY;
 }
 
-/** One filled ellipse: a unit-radius rounded rect mapped by a local scale. */
-void addEllipse(DisplayList &out, float cx, float cy, float rx, float ry, const Color &color,
-                const PaintClip &clip, const Matrix2D &world) {
-  if (rx <= 0.0f || ry <= 0.0f || color.a <= 0.0f) return;
-  Matrix2D local = Matrix2D::translate(cx, cy)
-                       .multiply(Matrix2D::scale(rx, ry))
-                       .multiply(Matrix2D::translate(-cx, -cy));
-  addRect(out, cx - 1.0f, cy - 1.0f, 2.0f, 2.0f, 1.0f, color, clip, world.multiply(local));
+/** Stable identity of a rasterised gradient: the ramp plus its geometry. The
+ * renderer keys its texture cache by this string, so an unchanged declaration
+ * rasterises once. */
+std::string gradientKey(const PaintGradient &gradient) {
+  char buffer[192];
+  std::string key;
+  for (const GradientStop &stop : gradient.stops) {
+    std::snprintf(buffer, sizeof(buffer), "%.4f/%.5f,%.5f,%.5f,%.5f;", stop.offset, stop.color.r,
+                  stop.color.g, stop.color.b, stop.color.a);
+    key += buffer;
+  }
+  std::snprintf(buffer, sizeof(buffer), "%.3f,%.3f,%.3f,%.3f;%d;%.5f", gradient.center_x,
+                gradient.center_y, gradient.radius_x, gradient.radius_y,
+                gradient.repeating ? 1 : 0, gradient.period);
+  key += buffer;
+  return key;
 }
 
 void paintRadial(const LayoutBox &box, const XtStyle &style, const BackgroundLayer &layer,
@@ -188,16 +311,49 @@ void paintRadial(const LayoutBox &box, const XtStyle &style, const BackgroundLay
   float ry = 0.0f;
   radialRadii(box, layer, style, viewportWidth, viewportHeight, &cx, &cy, &rx, &ry);
   if (rx <= 0.0f || ry <= 0.0f) return;
-  const int bands = 32;
-  for (int i = bands; i >= 1; i--) {
-    float t = (float)i / (float)bands;
-    Color color = filterColor(chain, gradientColorAt(layer, t));
-    if (color.a <= 0.0f) continue;
-    addEllipse(out, cx, cy, rx * t, ry * t, color, clip, box.world);
+  std::vector<GradientStop> stops = resolveStops(layer, std::max(rx, ry), style, viewportWidth,
+                                                 viewportHeight);
+  if (stops.size() < 2) return;
+  /* The colour functions fold into the stops (a per-stop application is exact
+   * for the linear ones); `brightness()` and `opacity()` stay out, because the
+   * image tint carries them exactly and leaving them out keeps the ramp — and
+   * therefore the texture cache key — stable while a fade animates. */
+  FilterChain stopChain = chain;
+  stopChain.opacity = 1.0f;
+  for (size_t i = stopChain.ops.size(); i-- > 0;) {
+    FilterKind kind = stopChain.ops[i].kind;
+    if (kind == FilterKind::Brightness || kind == FilterKind::Opacity) {
+      stopChain.ops.erase(stopChain.ops.begin() + (ptrdiff_t)i);
+    }
   }
-  /* Exact centre colour (the innermost band samples just off zero). */
-  Color center = filterColor(chain, gradientColorAt(layer, 0.0f));
-  addEllipse(out, cx, cy, 0.6f, 0.6f, center, clip, box.world);
+  auto gradient = std::make_shared<PaintGradient>();
+  gradient->stops.reserve(stops.size());
+  bool visible = false;
+  for (size_t i = 0; i < stops.size(); i++) {
+    GradientStop resolved = stops[i];
+    resolved.color = filterColor(stopChain, resolved.color);
+    visible = visible || resolved.color.a > 0.0f;
+    gradient->stops.push_back(resolved);
+  }
+  if (!visible) return;
+  gradient->center_x = cx - box.x;
+  gradient->center_y = cy - box.y;
+  gradient->radius_x = rx;
+  gradient->radius_y = ry;
+  gradient->repeating = layer.repeating;
+  gradient->period = stops.back().offset;
+  gradient->key = gradientKey(*gradient);
+
+  /* One quad for the whole layer: the renderer resolves the ramp per pixel, so
+   * the layer composites exactly once instead of once per translucent band. */
+  PaintImage image;
+  image.x = box.x;
+  image.y = box.y;
+  image.width = box.width;
+  image.height = box.height;
+  image.transform = box.world;
+  image.gradient = gradient;
+  addImage(out, std::move(image), clip, chain);
 }
 
 void paintImage(const LayoutBox &box, const BackgroundLayer &layer, const FilterChain &chain,
@@ -233,7 +389,7 @@ void paintBackgrounds(DisplayList &out, const LayoutBox &box, const XtStyle &sty
   for (size_t i = style.background_layers.size(); i-- > 0;) {
     const BackgroundLayer &layer = style.background_layers[i];
     if (layer.kind == BackgroundKind::Linear) {
-      paintLinear(box, layer, chain, layerClip, out);
+      paintLinear(box, style, layer, chain, layerClip, viewportWidth, viewportHeight, out);
     } else if (layer.kind == BackgroundKind::Radial) {
       paintRadial(box, style, layer, chain, layerClip, viewportWidth, viewportHeight, out);
     } else {

package/runtime/ext_gui/paint_effects.cpp

@@ -169,6 +169,7 @@ Color filterColor(const FilterChain &chain, Color color) {
     color.b = clamp01(color.b);
     color.a = clamp01(color.a);
   }
+  color.a = clamp01(color.a * chain.opacity);
   return color;
 }
 
@@ -190,7 +191,7 @@ Color imageTint(const FilterChain &chain) {
   tint.r = clamp01(tint.r);
   tint.g = clamp01(tint.g);
   tint.b = clamp01(tint.b);
-  tint.a = clamp01(tint.a);
+  tint.a = clamp01(tint.a * chain.opacity);
   return tint;
 }
 

package/runtime/ext_gui/paint_internal.h

@@ -25,6 +25,10 @@ namespace paint_detail {
 struct FilterChain {
   std::vector<FilterOp> ops;  // colour functions (and any unknown no-ops)
   float blur = 0.0f;          // resolved px
+  /** Product of the CSS `opacity` values on the ancestor chain (including the
+   * element itself). It multiplies every painted colour's alpha, which is the
+   * per-shape approximation of group opacity. */
+  float opacity = 1.0f;
   struct Shadow {
     float dx = 0.0f;
     float dy = 0.0f;
@@ -33,7 +37,7 @@ struct FilterChain {
   };
   std::vector<Shadow> shadows;
 
-  bool empty() const { return ops.empty() && blur <= 0.0f && shadows.empty(); }
+  bool empty() const { return ops.empty() && blur <= 0.0f && shadows.empty() && opacity >= 1.0f; }
 };
 
 /** Append `filters` (declared on a box with `style`) to `parent`. */

package/runtime/ext_gui/renderer.cpp

@@ -27,6 +27,8 @@ SDL_GPUGraphicsPipeline *g_pipeline = nullptr;
 SDL_GPUGraphicsPipeline *g_text_pipeline = nullptr;
 SDL_GPUGraphicsPipeline *g_image_pipeline = nullptr;
 SDL_GPUSampler *g_sampler = nullptr;
+SDL_GPUDevice *g_device = nullptr;
+SDL_GPUTextureFormat g_swapchain_format = SDL_GPU_TEXTUREFORMAT_INVALID;
 int g_renderer_failed = 0;
 bool g_text_ok = false;
 std::unordered_map<std::string, SDL_GPUTexture *> g_image_textures;
@@ -146,6 +148,8 @@ bool xt_gui_renderer_ensure(SDL_GPUDevice *device, SDL_Window *reference) {
   using namespace xtgui::renderer_detail;
   if (g_pipeline != nullptr) return true;
   if (g_renderer_failed) return false;
+  g_device = device;
+  g_swapchain_format = SDL_GetGPUSwapchainTextureFormat(device, reference);
   const ShaderSource fill_vs = selectShader(device, ShaderProgram::Fill, false);
   const ShaderSource fill_fs = selectShader(device, ShaderProgram::Fill, true);
   if (!fill_vs.valid() || !fill_fs.valid()) {
@@ -242,6 +246,7 @@ bool xt_gui_renderer_ensure(SDL_GPUDevice *device, SDL_Window *reference) {
 
 void xt_gui_renderer_destroy(SDL_GPUDevice *device) {
   using namespace xtgui::renderer_detail;
+  xtgui::renderer_detail::layerRendererDestroy(device);
   if (g_pipeline != nullptr) {
     SDL_ReleaseGPUGraphicsPipeline(device, g_pipeline);
     g_pipeline = nullptr;
@@ -275,6 +280,8 @@ void xt_gui_renderer_destroy(SDL_GPUDevice *device) {
   g_atlas_full_logged = false;
   g_text_ok = false;
   g_renderer_failed = 0;
+  g_device = nullptr;
+  g_swapchain_format = SDL_GPU_TEXTUREFORMAT_INVALID;
 }
 
 void xt_gui_geometry_destroy(SDL_GPUDevice *device, XtGuiGeometry *geometry) {
@@ -286,6 +293,13 @@ void xt_gui_geometry_destroy(SDL_GPUDevice *device, XtGuiGeometry *geometry) {
     SDL_ReleaseGPUTransferBuffer(device, geometry->staging);
     geometry->staging = nullptr;
   }
+  for (SDL_GPUTexture *texture : geometry->scene_textures) {
+    if (texture != nullptr) SDL_ReleaseGPUTexture(device, texture);
+  }
+  geometry->scene_textures.clear();
+  geometry->scene_width = 0;
+  geometry->scene_height = 0;
+  geometry->scene_format = SDL_GPU_TEXTUREFORMAT_INVALID;
   geometry->staging_capacity = 0;
   geometry->capacity_bytes = 0;
   geometry->vertex_count = 0;
@@ -314,6 +328,15 @@ void xt_gui_build_runs(XtGuiGeometry *shapes, XtGuiGeometry *texts, XtGuiGeometr
   shapes->runs.clear();
   uint32_t cursor[3] = {0, 0, 0};
   for (const xtgui::PaintOp &op : list.ops) {
+    if (op.kind == xtgui::PaintKind::LayerBegin ||
+        op.kind == xtgui::PaintKind::LayerEnd) {
+      XtGuiDrawRun marker;
+      marker.pipeline = op.kind == xtgui::PaintKind::LayerBegin ? XtGuiDrawRun::LayerBegin
+                                                                : XtGuiDrawRun::LayerEnd;
+      marker.layer = op.kind == xtgui::PaintKind::LayerBegin ? op.index : 0;
+      shapes->runs.push_back(marker);
+      continue;
+    }
     int pipeline = (int)op.kind;
     XtGuiGeometry *geometry = pipeline == 0 ? shapes : (pipeline == 1 ? texts : images);
     if (op.index >= geometry->op_counts.size()) continue;
@@ -349,17 +372,13 @@ void xt_gui_build_runs(XtGuiGeometry *shapes, XtGuiGeometry *texts, XtGuiGeometr
   }
 }
 
-void xt_gui_renderer_draw(SDL_GPUCommandBuffer *cmd, SDL_GPURenderPass *pass,
-                          XtGuiGeometry *shapes, XtGuiGeometry *texts, XtGuiGeometry *images,
-                          float viewport_width, float viewport_height, float pixel_density) {
-  using namespace xtgui::renderer_detail;
-  if (viewport_width <= 0.0f || viewport_height <= 0.0f) return;
-  if (pixel_density <= 0.0f) pixel_density = 1.0f;
-  float viewport[2] = {viewport_width, viewport_height};
-  SDL_PushGPUVertexUniformData(cmd, 0, viewport, sizeof(viewport));
+namespace xtgui {
+namespace renderer_detail {
 
-  int target_width = (int)(viewport_width * pixel_density + 0.5f);
-  int target_height = (int)(viewport_height * pixel_density + 0.5f);
+void drawRuns(SDL_GPURenderPass *pass, const std::vector<XtGuiDrawRun> &runs, size_t begin,
+              size_t end, XtGuiGeometry *shapes, XtGuiGeometry *texts, XtGuiGeometry *images,
+              int target_width, int target_height, float pixel_density) {
+  if (pass == nullptr) return;
   /* A run list alternates pipelines (background, text, background, …), so the
    * same scissor rectangle and the same pipeline were re-bound for every run.
    * Track what is bound and only issue the state change when it actually
@@ -389,7 +408,11 @@ void xt_gui_renderer_draw(SDL_GPUCommandBuffer *cmd, SDL_GPURenderPass *pass,
     SDL_BindGPUFragmentSamplers(pass, 0, &texture_binding, 1);
     bound_texture = texture;
   };
-  for (const XtGuiDrawRun &run : shapes->runs) {
+  for (size_t i = begin; i < end && i < runs.size(); i++) {
+    const XtGuiDrawRun &run = runs[i];
+    if (run.pipeline == XtGuiDrawRun::LayerBegin || run.pipeline == XtGuiDrawRun::LayerEnd)
+      continue;
+    if (run.count == 0) continue;
     SDL_Rect scissor;
     scissor.x = 0;
     scissor.y = 0;
@@ -426,7 +449,7 @@ void xt_gui_renderer_draw(SDL_GPUCommandBuffer *cmd, SDL_GPURenderPass *pass,
       bindTexture(g_atlas_texture);
       SDL_DrawGPUPrimitives(pass, run.count, 1, run.first, 0);
       xtgui::g_perf_frame.drawCalls += 1;
-    } else {
+    } else if (run.pipeline == XtGuiDrawRun::Image) {
       if (g_image_pipeline == nullptr || g_sampler == nullptr || images->buffer == nullptr ||
           run.texture == nullptr)
         continue;
@@ -437,7 +460,7 @@ void xt_gui_renderer_draw(SDL_GPUCommandBuffer *cmd, SDL_GPURenderPass *pass,
     }
   }
 
-  /* Restore the full-target scissor so the next frame starts clean. */
+  /* Restore the full-target scissor so the next pass starts clean. */
   SDL_Rect full;
   full.x = 0;
   full.y = 0;
@@ -445,3 +468,48 @@ void xt_gui_renderer_draw(SDL_GPUCommandBuffer *cmd, SDL_GPURenderPass *pass,
   full.h = target_height;
   SDL_SetGPUScissor(pass, &full);
 }
+
+}  // namespace renderer_detail
+}  // namespace xtgui
+
+void xt_gui_renderer_draw(SDL_GPUCommandBuffer *cmd, SDL_GPUTexture *swapchain,
+                          const float clear_color[4], XtGuiGeometry *shapes,
+                          XtGuiGeometry *texts, XtGuiGeometry *images,
+                          const xtgui::DisplayList &list, float viewport_width,
+                          float viewport_height, float pixel_density) {
+  using namespace xtgui::renderer_detail;
+  if (cmd == nullptr || swapchain == nullptr) return;
+  if (viewport_width <= 0.0f || viewport_height <= 0.0f) return;
+  if (pixel_density <= 0.0f) pixel_density = 1.0f;
+  float viewport[2] = {viewport_width, viewport_height};
+  SDL_PushGPUVertexUniformData(cmd, 0, viewport, sizeof(viewport));
+
+  /* `mix-blend-mode` needs the backdrop as a texture; the blend pipeline is
+   * compiled at run time on the SPIR-V/MSL backends. Everywhere else (or if
+   * that compilation failed) the ordinary single pass still paints the
+   * unblended content rather than dropping it. */
+  if (!list.layers.empty() && layerRendererReady(g_device)) {
+    if (drawLayeredScene(cmd, swapchain, clear_color, shapes, texts, images, list, viewport_width,
+                         viewport_height, pixel_density))
+      return;
+  }
+
+  SDL_GPUColorTargetInfo target;
+  memset(&target, 0, sizeof(target));
+  target.texture = swapchain;
+  target.clear_color.r = clear_color != nullptr ? clear_color[0] : 0.0f;
+  target.clear_color.g = clear_color != nullptr ? clear_color[1] : 0.0f;
+  target.clear_color.b = clear_color != nullptr ? clear_color[2] : 0.0f;
+  target.clear_color.a = clear_color != nullptr ? clear_color[3] : 1.0f;
+  target.load_op = SDL_GPU_LOADOP_CLEAR;
+  target.store_op = SDL_GPU_STOREOP_STORE;
+  SDL_GPURenderPass *pass = SDL_BeginGPURenderPass(cmd, &target, 1, nullptr);
+  if (pass == nullptr) return;
+  int target_width = (int)(viewport_width * pixel_density + 0.5f);
+  int target_height = (int)(viewport_height * pixel_density + 0.5f);
+  if (shapes != nullptr && texts != nullptr && images != nullptr) {
+    drawRuns(pass, shapes->runs, 0, shapes->runs.size(), shapes, texts, images, target_width,
+             target_height, pixel_density);
+  }
+  SDL_EndGPURenderPass(pass);
+}

package/runtime/ext_gui/renderer.h

@@ -33,7 +33,9 @@ struct DisplayList;
  * `clip_width <= 0` means the whole viewport. For image runs, `texture` is the
  * bound texture. */
 struct XtGuiDrawRun {
-  enum Pipeline { Shape = 0, Text = 1, Image = 2 };
+  /** `LayerBegin`/`LayerEnd` are zero-count markers around a
+   * `mix-blend-mode` group; `layer` indexes `DisplayList::layers`. */
+  enum Pipeline { Shape = 0, Text = 1, Image = 2, LayerBegin = 3, LayerEnd = 4 };
   int pipeline = Shape;
   uint32_t first = 0;
   uint32_t count = 0;
@@ -42,6 +44,7 @@ struct XtGuiDrawRun {
   float clip_width = 0;
   float clip_height = 0;
   SDL_GPUTexture *texture = nullptr;
+  uint32_t layer = 0;
 };
 
 /** Per-window GPU geometry (vertex buffer + draw range). */
@@ -63,6 +66,12 @@ struct XtGuiGeometry {
   /** Painter-order draw runs, built from the display list by
    * `xt_gui_build_runs` and consumed by `xt_gui_renderer_draw`. */
   std::vector<XtGuiDrawRun> runs;
+  /** Offscreen colour targets used by `mix-blend-mode` groups (two per nesting
+   * level). Reused across frames and tied to the swapchain size/format. */
+  std::vector<SDL_GPUTexture *> scene_textures;
+  uint32_t scene_width = 0;
+  uint32_t scene_height = 0;
+  SDL_GPUTextureFormat scene_format = SDL_GPU_TEXTUREFORMAT_INVALID;
 };
 
 /** One GPU command buffer shared by every upload a frame performs (shape, text,
@@ -91,10 +100,15 @@ void xt_gui_geometry_destroy(SDL_GPUDevice *device, XtGuiGeometry *geometry);
  * immediately. */
 void xt_gui_geometry_upload(SDL_GPUDevice *device, XtGuiGeometry *geometry,
                             const xtgui::DisplayList &list, XtGuiUploadBatch *batch = nullptr);
-/** Draw `geometry` inside an active render pass. */
-void xt_gui_renderer_draw(SDL_GPUCommandBuffer *cmd, SDL_GPURenderPass *pass,
-                          XtGuiGeometry *shapes, XtGuiGeometry *texts, XtGuiGeometry *images,
-                          float viewport_width, float viewport_height, float pixel_density);
+/** Draw the display list into `swapchain`, beginning and ending its own render
+ * passes. With `mix-blend-mode` groups the renderer draws them to offscreen
+ * textures and composites them with a runtime-compiled blend shader; without
+ * groups this is the original single clear-and-draw pass. */
+void xt_gui_renderer_draw(SDL_GPUCommandBuffer *cmd, SDL_GPUTexture *swapchain,
+                          const float clear_color[4], XtGuiGeometry *shapes,
+                          XtGuiGeometry *texts, XtGuiGeometry *images,
+                          const xtgui::DisplayList &list, float viewport_width,
+                          float viewport_height, float pixel_density);
 /** Shape `list.texts`, ensure their glyphs are in the atlas, and upload the
  * text geometry. `scale` is the device pixel density (1.0 = logical pixels). */
 void xt_gui_text_upload(SDL_GPUDevice *device, XtGuiGeometry *geometry,