@pexip/media-processor 22.1.0 → 22.2.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 22.2.0
+
+### Minor Changes
+
+- 746f6b6: Add Canvas2d rendering backend support: alpha mask converter,
+  Canvas2d mask renderer, canvas dimension-aware rendering, and proper backend
+  propagation through the video processor pipeline.
+- c101d02: Add inferencer
+
+### Patch Changes
+
+- f4af45a: Fix how we calculate the FPS
+- 476acbf: Fix the background image disappearing when it is replaced by another
+  image with the same key. `setImage` closes the previously cached bitmap, so
+  the render options kept pointing at a closed `ImageBitmap` until the pipeline
+  restarted. The currently rendered image is now repointed at the new bitmap.
+- 7c99e29: Fix hardware acceleration feature detection
+- 1b82fd5: Fix dynamic texture allocation issue
+- 265c898: Migrate test runner from Jest to Vitest.
+- a5e8026: Fix "We can't find your microphone" error when changing the
+  microphone while sharing content without audio. The audio mixing processor no
+  longer tries to create an audio source node from a presentation stream that
+  has no audio track, and audio nodes belonging to a stale `AudioContext` are
+  recreated instead of being reused.
+- 0878b3b: Fix race conditions in the video processing pipeline so effect
+  changes made during processor startup are correctly applied and worker option
+  diffs are computed against the previous state.
+- Updated dependencies [5a17991]
+- Updated dependencies [265c898]
+  - @pexip/utils@17.4.1
+
 ## 22.1.0
 
 ### Patch Changes

package/api-docs/README.mdx

@@ -371,6 +371,7 @@ A library for media analysis using Web APIs.
 | [handleWebGLContextLoss](variables/handleWebGLContextLoss.mdx) | - |
 | [cloneImageRecord](variables/cloneImageRecord.mdx) | - |
 | [compareImageRecords](variables/compareImageRecords.mdx) | Compare provided ImageRecord |
+| [getCanUseWebGL](variables/getCanUseWebGL.mdx) | - |
 | [urls](variables/urls.mdx) | - |
 | [SILENT\_THRESHOLD](variables/SILENT_THRESHOLD.mdx) | Default silent threshold At least one LSB 16-bit data (compare is on absolute value). |
 | [MONO\_THRESHOLD](variables/MONO_THRESHOLD.mdx) | Default mono detection threshold Data must be identical within one LSB 16-bit to be identified as mono. |

package/api-docs/functions/createBenchmark.mdx

@@ -15,12 +15,13 @@ Creates a benchmarking utility for measuring frame durations and calculating fra
 
 [`Benchmark`](../interfaces/Benchmark.mdx)
 
-An object with methods to start/end frame measurements, reset the benchmark, and calculate current FPS.
+An object with methods to start/end frame measurements, reset the benchmark, and get current FPS.
 
 ## Remarks
 
-This function is designed for performance measurement in animation or game loops.
-It records frame start/end times, ignores an initial warmup period, utilizes a circular buffer
-to average recent frame durations, and computes a smoothed FPS value on demand.
-The calculation may only occur if sufficient samples have been gathered and the minimum interval between
-calculations has elapsed.
+Uses a time-windowed sliding approach: each frame event stores both its timestamp and
+processing duration. Only events within the configured time window contribute to FPS.
+FPS is derived as `windowMs / averageProcessingTime` for events in the window.
+
+The `begin()`/`end()` API measures processing time per frame explicitly.
+Call `fps()` at any time to get the current FPS — no priming or two-call pattern needed.

package/api-docs/interfaces/Benchmark.mdx

@@ -48,14 +48,12 @@ reset(): void;
 
 ***
 
-### calculateFps()
+### fps()
 
 ```ts
-calculateFps(): [number, number];
+fps(): number;
 ```
 
 #### Returns
 
-```ts
-[number, number]
-```
+`number`

package/api-docs/interfaces/RendererOptions.mdx

@@ -9,7 +9,7 @@ All values are stable per-frame and can be safely updated in real-time.
 | <a id="backgroundbluramount"></a> `backgroundBlurAmount` | `number` | Amount of background blur (radius in px): [0,9]. Recommend: 3–6 for portraits. Higher may be slow and over-blurred. **Default** `3` |
 | <a id="edgebluramount"></a> `edgeBlurAmount` | `number` | Edge blur for mask boundary antialiasing (radius in px): [0,9]. Small values (1–5) smooth mask stair-steps; large values soften edges more visibly. **Default** `4` |
 | <a id="effects"></a> `effects` | `"blur" \| "none" \| "overlay"` | Effects to apply: "none", "blur", or "overlay". "blur" = background blur. "overlay" = replace BG with backgroundImageUrl. |
