typegpu 0.12.5 → 0.12.7

package/core/texture/texture.js

@@ -5,7 +5,8 @@ import { getName, setName } from "../../shared/meta.js";
 import { getTextureFormatInfo, } from "./textureFormats.js";
 import { $gpuValueOf, $internal, $ownSnippet, $repr, $resolve, $soul, } from "../../shared/symbols.js";
 import { valueProxyHandler } from "../valueProxyUtils.js";
-import { generateTextureMipmaps, getImageSourceDimensions, resampleImage } from "./textureUtils.js";
+import { clearTextureWithColor, generateTextureMipmaps, writeImages } from "./textureUtils.js";
+import { mipLevelSize, origin3d, resolveImageWrite, writeRegionSize, } from "./textureWrite.js";
 import { logger } from "../../tgpuLogger.js";
 function getDescriptorForProps(props) {
     return {
@@ -128,28 +129,25 @@ class TgpuTextureImpl {
         return new TgpuFixedTextureViewImpl(schema ?? textureDescriptorToSchema(getDescriptorForProps(this.props)), this, viewDescriptor);
     }
     #clearMipLevel(mip = 0) {
-        const scale = 2 ** mip;
-        const [width, height, depth] = [
-            Math.max(1, Math.floor((this.props.size[0] ?? 1) / scale)),
-            Math.max(1, Math.floor((this.props.size[1] ?? 1) / scale)),
-            Math.max(1, Math.floor((this.props.size[2] ?? 1) / scale)),
-        ];
+        const [width, height, depth] = mipLevelSize(this.props, mip);
         const texelSize = this.#formatInfo.texelSize;
         if (texelSize === 'non-copyable') {
             throw new Error(`Cannot clear texture with format '${this.props.format}': this format does not support copy operations.`);
         }
         this[$soul].device.queue.writeTexture({ texture: this[$internal].materialize(), mipLevel: mip }, new Uint8Array(width * height * depth * texelSize), { bytesPerRow: texelSize * width, rowsPerImage: height }, [width, height, depth]);
     }
-    clear(mipLevel = 'all') {
-        if (mipLevel === 'all') {
-            const mipLevels = this.props.mipLevelCount ?? 1;
-            for (let i = 0; i < mipLevels; i++) {
-                this.#clearMipLevel(i);
+    clear(colorOrMipLevel = 'all', mipLevel = 'all') {
+        const mipLevels = (level) => level === 'all' ? [...Array(this.props.mipLevelCount ?? 1).keys()] : [level];
+        if (typeof colorOrMipLevel !== 'object') {
+            for (const mip of mipLevels(colorOrMipLevel)) {
+                this.#clearMipLevel(mip);
             }
+            return;
         }
-        else {
-            this.#clearMipLevel(mipLevel);
+        if (!this.usableAsRender) {
+            throw new Error("texture.clear(color) requires 'render' usage. Add it via the $usage('render') method.");
         }
+        clearTextureWithColor(this[$soul].device, this[$internal].materialize(), colorOrMipLevel, mipLevels(mipLevel));
     }
     generateMipmaps(baseMipLevel = 0, mipLevels) {
         if (!this.usableAsRender) {
@@ -165,81 +163,88 @@ class TgpuTextureImpl {
         }
         generateTextureMipmaps(this[$soul].device, this[$internal].materialize(), baseMipLevel, actualMipLevels);
     }
-    write(source, optionsOrMipLevel = 0) {
+    write(source, options = {}) {
         if (source instanceof ArrayBuffer || ArrayBuffer.isView(source)) {
-            this.#writeBufferData(source, typeof optionsOrMipLevel === 'number' ? optionsOrMipLevel : 0);
+            this.#writeBufferData(source, typeof options === 'number' ? { mipLevel: options } : options);
             return;
         }
         if (!this.usableAsRender) {
             throw new Error("texture.write(...) with image sources requires 'render' usage. Add it via the $usage('render') method.");
         }
-        const options = typeof optionsOrMipLevel === 'number' ? undefined : optionsOrMipLevel;
-        const dimension = this.props.dimension ?? '2d';
-        const isArray = Array.isArray(source);
-        if (!isArray) {
-            this.#writeSingleLayer(source, dimension === '3d' ? 0 : undefined, options);
-            return;
+        const imageOptions = options;
+        const sources = Array.isArray(source) ? source : [source];
+        const baseLayer = imageOptions.origin?.[2] ?? 0;
+        const layerCount = mipLevelSize(this.props, imageOptions.mipLevel ?? 0)[2];
+        if (baseLayer + sources.length > layerCount) {
+            logger.warn('suspicious', `Too many image sources provided. Texture has ${layerCount} layers, got ${sources.length} sources starting at layer ${baseLayer}. Extra sources will be ignored.`);
         }
-        const layerCount = this.props.size[2] ?? 1;
-        if (source.length > layerCount) {
-            logger.warn('suspicious', `Too many image sources provided. Expected ${layerCount} layers, got ${source.length}. Extra sources will be ignored.`);
-        }
-        for (let layer = 0; layer < Math.min(source.length, layerCount); layer++) {
-            const bitmap = source[layer];
-            if (bitmap) {
-                this.#writeSingleLayer(bitmap, layer, options);
+        writeImages(this[$soul].device, this[$internal].materialize(), sources
+            .slice(0, layerCount - baseLayer)
+            .map((image, i) => resolveImageWrite(this.props, image, imageOptions, baseLayer + i)));
+    }
+    async writeAsync(source, options = {}) {
+        const [resizeWidth, resizeHeight] = writeRegionSize(this.props, options);
+        const bitmap = await createImageBitmap(source, options.fit === 'stretch'
+            ? {
+                resizeWidth,
+                resizeHeight,
+                resizeQuality: options.filter === 'nearest' ? 'pixelated' : 'high',
             }
+            : undefined);
+        try {
+            this.write(bitmap, options);
+        }
+        finally {
+            bitmap.close();
         }
     }
-    #writeBufferData(source, mipLevel) {
-        const mipWidth = Math.max(1, this.props.size[0] >> mipLevel);
-        const mipHeight = Math.max(1, (this.props.size[1] ?? 1) >> mipLevel);
-        const mipDepth = Math.max(1, (this.props.size[2] ?? 1) >> mipLevel);
+    #writeBufferData(source, options) {
         const texelSize = this.#formatInfo.texelSize;
         if (texelSize === 'non-copyable') {
             throw new Error(`Cannot write to texture with format '${this.props.format}': this format does not support copy operations.`);
         }
-        const expectedSize = mipWidth * mipHeight * mipDepth * texelSize;
-        const actualSize = source.byteLength ?? source.byteLength;
-        if (actualSize !== expectedSize) {
-            throw new Error(`Buffer size mismatch. Expected ${expectedSize} bytes for mip level ${mipLevel}, got ${actualSize} bytes.`);
+        const mipLevel = options.mipLevel ?? 0;
+        const [mipWidth, mipHeight, mipDepth] = mipLevelSize(this.props, mipLevel);
+        const origin = origin3d(options.origin);
+        const width = options.size?.[0] ?? mipWidth - origin.x;
+        const height = options.size?.[1] ?? mipHeight - origin.y;
+        const depth = options.size?.[2] ?? mipDepth - origin.z;
+        const expectedSize = width * height * depth * texelSize;
+        if (source.byteLength !== expectedSize) {
+            throw new Error(`Buffer size mismatch. Expected ${expectedSize} bytes for mip level ${mipLevel}, got ${source.byteLength} bytes.`);
         }
         this[$soul].device.queue.writeTexture({
             texture: this[$internal].materialize(),
             mipLevel,
-        }, 'buffer' in source ? source.buffer : source, {
-            bytesPerRow: texelSize * mipWidth,
-            rowsPerImage: mipHeight,
-        }, [mipWidth, mipHeight, mipDepth]);
-    }
-    #writeSingleLayer(source, layer, options) {
-        const targetWidth = this.props.size[0];
-        const targetHeight = this.props.size[1] ?? 1;
-        const { width: sourceWidth, height: sourceHeight } = getImageSourceDimensions(source);
-        const needsResampling = sourceWidth !== targetWidth || sourceHeight !== targetHeight;
-        if (needsResampling) {
-            if (options?.fit !== 'stretch') {
-                throw new Error(`Texture write source size ${sourceWidth}x${sourceHeight} does not match target size ${targetWidth}x${targetHeight}. Pass fit: 'stretch' to resize explicitly.`);
-            }
-            resampleImage(this[$soul].device, this[$internal].materialize(), source, layer);
-            return;
-        }
-        this[$soul].device.queue.copyExternalImageToTexture({ source }, {
-            texture: this[$internal].materialize(),
-            ...(layer !== undefined && { origin: { x: 0, y: 0, z: layer } }),
-        }, layer !== undefined ? [targetWidth, targetHeight, 1] : this.props.size);
+            origin,
+        }, source, {
+            bytesPerRow: texelSize * width,
+            rowsPerImage: height,
+        }, [width, height, depth]);
     }
-    copyFrom(source) {
+    copyFrom(source, options) {
         if (source.props.format !== this.props.format) {
             throw new Error(`Texture format mismatch. Source texture has format ${source.props.format}, target texture has format ${this.props.format}`);
         }
-        if (source.props.size[0] !== this.props.size[0] ||
-            (source.props.size[1] ?? 1) !== (this.props.size[1] ?? 1) ||
-            (source.props.size[2] ?? 1) !== (this.props.size[2] ?? 1)) {
-            throw new Error(`Texture size mismatch. Source texture has size ${source.props.size.join('x')}, target texture has size ${this.props.size.join('x')}`);
+        if (!options &&
+            (source.props.size[0] !== this.props.size[0] ||
+                (source.props.size[1] ?? 1) !== (this.props.size[1] ?? 1) ||
+                (source.props.size[2] ?? 1) !== (this.props.size[2] ?? 1))) {
+            throw new Error(`Texture size mismatch. Source texture has size ${source.props.size.join('x')}, target texture has size ${this.props.size.join('x')}. Pass copy options to copy a region.`);
         }
+        const sourceMipLevel = options?.sourceMipLevel ?? 0;
+        const sourceOrigin = origin3d(options?.sourceOrigin);
+        const [sourceWidth, sourceHeight, sourceDepth] = mipLevelSize(source.props, sourceMipLevel);
         const commandEncoder = this[$soul].device.createCommandEncoder();
-        commandEncoder.copyTextureToTexture({ texture: source[$internal].materialize() }, { texture: this[$internal].materialize() }, source.props.size);
+        commandEncoder.copyTextureToTexture({ texture: source[$internal].materialize(), mipLevel: sourceMipLevel, origin: sourceOrigin }, {
+            texture: this[$internal].materialize(),
+            mipLevel: options?.mipLevel ?? 0,
+            origin: origin3d(options?.origin),
+        }, [
+            options?.size?.[0] ?? sourceWidth - sourceOrigin.x,
+            options?.size?.[1] ?? sourceHeight - sourceOrigin.y,
+            options?.size?.[2] ?? sourceDepth - sourceOrigin.z,
+        ]);
         this[$soul].device.queue.submit([commandEncoder.finish()]);
     }
     toString() {
@@ -400,10 +405,14 @@ export class TgpuTextureRenderViewImpl {
         };
         this[$internal] = {
             unwrap: () => {
-                return baseTexture[$internal].materialize().createView({
-                    label: getName(this) ?? '<unnamed>',
-                    ...this.descriptor,
-                });
+                const soul = this[$soul];
+                if (!soul.raw) {
+                    soul.raw = soul.texture[$internal].materialize().createView({
+                        label: getName(this) ?? '<unnamed>',
+                        ...soul.descriptor,
+                    });
+                }
+                return soul.raw;
             },
             format: descriptor.format ?? baseTexture.props.format,
             aspect: descriptor.aspect,

package/core/texture/textureUtils.d.ts

@@ -1,8 +1,5 @@
-import type { ExternalImageSource } from './texture.ts';
-export declare function getImageSourceDimensions(source: ExternalImageSource): {
-    width: number;
-    height: number;
-};
+import { type ImageWrite } from './textureWrite.ts';
 export declare function clearTextureUtilsCache(device: GPUDevice): void;
 export declare function generateTextureMipmaps(device: GPUDevice, texture: GPUTexture, baseMipLevel?: number, mipLevels?: number): void;
-export declare function resampleImage(device: GPUDevice, targetTexture: GPUTexture, image: ExternalImageSource, layer?: number): void;
+export declare function clearTextureWithColor(device: GPUDevice, texture: GPUTexture, color: readonly [number, number, number, number], mipLevels: readonly number[]): void;
+export declare function writeImages(device: GPUDevice, texture: GPUTexture, writes: readonly ImageWrite[]): void;

package/core/texture/textureUtils.js

@@ -1,23 +1,5 @@
 import { getEffectiveSampleTypes, getTextureFormatInfo } from "./textureFormats.js";
-export function getImageSourceDimensions(source) {
-    const { videoWidth, videoHeight } = source;
-    if (videoWidth && videoHeight) {
-        return { width: videoWidth, height: videoHeight };
-    }
-    const { naturalWidth, naturalHeight } = source;
-    if (naturalWidth && naturalHeight) {
-        return { width: naturalWidth, height: naturalHeight };
-    }
-    const { codedWidth, codedHeight } = source;
-    if (codedWidth && codedHeight) {
-        return { width: codedWidth, height: codedHeight };
-    }
-    const { width, height } = source;
-    if (width && height) {
-        return { width, height };
-    }
-    throw new Error('Cannot determine dimensions of the provided image source.');
-}
+import { sameSize } from "./textureWrite.js";
 const FULLSCREEN_VERTEX_SHADER = `
 struct VertexOutput {
   @builtin(position) pos: vec4f,
@@ -30,13 +12,13 @@ fn vs_main(@builtin(vertex_index) i: u32) -> VertexOutput {
   const uv = array(vec2f(0, 1), vec2f(2, 1), vec2f(0, -1));
   return VertexOutput(vec4f(pos[i], 0, 1), uv[i]);
 }`;
-const SAMPLE_FRAGMENT_SHADER = `
+const sampleFragmentShader = (channel) => `
 @group(0) @binding(0) var src: texture_2d<f32>;
 @group(0) @binding(1) var samp: sampler;
 
 @fragment
 fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
-  return textureSample(src, samp, uv);
+  return textureSample(src, samp, uv)${channel ? `.${channel.repeat(4)}` : ''};
 }`;
 const GATHER_FRAGMENT_SHADER = `
 @group(0) @binding(0) var src: texture_2d<f32>;
@@ -50,181 +32,176 @@ fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
   let a = textureGather(3, src, samp, uv);
   return vec4f(dot(r, vec4f(0.25)), dot(g, vec4f(0.25)), dot(b, vec4f(0.25)), dot(a, vec4f(0.25)));
 }`;
-const blitCache = new WeakMap();
-function getOrCreateDeviceCache(device) {
-    let cache = blitCache.get(device);
+const CHANNEL_WRITE_MASKS = { r: 0x1, g: 0x2, b: 0x4, a: 0x8 };
+const deviceCaches = new WeakMap();
+function cached(device, key, create) {
+    let cache = deviceCaches.get(device);
     if (!cache) {
-        cache = {
-            vertexModule: device.createShaderModule({
-                code: FULLSCREEN_VERTEX_SHADER,
-            }),
-            filterableResources: new Map(),
-            layoutResources: new Map(),
-        };
-        blitCache.set(device, cache);
-    }
-    return cache;
-}
-function getBlitResources(device, filterable, sampleType) {
-    const cache = getOrCreateDeviceCache(device);
-    let filterableRes = cache.filterableResources.get(filterable);
-    if (!filterableRes) {
-        filterableRes = {
-            fragmentModule: device.createShaderModule({
-                code: filterable ? SAMPLE_FRAGMENT_SHADER : GATHER_FRAGMENT_SHADER,
-            }),
-            sampler: device.createSampler(filterable ? { magFilter: 'linear', minFilter: 'linear' } : {}),
-        };
-        cache.filterableResources.set(filterable, filterableRes);
+        cache = new Map();
+        deviceCaches.set(device, cache);
     }
-    const layoutKey = `${filterable}:${sampleType}`;
-    let layoutRes = cache.layoutResources.get(layoutKey);
-    if (!layoutRes) {
-        const bindGroupLayout = device.createBindGroupLayout({
-            entries: [
-                {
-                    binding: 0,
-                    visibility: GPUShaderStage.FRAGMENT,
-                    texture: { sampleType },
-                },
-                {
-                    binding: 1,
-                    visibility: GPUShaderStage.FRAGMENT,
-                    sampler: { type: filterable ? 'filtering' : 'non-filtering' },
-                },
-            ],
-        });
-        layoutRes = {
-            bindGroupLayout,
-            pipelineLayout: device.createPipelineLayout({
-                bindGroupLayouts: [bindGroupLayout],
-            }),
-        };
-        cache.layoutResources.set(layoutKey, layoutRes);
+    if (!cache.has(key)) {
+        cache.set(key, create());
     }
-    return {
-        vertexModule: cache.vertexModule,
-        ...filterableRes,
-        ...layoutRes,
-    };
+    return cache.get(key);
 }
-function blit(options) {
-    const { device, source, destination, format, filterable, sampleType } = options;
-    const resources = getBlitResources(device, filterable, sampleType);
-    const pipeline = device.createRenderPipeline({
-        layout: resources.pipelineLayout,
-        vertex: { module: resources.vertexModule },
-        fragment: { module: resources.fragmentModule, targets: [{ format }] },
-        primitive: { topology: 'triangle-list' },
-    });
-    const bindGroup = device.createBindGroup({
-        layout: resources.bindGroupLayout,
+export function clearTextureUtilsCache(device) {
+    deviceCaches.delete(device);
+}
+function blit(device, encoder, { format, filterable, filter = 'linear', channel }, source, attachment, viewport) {
+    const sampleType = filterable ? 'float' : 'unfilterable-float';
+    const bindGroupLayout = cached(device, `layout:${sampleType}`, () => device.createBindGroupLayout({
         entries: [
-            { binding: 0, resource: source },
-            { binding: 1, resource: resources.sampler },
-        ],
-    });
-    const ownEncoder = !options.encoder;
-    const encoder = options.encoder ?? device.createCommandEncoder();
-    const pass = encoder.beginRenderPass({
-        colorAttachments: [
+            { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType } },
             {
-                view: destination,
-                loadOp: 'clear',
-                storeOp: 'store',
+                binding: 1,
+                visibility: GPUShaderStage.FRAGMENT,
+                sampler: { type: filterable ? 'filtering' : 'non-filtering' },
             },
         ],
+    }));
+    const channelKey = channel ? `${channel.from}${channel.to}` : '';
+    const pipeline = cached(device, `pipeline:${format}:${sampleType}:${channelKey}`, () => device.createRenderPipeline({
+        layout: cached(device, `pipelineLayout:${sampleType}`, () => device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] })),
+        vertex: {
+            module: cached(device, 'vertex', () => device.createShaderModule({ code: FULLSCREEN_VERTEX_SHADER })),
+        },
+        fragment: {
+            module: cached(device, `fragment:${sampleType}:${channel?.from ?? ''}`, () => device.createShaderModule({
+                code: filterable ? sampleFragmentShader(channel?.from) : GATHER_FRAGMENT_SHADER,
+            })),
+            targets: [channel ? { format, writeMask: CHANNEL_WRITE_MASKS[channel.to] } : { format }],
+        },
+    }));
+    const sampler = cached(device, `sampler:${filterable && filter}`, () => device.createSampler(filterable ? { magFilter: filter, minFilter: filter } : {}));
+    const bindGroup = device.createBindGroup({
+        layout: bindGroupLayout,
+        entries: [
+            { binding: 0, resource: source },
+            { binding: 1, resource: sampler },
+        ],
     });
+    const pass = encoder.beginRenderPass({ colorAttachments: [attachment] });
+    if (viewport) {
+        pass.setViewport(...viewport, 0, 1);
+        pass.setScissorRect(...viewport);
+    }
     pass.setPipeline(pipeline);
     pass.setBindGroup(0, bindGroup);
     pass.draw(3);
     pass.end();
-    if (ownEncoder) {
-        device.queue.submit([encoder.finish()]);
-    }
 }
-export function clearTextureUtilsCache(device) {
-    blitCache.delete(device);
+function layerView(texture, mipLevel, layer) {
+    const is3d = texture.dimension === '3d';
+    return texture.createView({
+        dimension: is3d ? '3d' : '2d',
+        baseMipLevel: mipLevel,
+        mipLevelCount: 1,
+        baseArrayLayer: is3d ? 0 : layer,
+        arrayLayerCount: 1,
+    });
 }
-function validateBlitFormat(device, format, operation) {
-    const info = getTextureFormatInfo(format);
-    const effectiveSampleTypes = getEffectiveSampleTypes(device, format);
-    const isFloat = effectiveSampleTypes.includes('float');
-    const isUnfilterableFloat = effectiveSampleTypes.includes('unfilterable-float');
-    if (!isFloat && !isUnfilterableFloat) {
-        throw new Error(`Cannot ${operation} for format '${format}': only float formats are supported.`);
-    }
-    if (!info.canRenderAttachment) {
-        throw new Error(`Cannot ${operation} for format '${format}': format does not support render attachments.`);
-    }
+function layerAttachment(texture, mipLevel, layer, loadOp) {
     return {
-        filterable: isFloat,
-        sampleType: isFloat ? 'float' : 'unfilterable-float',
+        view: layerView(texture, mipLevel, layer),
+        ...(texture.dimension === '3d' && { depthSlice: layer }),
+        loadOp,
+        storeOp: 'store',
     };
 }
 export function generateTextureMipmaps(device, texture, baseMipLevel = 0, mipLevels) {
     if (texture.dimension !== '2d') {
         throw new Error('Mipmap generation only supports 2D textures.');
     }
-    const { filterable, sampleType } = validateBlitFormat(device, texture.format, 'generate mipmaps');
+    const { format } = texture;
+    const sampleTypes = getEffectiveSampleTypes(device, format);
+    const filterable = sampleTypes.includes('float');
+    if (!filterable && !sampleTypes.includes('unfilterable-float')) {
+        throw new Error(`Cannot generate mipmaps for format '${format}': only float formats are supported.`);
+    }
+    if (!getTextureFormatInfo(format).canRenderAttachment) {
+        throw new Error(`Cannot generate mipmaps for format '${format}': format does not support render attachments.`);
+    }
     const levels = mipLevels ?? texture.mipLevelCount - baseMipLevel;
+    const encoder = device.createCommandEncoder();
     for (let layer = 0; layer < texture.depthOrArrayLayers; layer++) {
         for (let mip = baseMipLevel; mip < baseMipLevel + levels - 1; mip++) {
-            const viewOptions = (level) => ({
-                dimension: '2d',
-                baseMipLevel: level,
-                mipLevelCount: 1,
-                baseArrayLayer: layer,
-                arrayLayerCount: 1,
-            });
-            blit({
-                device,
-                source: texture.createView(viewOptions(mip)),
-                destination: texture.createView(viewOptions(mip + 1)),
-                format: texture.format,
-                filterable,
-                sampleType,
-            });
+            blit(device, encoder, { format, filterable }, layerView(texture, mip, layer), layerAttachment(texture, mip + 1, layer, 'clear'));
         }
     }
+    device.queue.submit([encoder.finish()]);
 }
-export function resampleImage(device, targetTexture, image, layer = 0) {
-    if (targetTexture.dimension !== '2d') {
-        throw new Error('Resampling only supports 2D textures.');
+export function clearTextureWithColor(device, texture, color, mipLevels) {
+    const encoder = device.createCommandEncoder();
+    for (const mipLevel of mipLevels) {
+        const layers = texture.dimension === '3d'
+            ? Math.max(1, texture.depthOrArrayLayers >> mipLevel)
+            : texture.depthOrArrayLayers;
+        for (let layer = 0; layer < layers; layer++) {
+            encoder
+                .beginRenderPass({
+                colorAttachments: [
+                    { ...layerAttachment(texture, mipLevel, layer, 'clear'), clearValue: [...color] },
+                ],
+            })
+                .end();
+        }
     }
-    const { filterable } = validateBlitFormat(device, targetTexture.format, 'resample');
-    const { width, height } = getImageSourceDimensions(image);
-    const inputTexture = device.createTexture({
-        size: [width, height],
-        format: 'rgba8unorm',
+    device.queue.submit([encoder.finish()]);
+}
+function copyImage(device, write, destination, size) {
+    const { flipY = false, premultipliedAlpha = false, colorSpace = 'srgb' } = write.options;
+    device.queue.copyExternalImageToTexture({ source: write.source, origin: write.sourceOrigin, flipY }, { ...destination, premultipliedAlpha, colorSpace }, size);
+}
+function stageImage(device, write, format) {
+    const texture = device.createTexture({
+        size: write.sourceSize,
+        format,
         usage: GPUTextureUsage.TEXTURE_BINDING |
+            GPUTextureUsage.COPY_SRC |
             GPUTextureUsage.COPY_DST |
             GPUTextureUsage.RENDER_ATTACHMENT,
     });
-    device.queue.copyExternalImageToTexture({ source: image }, {
-        texture: inputTexture,
-    }, [width, height]);
-    const renderTexture = device.createTexture({
-        size: [targetTexture.width, targetTexture.height],
-        format: targetTexture.format,
-        usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
-    });
-    const encoder = device.createCommandEncoder();
-    blit({
-        device,
-        source: inputTexture.createView(),
-        destination: renderTexture.createView(),
-        format: targetTexture.format,
-        filterable,
-        sampleType: 'float', // Input is always rgba8unorm which is filterable
-        encoder,
-    });
-    encoder.copyTextureToTexture({ texture: renderTexture }, { texture: targetTexture, origin: { x: 0, y: 0, z: layer } }, {
-        width: targetTexture.width,
-        height: targetTexture.height,
-        depthOrArrayLayers: 1,
-    });
-    device.queue.submit([encoder.finish()]);
-    inputTexture.destroy();
-    renderTexture.destroy();
+    copyImage(device, write, { texture }, write.sourceSize);
+    return texture;
+}
+function stagingFormat(format) {
+    if (format.endsWith('-srgb')) {
+        return format;
+    }
+    return format.endsWith('8unorm') ? 'rgba8unorm' : 'rgba16float';
+}
+export function writeImages(device, texture, writes) {
+    const isCopy = (write) => !write.channel && sameSize(write.sourceSize, write.size);
+    const bySource = new Map();
+    for (const write of writes) {
+        if (isCopy(write) && texture.dimension === '2d') {
+            copyImage(device, write, { texture, mipLevel: write.mipLevel, origin: write.origin }, write.size);
+        }
+        else {
+            bySource.set(write.source, [...(bySource.get(write.source) ?? []), write]);
+        }
+    }
+    for (const group of bySource.values()) {
+        const encoder = device.createCommandEncoder();
+        let staged;
+        for (const write of group) {
+            if (isCopy(write)) {
+                // copyExternalImageToTexture only accepts 2d destinations, so 3d writes stage through a 2d texture
+                staged ??= stageImage(device, write, texture.format);
+                encoder.copyTextureToTexture({ texture: staged }, { texture, mipLevel: write.mipLevel, origin: write.origin }, [...write.size, 1]);
+            }
+            else {
+                staged ??= stageImage(device, write, stagingFormat(texture.format));
+                blit(device, encoder, {
+                    format: texture.format,
+                    filterable: true,
+                    filter: write.options.filter,
+                    channel: write.channel,
+                }, staged.createView(), layerAttachment(texture, write.mipLevel, write.origin.z, 'load'), [write.origin.x, write.origin.y, ...write.size]);
+            }
+        }
+        device.queue.submit([encoder.finish()]);
+        staged?.destroy();
+    }
 }

package/core/texture/textureWrite.d.ts

@@ -0,0 +1,61 @@
+import type { TextureProps } from './textureProps.ts';
+export type TextureWriteFit = 'stretch' | 'clip';
+export type TextureWriteOptions = {
+    mipLevel?: GPUIntegerCoordinate;
+    origin?: readonly [x: number, y: number, z?: number];
+    size?: readonly [width: number, height: number];
+    sourceOrigin?: readonly [x: number, y: number];
+    sourceSize?: readonly [width: number, height: number];
+    fit?: TextureWriteFit;
+    filter?: GPUFilterMode;
+    flipY?: boolean;
+    premultipliedAlpha?: boolean;
+    colorSpace?: PredefinedColorSpace;
+};
+export type TextureBlobWriteOptions = Omit<TextureWriteOptions, 'sourceOrigin' | 'sourceSize'>;
+export type TextureChannel = 'r' | 'g' | 'b' | 'a';
+export type TextureRawWriteOptions = {
+    mipLevel?: GPUIntegerCoordinate;
+    origin?: readonly [x: number, y: number, z?: number];
+    size?: readonly [width: number, height: number, depthOrArrayLayers?: number];
+};
+export type TextureCopyOptions = {
+    sourceMipLevel?: GPUIntegerCoordinate;
+    mipLevel?: GPUIntegerCoordinate;
+    sourceOrigin?: readonly [x: number, y: number, z?: number];
+    origin?: readonly [x: number, y: number, z?: number];
+    size?: readonly [width: number, height: number, depthOrArrayLayers?: number];
+};
+/** An image write resolved against a texture, with `fit` already applied */
+export type ImageWrite = {
+    source: GPUCopyExternalImageSource;
+    sourceOrigin: {
+        x: number;
+        y: number;
+    };
+    sourceSize: [width: number, height: number];
+    origin: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    size: [width: number, height: number];
+    mipLevel: number;
+    options: TextureWriteOptions;
+    channel?: {
+        from: TextureChannel;
+        to: TextureChannel;
+    };
+};
+type TextureShape = Pick<TextureProps, 'size' | 'dimension'>;
+export declare function origin3d([x, y, z]?: readonly (number | undefined)[]): {
+    x: number;
+    y: number;
+    z: number;
+};
+export declare function mipLevelSize({ size, dimension }: TextureShape, mipLevel: number): [number, number, number];
+/** The size of the written region: `size`, or the rest of the mip level past `origin` */
+export declare function writeRegionSize(texture: TextureShape, options: TextureWriteOptions): [number, number];
+export declare function sameSize(a: readonly number[], b: readonly number[]): boolean;
+export declare function resolveImageWrite(texture: TextureShape, source: GPUCopyExternalImageSource, options: TextureWriteOptions, layer?: number): ImageWrite;
+export {};