xbintsc 0.5.51 → 0.6.8

package/runtime/ext_gui/renderer_backdrop.cpp

@@ -0,0 +1,374 @@
+/*
+ * xbintsc GUI engine — `backdrop-filter` compositor.
+ *
+ * The backdrop is the scene painted before the element, which only the renderer
+ * sees. `drawBackdropPass` samples a copy of that scene (the caller ping-pongs a
+ * scratch scene texture), applies the Gaussian and the combined colour matrix in
+ * one runtime-compiled shader, and writes the result back through the element's
+ * rounded border-box mask. Split from `renderer_layer.cpp` so the blend
+ * compositor and this one stay independently readable.
+ */
+
+#include "renderer_internal.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cstdio>
+#include <cstring>
+#include <string>
+#include <vector>
+
+#include "gpu_shader_api.h"
+#include "perf.h"
+#include "webgl_glsl.h"
+
+namespace xtgui {
+namespace renderer_detail {
+
+namespace {
+
+/** Compile one GLSL stage into the format this device consumes. Mirrors the
+ * helper in `renderer_layer.cpp`; both shaders are compiled at run time because
+ * they are not part of the precompiled WebGL blobs. */
+bool prepareStage(const std::string &source, bool fragment, SDL_GPUShaderFormat formats,
+                  std::vector<uint32_t> *spirv, std::string *text, const Uint8 **code,
+                  size_t *code_size, std::string *entry, std::string *log) {
+  const GpuShaderApi *api = gpu_shader_api();
+  if (api == nullptr) {
+    *log = "shader translation was not linked (the 'gpu' link feature is inactive)";
+    return false;
+  }
+  GlslShaderInfo info;
+  api->scan_glsl(source, fragment, &info);
+  if (!info.unsupported.empty()) {
+    *log = info.unsupported;
+    return false;
+  }
+  GlslLinkLayout layout;
+  layout.varyings["v_uv"] = 0;
+  if (fragment) {
+    layout.samplers["u_backdrop"] = 0;
+    layout.block_members = info.uniforms;
+  }
+  const std::string rewritten = api->rewrite_glsl(source, fragment, layout, info);
+  if (!api->compile_glsl(rewritten, fragment, spirv, log)) return false;
+
+  if ((formats & SDL_GPU_SHADERFORMAT_MSL) != 0) {
+    if (!api->cross_compile_msl(*spirv, fragment, text, entry, log)) return false;
+    *code = (const Uint8 *)text->data();
+    *code_size = text->size();
+    return true;
+  }
+  if ((formats & SDL_GPU_SHADERFORMAT_SPIRV) != 0) {
+    *code = (const Uint8 *)spirv->data();
+    *code_size = spirv->size() * sizeof(uint32_t);
+    *entry = "main";
+    return true;
+  }
+  *log = "this GPU backend consumes neither Metal nor Vulkan shaders";
+  return false;
+}
+
+// `v_uv` comes from the shared full-screen vertex shader.
+const char *const kBlendVS = R"GLSL(#version 300 es
+precision highp float;
+
+out vec2 v_uv;
+
+void main() {
+  vec2 corners[6] = vec2[6](vec2(-1.0, -1.0), vec2(1.0, -1.0), vec2(-1.0, 1.0),
+                            vec2(1.0, -1.0), vec2(1.0, 1.0), vec2(-1.0, 1.0));
+  vec2 p = corners[gl_VertexIndex];
+  v_uv = vec2(p.x * 0.5 + 0.5, 0.5 - p.y * 0.5);
+  gl_Position = vec4(p, 0.0, 1.0);
+}
+)GLSL";
+
+/* `backdrop-filter`: samples the scene painted so far with a separable-looking
+ * 13x13 Gaussian (taps spread to cover sigma) and one combined colour matrix,
+ * then masks the result to the element's rounded border box. The scene has
+ * already been copied to the sampled texture by a copy pass, so this shader
+ * never reads the target it writes. */
+const char *const kBackdropFS = R"GLSL(#version 300 es
+precision highp float;
+
+in vec2 v_uv;
+uniform sampler2D u_backdrop;
+uniform vec4 u_rect;     // x, y, width, height in target pixels
+uniform vec4 u_mask;     // corner radius, sigma, target width, target height
+uniform vec4 u_texel;    // 1/target width, 1/target height
+uniform vec4 u_row0;     // colour matrix row 0 + offset
+uniform vec4 u_row1;
+uniform vec4 u_row2;
+uniform vec4 u_extra;    // alpha multiplier
+out vec4 fragColor;
+
+float roundedRectDistance(vec2 point, vec4 rect, float radius) {
+  vec2 half_size = rect.zw * 0.5;
+  vec2 centre = rect.xy + half_size;
+  radius = min(radius, min(half_size.x, half_size.y));
+  vec2 q = abs(point - centre) - (half_size - vec2(radius));
+  return min(max(q.x, q.y), 0.0) + length(max(q, vec2(0.0))) - radius;
+}
+
+void main() {
+  float sigma = u_mask.y;
+  vec4 sampled;
+  if (sigma > 0.05) {
+    float step = max(1.0, sigma * 3.0 / 6.0);
+    float total = 0.0;
+    vec4 sum = vec4(0.0);
+    for (int y = -6; y <= 6; y++) {
+      for (int x = -6; x <= 6; x++) {
+        float distance2 = float(x * x + y * y) * step * step;
+        float weight = exp(-distance2 / (2.0 * sigma * sigma));
+        vec4 texel = texture(u_backdrop, v_uv + vec2(float(x), float(y)) * step * u_texel.xy);
+        /* Premultiply before averaging: blurring straight alpha would pull
+         * transparent black into the edges of a shape. */
+        sum += vec4(texel.rgb * texel.a, texel.a) * weight;
+        total += weight;
+      }
+    }
+    vec4 blended = sum / total;
+    sampled = vec4(blended.a > 0.00001 ? blended.rgb / blended.a : vec3(0.0), blended.a);
+  } else {
+    sampled = texture(u_backdrop, v_uv);
+  }
+  vec3 rgb = sampled.rgb;
+  vec3 filtered = vec3(dot(u_row0.xyz, rgb) + u_row0.w,
+                       dot(u_row1.xyz, rgb) + u_row1.w,
+                       dot(u_row2.xyz, rgb) + u_row2.w);
+  filtered = clamp(filtered, 0.0, 1.0);
+  vec2 position = vec2(v_uv.x * u_mask.z, v_uv.y * u_mask.w);
+  float distance = roundedRectDistance(position, u_rect, u_mask.x);
+  float coverage = clamp(0.5 - distance, 0.0, 1.0);
+  if (coverage <= 0.0) discard;
+  fragColor = vec4(filtered, clamp(sampled.a, 0.0, 1.0) * u_extra.x * coverage);
+}
+)GLSL";
+
+}  // namespace
+
+SDL_GPUGraphicsPipeline *g_backdrop_pipeline = nullptr;
+SDL_GPUSampler *g_backdrop_sampler = nullptr;
+bool g_backdrop_failed = false;
+
+bool ensureBackdropPipeline(SDL_GPUDevice *device) {
+  if (g_backdrop_pipeline != nullptr) return true;
+  if (g_backdrop_failed) return false;
+  if (device == nullptr || g_swapchain_format == SDL_GPU_TEXTUREFORMAT_INVALID) return false;
+  const SDL_GPUTextureUsageFlags usage =
+      SDL_GPU_TEXTUREUSAGE_SAMPLER | SDL_GPU_TEXTUREUSAGE_COLOR_TARGET;
+  if (!SDL_GPUTextureSupportsFormat(device, g_swapchain_format, SDL_GPU_TEXTURETYPE_2D, usage)) {
+    g_backdrop_failed = true;
+    return false;
+  }
+  const SDL_GPUShaderFormat formats = SDL_GetGPUShaderFormats(device);
+  if ((formats & (SDL_GPU_SHADERFORMAT_MSL | SDL_GPU_SHADERFORMAT_SPIRV)) == 0) {
+    g_backdrop_failed = true;
+    return false;
+  }
+
+  std::string log;
+  std::vector<uint32_t> vs_spirv;
+  std::vector<uint32_t> fs_spirv;
+  std::string vs_text;
+  std::string fs_text;
+  const Uint8 *vs_code = nullptr;
+  const Uint8 *fs_code = nullptr;
+  size_t vs_size = 0;
+  size_t fs_size = 0;
+  std::string vs_entry;
+  std::string fs_entry;
+  if (!prepareStage(kBlendVS, false, formats, &vs_spirv, &vs_text, &vs_code, &vs_size, &vs_entry,
+                    &log) ||
+      !prepareStage(kBackdropFS, true, formats, &fs_spirv, &fs_text, &fs_code, &fs_size,
+                    &fs_entry, &log)) {
+    fprintf(stderr, "xt_gui: backdrop-filter shader unavailable: %s\n", log.c_str());
+    g_backdrop_failed = true;
+    return false;
+  }
+
+  const SDL_GPUShaderFormat shader_format =
+      (formats & SDL_GPU_SHADERFORMAT_MSL) != 0 ? SDL_GPU_SHADERFORMAT_MSL
+                                                : SDL_GPU_SHADERFORMAT_SPIRV;
+  SDL_GPUShaderCreateInfo vs_info;
+  std::memset(&vs_info, 0, sizeof(vs_info));
+  vs_info.code_size = vs_size;
+  vs_info.code = vs_code;
+  vs_info.entrypoint = vs_entry.c_str();
+  vs_info.format = shader_format;
+  vs_info.stage = SDL_GPU_SHADERSTAGE_VERTEX;
+  SDL_GPUShader *vs = SDL_CreateGPUShader(device, &vs_info);
+
+  SDL_GPUShaderCreateInfo fs_info;
+  std::memset(&fs_info, 0, sizeof(fs_info));
+  fs_info.code_size = fs_size;
+  fs_info.code = fs_code;
+  fs_info.entrypoint = fs_entry.c_str();
+  fs_info.format = shader_format;
+  fs_info.stage = SDL_GPU_SHADERSTAGE_FRAGMENT;
+  fs_info.num_uniform_buffers = 1;
+  fs_info.num_samplers = 1;
+  SDL_GPUShader *fs = SDL_CreateGPUShader(device, &fs_info);
+
+  if (vs == nullptr || fs == nullptr) {
+    fprintf(stderr, "xt_gui: backdrop-filter shader creation failed: %s\n", SDL_GetError());
+    if (vs != nullptr) SDL_ReleaseGPUShader(device, vs);
+    if (fs != nullptr) SDL_ReleaseGPUShader(device, fs);
+    g_backdrop_failed = true;
+    return false;
+  }
+
+  SDL_GPUColorTargetDescription target;
+  std::memset(&target, 0, sizeof(target));
+  target.format = g_swapchain_format;
+  target.blend_state.enable_blend = true;
+  target.blend_state.src_color_blendfactor = SDL_GPU_BLENDFACTOR_SRC_ALPHA;
+  target.blend_state.dst_color_blendfactor = SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA;
+  target.blend_state.color_blend_op = SDL_GPU_BLENDOP_ADD;
+  target.blend_state.src_alpha_blendfactor = SDL_GPU_BLENDFACTOR_ONE;
+  target.blend_state.dst_alpha_blendfactor = SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA;
+  target.blend_state.alpha_blend_op = SDL_GPU_BLENDOP_ADD;
+
+  SDL_GPUGraphicsPipelineCreateInfo info;
+  std::memset(&info, 0, sizeof(info));
+  info.vertex_shader = vs;
+  info.fragment_shader = fs;
+  info.primitive_type = SDL_GPU_PRIMITIVETYPE_TRIANGLELIST;
+  info.rasterizer_state.fill_mode = SDL_GPU_FILLMODE_FILL;
+  info.rasterizer_state.cull_mode = SDL_GPU_CULLMODE_NONE;
+  info.rasterizer_state.front_face = SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE;
+  info.multisample_state.sample_count = SDL_GPU_SAMPLECOUNT_1;
+  info.target_info.color_target_descriptions = &target;
+  info.target_info.num_color_targets = 1;
+  g_backdrop_pipeline = SDL_CreateGPUGraphicsPipeline(device, &info);
+  SDL_ReleaseGPUShader(device, vs);
+  SDL_ReleaseGPUShader(device, fs);
+  if (g_backdrop_pipeline == nullptr) {
+    fprintf(stderr, "xt_gui: backdrop-filter pipeline creation failed: %s\n", SDL_GetError());
+    g_backdrop_failed = true;
+    return false;
+  }
+
+  SDL_GPUSamplerCreateInfo sampler_info;
+  std::memset(&sampler_info, 0, sizeof(sampler_info));
+  sampler_info.min_filter = SDL_GPU_FILTER_LINEAR;
+  sampler_info.mag_filter = SDL_GPU_FILTER_LINEAR;
+  sampler_info.mipmap_mode = SDL_GPU_SAMPLERMIPMAPMODE_NEAREST;
+  sampler_info.address_mode_u = SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE;
+  sampler_info.address_mode_v = SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE;
+  sampler_info.address_mode_w = SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE;
+  g_backdrop_sampler = SDL_CreateGPUSampler(device, &sampler_info);
+  if (g_backdrop_sampler == nullptr) {
+    fprintf(stderr, "xt_gui: backdrop-filter sampler creation failed: %s\n", SDL_GetError());
+    SDL_ReleaseGPUGraphicsPipeline(device, g_backdrop_pipeline);
+    g_backdrop_pipeline = nullptr;
+    g_backdrop_failed = true;
+    return false;
+  }
+  return true;
+}
+
+struct BackdropParams {
+  float rect[4];
+  float mask[4];
+  float texel[4];
+  float row0[4];
+  float row1[4];
+  float row2[4];
+  float extra[4];
+};
+
+/** Filter `source` (the scene painted so far) into the active target only
+ * inside the element's rounded rect. The target already holds the same scene,
+ * so the fragment's source-over blend replaces the region with the filtered
+ * version while leaving rounded-corner coverage to antialias the edge. */
+void drawBackdropPass(SDL_GPUCommandBuffer *cmd, SDL_GPURenderPass *pass,
+                      SDL_GPUTexture *source, const DisplayList &list,
+                      const XtGuiDrawRun &run, int target_width, int target_height,
+                      float pixel_density) {
+  if (cmd == nullptr || pass == nullptr || source == nullptr ||
+      g_backdrop_pipeline == nullptr || g_backdrop_sampler == nullptr)
+    return;
+  if (run.backdrop >= list.backdrops.size()) return;
+  const xtgui::PaintBackdrop &backdrop = list.backdrops[run.backdrop];
+  if (backdrop.width <= 0.0f || backdrop.height <= 0.0f) return;
+
+  const float density = pixel_density;
+  float left = backdrop.x * density;
+  float top = backdrop.y * density;
+  float right = (backdrop.x + backdrop.width) * density;
+  float bottom = (backdrop.y + backdrop.height) * density;
+  if (run.clip_width > 0.0f && run.clip_height > 0.0f) {
+    left = std::max(left, run.clip_x * density);
+    top = std::max(top, run.clip_y * density);
+    right = std::min(right, (run.clip_x + run.clip_width) * density);
+    bottom = std::min(bottom, (run.clip_y + run.clip_height) * density);
+  }
+  int x0 = (int)std::floor(left);
+  int y0 = (int)std::floor(top);
+  int x1 = (int)std::ceil(right);
+  int y1 = (int)std::ceil(bottom);
+  if (x0 < 0) x0 = 0;
+  if (y0 < 0) y0 = 0;
+  if (x1 > target_width) x1 = target_width;
+  if (y1 > target_height) y1 = target_height;
+  if (x1 <= x0 || y1 <= y0) return;
+
+  SDL_BindGPUGraphicsPipeline(pass, g_backdrop_pipeline);
+  SDL_GPUTextureSamplerBinding binding;
+  binding.texture = source;
+  binding.sampler = g_backdrop_sampler;
+  SDL_BindGPUFragmentSamplers(pass, 0, &binding, 1);
+
+  BackdropParams params;
+  std::memset(&params, 0, sizeof(params));
+  params.rect[0] = backdrop.x * density;
+  params.rect[1] = backdrop.y * density;
+  params.rect[2] = backdrop.width * density;
+  params.rect[3] = backdrop.height * density;
+  params.mask[0] = backdrop.radius * density;
+  params.mask[1] = backdrop.blur * density;
+  params.mask[2] = (float)target_width;
+  params.mask[3] = (float)target_height;
+  params.texel[0] = 1.0f / (float)target_width;
+  params.texel[1] = 1.0f / (float)target_height;
+  for (int i = 0; i < 3; i++) {
+    params.row0[i] = backdrop.color[i];
+    params.row1[i] = backdrop.color[3 + i];
+    params.row2[i] = backdrop.color[6 + i];
+  }
+  params.row0[3] = backdrop.offset[0];
+  params.row1[3] = backdrop.offset[1];
+  params.row2[3] = backdrop.offset[2];
+  params.extra[0] = backdrop.alpha;
+  SDL_PushGPUFragmentUniformData(cmd, 0, &params, sizeof(params));
+
+  SDL_Rect scissor;
+  scissor.x = x0;
+  scissor.y = y0;
+  scissor.w = x1 - x0;
+  scissor.h = y1 - y0;
+  SDL_SetGPUScissor(pass, &scissor);
+  SDL_DrawGPUPrimitives(pass, 6, 1, 0, 0);
+  xtgui::g_perf_frame.drawCalls += 1;
+}
+
+
+bool backdropRendererReady(SDL_GPUDevice *device) { return ensureBackdropPipeline(device); }
+
+void backdropRendererDestroy(SDL_GPUDevice *device) {
+  if (g_backdrop_pipeline != nullptr) {
+    SDL_ReleaseGPUGraphicsPipeline(device, g_backdrop_pipeline);
+    g_backdrop_pipeline = nullptr;
+  }
+  if (g_backdrop_sampler != nullptr) {
+    SDL_ReleaseGPUSampler(device, g_backdrop_sampler);
+    g_backdrop_sampler = nullptr;
+  }
+  g_backdrop_failed = false;
+}
+
+}  // namespace renderer_detail
+}  // namespace xtgui

