xbintsc 0.3.68 → 0.3.79

package/runtime/ext_gui/paint.cpp

@@ -4,6 +4,7 @@
 
 #include "paint.h"
 
+#include <algorithm>
 #include <cstdio>
 #include <utility>
 
@@ -31,7 +32,7 @@ FontSpec specOf(const XtStyle &style) {
 }
 
 void addRect(DisplayList &out, float x, float y, float width, float height, float radius,
-             const Color &color) {
+             const Color &color, const PaintClip &clip) {
   if (width <= 0.0f || height <= 0.0f || color.a <= 0.0f) return;
   PaintRect rect;
   rect.x = x;
@@ -41,9 +42,11 @@ void addRect(DisplayList &out, float x, float y, float width, float height, floa
   rect.radius = radius;
   rect.color = color;
   out.rects.push_back(rect);
+  out.ops.push_back(PaintOp{PaintKind::Rect, (uint32_t)(out.rects.size() - 1), clip});
 }
 
-void addTextRuns(const LayoutBox *box, const XtStyle &style, DisplayList &out) {
+void addTextRuns(const LayoutBox *box, const XtStyle &style, DisplayList &out,
+                 const PaintClip &clip) {
   if (box->fragments.empty() || style.color.a <= 0.0f) return;
   FontSpec spec = specOf(style);
   float ascent = 0;
@@ -60,28 +63,71 @@ void addTextRuns(const LayoutBox *box, const XtStyle &style, DisplayList &out) {
     run.text = fragment.text;
     run.font = spec;
     out.texts.push_back(std::move(run));
+    out.ops.push_back(PaintOp{PaintKind::Text, (uint32_t)(out.texts.size() - 1), clip});
   }
 }
 
-void paintBox(const LayoutBox *box, DisplayList &out) {
+void addImage(const PaintImage &image, DisplayList &out, const PaintClip &clip) {
+  out.images.push_back(image);
+  out.ops.push_back(PaintOp{PaintKind::Image, (uint32_t)(out.images.size() - 1), clip});
+}
+
+void paintBox(const LayoutBox *box, DisplayList &out, const PaintClip &clip);
+
+/** The clip a box imposes on its content: its padding box, intersected with the
+ * clip already in effect. Only `overflow: hidden/scroll/auto` clips. */
+PaintClip clipForChildren(const LayoutBox *box, const PaintClip &parent) {
+  if (box->style == nullptr || box->style->overflow == Overflow::Visible) return parent;
+  float x = box->x + box->border_left;
+  float y = box->y + box->border_top;
+  float width = box->width - box->border_left - box->border_right;
+  float height = box->height - box->border_top - box->border_bottom;
+  if (width < 0) width = 0;
+  if (height < 0) height = 0;
+  if (!parent.active) return PaintClip{true, x, y, width, height};
+  float x0 = std::max(x, parent.x);
+  float y0 = std::max(y, parent.y);
+  float x1 = std::min(x + width, parent.x + parent.width);
+  float y1 = std::min(y + height, parent.y + parent.height);
+  return PaintClip{true, x0, y0, std::max(0.0f, x1 - x0), std::max(0.0f, y1 - y0)};
+}
+
+int zIndexOf(const LayoutBox *box) {
+  if (box->style == nullptr || !box->style->has_z_index) return 0;
+  return box->style->z_index;
+}
+
+/** Paint `box`'s children following z-index: negative z first (ascending), then
+ * auto/zero in document order, then positive z (ascending), so higher stacks
+ * paint last. */
+void paintChildren(const LayoutBox *box, DisplayList &out, const PaintClip &clip) {
+  std::vector<const LayoutBox *> children;
+  for (const std::unique_ptr<LayoutBox> &child : box->children) {
+    if (child->display == Display::None || child->style == nullptr) continue;
+    children.push_back(child.get());
+  }
+  std::stable_sort(children.begin(), children.end(), [](const LayoutBox *a, const LayoutBox *b) {
+    return zIndexOf(a) < zIndexOf(b);
+  });
+  for (const LayoutBox *child : children) paintBox(child, out, clip);
+}
+
+void paintBox(const LayoutBox *box, DisplayList &out, const PaintClip &clip) {
   if (box == nullptr) return;
   const XtStyle *style = box->style;
 
-  /* A fully transparent box paints nothing — not itself, and not its subtree.
-   * `opacity` is otherwise unsupported: a shape carries its colour's alpha only,
-   * so a partly transparent box (an `opacity` transition mid-flight, say) is
-   * still painted opaque. */
+  /* A fully transparent box paints nothing — not itself, and not its subtree. */
   if (style != nullptr && style->opacity <= 0.0f) return;
 
   if (style != nullptr && box->display != Display::None) {
     if (box->is_text) {
-      addTextRuns(box, *style, out);
+      addTextRuns(box, *style, out, clip);
     } else {
-      /* Background first, then the (sharp-cornered) border ring on top, then the
-       * children, so their content paints over the padding. */
+      /* Background first, then the border ring, then replaced content. Children
+       * are clipped by this box's padding box when it establishes one. */
       if (style->has_background) {
         addRect(out, box->x, box->y, box->width, box->height, style->border_radius,
-                style->background);
+                style->background, clip);
       }
       if (style->border_style != BorderStyle::None && style->has_border_color) {
         const Color bc = style->border_color;
@@ -90,52 +136,91 @@ void paintBox(const LayoutBox *box, DisplayList &out) {
         float bottom = box->border_bottom;
         float left = box->border_left;
         float inner_height = box->height - top - bottom;
-        /* Top/bottom span the whole width and overlap the side edges, which is
-         * harmless (same colour) and avoids seams from float rounding. */
-        addRect(out, box->x, box->y, box->width, top, 0.0f, bc);
-        addRect(out, box->x, box->y + box->height - bottom, box->width, bottom, 0.0f, bc);
-        addRect(out, box->x, box->y + top, left, inner_height, 0.0f, bc);
-        addRect(out, box->x + box->width - right, box->y + top, right, inner_height, 0.0f, bc);
+        addRect(out, box->x, box->y, box->width, top, 0.0f, bc, clip);
+        addRect(out, box->x, box->y + box->height - bottom, box->width, bottom, 0.0f, bc, clip);
+        addRect(out, box->x, box->y + top, left, inner_height, 0.0f, bc, clip);
+        addRect(out, box->x + box->width - right, box->y + top, right, inner_height, 0.0f, bc,
+                clip);
       }
-      if (box->is_image && !box->image_src.empty() && box->content_width > 0.0f &&
+      if (box->is_canvas && box->canvas_id != 0 && box->content_width > 0.0f &&
           box->content_height > 0.0f) {
         PaintImage image;
         image.x = box->content_x;
         image.y = box->content_y;
         image.width = box->content_width;
         image.height = box->content_height;
+        image.canvas_id = box->canvas_id;
+        addImage(image, out, clip);
+      } else if (box->is_media && box->media_id != 0 && box->content_width > 0.0f &&
+                 box->content_height > 0.0f) {
+        PaintImage image;
+        image.x = box->content_x;
+        image.y = box->content_y;
+        image.width = box->content_width;
+        image.height = box->content_height;
+        image.media_id = box->media_id;
+        addImage(image, out, clip);
+      } else if (box->is_image && !box->image_src.empty() && box->content_width > 0.0f &&
+                 box->content_height > 0.0f) {
+        PaintImage image;
+        image.x = box->content_x;
+        image.y = box->content_y;
+        image.width = box->content_width;
+        image.height = box->content_height;
         image.src = box->image_src;
-        out.images.push_back(std::move(image));
+        addImage(image, out, clip);
       }
     }
   }
 
-  for (const std::unique_ptr<LayoutBox> &child : box->children) paintBox(child.get(), out);
+  paintChildren(box, out, clipForChildren(box, clip));
 }
 
 }  // namespace
 
-void xt_paint_build(const LayoutBox *root, DisplayList &out) { paintBox(root, out); }
+void xt_paint_build(const LayoutBox *root, DisplayList &out) {
+  PaintClip none;
+  paintBox(root, out, none);
+}
 
 std::string DisplayList::dump() const {
   std::string text;
-  char buffer[192];
-  for (const PaintRect &rect : rects) {
-    std::snprintf(buffer, sizeof(buffer), "rect x=%.1f y=%.1f w=%.1f h=%.1f r=%.1f color=%s\n",
-                  rect.x, rect.y, rect.width, rect.height, rect.radius,
-                  formatColor(rect.color).c_str());
-    text += buffer;
-  }
-  for (const PaintText &run : texts) {
-    std::snprintf(buffer, sizeof(buffer),
-                  "text x=%.1f baseline=%.1f size=%.1f color=%s \"%s\"\n", run.x, run.baseline,
-                  run.font.pixel_size, formatColor(run.color).c_str(), run.text.c_str());
-    text += buffer;
-  }
-  for (const PaintImage &image : images) {
-    std::snprintf(buffer, sizeof(buffer), "image x=%.1f y=%.1f w=%.1f h=%.1f src=%s\n", image.x,
-                  image.y, image.width, image.height, image.src.c_str());
-    text += buffer;
+  char buffer[224];
+  for (const PaintOp &op : ops) {
+    std::string prefix;
+    if (op.clip.active) {
+      std::snprintf(buffer, sizeof(buffer), "clip=%.1f,%.1f,%.1f,%.1f ", op.clip.x, op.clip.y,
+                    op.clip.width, op.clip.height);
+      prefix = buffer;
+    }
+    if (op.kind == PaintKind::Rect) {
+      const PaintRect &rect = rects[op.index];
+      std::snprintf(buffer, sizeof(buffer),
+                    "rect x=%.1f y=%.1f w=%.1f h=%.1f r=%.1f color=%s\n", rect.x, rect.y,
+                    rect.width, rect.height, rect.radius, formatColor(rect.color).c_str());
+      text += prefix + buffer;
+    } else if (op.kind == PaintKind::Text) {
+      const PaintText &run = texts[op.index];
+      std::snprintf(buffer, sizeof(buffer),
+                    "text x=%.1f baseline=%.1f size=%.1f color=%s \"%s\"\n", run.x, run.baseline,
+                    run.font.pixel_size, formatColor(run.color).c_str(), run.text.c_str());
+      text += prefix + buffer;
+    } else {
+      const PaintImage &image = images[op.index];
+      if (image.media_id != 0) {
+        std::snprintf(buffer, sizeof(buffer), "image x=%.1f y=%.1f w=%.1f h=%.1f media=%llu\n",
+                      image.x, image.y, image.width, image.height,
+                      (unsigned long long)image.media_id);
+      } else if (image.canvas_id != 0) {
+        std::snprintf(buffer, sizeof(buffer), "image x=%.1f y=%.1f w=%.1f h=%.1f canvas=%llu\n",
+                      image.x, image.y, image.width, image.height,
+                      (unsigned long long)image.canvas_id);
+      } else {
+        std::snprintf(buffer, sizeof(buffer), "image x=%.1f y=%.1f w=%.1f h=%.1f src=%s\n",
+                      image.x, image.y, image.width, image.height, image.src.c_str());
+      }
+      text += prefix + buffer;
+    }
   }
   return text;
 }

package/runtime/ext_gui/paint.h

@@ -6,13 +6,14 @@
  * the same list into triangles (rectangles) and glyph quads (text), and
  * diagnostics/tests can inspect it without a GPU.
  *
- * Rectangles and text are kept in separate lists: backgrounds/borders are drawn
- * first, then all text on top. That matches almost every static UI and lets the
- * renderer use one draw call per list instead of switching pipelines per shape.
- */
+ * Rectangles, text and images share one painter-order `ops` list, so a
+ * `z-index`ed child can paint over a sibling's background and an `overflow`
+ * clip applies to every shape in the subtree. Coordinates are viewport-
+ * relative. */
 #ifndef XT_GUI_PAINT_H
 #define XT_GUI_PAINT_H
 
+#include <cstdint>
 #include <string>
 #include <vector>
 
@@ -43,27 +44,56 @@ struct PaintText {
   FontSpec font;
 };
 
-/** An image to draw, scaled into the given rectangle (viewport-relative). */
+/** An image to draw, scaled into the given rectangle (viewport-relative).
+ * A non-zero `media_id` names a live `<video>` frame owned by the media
+ * subsystem; a non-zero `canvas_id` names a live `<canvas>` bitmap owned by the
+ * DOM; `src` is then empty and the renderer binds that subsystem's texture. */
 struct PaintImage {
   float x = 0;
   float y = 0;
   float width = 0;
   float height = 0;
   std::string src;
+  uint64_t media_id = 0;
+  uint64_t canvas_id = 0;
+};
+
+/** The clip rectangle in effect for a painted shape (viewport-relative logical
+ * pixels). `width <= 0` means "no clip". */
+struct PaintClip {
+  bool active = false;
+  float x = 0;
+  float y = 0;
+  float width = 0;
+  float height = 0;
+};
+
+enum class PaintKind { Rect, Text, Image };
+
+/** One entry in painter order: which kind of shape, its index in the matching
+ * payload vector, and the clip in effect. */
+struct PaintOp {
+  PaintKind kind = PaintKind::Rect;
+  uint32_t index = 0;
+  PaintClip clip;
 };
 
 struct DisplayList {
   std::vector<PaintRect> rects;
   std::vector<PaintText> texts;
   std::vector<PaintImage> images;
+  /** Shapes in painter order (backgrounds/borders first, then children, then
+   * stacked siblings), each with the clip rectangle that bounds it. */
+  std::vector<PaintOp> ops;
 
   void clear() {
     rects.clear();
     texts.clear();
     images.clear();
+    ops.clear();
   }
   bool empty() const { return rects.empty() && texts.empty() && images.empty(); }
-  /** Human-readable dump, one shape per line (for diagnostics/tests). */
+  /** Human-readable dump, one shape per line, in painter order (diagnostics/tests). */
   std::string dump() const;
 };
 

package/runtime/ext_gui/renderer.cpp

@@ -28,7 +28,6 @@ SDL_GPUGraphicsPipeline *g_image_pipeline = nullptr;
 SDL_GPUSampler *g_sampler = nullptr;
 int g_renderer_failed = 0;
 bool g_text_ok = false;
-std::vector<ImageBatch> g_image_batches;
 std::unordered_map<std::string, SDL_GPUTexture *> g_image_textures;
 SDL_GPUTexture *g_atlas_texture = nullptr;
 std::vector<unsigned char> g_atlas_mirror;
@@ -246,7 +245,6 @@ void xt_gui_renderer_destroy(SDL_GPUDevice *device) {
     if (entry.second != nullptr) SDL_ReleaseGPUTexture(device, entry.second);
   }
   g_image_textures.clear();
-  g_image_batches.clear();
   if (g_atlas_texture != nullptr) {
     SDL_ReleaseGPUTexture(device, g_atlas_texture);
     g_atlas_texture = nullptr;
@@ -277,21 +275,126 @@ void xt_gui_geometry_upload(SDL_GPUDevice *device, XtGuiGeometry *geometry,
   using namespace xtgui::renderer_detail;
   std::vector<Vertex> verts;
   verts.reserve(list.rects.size() * 6);
+  geometry->op_counts.assign(list.rects.size(), 6);
   for (const xtgui::PaintRect &rect : list.rects) pushRect(verts, rect);
   uploadVertices(device, geometry, verts.data(), (uint32_t)verts.size(), sizeof(Vertex));
 }
 
+void xt_gui_build_runs(XtGuiGeometry *shapes, XtGuiGeometry *texts, XtGuiGeometry *images,
+                       const xtgui::DisplayList &list) {
+  shapes->runs.clear();
+  uint32_t cursor[3] = {0, 0, 0};
+  for (const xtgui::PaintOp &op : list.ops) {
+    int pipeline = (int)op.kind;
+    XtGuiGeometry *geometry = pipeline == 0 ? shapes : (pipeline == 1 ? texts : images);
+    if (op.index >= geometry->op_counts.size()) continue;
+    uint32_t count = geometry->op_counts[op.index];
+    uint32_t first = cursor[pipeline];
+    cursor[pipeline] += count;
+    if (count == 0) continue;
+    SDL_GPUTexture *texture = nullptr;
+    if (pipeline == 2 && op.index < images->op_textures.size()) texture = images->op_textures[op.index];
+    float cx = op.clip.active ? op.clip.x : 0.0f;
+    float cy = op.clip.active ? op.clip.y : 0.0f;
+    float cw = op.clip.active ? op.clip.width : 0.0f;
+    float ch = op.clip.active ? op.clip.height : 0.0f;
+    if (!shapes->runs.empty()) {
+      XtGuiDrawRun &last = shapes->runs.back();
+      if (last.pipeline == pipeline && last.first + last.count == first && last.clip_x == cx &&
+          last.clip_y == cy && last.clip_width == cw && last.clip_height == ch &&
+          last.texture == texture) {
+        last.count += count;
+        continue;
+      }
+    }
+    XtGuiDrawRun run;
+    run.pipeline = pipeline;
+    run.first = first;
+    run.count = count;
+    run.clip_x = cx;
+    run.clip_y = cy;
+    run.clip_width = cw;
+    run.clip_height = ch;
+    run.texture = texture;
+    shapes->runs.push_back(run);
+  }
+}
+
 void xt_gui_renderer_draw(SDL_GPUCommandBuffer *cmd, SDL_GPURenderPass *pass,
-                          XtGuiGeometry *geometry, float viewport_width, float viewport_height) {
+                          XtGuiGeometry *shapes, XtGuiGeometry *texts, XtGuiGeometry *images,
+                          float viewport_width, float viewport_height, float pixel_density) {
   using namespace xtgui::renderer_detail;
-  if (g_pipeline == nullptr || geometry->buffer == nullptr || geometry->vertex_count == 0) return;
   if (viewport_width <= 0.0f || viewport_height <= 0.0f) return;
-  SDL_BindGPUGraphicsPipeline(pass, g_pipeline);
-  SDL_GPUBufferBinding binding;
-  binding.buffer = geometry->buffer;
-  binding.offset = 0;
-  SDL_BindGPUVertexBuffers(pass, 0, &binding, 1);
+  if (pixel_density <= 0.0f) pixel_density = 1.0f;
   float viewport[2] = {viewport_width, viewport_height};
   SDL_PushGPUVertexUniformData(cmd, 0, viewport, sizeof(viewport));
-  SDL_DrawGPUPrimitives(pass, geometry->vertex_count, 1, 0, 0);
+
+  int target_width = (int)(viewport_width * pixel_density + 0.5f);
+  int target_height = (int)(viewport_height * pixel_density + 0.5f);
+  for (const XtGuiDrawRun &run : shapes->runs) {
+    SDL_Rect scissor;
+    scissor.x = 0;
+    scissor.y = 0;
+    scissor.w = target_width;
+    scissor.h = target_height;
+    if (run.clip_width > 0.0f && run.clip_height > 0.0f) {
+      int x0 = (int)(run.clip_x * pixel_density);
+      int y0 = (int)(run.clip_y * pixel_density);
+      int x1 = (int)((run.clip_x + run.clip_width) * pixel_density + 0.5f);
+      int y1 = (int)((run.clip_y + run.clip_height) * pixel_density + 0.5f);
+      if (x0 < 0) x0 = 0;
+      if (y0 < 0) y0 = 0;
+      if (x1 > target_width) x1 = target_width;
+      if (y1 > target_height) y1 = target_height;
+      scissor.x = x0;
+      scissor.y = y0;
+      scissor.w = x1 > x0 ? x1 - x0 : 0;
+      scissor.h = y1 > y0 ? y1 - y0 : 0;
+    }
+    SDL_SetGPUScissor(pass, &scissor);
+
+    if (run.pipeline == XtGuiDrawRun::Shape) {
+      if (g_pipeline == nullptr || shapes->buffer == nullptr) continue;
+      SDL_BindGPUGraphicsPipeline(pass, g_pipeline);
+      SDL_GPUBufferBinding binding;
+      binding.buffer = shapes->buffer;
+      binding.offset = 0;
+      SDL_BindGPUVertexBuffers(pass, 0, &binding, 1);
+      SDL_DrawGPUPrimitives(pass, run.count, 1, run.first, 0);
+    } else if (run.pipeline == XtGuiDrawRun::Text) {
+      if (!g_text_ok || g_atlas_texture == nullptr || texts->buffer == nullptr) continue;
+      SDL_BindGPUGraphicsPipeline(pass, g_text_pipeline);
+      SDL_GPUBufferBinding binding;
+      binding.buffer = texts->buffer;
+      binding.offset = 0;
+      SDL_BindGPUVertexBuffers(pass, 0, &binding, 1);
+      SDL_GPUTextureSamplerBinding atlas_binding;
+      atlas_binding.texture = g_atlas_texture;
+      atlas_binding.sampler = g_sampler;
+      SDL_BindGPUFragmentSamplers(pass, 0, &atlas_binding, 1);
+      SDL_DrawGPUPrimitives(pass, run.count, 1, run.first, 0);
+    } else {
+      if (g_image_pipeline == nullptr || g_sampler == nullptr || images->buffer == nullptr ||
+          run.texture == nullptr)
+        continue;
+      SDL_BindGPUGraphicsPipeline(pass, g_image_pipeline);
+      SDL_GPUBufferBinding binding;
+      binding.buffer = images->buffer;
+      binding.offset = 0;
+      SDL_BindGPUVertexBuffers(pass, 0, &binding, 1);
+      SDL_GPUTextureSamplerBinding texture_binding;
+      texture_binding.texture = run.texture;
+      texture_binding.sampler = g_sampler;
+      SDL_BindGPUFragmentSamplers(pass, 0, &texture_binding, 1);
+      SDL_DrawGPUPrimitives(pass, run.count, 1, run.first, 0);
+    }
+  }
+
+  /* Restore the full-target scissor so the next frame starts clean. */
+  SDL_Rect full;
+  full.x = 0;
+  full.y = 0;
+  full.w = target_width;
+  full.h = target_height;
+  SDL_SetGPUScissor(pass, &full);
 }

package/runtime/ext_gui/renderer.h

@@ -22,17 +22,43 @@
 
 #include <SDL3/SDL.h>
 #include <cstdint>
+#include <vector>
 
 namespace xtgui {
 struct DisplayList;
 }
 
+/** One draw call in painter order: a contiguous range of vertices in one of the
+ * three pipelines, with the clip rectangle (logical pixels) that bounds it. A
+ * `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 };
+  int pipeline = Shape;
+  uint32_t first = 0;
+  uint32_t count = 0;
+  float clip_x = 0;
+  float clip_y = 0;
+  float clip_width = 0;
+  float clip_height = 0;
+  SDL_GPUTexture *texture = nullptr;
+};
+
 /** Per-window GPU geometry (vertex buffer + draw range). */
 struct XtGuiGeometry {
   SDL_GPUBuffer *buffer = nullptr;
   uint32_t capacity_bytes = 0;
   uint32_t vertex_count = 0;
   bool dirty = true;
+  /** Vertex count contributed by each shape of this pipeline's kind, aligned
+   * with the display list's payload vector (used to build the run list). */
+  std::vector<uint32_t> op_counts;
+  /** Texture for each image op, aligned with `DisplayList::images` (image
+   * geometry only). */
+  std::vector<SDL_GPUTexture *> op_textures;
+  /** 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;
 };
 
 /** Create the shared pipelines if needed. Returns false when the backend has no
@@ -47,22 +73,36 @@ void xt_gui_geometry_upload(SDL_GPUDevice *device, XtGuiGeometry *geometry,
                             const xtgui::DisplayList &list);
 /** Draw `geometry` inside an active render pass. */
 void xt_gui_renderer_draw(SDL_GPUCommandBuffer *cmd, SDL_GPURenderPass *pass,
-                          XtGuiGeometry *geometry, float viewport_width, float viewport_height);
+                          XtGuiGeometry *shapes, XtGuiGeometry *texts, XtGuiGeometry *images,
+                          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,
                         const xtgui::DisplayList &list, float scale);
-/** Draw the text geometry (glyph atlas bound) inside an active render pass. */
-void xt_gui_text_draw(SDL_GPUCommandBuffer *cmd, SDL_GPURenderPass *pass, XtGuiGeometry *geometry,
-                      float viewport_width, float viewport_height);
 /** Decode/upload `list.images` and build the image quad geometry (one batch per
- * texture). Textures are cached by source path. */
+ * texture). Textures are cached by source path and pixel size. `scale` is the
+ * device pixel density (1.0 = logical pixels) used to pick the rasterisation
+ * size of a vector source (SVG); raster sources decode at their intrinsic size. */
 void xt_gui_image_upload(SDL_GPUDevice *device, XtGuiGeometry *geometry,
-                         const xtgui::DisplayList &list);
-/** Draw the image geometry (binds each batch's texture) inside a render pass. */
-void xt_gui_image_draw(SDL_GPUCommandBuffer *cmd, SDL_GPURenderPass *pass, XtGuiGeometry *geometry,
-                       float viewport_width, float viewport_height);
+                         const xtgui::DisplayList &list, float scale);
 /** Release the image texture cache (after SDL_WaitForGPUIdle). */
 void xt_gui_image_textures_destroy(SDL_GPUDevice *device);
+/** Build the painter-order run list from the display list, using the per-op
+ * vertex counts and textures recorded by the three upload functions. Stores the
+ * result in `shapes->runs`. */
+void xt_gui_build_runs(XtGuiGeometry *shapes, XtGuiGeometry *texts, XtGuiGeometry *images,
+                       const xtgui::DisplayList &list);
+/** Re-upload the current decoded frame of every live `<video>` texture. Called
+ * once per frame, before the render command buffer, so the texture sampled by
+ * the draw already holds that frame. */
+void xt_gui_media_upload_frames(SDL_GPUDevice *device);
+/** Release one media texture (when a `<video>` is removed or navigated away). */
+void xt_gui_media_texture_release(SDL_GPUDevice *device, uint64_t media_id);
+/** Re-upload the current bitmap of every live `<canvas>` texture. Called once
+ * per frame, before the render command buffer, so a canvas animated from
+ * `requestAnimationFrame` reaches the screen without a relayout. */
+void xt_gui_canvas_upload_frames(SDL_GPUDevice *device);
+/** Release one canvas texture (when the canvas is dropped). */
+void xt_gui_canvas_texture_release(SDL_GPUDevice *device, uint64_t canvas_id);
 
 #endif /* XT_GUI_RENDERER_H */