perf(export): blit GPU composite result directly to canvas instead of readback (#125)

Replace the costly GPU→CPU readback path (mapAsync + putImageData) with a
blit render pass that draws the composited texture directly onto a
GPUCanvasContext. This eliminates per-frame buffer mapping, row-stride
unpacking, and ImageData allocation during blend-mode compositing.

Add a dedicated blit shader and pipeline to CompositorPipeline with
compositeToCanvas(), and wire the render engine to use a persistent
OffscreenCanvas with a configured GPU context. Falls back to the
Canvas2D compositor path when GPU presentation isn't available.

Author: walterlow

src/features/export/utils/client-render-engine.ts

@@ -210,6 +210,10 @@ export async function createCompositionRenderer(
   // Lazily created from the effects pipeline's GPU device
   let gpuCompositor: CompositorPipeline | null = null;
   let gpuMaskManager: MaskTextureManager | null = null;
+  let gpuCompositeCanvas: OffscreenCanvas | null = null;
+  let gpuCompositeCtx: GPUCanvasContext | null = null;
+  let gpuCompositeW = 0;
+  let gpuCompositeH = 0;
 
   function ensureGpuCompositor(): boolean {
     if (gpuCompositor) return true;
@@ -220,6 +224,35 @@ export async function createCompositionRenderer(
     return true;
   }
 
+  function ensureGpuCompositeOutput(
+    width: number,
+    height: number,
+  ): { canvas: OffscreenCanvas; ctx: GPUCanvasContext } | null {
+    if (!gpuPipeline) return null;
+
+    if (!gpuCompositeCanvas) {
+      gpuCompositeCanvas = new OffscreenCanvas(width, height);
+    }
+
+    if (!gpuCompositeCtx || gpuCompositeW !== width || gpuCompositeH !== height) {
+      if (gpuCompositeCanvas.width !== width || gpuCompositeCanvas.height !== height) {
+        gpuCompositeCanvas.width = width;
+        gpuCompositeCanvas.height = height;
+      }
+      gpuCompositeCtx = gpuPipeline.configureCanvas(gpuCompositeCanvas);
+      if (!gpuCompositeCtx) {
+        gpuCompositeCanvas = null;
+        gpuCompositeW = 0;
+        gpuCompositeH = 0;
+        return null;
+      }
+      gpuCompositeW = width;
+      gpuCompositeH = height;
+    }
+
+    return { canvas: gpuCompositeCanvas, ctx: gpuCompositeCtx };
+  }
+
   // Build lookup maps
   const keyframesMap = buildKeyframesMap(keyframes);
 
@@ -1300,6 +1333,7 @@ export async function createCompositionRenderer(
       // Render tracks in order (bottom to top), with transitions at their track position
       // Track order: higher values render first (behind), lower values render last (on top)
       let skippedTracks = 0;
+      let finalCompositeSource: OffscreenCanvas = contentCanvas;
 
       // Parallelize item rendering (video decode is the bottleneck).
       // Collect all renderable items in z-order, fire all renders concurrently,
@@ -1354,19 +1388,27 @@ export async function createCompositionRenderer(
           (t) => t.type === 'item' && t.item.blendMode && t.item.blendMode !== 'normal',
         );
         const useGpuCompositor = hasNonNormalBlend && gpuPipeline && ensureGpuCompositor();
+        const gpuCompositeOutput = useGpuCompositor
+          ? ensureGpuCompositeOutput(canvasSettings.width, canvasSettings.height)
+          : null;
 
-        if (useGpuCompositor && gpuCompositor && gpuMaskManager) {
+        if (useGpuCompositor && gpuCompositor && gpuMaskManager && gpuCompositeOutput) {
           // GPU compositing path — pixel-perfect blend modes via WebGPU
           const device = gpuPipeline!.getDevice();
           const w = canvasSettings.width;
           const h = canvasSettings.height;
           const layers: CompositeLayer[] = [];
           const layerTextures: GPUTexture[] = [];
+          const compositedResults: Array<{
+            task: typeof renderTasks[number];
+            result: { source: OffscreenCanvas; poolCanvases: OffscreenCanvas[] };
+          }> = [];
 
           for (let i = 0; i < results.length; i++) {
             const task = renderTasks[i]!;
             const result = applyTrackScopedMasks(results[i] ?? null, task.trackOrder);
             if (!result) continue;
+            compositedResults.push({ task, result });
 
             const blendMode = task.type === 'item' ? (task.item.blendMode ?? 'normal') : 'normal';
 
@@ -1388,46 +1430,35 @@ export async function createCompositionRenderer(
               textureView: tex.createView(),
               maskView: gpuMaskManager.getFallbackView(),
             });
-
-            for (const c of result.poolCanvases) canvasPool.release(c);
           }
 
-          if (layers.length > 0) {
-            const commandEncoder = device.createCommandEncoder();
-            const composited = gpuCompositor.compositeToTexture(layers, w, h, commandEncoder);
+          const compositedToGpuCanvas = layers.length > 0
+            && gpuCompositor.compositeToCanvas(layers, w, h, gpuCompositeOutput.ctx);
 
-            if (composited) {
-              // Readback composited result to Canvas2D
-              const bytesPerRow = Math.ceil(w * 4 / 256) * 256;
-              const readBuffer = device.createBuffer({
-                size: bytesPerRow * h,
-                usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
-              });
-              commandEncoder.copyTextureToBuffer(
-                { texture: composited.texture },
-                { buffer: readBuffer, bytesPerRow },
-                { width: w, height: h },
-              );
-              device.queue.submit([commandEncoder.finish()]);
-
-              await readBuffer.mapAsync(GPUMapMode.READ);
-              const mapped = new Uint8Array(readBuffer.getMappedRange());
-              const pixels = new Uint8ClampedArray(w * h * 4);
-              for (let row = 0; row < h; row++) {
-                pixels.set(
-                  mapped.subarray(row * bytesPerRow, row * bytesPerRow + w * 4),
-                  row * w * 4,
-                );
+          if (compositedToGpuCanvas) {
+            finalCompositeSource = gpuCompositeOutput.canvas;
+          } else {
+            // Fall back to the established Canvas2D compositor if the GPU target
+            // isn't available for this frame. This preserves feature parity and
+            // avoids dropping content when WebGPU canvas presentation fails.
+            for (const { task, result } of compositedResults) {
+              const blendMode = task.type === 'item' ? task.item.blendMode : undefined;
+              if (blendMode && blendMode !== 'normal') {
+                contentCtx.globalCompositeOperation = getCompositeOperation(blendMode);
               }
-              readBuffer.unmap();
-              readBuffer.destroy();
 
-              contentCtx.putImageData(new ImageData(pixels, w, h), 0, 0);
-            } else {
-              device.queue.submit([commandEncoder.finish()]);
+              contentCtx.drawImage(result.source, 0, 0);
+
+              if (blendMode && blendMode !== 'normal') {
+                contentCtx.globalCompositeOperation = 'source-over';
+              }
             }
           }
 
+          for (const { result } of compositedResults) {
+            for (const c of result.poolCanvases) canvasPool.release(c);
+          }
+
           // Destroy per-frame textures
           for (const tex of layerTextures) tex.destroy();
         } else {
@@ -1458,7 +1489,7 @@ export async function createCompositionRenderer(
         log.debug(`Occlusion culling: skipped ${skippedTracks} tracks at frame ${frame}`);
       }
 
-      ctx.drawImage(contentCanvas, 0, 0);
+      ctx.drawImage(finalCompositeSource, 0, 0);
 
       // Release content canvas back to pool
       canvasPool.release(contentCanvas);
@@ -1616,6 +1647,10 @@ export async function createCompositionRenderer(
       gpuCompositor = null;
       gpuMaskManager?.destroy();
       gpuMaskManager = null;
+      gpuCompositeCtx = null;
+      gpuCompositeCanvas = null;
+      gpuCompositeW = 0;
+      gpuCompositeH = 0;
       gpuTransitionPipeline?.destroy();
       gpuTransitionPipeline = null;
       gpuPipeline?.destroy();

src/lib/gpu-compositor/compositor-pipeline.ts

@@ -19,6 +19,36 @@ const logger = createLogger('CompositorPipeline');
 
 // ─── Shader ───
 
+const BLIT_SHADER = /* wgsl */ `
+struct VertexOutput {
+  @builtin(position) position: vec4f,
+  @location(0) uv: vec2f,
+};
+@vertex
+fn vertexMain(@builtin(vertex_index) vi: u32) -> VertexOutput {
+  var pos = array<vec2f, 6>(
+    vec2f(-1,-1), vec2f(1,-1), vec2f(-1,1),
+    vec2f(-1,1), vec2f(1,-1), vec2f(1,1)
+  );
+  var uv = array<vec2f, 6>(
+    vec2f(0,1), vec2f(1,1), vec2f(0,0),
+    vec2f(0,0), vec2f(1,1), vec2f(1,0)
+  );
+  var o: VertexOutput;
+  o.position = vec4f(pos[vi], 0, 1);
+  o.uv = uv[vi];
+  return o;
+}
+
+@group(0) @binding(0) var texSampler: sampler;
+@group(0) @binding(1) var inputTex: texture_2d<f32>;
+
+@fragment
+fn blitFragment(input: VertexOutput) -> @location(0) vec4f {
+  return textureSample(inputTex, texSampler, input.uv);
+}
+`;
+
 const VERTEX_SHADER = /* wgsl */ `
 struct VertexOutput {
   @builtin(position) position: vec4f,
@@ -276,6 +306,7 @@ function packUniforms(p: CompositeLayerParams): Float32Array {
 
 export class CompositorPipeline {
   private device: GPUDevice;
+  private canvasFormat: GPUTextureFormat;
   private sampler: GPUSampler;
   private uniformBuffer: GPUBuffer;
 
@@ -284,19 +315,24 @@ export class CompositorPipeline {
 
   private externalPipeline: GPURenderPipeline | null = null;
   private externalLayout: GPUBindGroupLayout | null = null;
+  private blitPipeline: GPURenderPipeline | null = null;
+  private blitLayout: GPUBindGroupLayout | null = null;
 
   private pingTexture: GPUTexture | null = null;
   private pongTexture: GPUTexture | null = null;
   private pingView: GPUTextureView | null = null;
   private pongView: GPUTextureView | null = null;
   private texW = 0;
   private texH = 0;
+  private blitBindGroupPing: GPUBindGroup | null = null;
+  private blitBindGroupPong: GPUBindGroup | null = null;
 
   // Last packed uniforms for change detection
   private lastUniforms: Float32Array | null = null;
 
   constructor(device: GPUDevice) {
     this.device = device;
+    this.canvasFormat = navigator.gpu.getPreferredCanvasFormat();
     this.sampler = device.createSampler({ magFilter: 'linear', minFilter: 'linear' });
     this.uniformBuffer = device.createBuffer({
       size: UNIFORM_SIZE,
@@ -361,6 +397,29 @@ export class CompositorPipeline {
       this.externalPipeline = null;
       this.externalLayout = null;
     }
+
+    try {
+      const module = this.device.createShaderModule({
+        label: 'compositor-blit',
+        code: BLIT_SHADER,
+      });
+      this.blitLayout = this.device.createBindGroupLayout({
+        label: 'compositor-blit-layout',
+        entries: [
+          { binding: 0, visibility: GPUShaderStage.FRAGMENT, sampler: {} },
+          { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: {} },
+        ],
+      });
+      this.blitPipeline = this.device.createRenderPipeline({
+        label: 'compositor-blit-pipeline',
+        layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.blitLayout] }),
+        vertex: { module, entryPoint: 'vertexMain' },
+        fragment: { module, entryPoint: 'blitFragment', targets: [{ format: this.canvasFormat }] },
+        primitive: { topology: 'triangle-list' },
+      });
+    } catch (e) {
+      logger.warn('Failed to create compositor blit pipeline', e);
+    }
   }
 
   private ensurePingPong(w: number, h: number): void {
@@ -379,6 +438,8 @@ export class CompositorPipeline {
     this.pongView = this.pongTexture.createView();
     this.texW = w;
     this.texH = h;
+    this.blitBindGroupPing = null;
+    this.blitBindGroupPong = null;
   }
 
   private writeUniforms(params: CompositeLayerParams): void {
@@ -486,6 +547,52 @@ export class CompositorPipeline {
     return { texture: inputTex, view: inputView };
   }
 
+  compositeToCanvas(
+    layers: CompositeLayer[],
+    width: number,
+    height: number,
+    outputCtx: GPUCanvasContext,
+  ): boolean {
+    if (!this.blitPipeline || !this.blitLayout) return false;
+
+    const commandEncoder = this.device.createCommandEncoder();
+    const composited = this.compositeToTexture(layers, width, height, commandEncoder);
+    if (!composited) {
+      return false;
+    }
+
+    const blitBindGroup = composited.texture === this.pingTexture
+      ? (this.blitBindGroupPing ??= this.device.createBindGroup({
+          layout: this.blitLayout,
+          entries: [
+            { binding: 0, resource: this.sampler },
+            { binding: 1, resource: this.pingView! },
+          ],
+        }))
+      : (this.blitBindGroupPong ??= this.device.createBindGroup({
+          layout: this.blitLayout,
+          entries: [
+            { binding: 0, resource: this.sampler },
+            { binding: 1, resource: this.pongView! },
+          ],
+        }));
+
+    const outputPass = commandEncoder.beginRenderPass({
+      colorAttachments: [{
+        view: outputCtx.getCurrentTexture().createView(),
+        loadOp: 'clear',
+        storeOp: 'store',
+      }],
+    });
+    outputPass.setPipeline(this.blitPipeline);
+    outputPass.setBindGroup(0, blitBindGroup);
+    outputPass.draw(6);
+    outputPass.end();
+
+    this.device.queue.submit([commandEncoder.finish()]);
+    return true;
+  }
+
   getDevice(): GPUDevice {
     return this.device;
   }