package/runtime/ext_gui/renderer_bitmap.cpp

@@ -0,0 +1,82 @@
+/*
+ * xbintsc GUI engine — renderer textures for CPU-rasterised shadows.
+ *
+ * `paint_shadow.cpp` produces the blurred RGBA mask; this file uploads it once
+ * and caches the GPU texture by the mask's paint key. A shadow whose colour
+ * changes (the common animation) reuses the same mask and only the draw's tint
+ * differs, so the expensive rasterisation and upload happen on the first frame.
+ */
+
+#include "renderer_internal.h"
+
+#include <cstdio>
+#include <string>
+#include <unordered_map>
+
+namespace xtgui {
+namespace renderer_detail {
+
+namespace {
+
+struct ShadowTexture {
+  SDL_GPUTexture *texture = nullptr;
+  int width = 0;
+  int height = 0;
+  bool used = false;
+};
+
+std::unordered_map<std::string, ShadowTexture> g_shadow_textures;
+
+/** Keep a few stale masks for animated shadows that change shape every frame;
+ * the rest are released as soon as a paint pass stops drawing them. */
+constexpr size_t kMaxStaleShadowTextures = 16;
+
+}  // namespace
+
+void beginBitmapUpload() {
+  for (auto &entry : g_shadow_textures) entry.second.used = false;
+}
+
+void finishBitmapUpload(SDL_GPUDevice *device) {
+  if (g_shadow_textures.size() <= kMaxStaleShadowTextures) return;
+  for (auto it = g_shadow_textures.begin(); it != g_shadow_textures.end();) {
+    if (it->second.used) {
+      ++it;
+      continue;
+    }
+    if (it->second.texture != nullptr) SDL_ReleaseGPUTexture(device, it->second.texture);
+    it = g_shadow_textures.erase(it);
+  }
+}
+
+SDL_GPUTexture *ensureBitmapTexture(SDL_GPUDevice *device, const xtgui::PaintBitmap &bitmap,
+                                    XtGuiUploadBatch *batch) {
+  if (bitmap.width <= 0 || bitmap.height <= 0 || bitmap.pixels.empty()) return nullptr;
+  std::string key = bitmap.key + "#" + std::to_string(bitmap.width) + "x" +
+                    std::to_string(bitmap.height);
+  ShadowTexture &entry = g_shadow_textures[key];
+  entry.used = true;
+  if (entry.texture != nullptr && entry.width == bitmap.width && entry.height == bitmap.height) {
+    return entry.texture;
+  }
+  xtgui::Image image;
+  image.width = bitmap.width;
+  image.height = bitmap.height;
+  image.pixels = bitmap.pixels;
+  SDL_GPUTexture *texture = createImageTexture(device, image, batch);
+  if (entry.texture != nullptr) SDL_ReleaseGPUTexture(device, entry.texture);
+  entry.texture = texture;
+  entry.width = texture != nullptr ? bitmap.width : 0;
+  entry.height = texture != nullptr ? bitmap.height : 0;
+  return texture;
+}
+
+void releaseBitmapTextures(SDL_GPUDevice *device) {
+  for (auto &entry : g_shadow_textures) {
+    if (entry.second.texture != nullptr) SDL_ReleaseGPUTexture(device, entry.second.texture);
+  }
+  g_shadow_textures.clear();
+}
+
+}  // namespace renderer_detail
+}  // namespace xtgui

