@driftengine/ui2d 4.8.0 → 4.8.2

package/dist/spriteGpu.d.ts

@@ -6,8 +6,20 @@ export interface GpuSpriteSlot {
     readonly texture: GPUTexture;
     readonly bindGroup: GPUBindGroup;
 }
+/** Pipelines by colour format, then depth format, then sample count: a lookup that allocates nothing. */
+type PipelinesByTarget = Map<GPUTextureFormat, Map<GPUTextureFormat, Map<number, GPURenderPipeline>>>;
 export interface GpuSprites {
-    readonly pipeline: GPURenderPipeline;
+    /**
+     * One pipeline per pass the sprites have been drawn into, chosen at the draw by
+     * `spritePipelineFor`. A pipeline must match its pass's attachments exactly, and a 2D layer is
+     * drawn in the frame and over it, which are two different passes: the scene's target at the
+     * scene's samples, and the canvas at one.
+     */
+    readonly pipelines: PipelinesByTarget;
+    readonly pipelineLayout: GPUPipelineLayout;
+    readonly vertexModule: GPUShaderModule;
+    readonly fragmentModule: GPUShaderModule;
+    readonly label: string;
     readonly layout: GPUBindGroupLayout;
     readonly vertexUniforms: GPUBuffer;
     readonly fragmentUniforms: GPUBuffer;
@@ -28,9 +40,20 @@ export interface GpuSprites {
     readonly fragmentInts: Int32Array;
 }
 export declare function createGpuSprites(device: GPUDevice, format: GPUTextureFormat, depthFormat: GPUTextureFormat, samples: number, capacity: number, slots: number, label: string): GpuSprites;
+/**
+ * The pipeline for a pass with these attachments, built the first time it is asked for.
+ *
+ * Chosen at the draw from what the pass is (`PassContext.format`, `depthFormat`, `samples`), so a
+ * 2D layer drawn over the finished frame, on the canvas at one sample, is not refused for having
+ * been built for the scene target. A lookup through three maps on every later draw, no allocation.
+ */
+export declare function spritePipelineFor(device: GPUDevice, sprites: GpuSprites, format: GPUTextureFormat, depthFormat: GPUTextureFormat, samples: number): GPURenderPipeline;
 export declare function setGpuSpriteTexture(device: GPUDevice, sprites: GpuSprites, slot: number, source: SpriteImage, options: SpriteTextureOptions): void;
 /** The same one white texel, written straight into a texture. See the WebGL2 half for why. */
 export declare function setGpuWhiteTexture(device: GPUDevice, sprites: GpuSprites, slot: number): void;
 export declare function uploadGpuInstances(device: GPUDevice, sprites: GpuSprites, batch: SpriteBatch): void;
-export declare function drawGpuSprites(pass: GPURenderPassEncoder, sprites: GpuSprites, batch: SpriteBatch): void;
+export declare function drawGpuSprites(pass: GPURenderPassEncoder, sprites: GpuSprites, batch: SpriteBatch, 
+/** The pipeline for this pass's attachments: `spritePipelineFor`. */
+pipeline: GPURenderPipeline): void;
 export declare function disposeGpuSprites(sprites: GpuSprites): void;
+export {};

package/dist/spriteGpu.js

@@ -37,52 +37,14 @@ export function createGpuSprites(device, format, depthFormat, samples, capacity,
             },
         ],
     });