-| <a id="backend"></a> `backend` | `"webgl" \| "webgpu"` | Backend to render background effects |
+| <a id="backend"></a> `backend` | `"webgl" \| "webgpu" \| "canvas2d"` | Backend to render background effects |
 | <a id="foregroundthreshold"></a> `foregroundThreshold` | `number` | [0,1] Upper mask confidence: all mask pixels \>= this are considered definite foreground. Adjust to make mask edges tighter or more permissive for foreground inclusion. Example: 0.8 ("mask \> 0.8 = sure foreground"). Must always be \>= backgroundThreshold. **Default** `0.85` |
 | <a id="backgroundthreshold"></a> `backgroundThreshold` | `number` | [0,1] Lower mask confidence: all mask pixels \<= this are considered definite background. Adjust to make mask edges tighter or more permissive for background inclusion. Example: 0.3 ("mask \< 0.3 = sure background"). **Default** `0.35` |
 | <a id="sigmaspace"></a> `sigmaSpace` | `number` | Bilateral filter: sigma in pixel space for mask edge snapping. Controls the neighborhood/pixel distance—higher is larger window (5–10 typical). **Default** `5` |

package/api-docs/variables/RENDER_BACKEND.mdx

@@ -8,3 +8,4 @@ const RENDER_BACKEND: object;
 | ------ | ------ |
 | <a id="webgl"></a> `WebGL` | `"webgl"` |
 | <a id="webgpu"></a> `WebGPU` | `"webgpu"` |
+| <a id="canvas2d"></a> `Canvas2D` | `"canvas2d"` |

package/api-docs/variables/getCanUseWebGL.mdx

@@ -0,0 +1,7 @@
+```ts
+const getCanUseWebGL: () => boolean;
+```
+
+## Returns
+
+`boolean`

package/dist/common/backends/canvas2d/renderer.d.ts

@@ -0,0 +1,2 @@
+import type { Renderer, RenderEventHandlers } from '../../types/render';
+export declare const createRenderer: (renderEventHandlers: RenderEventHandlers, canvas?: OffscreenCanvas) => Renderer;

package/dist/common/backends/canvas2d/renderer.js

@@ -0,0 +1,36 @@
+import { PROCESSING_HEIGHT, PROCESSING_WIDTH } from '../../constants';
+import { createCanvasRenderUtils } from '../../canvasRenderUtils';
+export const createRenderer = (renderEventHandlers, canvas = new OffscreenCanvas(PROCESSING_WIDTH, PROCESSING_HEIGHT)) => {
+    const utils = createCanvasRenderUtils(canvas.width, canvas.height);
+    let ctx = null;
+    const init = () => {
+        ctx = canvas.getContext('2d');
+        if (!ctx) {
+            renderEventHandlers.contextCreationError('Failed to create 2D rendering context');
+        }
+    };
+    const render = (mask, frame, options) => {
+        if (!ctx) {
+            return;
+        }
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+        const inputImage = utils.evaluateInput(frame);
+        if (options.effects === 'blur' && options.backgroundBlurAmount) {
+            utils.drawBlurEffect(canvas, inputImage, mask, options.foregroundThreshold, options.backgroundBlurAmount, options.edgeBlurAmount);
+        }
+        else if (options?.effects === 'overlay' && options.backgroundImage) {
+            utils.drawOverlayEffect(canvas, inputImage, options.backgroundImage, mask, options.foregroundThreshold, 0, options.edgeBlurAmount);
+        }
+    };
+    const cleanup = () => {
+        utils.reset();
+        ctx = null;
+    };
+    const release = () => {
+        cleanup();
+    };
+    const isContextLost = () => {
+        return !ctx || ctx.isContextLost();
+    };
+    return { init, render, release, isContextLost };
+};

package/dist/common/backends/webgl/blur.d.ts

@@ -2,7 +2,7 @@ import type { TextureInfo } from './types';
 /**
  * Blur provided frame
  */