package/runtime/ext_gui/renderer_gradient.cpp

@@ -40,21 +40,28 @@ std::unordered_map<std::string, GradientTexture> g_gradient_textures;
  * 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
+/** Largest texture edge a gradient is rasterised at. A 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;
 
+/** The same cap for a linear ramp, which is one texel thick across its line and
+ * therefore cheap at any length. A hairline stop (`calc(100% - 1px)`) wants the
+ * full device resolution of a wide window, so the 2D cap would soften it. */
+constexpr int kMaxLinearGradientEdge = 4096;
+
 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. */
+/** Rasterise `gradient` into `out`: the box maps 1:1 onto the texture (the
+ * caller may have shrunk one axis, see `rasterSize`). The ramp covers the whole
+ * box — past the last stop CSS holds that colour rather than fading out — so
+ * there is no shape edge to antialias; the texels are sampled with linear
+ * filtering. A linear ramp is constant across the gradient line, so a walk
+ * along it is one row (or one column) of texels rather than a full box. */
 void rasterizeGradient(const PaintGradient &gradient, float logical_width, float logical_height,
                        int pixel_width, int pixel_height, Image *out) {
   out->width = pixel_width;
@@ -62,16 +69,29 @@ void rasterizeGradient(const PaintGradient &gradient, float logical_width, float
   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;
+  const bool linear = gradient.kind == PaintGradient::Kind::Linear;
+  const float inv_rx = linear || gradient.radius_x <= 0.0f ? 1.0f : 1.0f / gradient.radius_x;
+  const float inv_ry = linear || gradient.radius_y <= 0.0f ? 1.0f : 1.0f / gradient.radius_y;
+  const float inv_length =
+      linear && gradient.length > 0.00001f ? 1.0f / gradient.length : 0.0f;
   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);
+      float t = 0.0f;
+      if (linear) {
+        /* A linear ramp is the position projected onto the gradient line. */
+        t = ((local_x - gradient.start_x) * gradient.dir_x +
+             (local_y - gradient.start_y) * gradient.dir_y) *
+            inv_length;
+      } else {
+        /* A radial ramp is the distance from the centre, normalised by the
+         * ending ellipse. */
+        const float u = (local_x - gradient.center_x) * inv_rx;
+        const float v = (local_y - gradient.center_y) * inv_ry;
+        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;
@@ -85,12 +105,12 @@ void rasterizeGradient(const PaintGradient &gradient, float logical_width, float
 }
 
 /** 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) {
+ * preserving its aspect ratio under `max_edge`. */
+void rasterSize(int pixel_width, int pixel_height, int max_edge, 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);
+  if (*width <= max_edge && *height <= max_edge) return;
+  float shrink = (float)max_edge / (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));
 }