-    const pipeline = device.createRenderPipeline({
-        label,
-        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
-        vertex: {
-            module: device.createShaderModule({ label: `${label}.vert`, code: SPRITE_VERT_WGSL }),
-            entryPoint: 'main',
-            buffers: [
-                {
-                    arrayStride: STRIDE,
-                    stepMode: 'instance',
-                    attributes: [
-                        { shaderLocation: 0, offset: 0, format: 'float32x4' },
-                        { shaderLocation: 1, offset: 16, format: 'float32x4' },
-                        { shaderLocation: 2, offset: 32, format: 'float32x4' },
-                        { shaderLocation: 3, offset: 48, format: 'float32x2' },
-                    ],
-                },
-            ],
-        },
-        fragment: {
-            module: device.createShaderModule({ label: `${label}.frag`, code: SPRITE_FRAG_WGSL }),
-            entryPoint: 'main',
-            targets: [
-                {
-                    format,
-                    /* Premultiplied `over`, matching the WebGL2 half exactly. */
-                    blend: {
-                        color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-                        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-                    },
-                },
-            ],
-        },
-        /*
-         * Nothing is culled: a sprite is mirrored by giving it a negative width, which reverses its
-         * winding, and a character facing left is exactly that.
-         */
-        primitive: { topology: 'triangle-list', cullMode: 'none' },
-        multisample: { count: samples },
-        /*
-         * Neither tested nor written. The 2D layer's order *is* its layering — there is no z to sort
-         * by — and a pass that depth-tested would let whatever 3D geometry is in the frame punch holes
-         * in an overlay drawn over it. Declared all the same, because a pipeline in a render pass that
-         * has a depth attachment must name its format.
-         */
-        depthStencil: { format: depthFormat, depthWriteEnabled: false, depthCompare: 'always' },
+    const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [layout] });
+    const vertexModule = device.createShaderModule({
+        label: `${label}.vert`,
+        code: SPRITE_VERT_WGSL,
+    });
+    const fragmentModule = device.createShaderModule({
+        label: `${label}.frag`,
+        code: SPRITE_FRAG_WGSL,
     });
     const vertexUniforms = device.createBuffer({
         label: `${label}.vertexUniforms`,
@@ -101,8 +63,12 @@ export function createGpuSprites(device, format, depthFormat, samples, capacity,
     });
     const vertexScratch = new ArrayBuffer(VERT.uniformSize);
     const fragmentScratch = new ArrayBuffer(FRAG.uniformSize);
-    return {
-        pipeline,
+    const sprites = {
+        pipelines: new Map(),
+        pipelineLayout,
+        vertexModule,
+        fragmentModule,
+        label,
         layout,
         vertexUniforms,
         fragmentUniforms,
@@ -138,6 +104,80 @@ export function createGpuSprites(device, format, depthFormat, samples, capacity,
         fragmentFloats: new Float32Array(fragmentScratch),
         fragmentInts: new Int32Array(fragmentScratch),
     };
+    /* The frame's own target, built now, so the common case compiles before its first draw. */
+    spritePipelineFor(device, sprites, format, depthFormat, samples);
+    return sprites;
+}
+/**
+ * The pipeline for a pass with these attachments, built the first time it is asked for.
+ *
+ * Chosen at the draw from what the pass is (`PassContext.format`, `depthFormat`, `samples`), so a
+ * 2D layer drawn over the finished frame, on the canvas at one sample, is not refused for having
+ * been built for the scene target. A lookup through three maps on every later draw, no allocation.
+ */
+export function spritePipelineFor(device, sprites, format, depthFormat, samples) {
+    let byDepth = sprites.pipelines.get(format);
+    if (byDepth === undefined) {
+        byDepth = new Map();
+        sprites.pipelines.set(format, byDepth);
+    }
+    let bySamples = byDepth.get(depthFormat);
+    if (bySamples === undefined) {
+        bySamples = new Map();
+        byDepth.set(depthFormat, bySamples);
+    }
+    const found = bySamples.get(samples);
+    if (found !== undefined)
+        return found;
+    const pipeline = device.createRenderPipeline({
+        label: `${sprites.label}:${format}x${samples}`,
+        layout: sprites.pipelineLayout,
+        vertex: {
+            module: sprites.vertexModule,
+            entryPoint: 'main',
+            buffers: [
+                {
+                    arrayStride: STRIDE,
+                    stepMode: 'instance',
+                    attributes: [
+                        { shaderLocation: 0, offset: 0, format: 'float32x4' },
+                        { shaderLocation: 1, offset: 16, format: 'float32x4' },
+                        { shaderLocation: 2, offset: 32, format: 'float32x4' },
+                        { shaderLocation: 3, offset: 48, format: 'float32x2' },
+                    ],
+                },
+            ],
+        },
+        fragment: {
+            module: sprites.fragmentModule,
+            entryPoint: 'main',
+            targets: [
+                {
+                    format,
+                    /* Premultiplied `over`, matching the WebGL2 half exactly. */
+                    blend: {
+                        color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                    },
+                },
+            ],
+        },
+        /*
+         * Nothing is culled: a sprite is mirrored by giving it a negative width, which reverses its
+         * winding, and a character facing left is exactly that.
+         */
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+        multisample: { count: samples },
+        /*
+         * Neither tested nor written. The 2D layer's order *is* its layering — there is no z to sort
+         * by — and a pass that depth-tested would let whatever 3D geometry is in the frame punch holes
+         * in an overlay drawn over it. Declared all the same, because a pipeline in a render pass that
+         * has a depth attachment must name its format.
+         */
+        depthStencil: { format: depthFormat, depthWriteEnabled: false, depthCompare: 'always' },
+    });
+    bySamples.set(samples, pipeline);
+    return pipeline;
 }
 /**
  * One pipeline per format, kept on the sprite pass rather than in the renderer's cache.
@@ -231,10 +271,12 @@ export function uploadGpuInstances(device, sprites, batch) {
         return;
     device.queue.writeBuffer(sprites.instances, 0, batch.instances.buffer, batch.instances.byteOffset, batch.count * STRIDE);
 }
-export function drawGpuSprites(pass, sprites, batch) {
+export function drawGpuSprites(pass, sprites, batch, 
+/** The pipeline for this pass's attachments: `spritePipelineFor`. */
+pipeline) {
     if (batch.count === 0)
         return;
-    pass.setPipeline(sprites.pipeline);
+    pass.setPipeline(pipeline);
     for (let run = 0; run < batch.runCount; run += 1) {
         const at = run * 3;
         const slot = sprites.slots[batch.runs[at]];

package/dist/spritePass.js

@@ -3,7 +3,7 @@ import { SPRITE_BINDINGS } from './shaders/generated/sprite.wgsl.js';
 import { createAffine2D } from './camera2d.js';
 import { createSpriteBatch, resetSpriteBatch } from './spriteBatch.js';
 import { createWebgl2Sprites, disposeWebgl2Sprites, drawWebgl2Sprites, setWebgl2SpriteTexture, setWebgl2WhiteTexture, uploadWebgl2Instances, } from './spriteGl.js';
-import { createGpuSprites, disposeGpuSprites, drawGpuSprites, setGpuSpriteTexture, setGpuWhiteTexture, uploadGpuInstances, } from './spriteGpu.js';
+import { createGpuSprites, disposeGpuSprites, drawGpuSprites, spritePipelineFor, setGpuSpriteTexture, setGpuWhiteTexture, uploadGpuInstances, } from './spriteGpu.js';
 import { DEFAULT_SPRITE_TEXTURE_OPTIONS } from './spriteTexture.js';
 const VERT = SPRITE_BINDINGS.SPRITE_VERT;
 const FRAG = SPRITE_BINDINGS.SPRITE_FRAG;
@@ -126,7 +126,8 @@ export function createSpritePass(options = {}) {
             device.queue.writeBuffer(gpu.vertexUniforms, 0, gpu.vertexScratch);
             device.queue.writeBuffer(gpu.fragmentUniforms, 0, gpu.fragmentScratch);
             uploadGpuInstances(device, gpu, batch);
-            drawGpuSprites(ctx.pass, gpu, batch);
+            /* For the pass this lands in, which after `endFrame` is the canvas: see `spritePipelineFor`. */
+            drawGpuSprites(ctx.pass, gpu, batch, spritePipelineFor(device, gpu, ctx.format, ctx.depthFormat, ctx.samples));
         },
         dispose() {
             if (gl !== null && context !== null)

package/dist/uiDraw.js

@@ -1,6 +1,7 @@
 /** Turn a laid-out interface tree into quads, parents first so children land on top. */
 import { drawSprite } from './spriteBatch.js';
 import { createSpriteFrame } from './spriteSheet.js';
+import { layersPresent } from './uiLayer.js';
 /* One placement, refilled per node. This is a per-frame path and these are the only objects in it. */
 const PLACEMENT = {
     x: 0,
@@ -30,11 +31,26 @@ const CUT = createSpriteFrame();
  * left at.
  */
 export function drawUiTree(batch, root, white, sink) {
-    return drawWithin(batch, root, white, sink, -Infinity, -Infinity, Infinity, Infinity);
+    /*
+     * **Layer by layer, lowest first, and tree order within one.** A raised node — a dropdown that
+     * must cover the panel its control sits in — was drawn in tree order with everything else, so a
+     * later sibling covered it. Each layer is a walk of the whole tree with the clips it would have
+     * had anyway, so a raised node is still cut by a clipping ancestor; a tree with no raised node is
+     * one walk, as before.
+     */
+    const count = layersPresent(root, LAYERS);
+    let drawn = 0;
+    for (let at = 0; at < count; at += 1) {
+        drawn += drawWithin(batch, root, white, sink, -Infinity, -Infinity, Infinity, Infinity, 0, LAYERS[at] ?? 0);
+    }
+    return drawn;
 }
-function drawWithin(batch, node, white, sink, left, top, right, bottom) {
+/** The layers of the tree being drawn, reused: this runs per frame. */
+const LAYERS = [];
+function drawWithin(batch, node, white, sink, left, top, right, bottom, inherited, only) {
     if (node.hidden)
         return 0;
+    const layer = node.layer === 0 ? inherited : node.layer;
     const rect = node.rect;
     const clipped = left !== -Infinity;
     const x0 = Math.max(rect.x, left);
@@ -47,7 +63,7 @@ function drawWithin(batch, node, white, sink, left, top, right, bottom) {
      * a node is drawn as it always was, whatever its size. Its children are cut one by one either way,
      * since a child can lie outside its parent's box and still inside the clip.
      */
-    if (!clipped || (x1 > x0 && y1 > y0)) {
+    if (layer === only && (!clipped || (x1 > x0 && y1 > y0))) {
         PLACEMENT.x = clipped ? x0 : rect.x;
         PLACEMENT.y = clipped ? y0 : rect.y;
         PLACEMENT.w = clipped ? x1 - x0 : rect.w;
@@ -75,8 +91,9 @@ function drawWithin(batch, node, white, sink, left, top, right, bottom) {
     const ct = keep ? Math.max(top, rect.y) : top;
     const cr = keep ? Math.min(right, rect.x + rect.w) : right;
     const cb = keep ? Math.min(bottom, rect.y + rect.h) : bottom;
-    for (const child of node.children)
-        drawn += drawWithin(batch, child, white, sink, cl, ct, cr, cb);
+    for (const child of node.children) {
+        drawn += drawWithin(batch, child, white, sink, cl, ct, cr, cb, layer, only);
+    }
     return drawn;
 }
 /** The part of a node's frame its visible box shows, or the whole frame when nothing was cut. */

package/dist/uiFocus.js

@@ -1,5 +1,6 @@
 /** Which node a point is on, and which node a keyboard should be talking to. */
 import { uiRectHolds } from './uiNode.js';
+import { layersPresent } from './uiLayer.js';
 /**
  * The interactive node under a point, or `null`.
  *
@@ -14,18 +15,32 @@ import { uiRectHolds } from './uiNode.js';
  * Allocates nothing.
  */
 export function uiHitTest(root, x, y) {
-    if (root.hidden)
+    /* The highest layer first, as it is drawn last: a raised popup takes the pointer over a later
+       sibling it covers. See `drawUiTree`. */
+    const count = layersPresent(root, HIT_LAYERS);
+    for (let at = count - 1; at >= 0; at -= 1) {
+        const hit = hitOn(root, x, y, 0, HIT_LAYERS[at] ?? 0);
+        if (hit !== null)
+            return hit;
+    }
+    return null;
+}
+/** The layers of the tree being pointed at, reused: a hit test runs per pointer event. */
+const HIT_LAYERS = [];
+function hitOn(node, x, y, inherited, only) {
+    if (node.hidden)
         return null;
     /* A clipping node bounds its descendants here as it does in the picture: a row scrolled out of a
        list is not under the pointer, whatever is drawn where it would have been. */
-    if (root.clip && !uiRectHolds(root, x, y))
+    if (node.clip && !uiRectHolds(node, x, y))
         return null;
-    for (let i = root.children.length - 1; i >= 0; i -= 1) {
-        const hit = uiHitTest(root.children[i], x, y);
+    const layer = node.layer === 0 ? inherited : node.layer;
+    for (let i = node.children.length - 1; i >= 0; i -= 1) {
+        const hit = hitOn(node.children[i], x, y, layer, only);
         if (hit !== null)
             return hit;
     }
-    return root.interactive && uiRectHolds(root, x, y) ? root : null;
+    return layer === only && node.interactive && uiRectHolds(node, x, y) ? node : null;
 }
 /**
  * Every focusable node, in tree order, appended to `out`.

package/dist/uiLayer.d.ts

@@ -16,3 +16,10 @@
 import type { UiNode } from './uiNode.ts';
 /** Fill `out` with the tree in draw order and return how many entries were written. */
 export declare function layerOrder(root: UiNode, out: UiNode[]): number;
+/**
+ * The layers a tree draws on, ascending, into `out`; how many there are.
+ *
+ * What `drawUiTree` and `uiHitTest` walk a tree once per: a tree with no raised node answers one
+ * layer and is walked once, exactly as it was before either read a layer.
+ */
+export declare function layersPresent(root: UiNode, out: number[]): number;

package/dist/uiLayer.js

@@ -28,3 +28,27 @@ export function layerOrder(root, out) {
     out.length = count;
     return count;
 }
+/** Ascending, without allocating a comparator per call. */
+const ASCENDING = (a, b) => a - b;
+/**
+ * The layers a tree draws on, ascending, into `out`; how many there are.
+ *
+ * What `drawUiTree` and `uiHitTest` walk a tree once per: a tree with no raised node answers one
+ * layer and is walked once, exactly as it was before either read a layer.
+ */
+export function layersPresent(root, out) {
+    out.length = 0;
+    collect(root, 0, out);
+    if (out.length > 1)
+        out.sort(ASCENDING);
+    return out.length;
+}
+function collect(node, inherited, out) {
+    if (node.hidden)
+        return;
+    const layer = node.layer === 0 ? inherited : node.layer;
+    if (!out.includes(layer))
+        out.push(layer);
+    for (const child of node.children)
+        collect(child, layer, out);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/ui2d",
-  "version": "4.8.0",
+  "version": "4.8.2",
   "description": "The 2D layer: batched sprites, sheets, tilemaps, and a retained interface tree over them",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "peerDependencies": {
-    "@driftengine/core": "4.8.0"
+    "@driftengine/core": "4.8.2"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/spriteGpu.ts

@@ -34,8 +34,24 @@ export interface GpuSpriteSlot {
   readonly bindGroup: GPUBindGroup;
 }
 
+/** Pipelines by colour format, then depth format, then sample count: a lookup that allocates nothing. */
+type PipelinesByTarget = Map<
+  GPUTextureFormat,
+  Map<GPUTextureFormat, Map<number, GPURenderPipeline>>
+>;
+
 export interface GpuSprites {
-  readonly pipeline: GPURenderPipeline;
+  /**
+   * One pipeline per pass the sprites have been drawn into, chosen at the draw by
+   * `spritePipelineFor`. A pipeline must match its pass's attachments exactly, and a 2D layer is
+   * drawn in the frame and over it, which are two different passes: the scene's target at the
+   * scene's samples, and the canvas at one.
+   */
+  readonly pipelines: PipelinesByTarget;
+  readonly pipelineLayout: GPUPipelineLayout;
+  readonly vertexModule: GPUShaderModule;
+  readonly fragmentModule: GPUShaderModule;
+  readonly label: string;
   readonly layout: GPUBindGroupLayout;
   readonly vertexUniforms: GPUBuffer;
   readonly fragmentUniforms: GPUBuffer;
@@ -83,52 +99,14 @@ export function createGpuSprites(
     ],
   });
 
-  const pipeline = device.createRenderPipeline({
-    label,
-    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
-    vertex: {
-      module: device.createShaderModule({ label: `${label}.vert`, code: SPRITE_VERT_WGSL }),
-      entryPoint: 'main',
-      buffers: [
-        {
-          arrayStride: STRIDE,
-          stepMode: 'instance',
-          attributes: [
-            { shaderLocation: 0, offset: 0, format: 'float32x4' },
-            { shaderLocation: 1, offset: 16, format: 'float32x4' },
-            { shaderLocation: 2, offset: 32, format: 'float32x4' },
-            { shaderLocation: 3, offset: 48, format: 'float32x2' },
-          ],
-        },
-      ],
-    },
-    fragment: {
-      module: device.createShaderModule({ label: `${label}.frag`, code: SPRITE_FRAG_WGSL }),
-      entryPoint: 'main',
-      targets: [
-        {
-          format,
-          /* Premultiplied `over`, matching the WebGL2 half exactly. */
-          blend: {
-            color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-          },
-        },
-      ],
-    },
-    /*
-     * Nothing is culled: a sprite is mirrored by giving it a negative width, which reverses its
-     * winding, and a character facing left is exactly that.
-     */
-    primitive: { topology: 'triangle-list', cullMode: 'none' },
-    multisample: { count: samples },
-    /*
-     * Neither tested nor written. The 2D layer's order *is* its layering — there is no z to sort
-     * by — and a pass that depth-tested would let whatever 3D geometry is in the frame punch holes
-     * in an overlay drawn over it. Declared all the same, because a pipeline in a render pass that
-     * has a depth attachment must name its format.
-     */
-    depthStencil: { format: depthFormat, depthWriteEnabled: false, depthCompare: 'always' },
+  const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [layout] });
+  const vertexModule = device.createShaderModule({
+    label: `${label}.vert`,
+    code: SPRITE_VERT_WGSL,
+  });
+  const fragmentModule = device.createShaderModule({
+    label: `${label}.frag`,
+    code: SPRITE_FRAG_WGSL,
   });
 
   const vertexUniforms = device.createBuffer({
@@ -150,8 +128,12 @@ export function createGpuSprites(
   const vertexScratch = new ArrayBuffer(VERT.uniformSize);
   const fragmentScratch = new ArrayBuffer(FRAG.uniformSize);
 
-  return {
-    pipeline,
+  const sprites: GpuSprites = {
+    pipelines: new Map(),
+    pipelineLayout,
+    vertexModule,
+    fragmentModule,
+    label,
     layout,
     vertexUniforms,
     fragmentUniforms,
@@ -187,6 +169,86 @@ export function createGpuSprites(
     fragmentFloats: new Float32Array(fragmentScratch),
     fragmentInts: new Int32Array(fragmentScratch),
   };
+  /* The frame's own target, built now, so the common case compiles before its first draw. */
+  spritePipelineFor(device, sprites, format, depthFormat, samples);
+  return sprites;
+}
+
+/**
+ * The pipeline for a pass with these attachments, built the first time it is asked for.
+ *
+ * Chosen at the draw from what the pass is (`PassContext.format`, `depthFormat`, `samples`), so a
+ * 2D layer drawn over the finished frame, on the canvas at one sample, is not refused for having
+ * been built for the scene target. A lookup through three maps on every later draw, no allocation.
+ */
+export function spritePipelineFor(
+  device: GPUDevice,
+  sprites: GpuSprites,
+  format: GPUTextureFormat,
+  depthFormat: GPUTextureFormat,
+  samples: number,
+): GPURenderPipeline {
+  let byDepth = sprites.pipelines.get(format);
+  if (byDepth === undefined) {
+    byDepth = new Map();
+    sprites.pipelines.set(format, byDepth);
+  }
+  let bySamples = byDepth.get(depthFormat);
+  if (bySamples === undefined) {
+    bySamples = new Map();
+    byDepth.set(depthFormat, bySamples);
+  }
+  const found = bySamples.get(samples);
+  if (found !== undefined) return found;
+  const pipeline = device.createRenderPipeline({
+    label: `${sprites.label}:${format}x${samples}`,
+    layout: sprites.pipelineLayout,
+    vertex: {
+      module: sprites.vertexModule,
+      entryPoint: 'main',
+      buffers: [
+        {
+          arrayStride: STRIDE,
+          stepMode: 'instance',
+          attributes: [
+            { shaderLocation: 0, offset: 0, format: 'float32x4' },
+            { shaderLocation: 1, offset: 16, format: 'float32x4' },
+            { shaderLocation: 2, offset: 32, format: 'float32x4' },
+            { shaderLocation: 3, offset: 48, format: 'float32x2' },
+          ],
+        },
+      ],
+    },
+    fragment: {
+      module: sprites.fragmentModule,
+      entryPoint: 'main',
+      targets: [
+        {
+          format,
+          /* Premultiplied `over`, matching the WebGL2 half exactly. */
+          blend: {
+            color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+          },
+        },
+      ],
+    },
+    /*
+     * Nothing is culled: a sprite is mirrored by giving it a negative width, which reverses its
+     * winding, and a character facing left is exactly that.
+     */
+    primitive: { topology: 'triangle-list', cullMode: 'none' },
+    multisample: { count: samples },
+    /*
+     * Neither tested nor written. The 2D layer's order *is* its layering — there is no z to sort
+     * by — and a pass that depth-tested would let whatever 3D geometry is in the frame punch holes
+     * in an overlay drawn over it. Declared all the same, because a pipeline in a render pass that
+     * has a depth attachment must name its format.
+     */
+    depthStencil: { format: depthFormat, depthWriteEnabled: false, depthCompare: 'always' },
+  });
+  bySamples.set(samples, pipeline);
+  return pipeline;
 }
 
 /**
@@ -313,9 +375,11 @@ export function drawGpuSprites(
   pass: GPURenderPassEncoder,
   sprites: GpuSprites,
   batch: SpriteBatch,
+  /** The pipeline for this pass's attachments: `spritePipelineFor`. */
+  pipeline: GPURenderPipeline,
 ): void {
   if (batch.count === 0) return;
-  pass.setPipeline(sprites.pipeline);
+  pass.setPipeline(pipeline);
   for (let run = 0; run < batch.runCount; run += 1) {
     const at = run * 3;
     const slot = sprites.slots[batch.runs[at] as number];

package/src/spritePass.ts

@@ -20,6 +20,7 @@ import {
   createGpuSprites,
   disposeGpuSprites,
   drawGpuSprites,
+  spritePipelineFor,
   setGpuSpriteTexture,
   setGpuWhiteTexture,
   uploadGpuInstances,
@@ -216,7 +217,13 @@ export function createSpritePass(options: SpritePassOptions = {}): SpritePass {
       device.queue.writeBuffer(gpu.vertexUniforms, 0, gpu.vertexScratch);
       device.queue.writeBuffer(gpu.fragmentUniforms, 0, gpu.fragmentScratch);
       uploadGpuInstances(device, gpu, batch);
-      drawGpuSprites(ctx.pass, gpu, batch);
+      /* For the pass this lands in, which after `endFrame` is the canvas: see `spritePipelineFor`. */
+      drawGpuSprites(
+        ctx.pass,
+        gpu,
+        batch,
+        spritePipelineFor(device, gpu, ctx.format, ctx.depthFormat, ctx.samples),
+      );
     },
 
     dispose(): void {

package/src/uiDraw.ts

@@ -5,6 +5,7 @@ import type { SpriteBatch, SpritePlacement } from './spriteBatch.ts';
 import { createSpriteFrame } from './spriteSheet.ts';
 import type { SpriteFrame } from './spriteSheet.ts';
 import type { UiNode, UiRect } from './uiNode.ts';
+import { layersPresent } from './uiLayer.ts';
 
 /**
  * Where a caller draws what a quad cannot be.
@@ -61,9 +62,35 @@ export function drawUiTree(
   white: number,
   sink: UiContentSink | null,
 ): number {
-  return drawWithin(batch, root, white, sink, -Infinity, -Infinity, Infinity, Infinity);
+  /*
+   * **Layer by layer, lowest first, and tree order within one.** A raised node — a dropdown that
+   * must cover the panel its control sits in — was drawn in tree order with everything else, so a
+   * later sibling covered it. Each layer is a walk of the whole tree with the clips it would have
+   * had anyway, so a raised node is still cut by a clipping ancestor; a tree with no raised node is
+   * one walk, as before.
+   */
+  const count = layersPresent(root, LAYERS);
+  let drawn = 0;
+  for (let at = 0; at < count; at += 1) {
+    drawn += drawWithin(
+      batch,
+      root,
+      white,
+      sink,
+      -Infinity,
+      -Infinity,
+      Infinity,
+      Infinity,
+      0,
+      LAYERS[at] ?? 0,
+    );
+  }
+  return drawn;
 }
 
+/** The layers of the tree being drawn, reused: this runs per frame. */
+const LAYERS: number[] = [];
+
 function drawWithin(
   batch: SpriteBatch,
   node: UiNode,
@@ -73,8 +100,11 @@ function drawWithin(
   top: number,
   right: number,
   bottom: number,
+  inherited: number,
+  only: number,
 ): number {
   if (node.hidden) return 0;
+  const layer = node.layer === 0 ? inherited : node.layer;
   const rect = node.rect;
   const clipped = left !== -Infinity;
   const x0 = Math.max(rect.x, left);
@@ -87,7 +117,7 @@ function drawWithin(
    * a node is drawn as it always was, whatever its size. Its children are cut one by one either way,
    * since a child can lie outside its parent's box and still inside the clip.
    */
-  if (!clipped || (x1 > x0 && y1 > y0)) {
+  if (layer === only && (!clipped || (x1 > x0 && y1 > y0))) {
     PLACEMENT.x = clipped ? x0 : rect.x;
     PLACEMENT.y = clipped ? y0 : rect.y;
     PLACEMENT.w = clipped ? x1 - x0 : rect.w;
@@ -115,7 +145,9 @@ function drawWithin(
   const ct = keep ? Math.max(top, rect.y) : top;
   const cr = keep ? Math.min(right, rect.x + rect.w) : right;
   const cb = keep ? Math.min(bottom, rect.y + rect.h) : bottom;
-  for (const child of node.children) drawn += drawWithin(batch, child, white, sink, cl, ct, cr, cb);
+  for (const child of node.children) {
+    drawn += drawWithin(batch, child, white, sink, cl, ct, cr, cb, layer, only);
+  }
   return drawn;
 }
 

package/src/uiFocus.ts

@@ -2,6 +2,7 @@
 
 import { uiRectHolds } from './uiNode.ts';
 import type { UiNode } from './uiNode.ts';
+import { layersPresent } from './uiLayer.ts';
 
 /**
  * The interactive node under a point, or `null`.
@@ -17,15 +18,30 @@ import type { UiNode } from './uiNode.ts';
  * Allocates nothing.
  */
 export function uiHitTest(root: UiNode, x: number, y: number): UiNode | null {
-  if (root.hidden) return null;
+  /* The highest layer first, as it is drawn last: a raised popup takes the pointer over a later
+     sibling it covers. See `drawUiTree`. */
+  const count = layersPresent(root, HIT_LAYERS);
+  for (let at = count - 1; at >= 0; at -= 1) {
+    const hit = hitOn(root, x, y, 0, HIT_LAYERS[at] ?? 0);
+    if (hit !== null) return hit;
+  }
+  return null;
+}
+
+/** The layers of the tree being pointed at, reused: a hit test runs per pointer event. */
+const HIT_LAYERS: number[] = [];
+
+function hitOn(node: UiNode, x: number, y: number, inherited: number, only: number): UiNode | null {
+  if (node.hidden) return null;
   /* A clipping node bounds its descendants here as it does in the picture: a row scrolled out of a
      list is not under the pointer, whatever is drawn where it would have been. */
-  if (root.clip && !uiRectHolds(root, x, y)) return null;
-  for (let i = root.children.length - 1; i >= 0; i -= 1) {
-    const hit = uiHitTest(root.children[i] as UiNode, x, y);
+  if (node.clip && !uiRectHolds(node, x, y)) return null;
+  const layer = node.layer === 0 ? inherited : node.layer;
+  for (let i = node.children.length - 1; i >= 0; i -= 1) {
+    const hit = hitOn(node.children[i] as UiNode, x, y, layer, only);
     if (hit !== null) return hit;
   }
-  return root.interactive && uiRectHolds(root, x, y) ? root : null;
+  return layer === only && node.interactive && uiRectHolds(node, x, y) ? node : null;
 }
 
 /**

package/src/uiLayer.ts

@@ -45,3 +45,26 @@ export function layerOrder(root: UiNode, out: UiNode[]): number {
   out.length = count;
   return count;
 }
+
+/** Ascending, without allocating a comparator per call. */
+const ASCENDING = (a: number, b: number): number => a - b;
+
+/**
+ * The layers a tree draws on, ascending, into `out`; how many there are.
+ *
+ * What `drawUiTree` and `uiHitTest` walk a tree once per: a tree with no raised node answers one
+ * layer and is walked once, exactly as it was before either read a layer.
+ */
+export function layersPresent(root: UiNode, out: number[]): number {
+  out.length = 0;
+  collect(root, 0, out);
+  if (out.length > 1) out.sort(ASCENDING);
+  return out.length;
+}
+
+function collect(node: UiNode, inherited: number, out: number[]): void {
+  if (node.hidden) return;
+  const layer = node.layer === 0 ? inherited : node.layer;
+  if (!out.includes(layer)) out.push(layer);
+  for (const child of node.children) collect(child, layer, out);
+}