@woosh/meep-engine 3.29.0 → 3.31.0

package/src/shade/renderer/texture/mipmaps/WebGPUMipmapGenerator.js

@@ -8,12 +8,8 @@ import { round_up } from "../../../../core/math/round_up.js";
 import { objectKeyByValue } from "../../../../core/model/object/objectKeyByValue.js";
 import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 import { write_wgsl_type_value } from "../../shader/type/serde/write_gpu_typed_buffer.js";
-import { ColorSpace } from "../ColorSpace.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { vertex_full_viewport_quad } from "../../shader/fullscreen/vertex_full_viewport_quad.js";
-import { gpu_texture_descriptor_has_view_format } from "../format/gpu_texture_descriptor_has_view_format.js";
-import { gpu_texture_format_srg_to_linear } from "../format/gpu_texture_format_srg_to_linear.js";
-import { gpu_texture_format_to_color_space } from "../format/gpu_texture_format_to_color_space.js";
 import { TextureFilterType } from "../TextureFilterType.js";
 import { mipmap_shader_code_catmull_rom } from "./filters/mipmap_shader_code_catmull_rom.js";
 import { mipmap_shader_code_linear } from "./filters/mipmap_shader_code_linear.js";
@@ -255,7 +251,14 @@ export class WebGPUMipmapGenerator {
      */
     constructor(device) {
         this.device = device;
-        this.sampler = device.createSampler({ minFilter: 'linear' });
+
+        /*
+         `magFilter` as well as `minFilter`. Most filters read exact texels with `textureLoad`, and the
+         linear one samples a level twice the size of its target, which is minification. Wronski2021
+         samples between texels at an explicit level 0, and an explicit level 0 is magnification: at
+         the default 'nearest', every one of its bilinear taps read a single texel.
+        */
+        this.sampler = device.createSampler({ minFilter: 'linear', magFilter: 'linear' });
 
         this.#parameters_buffer_stride = round_up(MIP_SHADER_UNIFORM_STRUCT.aligned_size, device.limits.minUniformBufferOffsetAlignment);
 
@@ -490,17 +493,35 @@ export class WebGPUMipmapGenerator {
      * @param {GPUTexture} texture - Texture to generate mipmaps for.
      * @param {GPUTextureDescriptor} texture_descriptor - GPUTextureDescriptor the texture was created with.
      * @param {TextureFilterType} [filter]
-     * @param {GPUCommandEncoder} [commandEncoder]
+     * @param {GPUCommandEncoder} [commandEncoder] when supplied, the commands are recorded rather
+     *   than submitted, so the scratch resources outlive this call and `release_after_submit` is
+     *   required
+     * @param {{destroy: function():void}[]} [release_after_submit] where the scratch buffer and
+     *   textures go when the encoder is the caller's; destroy them once it has submitted
      * @returns {GPUTexture} - The originally passed texture
      */
     generateMipmap(
         texture,
         texture_descriptor,
         filter = TextureFilterType.Linear,
-        commandEncoder
+        commandEncoder,
+        release_after_submit
     ) {
         assert.defined(texture, 'texture');
         assert.defined(texture_descriptor, 'texture descriptor');
+
+        /**
+         * An ordinary throw, not an assert: a caller that supplies its own encoder has to say where
+         * the scratch resources go, because we cannot destroy them — its commands reference them and
+         * it has not submitted yet. Getting this wrong loses the caller's whole command buffer with
+         * no error of any kind, so it is not a check that may be stripped.
+         */
+        if (commandEncoder !== undefined && !Array.isArray(release_after_submit)) {
+            throw new Error(
+                "generateMipmap with a caller-supplied commandEncoder needs a `release_after_submit` array: "
+                + "the scratch resources outlive this call and must be destroyed once the caller has submitted"
+            );
+        }
         assert.enum(filter, TextureFilterType, 'filter');
 
         const mip_level_count = texture.mipLevelCount;
@@ -524,46 +545,24 @@ export class WebGPUMipmapGenerator {
             created_command_encoder = true;
         }
 
-        let decoded_texture = texture;
-
-        const input_color_space = gpu_texture_format_to_color_space(texture.format);
+        /*
+         Every view below, every scratch texture and every pipeline target is the texture's own
+         format, sRGB included, and for an sRGB texture that is the whole of the colour handling:
+         sampling an `-srgb` view decodes each texel before it is filtered, and rendering into one
+         encodes the result, so the filters average linear light while the levels hold encoded bytes.
 
-        let texture_format_decoded = texture_descriptor.format;
+         The linear reinterpretation (`rgba8unorm` for `rgba8unorm-srgb`), which this used to view
+         every level as, does neither — so each level was an average of encoded values, darker than
+         its parent wherever there was contrast. Nor did the "decode" copy into a linear twin that it
+         made when the descriptor did not allow that view: a texture copy is byte-exact.
 
-        if (input_color_space === ColorSpace.SRGB) {
-            // non-linear space, need to convert to linear space
-            texture_format_decoded = gpu_texture_format_srg_to_linear(texture.format);
+         A block-compressed sRGB format cannot be rendered into under either name, and fails here as
+         its linear counterpart does; `gpu_texture_format_can_generate_mipmaps` is what turns callers
+         away before this.
+        */
+        const format = texture.format;
 
-            const can_bind_linear = gpu_texture_descriptor_has_view_format(texture_descriptor, texture_format_decoded);
-
-            if (!can_bind_linear) {
-
-                // override mip texture
-
-                const linear_texture = device.createTexture({
-                    size: {
-                        width: Math.max(1, source_width),
-                        height: Math.max(1, source_height),
-                        depthOrArrayLayers: arrayLayerCount,
-                    },
-                    format: texture_format_decoded,
-                    usage: GPUTextureUsage.TEXTURE_BINDING| GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC | GPUTextureUsage.COPY_DST ,
-                    mipLevelCount: mip_level_count,
-                });
-
-                // convert
-                commandEncoder.copyTextureToTexture(
-                    { texture: decoded_texture },
-                    { texture: linear_texture, mipLevel: 0 },
-                    { width: source_width, height: source_height, depthOrArrayLayers: arrayLayerCount },
-                );
-
-                decoded_texture = linear_texture;
-            }
-
-        }
-
-        let mip_texture = decoded_texture;
+        let mip_texture = texture;
 
         /**
          * @type {GPUBuffer}
@@ -606,7 +605,7 @@ export class WebGPUMipmapGenerator {
             // safe to do straight recursive downsample
 
             const key_forward = new MipmapShaderKey();
-            key_forward.format = texture_format_decoded;
+            key_forward.format = format;
             key_forward.filter = filter_process_descriptor.filter;
 
             pipeline_forward = this.pipelines.getOrCompute(key_forward, this.#createPipeline, this);
@@ -618,11 +617,11 @@ export class WebGPUMipmapGenerator {
             // We then go backwards and apply our actual non-preserving filter
 
             const key_forward = new MipmapShaderKey();
-            key_forward.format = texture_format_decoded;
+            key_forward.format = format;
             key_forward.filter = filter_process_descriptor.base_filter;
 
             const key_backward = new MipmapShaderKey();
-            key_backward.format = texture_format_decoded;
+            key_backward.format = format;
             key_backward.filter = filter_process_descriptor.filter;
 
             pipeline_forward = this.pipelines.getOrCompute(key_forward, this.#createPipeline, this);
@@ -635,9 +634,9 @@ export class WebGPUMipmapGenerator {
         }
 
         // If the texture was created with RENDER_ATTACHMENT usage we can render directly between mip levels.
-        const write_to_decoded = (decoded_texture.usage & GPUTextureUsage.RENDER_ATTACHMENT) !== 0;
+        const write_in_place = (texture.usage & GPUTextureUsage.RENDER_ATTACHMENT) !== 0;
 
-        if (!write_to_decoded) {
+        if (!write_in_place) {
             // Otherwise we have to use a separate texture to render into. It can be one mip level smaller than the source
             // texture, since we already have the top level.
             const mipTextureDescriptor = {
@@ -646,7 +645,7 @@ export class WebGPUMipmapGenerator {
                     height: Math.max(1, source_height >>> 1),
                     depthOrArrayLayers: arrayLayerCount,
                 },
-                format: texture_format_decoded,
+                format,
                 usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC | GPUTextureUsage.RENDER_ATTACHMENT,
                 mipLevelCount: mip_level_count - 1,
             };
@@ -664,7 +663,7 @@ export class WebGPUMipmapGenerator {
                     height: Math.max(1, source_height >>> 1),
                     depthOrArrayLayers: arrayLayerCount,
                 },
-                format: texture_format_decoded,
+                format,
                 usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC | GPUTextureUsage.RENDER_ATTACHMENT,
                 mipLevelCount: mip_level_count - 1,
             };
@@ -675,16 +674,16 @@ export class WebGPUMipmapGenerator {
 
         for (let arrayLayer = 0; arrayLayer < arrayLayerCount; ++arrayLayer) {
 
-            let srcView = decoded_texture.createView({
+            let srcView = texture.createView({
                 baseMipLevel: 0,
                 mipLevelCount: 1,
                 dimension: '2d',
                 baseArrayLayer: arrayLayer,
                 arrayLayerCount: 1,
-                format: texture_format_decoded,
+                format,
             });
 
-            let dstMipLevel = (forward_texture === decoded_texture) ? 1 : 0;
+            let dstMipLevel = (forward_texture === texture) ? 1 : 0;
 
             for (let i = 1; i < mip_level_count; ++i) {
                 const dstView = forward_texture.createView({
@@ -693,7 +692,7 @@ export class WebGPUMipmapGenerator {
                     dimension: '2d',
                     baseArrayLayer: arrayLayer,
                     arrayLayerCount: 1,
-                    format: texture_format_decoded,
+                    format,
                 });
 
                 const passEncoder = commandEncoder.beginRenderPass({
@@ -754,16 +753,31 @@ export class WebGPUMipmapGenerator {
                 let src_texture_obj = forward_texture;
                 let src_base_level = source_mip_level;
 
-                if (forward_texture !== decoded_texture && source_mip_level > 0) {
+                if (forward_texture !== texture) {
                     // The separate forward target is shifted: Index 0 is Mip 1.
-                    // (Comparing against 'decoded_texture', not 'texture' — the sRGB-decode
-                    // copy is full-size and unshifted even though it differs from 'texture'.)
-                    src_base_level--;
+                    if (source_mip_level === 0) {
+                        /*
+                         Original mip 0 is not in the shifted target AT ALL, so there is no index
+                         to shift: it is the top level of 'texture', which is where the forward
+                         pass read it from in the first place.
+
+                         Clamping the shifted index at 0, which is what this did, names scratch
+                         level 0 — original mip 1 — so a Mitchell or CatmullRom mip 2 was filtered
+                         from mip 1 and the 4x4 kernel support the filter was chosen for silently
+                         became 2x2. With a skip distance of 1 it is worse than wrong: at i = 1 the
+                         destination is scratch level 0 as well, and one render pass binding the
+                         same subresource as its sampled texture and as its colour attachment is
+                         something WebGPU refuses outright.
+                        */
+                        src_texture_obj = texture;
+                    } else {
+                        src_base_level--;
+                    }
                 }
 
                 // Determine destination offset
-                let dst_texture_obj = write_to_decoded ? decoded_texture : mip_texture;
-                let dst_base_level = write_to_decoded ? i : (i - 1);
+                let dst_texture_obj = write_in_place ? texture : mip_texture;
+                let dst_base_level = write_in_place ? i : (i - 1);
 
                 const srcView = src_texture_obj.createView({
                     baseMipLevel: src_base_level,
@@ -771,7 +785,7 @@ export class WebGPUMipmapGenerator {
                     dimension: '2d',
                     baseArrayLayer: arrayLayer,
                     arrayLayerCount: 1,
-                    format: texture_format_decoded,
+                    format,
                 });
                 const dstView = dst_texture_obj.createView({
                     baseMipLevel: dst_base_level,
@@ -779,7 +793,7 @@ export class WebGPUMipmapGenerator {
                     dimension: '2d',
                     baseArrayLayer: arrayLayer,
                     arrayLayerCount: 1,
-                    format: texture_format_decoded,
+                    format,
                 });
 
                 const passEncoder = commandEncoder.beginRenderPass({
@@ -832,12 +846,11 @@ export class WebGPUMipmapGenerator {
                 depthOrArrayLayers: arrayLayerCount,
             };
 
-            const mip_offset = mip_texture.width === texture.width ? 0 : 1;
-
             for (let i = 1; i < mip_level_count; ++i) {
                 commandEncoder.copyTextureToTexture({
                     texture: mip_texture,
-                    mipLevel: i - mip_offset,
+                    // the scratch texture starts at mip 1
+                    mipLevel: i - 1,
                 }, {
                     texture: texture,
                     mipLevel: i,
@@ -848,22 +861,35 @@ export class WebGPUMipmapGenerator {
             }
         }
 
+        /**
+         * Nothing here has run yet when the encoder is the caller's: the commands are recorded, and
+         * the caller submits later. `finish()`/`submit()` validate that every resource a command
+         * buffer touches is still alive, so destroying these inline had the whole command buffer
+         * rejected — not just the mips, but every pass the caller recorded in the same context, and
+         * silently, because WebGPU validation errors do not throw. The branch that was written to be
+         * careful, and the only one, was the one that got it wrong.
+         *
+         * So: when we made the encoder we submit and release; when we did not, the temporaries go to
+         * the caller's release list, to be destroyed once it has submitted.
+         *
+         * @param {{destroy: function():void}} resource
+         */
+        const release = created_command_encoder
+            ? resource => resource.destroy()
+            : resource => release_after_submit.push(resource);
+
         if (created_command_encoder) {
             device.queue.submit([commandEncoder.finish()]);
         } else {
-            parameters_buffer.destroy();
-        }
-
-        if (texture !== decoded_texture) {
-            decoded_texture.destroy();
+            release(parameters_buffer);
         }
 
         if (texture !== mip_texture) {
-            mip_texture.destroy();
+            release(mip_texture);
         }
 
         if (need_separate_forward_target) {
-            forward_texture.destroy();
+            release(forward_texture);
         }
 
         return texture;

package/src/shade/renderer/texture/mipmaps/filters/mipmap_shader_code_wronski2021.d.ts

@@ -1,5 +1,34 @@
 /**
- * We're using the bilinear-optimized 10-tap filter from Wronski's 2021 paper.
+ * Where the six taps along each axis sit, in source texels from the centre of the output pixel —
+ * for a 2x reduction, the boundary between two texels. Each tap is a bilinear sample standing for
+ * the two texels either side of it, and the filter is separable: a 2D tap weighs the product of its
+ * two axes' weights.
+ *
+ * This is the widest of the filters Wronski lists, twelve texels a side, with each tap mirrored
+ * within its pair of texels. The article puts a tap `w_a / (w_a + w_b)` of the way from texel `a` to
+ * texel `b`, and bilinear filtering gives that position `b`'s share to `a`. As printed (±1.331,
+ * ±3.151 and ±5.198 from the centre), the taps weigh the texels 1.5 out far above the two nearest
+ * ones, and they turn the band above half-Nyquist, which the filter exists to remove, into an
+ * inverted copy at up to 1.45 times its strength. Mirrored, they are the filter the article
+ * describes: a boost below half-Nyquist, and next to nothing above it.
+ *
+ * @see https://bartwronski.com/2021/07/20/processing-aware-image-filtering-compensating-for-the-upsampling/
+ * @type {number[]}
+ */
+export const WRONSKI2021_TAP_OFFSETS: number[];
+/**
+ * The weight of each tap in {@link WRONSKI2021_TAP_OFFSETS}, as the article gives it. They sum to 1.
+ *
+ * @type {number[]}
+ */
+export const WRONSKI2021_TAP_WEIGHTS: number[];
+/**
+ * Wronski's 2021 processing-aware downsampling filter, in bilinear taps — see
+ * {@link WRONSKI2021_TAP_OFFSETS}.
+ *
+ * The taps are bilinear only if the sampler says so. They are read at an explicit level 0, which is
+ * magnification, so it is the sampler's `magFilter` that has to be 'linear'.
+ *
  * @see https://bartwronski.com/2021/07/20/processing-aware-image-filtering-compensating-for-the-upsampling/
  * @type {CodeChunk}
  */

package/src/shade/renderer/texture/mipmaps/filters/mipmap_shader_code_wronski2021.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mipmap_shader_code_wronski2021.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/texture/mipmaps/filters/mipmap_shader_code_wronski2021.js"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,6CAFU,SAAS,CA4EZ;0BAlFmB,uCAAuC"}
+{"version":3,"file":"mipmap_shader_code_wronski2021.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/texture/mipmaps/filters/mipmap_shader_code_wronski2021.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;GAgBG;AACH,sCAFU,MAAM,EAAE,CAEuE;AAEzF;;;;GAIG;AACH,sCAFU,MAAM,EAAE,CAEkE;AAEpF;;;;;;;;;GASG;AACH,6CAFU,SAAS,CA8DZ;0BAnGmB,uCAAuC"}

package/src/shade/renderer/texture/mipmaps/filters/mipmap_shader_code_wronski2021.js

@@ -4,7 +4,38 @@ import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
 import { MIP_SHADER_UNIFORM_STRUCT } from "../MIP_SHADER_UNIFORM_STRUCT.js";
 
 /**
- * We're using the bilinear-optimized 10-tap filter from Wronski's 2021 paper.
+ * Where the six taps along each axis sit, in source texels from the centre of the output pixel —
+ * for a 2x reduction, the boundary between two texels. Each tap is a bilinear sample standing for
+ * the two texels either side of it, and the filter is separable: a 2D tap weighs the product of its
+ * two axes' weights.
+ *
+ * This is the widest of the filters Wronski lists, twelve texels a side, with each tap mirrored
+ * within its pair of texels. The article puts a tap `w_a / (w_a + w_b)` of the way from texel `a` to
+ * texel `b`, and bilinear filtering gives that position `b`'s share to `a`. As printed (±1.331,
+ * ±3.151 and ±5.198 from the centre), the taps weigh the texels 1.5 out far above the two nearest
+ * ones, and they turn the band above half-Nyquist, which the filter exists to remove, into an
+ * inverted copy at up to 1.45 times its strength. Mirrored, they are the filter the article
+ * describes: a boost below half-Nyquist, and next to nothing above it.
+ *
+ * @see https://bartwronski.com/2021/07/20/processing-aware-image-filtering-compensating-for-the-upsampling/
+ * @type {number[]}
+ */
+export const WRONSKI2021_TAP_OFFSETS = [-4.802, -2.8485, -0.6695, 0.6695, 2.8485, 4.802];
+
+/**
+ * The weight of each tap in {@link WRONSKI2021_TAP_OFFSETS}, as the article gives it. They sum to 1.
+ *
+ * @type {number[]}
+ */
+export const WRONSKI2021_TAP_WEIGHTS = [0.115, -0.304, 0.689, 0.689, -0.304, 0.115];
+
+/**
+ * Wronski's 2021 processing-aware downsampling filter, in bilinear taps — see
+ * {@link WRONSKI2021_TAP_OFFSETS}.
+ *
+ * The taps are bilinear only if the sampler says so. They are read at an explicit level 0, which is
+ * magnification, so it is the sampler's `magFilter` that has to be 'linear'.
+ *
  * @see https://bartwronski.com/2021/07/20/processing-aware-image-filtering-compensating-for-the-upsampling/
  * @type {CodeChunk}
  */
@@ -27,25 +58,11 @@ fn main(
     let stride = max(vec2(1.0), ( vec2<f32>(source_dim) * 0.5 ) / vec2<f32>(output_dim));
     
     let src_center = uv_to_texel_coordinate(uv, source_dim);
-    
-    // coordinates are shifted by 0.5 since we're sampling from the center of the pixel
-    const SAMPLE_DISTANCES = array<f32, 6>(
-        -5.198, 
-        -3.151, 
-        -1.331, 
-        1.331, 
-        3.151, 
-        5.198
-    );
-    
-    const SAMPLE_WEIGHTS = array<f32, 6>(
-        0.115, 
-        -0.304, 
-        0.689, 
-        0.689, 
-        -0.304, 
-        0.115
-    );
+
+    // distances from the centre of the output pixel, in source texels
+    const SAMPLE_DISTANCES = array<f32, 6>(${WRONSKI2021_TAP_OFFSETS.join(', ')});
+
+    const SAMPLE_WEIGHTS = array<f32, 6>(${WRONSKI2021_TAP_WEIGHTS.join(', ')});
     
     var result = vec4<f32>(0.0);
     var weight_sum = 0.0;

package/src/shade/renderer/texture/texture_descriptor_from_texture_shade.js

@@ -1,74 +1,74 @@
-import { TextureDescriptor } from "../../descriptor/texture/TextureDescriptor.js";
-import { gpu_texture_format_can_generate_mipmaps } from "./format/gpu_texture_format_can_generate_mipmaps.js";
-import { texture_format_from_shade_image } from "./format/texture_format_from_shade_image.js";
-import { texture_mip_level_count } from "../../util/texture_mip_extent.js";
-
-import { ShadeTextureFlags } from "./ShadeTextureFlags.js";
-
-/**
- *
- * @param {ShadeTexture} shade
- * @returns {TextureDescriptor}
- */
-export function texture_descriptor_from_texture_shade(shade) {
-
-    const image = shade.image;
-
-    let usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.COPY_SRC;
-
-    /**
-     * @type {GPUTextureFormat}
-     */
-    const format = texture_format_from_shade_image(image);
-
-    /*
-     Two independent things, which used to be one.
-
-     Where the levels come from is a property of the image: it supplies `level_count` of them, and
-     that is how many the texture gets. Whether to run the mip generator is an instruction the caller
-     gives, and it is honoured or it throws — never quietly reinterpreted from what the image happens
-     to carry. Set the flag on an image that already has a chain and the chain is regenerated, which
-     is a real use: a container whose mips were built with a filter you do not want.
-    */
-    const generate = (shade.flags & ShadeTextureFlags.GenerateMipMaps) !== 0;
-
-    let dimension = "1d";
-
-    if (shade.dimensions === 2) {
-        dimension = "2d";
-    } else if (shade.dimensions === 3) {
-        dimension = "3d";
-    }
-
-    let mipLevelCount;
-
-    if (generate) {
-        if (!gpu_texture_format_can_generate_mipmaps(format)) {
-            throw new Error(
-                `${shade.label || 'texture'}: mipmap generation was requested for '${format}',`
-                + ` which cannot be a render attachment. Mips for this format come from whatever`
-                + ` encoded it — supply them in the payload and clear`
-                + ` ShadeTextureFlags.GenerateMipMaps.`
-            );
-        }
-
-        // the generator renders between levels, so the texture has to be bindable for writing
-        usage |= GPUTextureUsage.RENDER_ATTACHMENT;
-
-        // through the dimension: a volume's chain runs down its depth too, so a 4x4x16 asking for
-        // generated mips wants five levels and not the three its width alone implies
-        mipLevelCount = texture_mip_level_count(image.width, image.height, image.depth, dimension);
-    } else {
-        mipLevelCount = image.level_count;
-    }
-
-    return TextureDescriptor.from({
-        label: shade.label,
-        size: [image.width, image.height, image.depth],
-        format,
-        usage: usage,
-        mipLevelCount,
-        dimension,
-    });
-
+import { TextureDescriptor } from "../../descriptor/texture/TextureDescriptor.js";
+import { gpu_texture_format_can_generate_mipmaps } from "./format/gpu_texture_format_can_generate_mipmaps.js";
+import { texture_format_from_shade_image } from "./format/texture_format_from_shade_image.js";
+import { texture_mip_level_count } from "../../util/texture_mip_extent.js";
+
+import { ShadeTextureFlags } from "./ShadeTextureFlags.js";
+
+/**
+ *
+ * @param {ShadeTexture} shade
+ * @returns {TextureDescriptor}
+ */
+export function texture_descriptor_from_texture_shade(shade) {
+
+    const image = shade.image;
+
+    let usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.COPY_SRC;
+
+    /**
+     * @type {GPUTextureFormat}
+     */
+    const format = texture_format_from_shade_image(image, shade.color_space ?? image.color_space);
+
+    /*
+     Two independent things, which used to be one.
+
+     Where the levels come from is a property of the image: it supplies `level_count` of them, and
+     that is how many the texture gets. Whether to run the mip generator is an instruction the caller
+     gives, and it is honoured or it throws — never quietly reinterpreted from what the image happens
+     to carry. Set the flag on an image that already has a chain and the chain is regenerated, which
+     is a real use: a container whose mips were built with a filter you do not want.
+    */
+    const generate = (shade.flags & ShadeTextureFlags.GenerateMipMaps) !== 0;
+
+    let dimension = "1d";
+
+    if (shade.dimensions === 2) {
+        dimension = "2d";
+    } else if (shade.dimensions === 3) {
+        dimension = "3d";
+    }
+
+    let mipLevelCount;
+
+    if (generate) {
+        if (!gpu_texture_format_can_generate_mipmaps(format)) {
+            throw new Error(
+                `${shade.label || 'texture'}: mipmap generation was requested for '${format}',`
+                + ` which cannot be a render attachment. Mips for this format come from whatever`
+                + ` encoded it — supply them in the payload and clear`
+                + ` ShadeTextureFlags.GenerateMipMaps.`
+            );
+        }
+
+        // the generator renders between levels, so the texture has to be bindable for writing
+        usage |= GPUTextureUsage.RENDER_ATTACHMENT;
+
+        // through the dimension: a volume's chain runs down its depth too, so a 4x4x16 asking for
+        // generated mips wants five levels and not the three its width alone implies
+        mipLevelCount = texture_mip_level_count(image.width, image.height, image.depth, dimension);
+    } else {
+        mipLevelCount = image.level_count;
+    }
+
+    return TextureDescriptor.from({
+        label: shade.label,
+        size: [image.width, image.height, image.depth],
+        format,
+        usage: usage,
+        mipLevelCount,
+        dimension,
+    });
+
 }

package/src/shade/renderer/view/ViewManager.d.ts

@@ -44,6 +44,14 @@ export class ViewManager {
      * @param {View} view
      */
     release(view: View): void;
+    /**
+     * Release every view context this handed out. Each owns its render targets and uniform buffer.
+     *
+     * The camera contexts are the {@link CameraManager}s, as in {@link release}.
+     *
+     * @returns {void}
+     */
+    destroy(): void;
     #private;
 }
 export type GraphicsContext = import("../GraphicsContext.js").GraphicsContext;

package/src/shade/renderer/view/ViewManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ViewManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/view/ViewManager.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH;IAmCI;;;;;OAKG;IACH,sBAJW,eAAe,WACf,aAAa,UACb,YAAY,EAQtB;IA9BD;;;OAGG;IACH,8DAEC;IA2CD;;;;OAIG;IACH,aAHW,IAAI,GACF,OAAO,CAInB;IAED;;;;OAIG;IACH,aAHW,IAAI,GACF,cAAc,CAI1B;IAED;;;;;;;;;;;;;OAaG;IACH,cAFW,IAAI,QASd;;CACJ;8BAhHY,OAAO,uBAAuB,EAAE,eAAe;4BAC/C,OAAO,4BAA4B,EAAE,aAAa;2BAClD,OAAO,0BAA0B,EAAE,YAAY;mBAC/C,OAAO,WAAW,EAAE,IAAI;+BANN,qBAAqB"}
+{"version":3,"file":"ViewManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/view/ViewManager.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH;IAmCI;;;;;OAKG;IACH,sBAJW,eAAe,WACf,aAAa,UACb,YAAY,EAQtB;IA9BD;;;OAGG;IACH,8DAEC;IA2CD;;;;OAIG;IACH,aAHW,IAAI,GACF,OAAO,CAInB;IAED;;;;OAIG;IACH,aAHW,IAAI,GACF,cAAc,CAI1B;IAED;;;;;;;;;;;;;OAaG;IACH,cAFW,IAAI,QASd;IAED;;;;;;OAMG;IACH,WAFa,IAAI,CAQhB;;CACJ;8BA/HY,OAAO,uBAAuB,EAAE,eAAe;4BAC/C,OAAO,4BAA4B,EAAE,aAAa;2BAClD,OAAO,0BAA0B,EAAE,YAAY;mBAC/C,OAAO,WAAW,EAAE,IAAI;+BANN,qBAAqB"}

package/src/shade/renderer/view/ViewManager.js

@@ -114,4 +114,19 @@ export class ViewManager {
         gpu_ctx.destroy();
         this.#cache.delete(view);
     }
+
+    /**
+     * Release every view context this handed out. Each owns its render targets and uniform buffer.
+     *
+     * The camera contexts are the {@link CameraManager}s, as in {@link release}.
+     *
+     * @returns {void}
+     */
+    destroy() {
+        for (const gpu_ctx of this.#cache.values()) {
+            gpu_ctx.destroy();
+        }
+
+        this.#cache.clear();
+    }
 }

package/src/shade/renderer/volumetrics/GPUViewVolumetrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUViewVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/GPUViewVolumetrics.js"],"names":[],"mappings":"AAiCA;IAkII;;;;OAIG;IACH,kBAHW,cAAc,qBAwBxB;IAxHD;;OAEG;IACH,4BAOC;IAjBD;;OAEG;IACH,2BAEC;IAsCD;;OAEG;IACH,0BAEC;IAZD;;OAEG;IACH,yBAEC;IAwFD,gBAWC;IA6ND;;;;;;;;OAQG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACM,kBAAkB,EAAlC,MAAM;QACU,oBAAoB,EAApC,MAAM;QACU,wBAAwB,EAAxC,MAAM;QACU,eAAe,EAA/B,MAAM;;;;MA2EhB;;CAEJ;yBAneY,OAAO,2DAA2D,EAAE,UAAU;6BAC9E,OAAO,2BAA2B,EAAE,cAAc"}
+{"version":3,"file":"GPUViewVolumetrics.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/volumetrics/GPUViewVolumetrics.js"],"names":[],"mappings":"AAiCA;IAkII;;;;OAIG;IACH,kBAHW,cAAc,qBAwBxB;IAxHD;;OAEG;IACH,4BAOC;IAjBD;;OAEG;IACH,2BAEC;IAsCD;;OAEG;IACH,0BAEC;IAZD;;OAEG;IACH,yBAEC;IAwFD,gBAWC;IA6ND;;;;;;;;OAQG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACM,kBAAkB,EAAlC,MAAM;QACU,oBAAoB,EAApC,MAAM;QACU,wBAAwB,EAAxC,MAAM;QACU,eAAe,EAA/B,MAAM;;;;MAoFhB;;CAEJ;yBA5eY,OAAO,2DAA2D,EAAE,UAAU;6BAC9E,OAAO,2BAA2B,EAAE,cAAc"}