@@ -119,12 +139,26 @@ SDL_GPUTexture *ensureGradientTexture(SDL_GPUDevice *device, const xtgui::PaintI
                                       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) {
+  if (gradient.stops.size() < 2) return nullptr;
+  const bool linear = gradient.kind == xtgui::PaintGradient::Kind::Linear;
+  if (linear) {
+    if (gradient.length <= 0.00001f) return nullptr;
+  } else if (gradient.radius_x <= 0.0f || gradient.radius_y <= 0.0f) {
     return nullptr;
   }
+  int across = pixel_width;
+  int down = pixel_height;
+  if (linear) {
+    /* A linear ramp does not change along the box's other axis, so one texel of
+     * it is enough: only the axis the ramp runs along needs resolution. */
+    if (std::fabs(gradient.dir_y) < 0.0001f) down = 1;
+    else if (std::fabs(gradient.dir_x) < 0.0001f) across = 1;
+  }
+  const bool one_dimensional = linear && (across == 1 || down == 1);
   int width = 0;
   int height = 0;
-  rasterSize(pixel_width, pixel_height, &width, &height);
+  rasterSize(across, down, one_dimensional ? kMaxLinearGradientEdge : kMaxGradientEdge, &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];

package/runtime/ext_gui/renderer_image.cpp

@@ -387,6 +387,7 @@ void xt_gui_image_upload(SDL_GPUDevice *device, XtGuiGeometry *geometry,
   full.u1 = 1.0f;
   full.v1 = 1.0f;
   beginGradientUpload();
+  beginBitmapUpload();
   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];
@@ -398,7 +399,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.gradient != nullptr) {
+    if (image.bitmap != nullptr) {
+      texture = ensureBitmapTexture(device, *image.bitmap, batch);
+    } else 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);
@@ -416,12 +419,14 @@ void xt_gui_image_upload(SDL_GPUDevice *device, XtGuiGeometry *geometry,
     geometry->op_textures[op.index] = texture;
   }
   finishGradientUpload(device);
