xbintsc 0.5.42 → 0.5.45

package/runtime/ext_gui/paint.h

@@ -14,6 +14,7 @@
 #define XT_GUI_PAINT_H
 
 #include <cstdint>
+#include <memory>
 #include <string>
 #include <vector>
 
@@ -24,6 +25,35 @@
 
 namespace xtgui {
 
+/** One resolved colour stop of a gradient. `offset` is a fraction of the
+ * gradient line and non-decreasing, as in CSS. */
+struct GradientStop {
+  float offset = 0.0f;
+  Color color;
+};
+
+/** A radial `background-image` layer resolved by the paint pass: the renderer
+ * rasterises it into one RGBA texture and draws that as a single image quad.
+ *
+ * Nesting translucent bands instead composites every band's alpha once per band
+ * — each band covers the whole interior — so a vignette whose stops fade to
+ * `transparent` turns into an opaque disc that hides the scene behind it.
+ * Resolving the ramp per pixel composites it exactly once. */
+struct PaintGradient {
+  std::vector<GradientStop> stops;
+  /** Centre in box-local logical pixels; the drawn quad spans the whole box. */
+  float center_x = 0.0f;
+  float center_y = 0.0f;
+  float radius_x = 0.0f;
+  float radius_y = 0.0f;
+  /** `repeating-radial-gradient()`: the stop pattern restarts every `period`
+   * (the last stop's offset) instead of clamping at the outer ellipse. */
+  bool repeating = false;
+  float period = 1.0f;
+  /** Identity of the ramp (stops and geometry) for the renderer's texture cache. */
+  std::string key;
+};
+
 /** A solid, optionally rounded, rectangle. Coordinates are viewport-relative. */
 struct PaintRect {
   float x = 0;
@@ -71,6 +101,10 @@ struct PaintImage {
   /** Modulating colour for the image shader (white normally; a filter's
    * multiplicative effect may tint it). */
   Color tint{1.0f, 1.0f, 1.0f, 1.0f};
+  /** A `background-image` radial gradient: the renderer rasterises it into the
+   * quad instead of loading `src`/`svg`. Its stops already carry the colour
+   * functions of the filter chain; `tint` still carries brightness/opacity. */
+  std::shared_ptr<const PaintGradient> gradient;
 };
 
 /** One triangle of a clip path in device-space logical pixels. The paint pass
@@ -144,6 +178,18 @@ struct DisplayList {
   std::string dump() const;
 };
 
+namespace paint_detail {
+
+/** Interpolate a gradient's colour at `t` (a fraction of the gradient line; any
+ * value when `repeating`). Stops interpolate in premultiplied alpha, as CSS
+ * does, so a `transparent` stop does not darken the ramp towards an opaque
+ * colour; the result is converted back to straight alpha, which is what both the
+ * band and the texture paths blend. */
+Color gradientColorAt(const std::vector<GradientStop> &stops, bool repeating, float period,
+                      float t);
+
+}  // namespace paint_detail
+
 /** Build the display list for a laid-out tree and append it to `out`. The
  * viewport size resolves `vw`/`vh` units inside `clip-path` and shadows; pass 0
  * to take it from the root box's containing block. */

package/runtime/ext_gui/paint_background.cpp

@@ -1,18 +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
- * (64 while repeating) and 32 concentric ellipses for a radial one (64 while
- * repeating). 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 {
@@ -20,21 +24,60 @@ namespace paint_detail {
 
 namespace {
 
-struct ResolvedStop {
-  float offset = 0.0f;
-  Color color;
-};
+/** 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;
+    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<ResolvedStop> resolveStops(const BackgroundLayer &layer, float line_length,
+std::vector<GradientStop> resolveStops(const BackgroundLayer &layer, float line_length,
                                        const XtStyle &style, float viewportWidth,
                                        float viewportHeight) {
-  std::vector<ResolvedStop> stops;
+  std::vector<GradientStop> stops;
   for (const BackgroundGradientStop &stop : layer.stops) {
-    ResolvedStop resolved;
+    GradientStop resolved;
     resolved.color = stop.color;
     resolved.offset = -1.0f;
     if (stop.offset.unit == Unit::Percent) {
@@ -51,7 +94,7 @@ std::vector<ResolvedStop> resolveStops(const BackgroundLayer &layer, float line_
 
   /* Explicit offsets are non-decreasing, as in CSS. */
   float last = -1.0f;
-  for (ResolvedStop &stop : stops) {
+  for (GradientStop &stop : stops) {
     if (stop.offset < 0.0f) continue;
     if (stop.offset < last) stop.offset = last;
     last = stop.offset;
@@ -87,33 +130,6 @@ std::vector<ResolvedStop> resolveStops(const BackgroundLayer &layer, float line_
   return stops;
 }
 
-Color gradientColorAt(const std::vector<ResolvedStop> &stops, bool repeating, float t) {
-  if (stops.empty()) return Color();
-  /* A repeating gradient restarts its stop pattern at the last stop's offset. */
-  if (repeating) {
-    float period = stops.back().offset;
-    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 stops.back().color;
-}
-
 /** 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) {
@@ -160,11 +176,13 @@ void paintLinear(const LayoutBox &box, const XtStyle &style, const BackgroundLay
   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<ResolvedStop> stops = resolveStops(layer, line_length, style, viewportWidth,
+  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(stops, layer.repeating, 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) {
@@ -177,6 +195,18 @@ void paintLinear(const LayoutBox &box, const XtStyle &style, const BackgroundLay
   }
 }
 
+/** 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,
@@ -230,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,
@@ -267,18 +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;
-  std::vector<ResolvedStop> stops = resolveStops(layer, std::max(rx, ry), style, viewportWidth,
+  std::vector<GradientStop> stops = resolveStops(layer, std::max(rx, ry), style, viewportWidth,
                                                  viewportHeight);
-  const int bands = layer.repeating ? 64 : 32;
-  for (int i = bands; i >= 1; i--) {
-    float t = (float)i / (float)bands;
-    Color color = filterColor(chain, gradientColorAt(stops, layer.repeating, t));
-    if (color.a <= 0.0f) continue;
-    addEllipse(out, cx, cy, rx * t, ry * t, color, clip, box.world);
+  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);
+    }
+  }
+  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);
   }
-  /* Exact centre colour (the innermost band samples just off zero). */
-  Color center = filterColor(chain, gradientColorAt(stops, layer.repeating, 0.0f));
-  addEllipse(out, cx, cy, 0.6f, 0.6f, center, clip, box.world);
+  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,

package/runtime/ext_gui/renderer_gradient.cpp

@@ -0,0 +1,156 @@
+/*
+ * xbintsc GUI engine — radial `background-image` rasterisation.
+ *
+ * The shape pipeline fills one shape with one flat colour, and the bands a
+ * radial gradient used to be drawn as are nested ellipses: every band covers the
+ * whole interior, so each band's alpha composites over the previous ones and a
+ * vignette whose stops fade to `transparent` ends up opaque. The ramp is
+ * therefore resolved per pixel into an RGBA texture, which the image pipeline
+ * draws as one quad and composites exactly once.
+ */
+
+#include "renderer_internal.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cstdio>
+#include <string>
+#include <unordered_map>
+
+namespace xtgui {
+namespace renderer_detail {
+
+namespace {
+
+/** A rasterised gradient, keyed by the paint pass's cache key plus the logical
+ * box size. The texture is re-rasterised in place when the device pixel size
+ * changes (a DPI change), so a resized gradient never leaves a stale texture. */
+struct GradientTexture {
+  SDL_GPUTexture *texture = nullptr;
+  int width = 0;
+  int height = 0;
+  /** Set by the upload pass that draws this gradient; see `finishGradientUpload`. */
+  bool used = false;
+};
+
+std::unordered_map<std::string, GradientTexture> g_gradient_textures;
+
+/** How many rasterised gradients that are no longer drawn are kept. A gradient's
+ * stops can animate (a `hue-rotate` loop, say), which would otherwise rasterise a
+ * fresh texture every frame and never free the old ones. */
+constexpr size_t kMaxStaleGradients = 8;
+
+/** Largest texture edge a gradient is rasterised at. A radial ramp is smooth, so
+ * a larger box is rasterised smaller and stretched: the sampled colours are
+ * unchanged (the stretch is uniform), only the resolution of the ramp drops. */
+constexpr int kMaxGradientEdge = 1024;
+
+unsigned char byteOf(float value) {
+  if (!(value > 0.0f)) return 0;  // NaN and negatives
+  if (value > 1.0f) value = 1.0f;
+  return (unsigned char)(value * 255.0f + 0.5f);
+}
+
+/** Rasterise `gradient` into `out`: the box maps 1:1 onto the texture. The ramp
+ * covers the whole box — past the ending shape CSS keeps the last stop's colour
+ * rather than fading out — so there is no shape edge to antialias; the texels
+ * are sampled with linear filtering. */
+void rasterizeGradient(const PaintGradient &gradient, float logical_width, float logical_height,
+                       int pixel_width, int pixel_height, Image *out) {
+  out->width = pixel_width;
+  out->height = pixel_height;
+  out->pixels.assign((size_t)pixel_width * (size_t)pixel_height * 4u, 0);
+  const float pixel_x = logical_width / (float)pixel_width;  // logical px per texel
+  const float pixel_y = logical_height / (float)pixel_height;
+  const float inv_rx = 1.0f / gradient.radius_x;
+  const float inv_ry = 1.0f / gradient.radius_y;
+  for (int y = 0; y < pixel_height; y++) {
+    const float local_y = ((float)y + 0.5f) * pixel_y;
+    unsigned char *row = out->pixels.data() + (size_t)y * (size_t)pixel_width * 4u;
+    for (int x = 0; x < pixel_width; x++) {
+      const float local_x = ((float)x + 0.5f) * pixel_x;
+      const float u = (local_x - gradient.center_x) * inv_rx;
+      const float v = (local_y - gradient.center_y) * inv_ry;
+      const float t = std::sqrt(u * u + v * v);
+      Color color =
+          paint_detail::gradientColorAt(gradient.stops, gradient.repeating, gradient.period, t);
+      if (color.a <= 0.0f) continue;
+      unsigned char *texel = row + (size_t)x * 4u;
+      texel[0] = byteOf(color.r);
+      texel[1] = byteOf(color.g);
+      texel[2] = byteOf(color.b);
+      texel[3] = byteOf(color.a);
+    }
+  }
+}
+
+/** The device size a gradient of `pixel_width` x `pixel_height` is rasterised at,
+ * preserving its aspect ratio under `kMaxGradientEdge`. */
+void rasterSize(int pixel_width, int pixel_height, int *width, int *height) {
+  *width = std::max(1, pixel_width);
+  *height = std::max(1, pixel_height);
+  if (*width <= kMaxGradientEdge && *height <= kMaxGradientEdge) return;
+  float shrink = (float)kMaxGradientEdge / (float)std::max(*width, *height);
+  *width = std::max(1, (int)((float)*width * shrink + 0.5f));
+  *height = std::max(1, (int)((float)*height * shrink + 0.5f));
+}
+
+}  // namespace
+
+void beginGradientUpload() {
+  for (auto &entry : g_gradient_textures) entry.second.used = false;
+}
+
+void finishGradientUpload(SDL_GPUDevice *device) {
+  if (g_gradient_textures.size() <= kMaxStaleGradients) return;
+  /* The display list of the frame being built may hold pointers to the textures
+   * it used, so only gradients it did *not* use can go. */
+  for (auto it = g_gradient_textures.begin(); it != g_gradient_textures.end();) {
+    if (it->second.used) {
+      ++it;
+      continue;
+    }
+    if (it->second.texture != nullptr) SDL_ReleaseGPUTexture(device, it->second.texture);
+    it = g_gradient_textures.erase(it);
+  }
+}
+
+SDL_GPUTexture *ensureGradientTexture(SDL_GPUDevice *device, const xtgui::PaintImage &image,
+                                      int pixel_width, int pixel_height, XtGuiUploadBatch *batch) {
+  if (image.gradient == nullptr || image.width <= 0.0f || image.height <= 0.0f) return nullptr;
+  const xtgui::PaintGradient &gradient = *image.gradient;
+  if (gradient.radius_x <= 0.0f || gradient.radius_y <= 0.0f || gradient.stops.size() < 2) {
+    return nullptr;
+  }
+  int width = 0;
+  int height = 0;
+  rasterSize(pixel_width, pixel_height, &width, &height);
+  /* The key carries the ramp, its geometry and the logical box size: two boxes
+   * of different sizes can resolve the same px radius but not the same picture. */
+  char box[64];
+  std::snprintf(box, sizeof(box), "@%.3f,%.3f", image.width, image.height);
+  std::string key = gradient.key + box;
+  GradientTexture &entry = g_gradient_textures[key];
+  entry.used = true;
+  if (entry.texture != nullptr && entry.width == width && entry.height == height) {
+    return entry.texture;
+  }
+  Image raster;
+  rasterizeGradient(gradient, image.width, image.height, width, height, &raster);
+  SDL_GPUTexture *texture = createImageTexture(device, raster, batch);
+  if (entry.texture != nullptr) SDL_ReleaseGPUTexture(device, entry.texture);
+  entry.texture = texture;
+  entry.width = texture != nullptr ? width : 0;
+  entry.height = texture != nullptr ? height : 0;
+  return texture;
+}
+
+void releaseGradientTextures(SDL_GPUDevice *device) {
+  for (auto &entry : g_gradient_textures) {
+    if (entry.second.texture != nullptr) SDL_ReleaseGPUTexture(device, entry.second.texture);
+  }
+  g_gradient_textures.clear();
+}
+
+}  // namespace renderer_detail
+}  // namespace xtgui

package/runtime/ext_gui/renderer_image.cpp

@@ -379,6 +379,7 @@ void xt_gui_image_upload(SDL_GPUDevice *device, XtGuiGeometry *geometry,
   full.v0 = 0.0f;
   full.u1 = 1.0f;
   full.v1 = 1.0f;
+  beginGradientUpload();
   for (const xtgui::PaintOp &op : list.ops) {
     if (op.kind != xtgui::PaintKind::Image || op.index >= list.images.size()) continue;
     const xtgui::PaintImage &image = list.images[op.index];
@@ -390,7 +391,9 @@ void xt_gui_image_upload(SDL_GPUDevice *device, XtGuiGeometry *geometry,
     if (pixel_width < 1) pixel_width = 1;
     if (pixel_height < 1) pixel_height = 1;
     SDL_GPUTexture *texture = nullptr;
-    if (image.canvas_id != 0) {
+    if (image.gradient != nullptr) {
+      texture = ensureGradientTexture(device, image, pixel_width, pixel_height, batch);
+    } else if (image.canvas_id != 0) {
       texture = ensureCanvasTexture(device, image.canvas_id, batch);
     } else if (image.media_id != 0) {
       texture = ensureMediaTexture(device, image.media_id, batch);
@@ -405,11 +408,13 @@ void xt_gui_image_upload(SDL_GPUDevice *device, XtGuiGeometry *geometry,
     geometry->op_counts[op.index] = count;
     geometry->op_textures[op.index] = texture;
   }
+  finishGradientUpload(device);
   uploadVertices(device, geometry, verts.data(), (uint32_t)verts.size(), sizeof(TextVertex), batch);
 }
 
 void xt_gui_image_textures_destroy(SDL_GPUDevice *device) {
   using namespace xtgui::renderer_detail;
+  releaseGradientTextures(device);
   for (auto &entry : g_image_textures) {
     if (entry.second != nullptr) SDL_ReleaseGPUTexture(device, entry.second);
   }

package/runtime/ext_gui/renderer_internal.h

@@ -14,6 +14,7 @@
 #include <unordered_map>
 #include <vector>
 
+#include "image.h"
 #include "paint.h"
 #include "renderer.h"
 
@@ -147,6 +148,10 @@ void layerRendererDestroy(SDL_GPUDevice *device);
 /* -- images --------------------------------------------------------------- */
 
 SDL_GPUGraphicsPipeline *createImagePipeline(SDL_GPUDevice *device, SDL_Window *reference);
+/** Create an RGBA texture holding `image` and upload its pixels. Returns null
+ * (after reporting the SDL error) when either step fails. */
+SDL_GPUTexture *createImageTexture(SDL_GPUDevice *device, const xtgui::Image &image,
+                                   XtGuiUploadBatch *batch);
 /** Decode `src` (cached) and upload it as an RGBA texture. `pixel_width` /
  * `pixel_height` are the drawn size in device pixels; vector sources (SVG) are
  * rasterised at that size, raster sources ignore it. The texture cache is keyed
@@ -154,6 +159,23 @@ SDL_GPUGraphicsPipeline *createImagePipeline(SDL_GPUDevice *device, SDL_Window *
 SDL_GPUTexture *ensureImageTexture(SDL_GPUDevice *device, const std::string &src, int pixel_width,
                                    int pixel_height, XtGuiUploadBatch *batch);
 
+/* -- background gradients ------------------------------------------------- */
+
+/** Rasterise a `PaintImage` radial gradient into an RGBA texture and cache it by
+ * the paint pass's key. The ramp is resolved per device pixel, so a translucent
+ * gradient composites once instead of once per band. Bracket a frame's uploads
+ * with `beginGradientUpload`/`finishGradientUpload` so textures the frame no
+ * longer draws can be reclaimed; returns null when it cannot be created. */
+SDL_GPUTexture *ensureGradientTexture(SDL_GPUDevice *device, const xtgui::PaintImage &image,
+                                      int pixel_width, int pixel_height, XtGuiUploadBatch *batch);
+/** Mark every cached gradient unused; `ensureGradientTexture` marks the ones the
+ * upload pass draws. */
+void beginGradientUpload();
+/** Release cached gradients the pass did not draw, keeping the cache bounded. */
+void finishGradientUpload(SDL_GPUDevice *device);
+/** Release every rasterised gradient texture. */
+void releaseGradientTextures(SDL_GPUDevice *device);
+
 }  // namespace renderer_detail
 }  // namespace xtgui
 

package/runtime/ext_gui/window.cpp

@@ -413,7 +413,8 @@ static xt_value win_hit_test(xt_value self, xt_value env, int32_t argc, xt_value
 /** Test/debug hook: synthesise an input event and deliver it to handlers.
  * `win.sendEvent("click", { x, y, button, clicks })`,
  * `win.sendEvent("wheel", { x, y, deltaX, deltaY })` or
- * `win.sendEvent("keydown", { key, code })`. */
+ * `win.sendEvent("keydown", { key, code })`. A key event may instead name the
+ * SDL `scancode`/`keycode` plus modifiers to exercise a real-keyboard path. */
 static xt_value win_send_event(xt_value self, xt_value env, int32_t argc, xt_value *argv) {
   (void)env;
   XtGuiWindow *win = xt_gui_window_from_this(self);
@@ -439,6 +440,14 @@ static xt_value win_send_event(xt_value self, xt_value env, int32_t argc, xt_val
     return XT_TRUE;
   }
   if (name == "keydown" || name == "keyup") {
+    if (XT_IS_OBJECT(options) && XT_IS_NUMBER(xt_object_get_cstr(options, "scancode"))) {
+      int scancode = (int)xt_gui_number_or(xt_object_get_cstr(options, "scancode"), 0);
+      int keycode = (int)xt_gui_number_or(xt_object_get_cstr(options, "keycode"), 0);
+      auto flag = [options](const char *key) { return xt_truthy(xt_object_get_cstr(options, key)); };
+      xt_gui_dispatch_physical_key(win, type, scancode, keycode, flag("repeat"), flag("ctrl"),
+                                   flag("shift"), flag("alt"), flag("meta"), flag("caps"));
+      return XT_TRUE;
+    }
     const char *key = "";
     const char *code = "";
     if (XT_IS_OBJECT(options)) {

package/src/driver/version.ts

@@ -9,4 +9,4 @@
  * `main`/`master` only (see `.githooks/pre-commit`), so feature branches never
  * change this line and merging two of them cannot conflict here.
  */
-export const COMPILER_VERSION = "0.5.42";
+export const COMPILER_VERSION = "0.5.45";