-export declare const createBlurRenderer: (processor: OffscreenCanvas, pass: number, redOnly?: boolean) => {
+export declare const createBlurRenderer: (processor: OffscreenCanvas, redOnly?: boolean) => {
     render: (frame: TextureInfo, pass: number) => TextureInfo;
     release: () => void;
 };

package/dist/common/backends/webgl/blur.js

@@ -5,11 +5,12 @@ import { m3 } from '../../m3';
 import { createFrameBuffer, createGLProgram, createMaskTexture, createRGBAFrameTexture, } from './webglUtils';
 import vertexSrc from './shaders/matrix.vert';
 import fragmentSrc from './shaders/dualFilterBlur.frag';
-const clampBlurAmount = clamping(1, 9);
+const MAX_BLUR_LEVEL = 9;
+const clampBlurAmount = clamping(1, MAX_BLUR_LEVEL);
 /**
  * Blur provided frame
  */
-export const createBlurRenderer = (processor, pass, redOnly = false) => {
+export const createBlurRenderer = (processor, redOnly = false) => {
     const { gl, program, attribLocations, uniformLocations, floatSingleChannelSupported, floatFullChannelSupported, release, } = createGLProgram(processor, {
         attribs: {
             position: 'a_position',
@@ -62,23 +63,19 @@ export const createBlurRenderer = (processor, pass, redOnly = false) => {
     };
     const createFramebufferAndTexture = (idx) => {
         // Avoid fractional value
-        const width = Math.trunc(processor.width / 2 ** idx);
-        const height = Math.trunc(processor.height / 2 ** idx);
+        const width = Math.max(Math.trunc(processor.width / 2 ** idx), 1);
+        const height = Math.max(Math.trunc(processor.height / 2 ** idx), 1);
         const texture = redOnly
             ? createMaskTexture(gl, width, height, true, floatSingleChannelSupported, floatFullChannelSupported)
             : createRGBAFrameTexture(gl, width, height, true, floatFullChannelSupported);
         const frameBuffer = createFrameBuffer(gl, texture);
         return { texture, frameBuffer, width, height };
     };
-    const generateBlurBuffers = (pass, offset = 0) => {
-        const length = Math.max(clampBlurAmount(offset + pass) - offset, 0);
-        return Array.from({
-            length,
-        }).map((_, currentIdx) => createFramebufferAndTexture(offset + currentIdx));
-    };
-    // Generate multiple FrameBuffers, textures and the widths and heights are of size
+    // Allocate all levels upfront, textures and the widths and heights are of size
     // of half of the previous one. E.g. 640x480 -> 320x240 -> 160x120 -> 80x60
-    const blurBuffers = generateBlurBuffers(pass + 1);
+    const blurBuffers = Array.from({
+        length: MAX_BLUR_LEVEL,
+    }).map((_, currentIdx) => createFramebufferAndTexture(currentIdx));
     return {
         render: (frame, pass) => {
             assert(!gl.isContextLost(), RENDERING_EVENTS.ContextLost);
@@ -98,18 +95,7 @@ export const createBlurRenderer = (processor, pass, redOnly = false) => {
             // Dual filter blur
             // Downsampling
             gl.uniform1i(uniformLocations.downsampling, 1);
-            // Adjust pass number accordingly
-            const currentPass = pass + 1;
-            if (currentPass > blurBuffers.length) {
-                for (const buffer of generateBlurBuffers(currentPass - blurBuffers.length, blurBuffers.length)) {
-                    blurBuffers.push(buffer);
-                }
-            }
-            while (currentPass < blurBuffers.length) {
-                const buffer = blurBuffers.pop();
-                gl.deleteTexture(buffer?.texture ?? null);
-                gl.deleteFramebuffer(buffer?.frameBuffer ?? null);
-            }
+            const currentPass = clampBlurAmount(pass + 1);
             // Skip the first pass
             for (let i = 1; i < currentPass; i++) {
                 const { frameBuffer = null, texture = null, width = processor.width, height = processor.height, } = blurBuffers[i] ?? {};
@@ -134,7 +120,7 @@ export const createBlurRenderer = (processor, pass, redOnly = false) => {
             // Upsampling
             gl.uniform1i(uniformLocations.downsampling, 0);
             // Skip the first pass
-            for (let i = pass - 1; i >= 0; i--) {
+            for (let i = currentPass - 2; i >= 0; i--) {
                 const { frameBuffer = null, texture = null, width = processor.width, height = processor.height, } = blurBuffers[i] ?? {};
                 // console.log(`Drawing upsampling pass ${i}, ${width}x${height}`);
                 // Setup to draw to the frame buffer

package/dist/common/backends/webgl/renderer.js

@@ -1,5 +1,5 @@
 import { assert } from '@pexip/utils';
-import { BACKGROUND_BLUR_AMOUNT, PROCESSING_HEIGHT, PROCESSING_WIDTH, RENDERING_EVENTS, STRONG_EDGE_BLUR_AMOUNT, } from '../../constants';
+import { PROCESSING_HEIGHT, PROCESSING_WIDTH, RENDERING_EVENTS, STRONG_EDGE_BLUR_AMOUNT, } from '../../constants';
 import { createLazyProps, handleWebGLContextLoss } from '../../utils';
 import { createBinaryMaskRenderer } from './binaryMask';
 import { createBlendRenderer } from './blender';
@@ -25,7 +25,7 @@ export const createRenderer = (renderEventHandlers, canvas = new OffscreenCanvas
     const rendererCreator = {
         backgroundImageRenderer: () => createTextureRenderer(canvas, false),
         blendRenderer: () => createBlendRenderer(canvas),
-        blurRenderer: () => createBlurRenderer(canvas, BACKGROUND_BLUR_AMOUNT),
+        blurRenderer: () => createBlurRenderer(canvas),
         canvasRenderer: () => createCanvasRenderer(canvas),
         frameDownsampler2: () => createTextureToTextureRenderer(canvas, false, true, halfWidth, halfHeight),
         frameDownsampler4: () => createTextureToTextureRenderer(canvas, false, true, quarterWidth, quarterHeight),
@@ -34,9 +34,9 @@ export const createRenderer = (renderEventHandlers, canvas = new OffscreenCanvas
         jointBilateralFilterRenderer2: () => createJointBilateralFilterRenderer(canvas, halfWidth, halfHeight),
         jointBilateralFilterRenderer4: () => createJointBilateralFilterRenderer(canvas, quarterWidth, quarterHeight),
         jointBilateralFilterRenderer: () => createJointBilateralFilterRenderer(canvas, canvas.width, canvas.height),
-        lightWrapBlurRenderer: () => createBlurRenderer(canvas, BACKGROUND_BLUR_AMOUNT),
+        lightWrapBlurRenderer: () => createBlurRenderer(canvas),
         maskBlurRenderer: () => createTentBlurRenderer(canvas, canvas.width, canvas.height),
-        strongMaskBlurRenderer: () => createBlurRenderer(canvas, STRONG_EDGE_BLUR_AMOUNT),
+        strongMaskBlurRenderer: () => createBlurRenderer(canvas),
         maskDownsampler2: () => createTextureToTextureRenderer(canvas, true, false, halfWidth, halfHeight),
         maskDownsampler4: () => createTextureToTextureRenderer(canvas, true, false, quarterWidth, quarterHeight),
         maskRenderer: () => createTextureRenderer(canvas, true),

package/dist/common/backends/webgpu/dualFilterBlur.js

@@ -2,7 +2,8 @@ import { assert } from '@pexip/utils';
 import { RENDERING_EVENTS } from '../../constants';
 import blurComputeShader from './shaders/dualBlurComputeShader.wgsl';
 import { clamping } from '../../utils';
-const clampBlurAmount = clamping(1, 9);
+const MAX_BLUR_LEVEL = 9;
+const clampBlurAmount = clamping(1, MAX_BLUR_LEVEL);
 export const createBlurRenderer = (device, width, height, textureFormat, isContextLost) => {
     const shaderModule = device.createShaderModule({
         label: 'dual blur compute shader',
@@ -34,103 +35,80 @@ export const createBlurRenderer = (device, width, height, textureFormat, isConte
         addressModeU: 'clamp-to-edge',
         addressModeV: 'clamp-to-edge',
     });
-    // Helper to create a texture of given size
-    const createTexture = (w, h) => device.createTexture({
-        label: 'dual filter blur texture',
-        format: textureFormat,
-        size: [w, h],
-        usage: GPUTextureUsage.TEXTURE_BINDING |
-            GPUTextureUsage.RENDER_ATTACHMENT,
-    });
-    // --- State for persistent textures and bind groups ---
-    let blurTextures = [];
-    let lastWidth = -1;
-    let lastHeight = -1;
-    let downsampleRenderPassDescriptor = [];
-    let upsampleRenderPassDescriptor = [];
-    let downsampleBindGroups = [];
-    let upsampleBindGroups = [];
+    // Allocate all levels upfront at max blur depth
+    const blurTextures = [];
+    for (let i = 0; i < MAX_BLUR_LEVEL; i++) {
+        const w = Math.max(Math.trunc(width / 2 ** i), 1);
+        const h = Math.max(Math.trunc(height / 2 ** i), 1);
+        const texture = device.createTexture({
+            label: `dual filter blur texture level ${i}`,
+            format: textureFormat,
+            size: [w, h],
+            usage: GPUTextureUsage.TEXTURE_BINDING |
+                GPUTextureUsage.RENDER_ATTACHMENT,
+        });
+        blurTextures.push({
+            texture,
+            view: texture.createView(),
+            width: w,
+            height: h,
+        });
+    }
+    // Pre-create all downsample bind groups: blurTextures[i-1] → blurTextures[i]
+    const downsampleBindGroups = [];
+    const downsampleRenderPassDescriptors = [];
+    for (let i = 2; i < MAX_BLUR_LEVEL; i++) {
+        const src = blurTextures[i - 1];
+        const dst = blurTextures[i];
+        assert(src);
+        assert(dst);
+        downsampleBindGroups.push(device.createBindGroup({
+            layout: downsamplePipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: sampler },
+                { binding: 1, resource: src.view },
+            ],
+        }));
+        downsampleRenderPassDescriptors.push({
+            label: `downsample render pass ${i}`,
+            colorAttachments: [
+                { loadOp: 'load', storeOp: 'store', view: dst.view },
+            ],
+        });
+    }
+    // Pre-create all upsample bind groups: blurTextures[i+1] → blurTextures[i]
+    // Index 0 = deepest pair (MAX_BLUR_LEVELS-1 → MAX_BLUR_LEVEL-2)
+    const upsampleBindGroups = [];
+    const upsampleRenderPassDescriptors = [];
+    for (let i = MAX_BLUR_LEVEL - 2; i >= 0; i--) {
+        const src = blurTextures[i + 1];
+        const dst = blurTextures[i];
+        assert(src);
+        assert(dst);
+        upsampleBindGroups.push(device.createBindGroup({
+            layout: upsamplePipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: sampler },
+                { binding: 1, resource: src.view },
+            ],
+        }));
+        upsampleRenderPassDescriptors.push({
+            label: `upsample render pass ${i}`,
+            colorAttachments: [
+                { loadOp: 'load', storeOp: 'store', view: dst.view },
+            ],
+        });
+    }
     let cacheFrameTexture = null;
     let cacheFirstDownsampleBindGroup = null;
     let cacheFirstDownsampleRenderPassDescriptor = null;
-    // Helper to (re)generate textures and bind groups if needed
-    function ensureBlurTextures(pass, frameWidth, frameHeight) {
-        const length = clampBlurAmount(pass + 1);
-        if (blurTextures.length !== length ||
-            lastWidth !== frameWidth ||
-            lastHeight !== frameHeight) {
-            // Destroy old textures
-            for (const t of blurTextures) {
-                t.texture.destroy();
-            }
-            blurTextures = [];
-            downsampleBindGroups = [];
-            downsampleRenderPassDescriptor = [];
-            upsampleBindGroups = [];
-            // Invalidate frame cache since firstDst view has changed
-            cacheFrameTexture = null;
-            cacheFirstDownsampleBindGroup = null;
-            for (let i = 0; i < length; i++) {
-                const w = Math.max(Math.trunc(frameWidth / 2 ** i), 1);
-                const h = Math.max(Math.trunc(frameHeight / 2 ** i), 1);
-                const texture = createTexture(w, h);
-                blurTextures.push({
-                    texture,
-                    view: texture.createView(),
-                    width: w,
-                    height: h,
-                });
-            }
-            // Pre-create downsample bind groups: blurTextures[i-1] → blurTextures[i]
-            for (let i = 2; i < blurTextures.length; i++) {
-                const src = blurTextures[i - 1];
-                const dst = blurTextures[i];
-                assert(src);
-                assert(dst);
-                downsampleBindGroups.push(device.createBindGroup({
-                    layout: downsamplePipeline.getBindGroupLayout(0),
-                    entries: [
-                        { binding: 0, resource: sampler },
-                        { binding: 1, resource: src.view },
-                    ],
-                }));
-                downsampleRenderPassDescriptor.push({
-                    label: `downsample render pass ${i}`,
-                    colorAttachments: [
-                        { loadOp: 'load', storeOp: 'store', view: dst.view },
-                    ],
-                });
-            }
-            // Pre-create upsample bind groups: blurTextures[i+1] → blurTextures[i]
-            // Filled in descending order so upsampleBindGroups[0] is the deepest pair.
-            for (let i = blurTextures.length - 2; i >= 0; i--) {
-                const src = blurTextures[i + 1];
-                const dst = blurTextures[i];
-                assert(src);
-                assert(dst);
-                upsampleBindGroups.push(device.createBindGroup({
-                    layout: upsamplePipeline.getBindGroupLayout(0),
-                    entries: [
-                        { binding: 0, resource: sampler },
-                        { binding: 1, resource: src.view },
-                    ],
-                }));
-                upsampleRenderPassDescriptor.push({
-                    label: `upsample render pass ${i}`,
-                    colorAttachments: [
-                        { loadOp: 'load', storeOp: 'store', view: dst.view },
-                    ],
-                });
-            }
-            lastWidth = frameWidth;
-            lastHeight = frameHeight;
-        }
-    }
     return {
         render: (encoder, frame, pass) => {
             assert(!isContextLost(), RENDERING_EVENTS.ContextLost);
-            // Ensure textures and bind groups are up-to-date
-            ensureBlurTextures(pass, width, height);
+            if (!pass) {
+                return frame;
+            }
+            const length = clampBlurAmount(pass + 1);
             const firstDst = blurTextures[1];
             assert(firstDst);
             // Cache the first downsample bind group (frame → blurTextures[1])
@@ -158,34 +136,34 @@ export const createBlurRenderer = (device, width, height, textureFormat, isConte
             firstComputePass.draw(3);
             firstComputePass.end();
             // Subsequent downsampling passes: blurTextures[i-1] → blurTextures[i]
-            for (let i = 2; i < blurTextures.length; i++) {
+            for (let i = 2; i < length; i++) {
                 const dst = blurTextures[i];
                 assert(dst);
                 // downsampleBindGroups[i-1] covers blurTextures[i-1] → blurTextures[i]
                 const bindGroup = downsampleBindGroups[i - 2];
-                const renderPassDescriptor = downsampleRenderPassDescriptor[i - 2];
+                const renderPassDescriptor = downsampleRenderPassDescriptors[i - 2];
                 assert(bindGroup);
                 assert(renderPassDescriptor);
-                const pass = encoder.beginRenderPass(renderPassDescriptor);
-                pass.setPipeline(downsamplePipeline);
-                pass.setBindGroup(0, bindGroup);
-                pass.draw(3);
-                pass.end();
+                const renderPass = encoder.beginRenderPass(renderPassDescriptor);
+                renderPass.setPipeline(downsamplePipeline);
+                renderPass.setBindGroup(0, bindGroup);
+                renderPass.draw(3);
+                renderPass.end();
             }
             // Upsampling passes (deepest level first, up to blurTextures[0])
-            for (let i = 0; i < upsampleBindGroups.length; i++) {
-                const dstIdx = blurTextures.length - 2 - i;
-                const dst = blurTextures[dstIdx];
-                assert(dst);
+            // upsampleBindGroups are indexed from deepest (MAX-2 → MAX-1) at [0]
+            // We need to start from the pair ending at `length-1` and go up to 0
+            const upsampleStartIdx = MAX_BLUR_LEVEL - 1 - (length - 1);
+            for (let i = upsampleStartIdx; i < upsampleBindGroups.length; i++) {
                 const bindGroup = upsampleBindGroups[i];
-                const renderPassDescriptor = upsampleRenderPassDescriptor[i];
+                const renderPassDescriptor = upsampleRenderPassDescriptors[i];
                 assert(bindGroup);
                 assert(renderPassDescriptor);
-                const pass = encoder.beginRenderPass(renderPassDescriptor);
-                pass.setPipeline(upsamplePipeline);
-                pass.setBindGroup(0, bindGroup);
-                pass.draw(3);
-                pass.end();
+                const renderPass = encoder.beginRenderPass(renderPassDescriptor);
+                renderPass.setPipeline(upsamplePipeline);
+                renderPass.setBindGroup(0, bindGroup);
+                renderPass.draw(3);
+                renderPass.end();
             }
             const finalTexture = blurTextures[0];
             assert(finalTexture);
@@ -195,13 +173,14 @@ export const createBlurRenderer = (device, width, height, textureFormat, isConte
             for (const t of blurTextures) {
                 t.texture.destroy();
             }
-            blurTextures = [];
-            downsampleRenderPassDescriptor = [];
-            upsampleRenderPassDescriptor = [];
-            downsampleBindGroups = [];
-            upsampleBindGroups = [];
+            blurTextures.length = 0;
+            downsampleBindGroups.length = 0;
+            downsampleRenderPassDescriptors.length = 0;
+            upsampleBindGroups.length = 0;
+            upsampleRenderPassDescriptors.length = 0;
             cacheFrameTexture = null;
             cacheFirstDownsampleBindGroup = null;
+            cacheFirstDownsampleRenderPassDescriptor = null;
         },
     };
 };

package/dist/common/canvasRenderUtils.d.ts

@@ -1,4 +1,23 @@
-import type { Segmentation } from './types/media';
+/**
+ * Create a reusable converter that transforms a single-channel mask into
+ * RGBA ImageData with values written into the alpha channel.
+ * The returned function reuses the same ImageData buffer across calls.
+ *
+ * @example
+ * ```ts
+ * const toAlphaMask = createAlphaMaskConverter();
+ * const imageData = toAlphaMask(mask);
+ * ctx.putImageData(imageData, 0, 0);
+ * ```
+ */
+export declare const createAlphaMaskConverter: () => (mask: {
+    getAsUint8Array(): Uint8Array;
+    width: number;
+    height: number;
+}) => ImageData;
+export declare const createCpuMaskRenderer: (canvas: OffscreenCanvas) => {
+    render: (imageData: ImageData) => void;
+};
 declare const INTERNAL_CANVAS_KEYS: {
     readonly drawImageDataCanvas: "drawImageDataCanvas";
     readonly maskCanvas: "maskCanvas";
@@ -52,12 +71,12 @@ export declare const clearCanvas: (canvas: OffscreenCanvas) => void;
 export declare const createCanvasRenderUtils: (processingWidth: number, processingHeight: number) => {
     evaluateInput: (inputImage: CanvasImageSource) => OffscreenCanvas;
     renderImageToCanvas: (image: CanvasImageSource, canvas: OffscreenCanvas, dw?: number, dh?: number, options?: CanvasRenderingContext2DOptions) => void;
-    drawBlurEffect: (canvas: OffscreenCanvas, inputImage: CanvasImageSource, segmentations: Segmentation | Segmentation[], foregroundThreshold?: number, backgroundBlurAmount?: number, edgeBlurAmount?: number, flipHorizontal?: boolean) => void;
-    drawOverlayEffect: (canvas: OffscreenCanvas, inputImage: CanvasImageSource, backgroundImage: CanvasImageSource | OffscreenCanvas, segmentations: Segmentation | Segmentation[], foregroundThreshold?: number, backgroundBlurAmount?: number, edgeBlurAmount?: number, flipHorizontal?: boolean) => void;
+    drawBlurEffect: (canvas: OffscreenCanvas, inputImage: CanvasImageSource, mask: CanvasImageSource | OffscreenCanvas, foregroundThreshold?: number, backgroundBlurAmount?: number, edgeBlurAmount?: number, flipHorizontal?: boolean) => void;
+    drawOverlayEffect: (canvas: OffscreenCanvas, inputImage: CanvasImageSource, backgroundImage: CanvasImageSource | OffscreenCanvas, mask: CanvasImageSource | OffscreenCanvas, foregroundThreshold?: number, backgroundBlurAmount?: number, edgeBlurAmount?: number, flipHorizontal?: boolean) => void;
     renderImageToOffScreenCanvas: (image: CanvasImageSource, canvasName: keyof InternalCanvases) => OffscreenCanvas;
     renderImageDataToOffScreenCanvas: (image: ImageData, canvasName: keyof InternalCanvases) => OffscreenCanvas;
     drawAndBlurImageOnOffScreenCanvas: ({ image, blurAmount, offscreenCanvasName, preserveOldDrawing, }: {
-        image: CanvasImageSource;
+        image: CanvasImageSource | OffscreenCanvas;
         blurAmount: number;
         offscreenCanvasName: keyof InternalCanvases;
         preserveOldDrawing?: boolean;