+  finishBitmapUpload(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);
+  releaseBitmapTextures(device);
   for (auto &entry : g_image_textures) {
     if (entry.second != nullptr) SDL_ReleaseGPUTexture(device, entry.second);
   }

package/runtime/ext_gui/renderer_internal.h

@@ -135,6 +135,16 @@ void drawRuns(SDL_GPURenderPass *pass, const std::vector<XtGuiDrawRun> &runs, si
  * SPIR-V or MSL). D3D12/DXIL has no shader compiler here, so it falls back to
  * the ordinary single-pass painter. */
 bool layerRendererReady(SDL_GPUDevice *device);
+/** True when the `backdrop-filter` snapshot/filter pipeline was created. */
+bool backdropRendererReady(SDL_GPUDevice *device);
+/** Filter `source` into the active scene pass inside the element's rounded
+ * border box. No-op when the pipeline is unavailable. */
+void drawBackdropPass(SDL_GPUCommandBuffer *cmd, SDL_GPURenderPass *pass,
+                      SDL_GPUTexture *source, const xtgui::DisplayList &list,
+                      const XtGuiDrawRun &run, int target_width, int target_height,
+                      float pixel_density);
+/** Release the backdrop pipeline and sampler. */
+void backdropRendererDestroy(SDL_GPUDevice *device);
 /** Render `list` through the offscreen layer compositor into `swapchain`.
  * Returns false before recording any pass when the scene textures cannot be
  * created, so the caller can fall back to the ordinary painter. */
@@ -159,6 +169,17 @@ SDL_GPUTexture *createImageTexture(SDL_GPUDevice *device, const xtgui::Image &im
 SDL_GPUTexture *ensureImageTexture(SDL_GPUDevice *device, const std::string &src, int pixel_width,
                                    int pixel_height, XtGuiUploadBatch *batch);
 
+/* -- CPU-rasterised shadows ---------------------------------------------- */
+
+/** Upload (once) the blurred mask of a `box-shadow`/`text-shadow` layer and
+ * return its cached texture. Bracket the frame's image upload with
+ * `beginBitmapUpload`/`finishBitmapUpload` so stale masks are reclaimed. */
+SDL_GPUTexture *ensureBitmapTexture(SDL_GPUDevice *device, const xtgui::PaintBitmap &bitmap,
+                                    XtGuiUploadBatch *batch);
+void beginBitmapUpload();
+void finishBitmapUpload(SDL_GPUDevice *device);
+void releaseBitmapTextures(SDL_GPUDevice *device);
+
 /* -- background gradients ------------------------------------------------- */
 
 /** Rasterise a `PaintImage` radial gradient into an RGBA texture and cache it by