@forgeax/engine-render 0.1.4 → 0.1.7

package/src/hdrp-cluster-membership.ts

@@ -1,70 +0,0 @@
-// @forgeax/engine-runtime - WebGPU HDRP cluster membership producer.
-//
-// The CPU binner remains the owner of bounds, occupancy, ordering, and
-// overflow validation. This compute entry only materializes the already
-// reserved ordered list on storage-buffer devices. Keeping the source here
-// makes the producer boot-time compiled and avoids adding a material shader
-// artifact or a second manifest identity.
-
-export const HDRP_CLUSTER_MEMBERSHIP_WGSL = /* wgsl */ `
-struct ClusterUniform {
-  grid : vec4<u32>,
-  near_far_log : vec4<f32>,
-};
-
-@group(0) @binding(0) var<storage, read> cluster_grid : array<u32>;
-@group(0) @binding(1) var<storage, read_write> light_index_list : array<u32>;
-@group(0) @binding(2) var<uniform> cluster_uniform : ClusterUniform;
-@group(0) @binding(3) var<storage, read> light_bounds : array<i32>;
-
-@compute @workgroup_size(64)
-fn cs_cluster_membership(@builtin(global_invocation_id) global_id : vec3<u32>) {
-  let cluster_index = global_id.x;
-  let grid_x = cluster_uniform.grid.x;
-  let grid_y = cluster_uniform.grid.y;
-  let grid_z = cluster_uniform.grid.z;
-  let cluster_count = grid_x * grid_y * grid_z;
-  if (cluster_index >= cluster_count) {
-    return;
-  }
-
-  let cluster_x = cluster_index % grid_x;
-  let cluster_yz = cluster_index / grid_x;
-  let cluster_y = cluster_yz % grid_y;
-  let cluster_z = cluster_yz / grid_y;
-  let grid_offset = cluster_index * 2u;
-  let output_offset = cluster_grid[grid_offset];
-  let output_count = cluster_grid[grid_offset + 1u];
-  let cluster_x_i = i32(cluster_x);
-  let cluster_y_i = i32(cluster_y);
-  let cluster_z_i = i32(cluster_z);
-  var output_index = output_offset;
-
-  var light_index = 0u;
-  loop {
-    if (light_index >= cluster_uniform.grid.w || light_index >= 256u) {
-      break;
-    }
-    let bounds_offset = light_index * 6u;
-    let min_x = light_bounds[bounds_offset];
-    if (min_x >= 0) {
-      let min_y = light_bounds[bounds_offset + 1u];
-      let min_z = light_bounds[bounds_offset + 2u];
-      let max_x = light_bounds[bounds_offset + 3u];
-      let max_y = light_bounds[bounds_offset + 4u];
-      let max_z = light_bounds[bounds_offset + 5u];
-      if (
-        cluster_x_i >= min_x && cluster_x_i <= max_x &&
-        cluster_y_i >= min_y && cluster_y_i <= max_y &&
-        cluster_z_i >= min_z && cluster_z_i <= max_z
-      ) {
-        if (output_index < output_offset + output_count) {
-          light_index_list[output_index] = light_index;
-          output_index += 1u;
-        }
-      }
-    }
-    light_index += 1u;
-  }
-}
-`;

package/src/ibl/cubemap-projection.ts

@@ -1,60 +0,0 @@
-// Shared cubemap capture projection — Y negated for WebGPU top-left framebuffer origin.
-
-/** The canonical diffuse IBL payload stores irradiance as E times pi. */
-export const IBL_DIFFUSE_PAYLOAD_SEMANTIC = 'irradianceEOverPi' as const;
-export type IblDiffusePayloadSemantic = typeof IBL_DIFFUSE_PAYLOAD_SEMANTIC;
-
-export interface IblCapabilityReport {
-  readonly capabilityStatus: 'supported' | 'degraded';
-  readonly executionStatus: 'notExecuted' | 'complete';
-  readonly verdict: 'failed' | 'passed';
-  readonly rgba16floatRenderable: boolean;
-  readonly outputFormat: 'rgba16float' | null;
-  readonly fallbackArtifact: 'white-cube' | null;
-  readonly expectedImpact: string;
-  readonly hint: string;
-}
-
-export function describeIblCapability(input: {
-  readonly rgba16floatRenderable: boolean;
-}): IblCapabilityReport {
-  if (input.rgba16floatRenderable) {
-    return {
-      capabilityStatus: 'supported',
-      executionStatus: 'complete',
-      verdict: 'passed',
-      rgba16floatRenderable: true,
-      outputFormat: 'rgba16float',
-      fallbackArtifact: null,
-      expectedImpact: 'HDR IBL irradiance and specular lighting execute normally',
-      hint: 'capture the named rgba16float producer attachment for raw evidence',
-    };
-  }
-  return {
-    capabilityStatus: 'degraded',
-    executionStatus: 'notExecuted',
-    verdict: 'failed',
-    rgba16floatRenderable: false,
-    outputFormat: null,
-    fallbackArtifact: 'white-cube',
-    expectedImpact: 'HDR IBL producer execution is unavailable; lighting cannot be calibrated',
-    hint: 'inspect rgba16floatRenderable and restore HDR capability before retrying the IBL case',
-  };
-}
-
-/**
- * Build a perspective projection matrix for rendering into cubemap faces.
- * Y is negated to match WebGPU's top-left framebuffer origin (unlike OpenGL's bottom-left).
- * All cubemap passes (equirect-to-cube / irradiance / prefilter) should use this.
- */
-export function cubemapCaptureProjection(fovy: number, near: number, far: number): Float32Array {
-  const f = 1.0 / Math.tan(fovy / 2);
-  const nf = 1.0 / (near - far);
-  // biome-ignore format: manual column-major mat4
-  return new Float32Array([
-    f, 0, 0, 0,
-    0, -f, 0, 0,
-    0, 0, (far + near) * nf, -1,
-    0, 0, 2 * far * near * nf, 0,
-  ]);
-}

package/src/ibl/face-uniforms.ts

@@ -1,150 +0,0 @@
-// face-uniforms.ts -- M3.5 t55.
-//
-// CPU-side helpers that allocate + populate the per-face viewProj uniform
-// buffer (6 entries) and the per-prefilter-sub-pass roughness uniform
-// buffer (5 mip x 6 face = 30 entries). Both are 256-byte stride to honour
-// the WebGPU dynamic-offset alignment SSOT (plan-strategy section 3.2
-// sequence diagram, D-9 face-uniforms layout cross-pipeline reuse).
-//
-// The buffer payloads are:
-//   faceUniforms[face]      = mat4x4<f32> viewProj  (64 byte usable; 256 byte stride)
-//   prefilterUniforms[idx]  = { roughness: f32, faceSize: f32, _pad0, _pad1 }
-//                             (16 byte usable; 256 byte stride)
-//
-// Indexed as:
-//   face       = 0..5
-//   prefilter  = mip * 6 + face   (mip 0..4, face 0..5)
-
-import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
-import { CAPTURE_VIEW_PROJS, PREFILTER_MIP_LEVELS, PREFILTER_SIZE } from './IblPipelineCache';
-
-const DYNAMIC_OFFSET_STRIDE = 256;
-const FACE_COUNT = 6;
-const PREFILTER_SUBPASS_COUNT = PREFILTER_MIP_LEVELS * FACE_COUNT;
-
-/**
- * Minimal device shape consumed by the helpers -- mirrors
- * `IblPipelineDevice` createBuffer surface plus queue.writeBuffer.
- */
-export interface FaceUniformsDevice {
-  // biome-ignore lint/suspicious/noExplicitAny: shim shape
-  createBuffer(desc: any): { ok: true; value: any } | { ok: false; error: unknown };
-  readonly queue: {
-    // biome-ignore lint/suspicious/noExplicitAny: shim shape
-    writeBuffer?: (...args: any[]) => unknown;
-  };
-}
-
-/**
- * Allocate the 6-face viewProj uniform buffer. Size = 6 * 256 bytes so
- * each face slot is dynamic-offset addressable.
- */
-export function createFaceUniformsBuffer(
-  device: FaceUniformsDevice,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU buffer
-): { ok: true; value: any } | { ok: false; error: unknown } {
-  return device.createBuffer({
-    label: 'ibl-face-uniforms',
-    size: FACE_COUNT * DYNAMIC_OFFSET_STRIDE,
-    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
-    mappedAtCreation: false,
-  });
-}
-
-/**
- * Allocate the prefilter sub-pass uniform buffer. Size = 30 * 256 bytes.
- */
-export function createPrefilterUniformsBuffer(
-  device: FaceUniformsDevice,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU buffer
-): { ok: true; value: any } | { ok: false; error: unknown } {
-  return device.createBuffer({
-    label: 'ibl-prefilter-uniforms',
-    size: PREFILTER_SUBPASS_COUNT * DYNAMIC_OFFSET_STRIDE,
-    usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
-    mappedAtCreation: false,
-  });
-}
-
-/**
- * Write a single face's viewProj matrix at the dynamic-offset slot.
- *
- * @param device device with queue.writeBuffer
- * @param buffer face-uniforms buffer from createFaceUniformsBuffer
- * @param faceIdx 0..5
- * @param viewProj 16-element column-major mat4
- */
-export function writeFaceUniforms(
-  device: FaceUniformsDevice,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU buffer
-  buffer: any,
-  faceIdx: number,
-  viewProj: Float32Array,
-): void {
-  if (typeof device.queue.writeBuffer !== 'function') return;
-  if (faceIdx < 0 || faceIdx >= FACE_COUNT) {
-    throw new Error(`writeFaceUniforms: faceIdx ${faceIdx} out of range [0,5]`);
-  }
-  if (viewProj.length !== 16) {
-    throw new Error(`writeFaceUniforms: viewProj must be 16 floats, got ${viewProj.length}`);
-  }
-  device.queue.writeBuffer(buffer, faceIdx * DYNAMIC_OFFSET_STRIDE, viewProj);
-}
-
-/**
- * Write all 6 capture viewProj matrices into the face-uniforms buffer.
- * Uses the static CAPTURE_VIEW_PROJS SSOT from IblPipelineCache.
- */
-export function writeAllFaceUniforms(
-  device: FaceUniformsDevice,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU buffer
-  buffer: any,
-): void {
-  for (let face = 0; face < FACE_COUNT; face++) {
-    const vp = CAPTURE_VIEW_PROJS[face];
-    if (vp === undefined) continue;
-    writeFaceUniforms(device, buffer, face, vp);
-  }
-}
-
-/**
- * Write a single prefilter sub-pass uniform slot (roughness + faceSize).
- * subPassIdx = mip * 6 + face.
- */
-export function writePrefilterUniforms(
-  device: FaceUniformsDevice,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU buffer
-  buffer: any,
-  subPassIdx: number,
-  roughness: number,
-  mipFaceSize: number,
-): void {
-  if (typeof device.queue.writeBuffer !== 'function') return;
-  if (subPassIdx < 0 || subPassIdx >= PREFILTER_SUBPASS_COUNT) {
-    throw new Error(`writePrefilterUniforms: subPassIdx ${subPassIdx} out of range`);
-  }
-  const payload = new Float32Array([roughness, mipFaceSize, 0, 0]);
-  device.queue.writeBuffer(buffer, subPassIdx * DYNAMIC_OFFSET_STRIDE, payload);
-}
-
-/**
- * Write all 30 prefilter sub-pass uniforms (5 mip x 6 face) with
- * roughness = mip / (mipLevels - 1) and mipFaceSize halved per mip.
- */
-export function writeAllPrefilterUniforms(
-  device: FaceUniformsDevice,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU buffer
-  buffer: any,
-): void {
-  for (let mip = 0; mip < PREFILTER_MIP_LEVELS; mip++) {
-    const roughness = mip / (PREFILTER_MIP_LEVELS - 1);
-    const mipFaceSize = PREFILTER_SIZE / 2 ** mip;
-    for (let face = 0; face < FACE_COUNT; face++) {
-      writePrefilterUniforms(device, buffer, mip * FACE_COUNT + face, roughness, mipFaceSize);
-    }
-  }
-}
-
-export const FACE_UNIFORMS_STRIDE = DYNAMIC_OFFSET_STRIDE;
-export const FACE_UNIFORMS_BUFFER_SIZE = FACE_COUNT * DYNAMIC_OFFSET_STRIDE;
-export const PREFILTER_UNIFORMS_BUFFER_SIZE = PREFILTER_SUBPASS_COUNT * DYNAMIC_OFFSET_STRIDE;

package/src/mesh-update-errors.ts

@@ -1,113 +0,0 @@
-/** Structured failures for typed resident-mesh updates. */
-
-export type MeshUpdateErrorCode = keyof typeof MESH_UPDATE_POLICY;
-
-export interface MeshNotResidentDetail {
-  readonly handle: number;
-}
-
-export interface MeshShapeMismatchDetail {
-  readonly handle: number;
-  readonly expected: string;
-  readonly actual: string;
-}
-
-export type MeshRangeInvalidReason =
-  | 'non-integer'
-  | 'negative'
-  | 'empty'
-  | 'out-of-bounds'
-  | 'stride-mismatch';
-
-interface MeshRangeInvalidLocationDetail {
-  readonly handle: number;
-  readonly firstVertex: number;
-  readonly vertexCount: number;
-  readonly residentVertexCount: number;
-  readonly reason: Exclude<MeshRangeInvalidReason, 'stride-mismatch'>;
-}
-
-interface MeshRangeInvalidStrideDetail {
-  readonly handle: number;
-  readonly firstVertex: number;
-  readonly vertexCount: number;
-  readonly residentVertexCount: number;
-  readonly reason: 'stride-mismatch';
-  readonly expectedByteLength: number;
-  readonly actualByteLength: number;
-}
-
-export type MeshRangeInvalidDetail = MeshRangeInvalidLocationDetail | MeshRangeInvalidStrideDetail;
-
-export type MeshUpdateErrorDetailFor<C extends MeshUpdateErrorCode> = C extends 'mesh-not-resident'
-  ? MeshNotResidentDetail
-  : C extends 'mesh-shape-mismatch'
-    ? MeshShapeMismatchDetail
-    : C extends 'mesh-range-invalid'
-      ? MeshRangeInvalidDetail
-      : never;
-
-type MeshUpdateErrorDetail = MeshUpdateErrorDetailFor<MeshUpdateErrorCode>;
-
-const MESH_UPDATE_POLICY = {
-  'mesh-not-resident': {
-    expected: 'the mesh handle is resident in the renderer before it is updated',
-    hint: (detail: MeshNotResidentDetail) =>
-      `mesh handle ${detail.handle} is not resident; call renderer.assets.get(handle) and ensure the mesh is resident before updating`,
-  },
-  'mesh-shape-mismatch': {
-    expected: 'a same-shape update preserves the resident mesh layout, counts, and index format',
-    hint: (detail: MeshShapeMismatchDetail) =>
-      `mesh handle ${detail.handle} cannot be updated in place: expected ${detail.expected}, got ${detail.actual}; use a new mesh asset handle for a shape change`,
-  },
-  'mesh-range-invalid': {
-    expected: 'a vertex range is within the resident mesh and matches the resident stride',
-    hint: (detail: MeshRangeInvalidDetail) => {
-      if (detail.reason === 'stride-mismatch') {
-        return `vertex range for mesh handle ${detail.handle} has ${detail.actualByteLength} bytes; expected ${detail.expectedByteLength} bytes for the resident stride`;
-      }
-      return `vertex range [${detail.firstVertex}, ${detail.firstVertex + detail.vertexCount}) is invalid (${detail.reason}) for resident mesh handle ${detail.handle} with ${detail.residentVertexCount} vertices`;
-    },
-  },
-} satisfies Record<string, { readonly expected: string; readonly hint: (detail: never) => string }>;
-
-class MeshUpdateErrorClass extends Error {
-  readonly code: MeshUpdateErrorCode;
-  readonly expected: string;
-  readonly hint: string;
-  readonly detail: MeshUpdateErrorDetail;
-
-  constructor(args: { code: MeshUpdateErrorCode; detail: MeshUpdateErrorDetail }) {
-    const policy = MESH_UPDATE_POLICY[args.code] as {
-      readonly expected: string;
-      readonly hint: (detail: MeshUpdateErrorDetail) => string;
-    };
-    const hint = policy.hint(args.detail);
-    super(`mesh update: ${args.code} (${hint})`);
-    this.name = 'MeshUpdateError';
-    this.code = args.code;
-    this.expected = policy.expected;
-    this.hint = hint;
-    this.detail = args.detail;
-  }
-}
-
-type MeshUpdateErrorVariant<C extends MeshUpdateErrorCode> = MeshUpdateErrorClass & {
-  readonly code: C;
-  readonly detail: MeshUpdateErrorDetailFor<C>;
-};
-
-export type MeshUpdateError = {
-  [C in MeshUpdateErrorCode]: MeshUpdateErrorVariant<C>;
-}[MeshUpdateErrorCode];
-
-interface MeshUpdateErrorConstructor {
-  new <C extends MeshUpdateErrorCode>(args: {
-    code: C;
-    detail: MeshUpdateErrorDetailFor<C>;
-  }): MeshUpdateErrorVariant<C>;
-  readonly prototype: MeshUpdateErrorClass;
-}
-
-export const MeshUpdateError: MeshUpdateErrorConstructor =
-  MeshUpdateErrorClass as unknown as MeshUpdateErrorConstructor;

package/src/mipmap-generator.ts

@@ -1,244 +0,0 @@
-import { err, ok, type Result, RhiError } from '@forgeax/engine-rhi';
-
-export type MipmapDevice = {
-  // biome-ignore lint/suspicious/noExplicitAny: RHI descriptors are opaque here
-  createSampler(desc?: any): Result<any, any>;
-  // biome-ignore lint/suspicious/noExplicitAny: RHI descriptors are opaque here
-  createBindGroupLayout(desc: any): Result<any, any>;
-  // biome-ignore lint/suspicious/noExplicitAny: RHI descriptors are opaque here
-  createPipelineLayout(desc: any): Result<any, any>;
-  // biome-ignore lint/suspicious/noExplicitAny: RHI descriptors are opaque here
-  createRenderPipeline(desc: any): Result<any, any>;
-};
-
-export type MipmapShaderModuleFactory = (
-  device: MipmapDevice,
-  desc: { code: string; label?: string },
-) => Promise<Result<unknown, RhiError>>;
-
-interface MipmapPipelineCache {
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU handles
-  readonly sampler: any;
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU handles
-  readonly module: any;
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU handles
-  readonly layout: any;
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU handles
-  readonly pipelines: Map<GPUTextureFormat, any>;
-}
-
-const deviceCache = new WeakMap<MipmapDevice, MipmapPipelineCache>();
-const MIPMAP_WGSL = `
-struct VsOut { @builtin(position) clip : vec4<f32>, @location(0) uv : vec2<f32> };
-@vertex fn vs_main(@builtin(vertex_index) vid : u32) -> VsOut {
-  var positions = array<vec2<f32>, 3>(vec2<f32>(-1.0, -1.0), vec2<f32>(-1.0, 3.0), vec2<f32>(3.0, -1.0));
-  let pos = positions[vid];
-  var out : VsOut;
-  out.clip = vec4<f32>(pos, 0.0, 1.0);
-  out.uv = pos * vec2<f32>(0.5, -0.5) + vec2<f32>(0.5);
-  return out;
-}
-@group(0) @binding(0) var src_sampler : sampler;
-@group(0) @binding(1) var src_texture : texture_2d<f32>;
-@fragment fn fs_main(in : VsOut) -> @location(0) vec4<f32> { return textureSample(src_texture, src_sampler, in.uv); }
-`;
-
-export function numMipLevels(size: { width: number; height: number }): number {
-  const max = Math.max(size.width, size.height);
-  return max <= 1 ? 1 : Math.floor(Math.log2(max)) + 1;
-}
-
-export function mipmapCacheSize(device: MipmapDevice): number {
-  return deviceCache.get(device)?.pipelines.size ?? 0;
-}
-
-export async function getOrCreateMipmapPipeline(
-  device: MipmapDevice,
-  format: GPUTextureFormat,
-  asyncCreateShaderModule: MipmapShaderModuleFactory,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU pipeline
-): Promise<Result<any, unknown>> {
-  const cache = await ensureDeviceCache(device, asyncCreateShaderModule);
-  if (!cache.ok) return cache;
-  const existing = cache.value.pipelines.get(format);
-  if (existing !== undefined) return ok(existing);
-  const layoutRes = device.createPipelineLayout({
-    label: 'mipmap-pl',
-    bindGroupLayouts: [cache.value.layout],
-  });
-  if (!layoutRes.ok) return layoutRes;
-  const pipelineRes = device.createRenderPipeline({
-    label: `mipmap-pipeline-${format}`,
-    layout: layoutRes.value,
-    vertex: { module: cache.value.module, entryPoint: 'vs_main' },
-    fragment: { module: cache.value.module, entryPoint: 'fs_main', targets: [{ format }] },
-    primitive: { topology: 'triangle-list' },
-  });
-  if (!pipelineRes.ok) return pipelineRes;
-  cache.value.pipelines.set(format, pipelineRes.value);
-  return pipelineRes;
-}
-
-async function ensureDeviceCache(
-  device: MipmapDevice,
-  asyncCreateShaderModule: MipmapShaderModuleFactory,
-): Promise<Result<MipmapPipelineCache, RhiError>> {
-  const existing = deviceCache.get(device);
-  if (existing !== undefined) return ok(existing);
-  const moduleRes = await asyncCreateShaderModule(device, {
-    code: MIPMAP_WGSL,
-    label: 'mipmap-wgsl',
-  });
-  if (!moduleRes.ok) return moduleRes;
-  const samplerRes = device.createSampler({
-    magFilter: 'linear',
-    minFilter: 'linear',
-    mipmapFilter: 'linear',
-  });
-  if (!samplerRes.ok) return samplerRes;
-  const layoutRes = device.createBindGroupLayout({
-    label: 'mipmap-bgl',
-    entries: [
-      { binding: 0, visibility: 0x2, sampler: { type: 'filtering' } },
-      { binding: 1, visibility: 0x2, texture: { sampleType: 'float', viewDimension: '2d' } },
-    ],
-  });
-  if (!layoutRes.ok) return layoutRes;
-  const cache: MipmapPipelineCache = {
-    sampler: samplerRes.value,
-    module: moduleRes.value,
-    layout: layoutRes.value,
-    pipelines: new Map(),
-  };
-  deviceCache.set(device, cache);
-  return ok(cache);
-}
-
-export type MipmapBlitDevice = MipmapDevice & {
-  // biome-ignore lint/suspicious/noExplicitAny: RHI descriptors are opaque here
-  createTexture(desc: any): Result<any, any>;
-  // biome-ignore lint/suspicious/noExplicitAny: RHI descriptors are opaque here
-  createBindGroup(desc: any): Result<any, any>;
-  // biome-ignore lint/suspicious/noExplicitAny: RHI descriptors are opaque here
-  createTextureView(texture: any, desc: any): Result<any, any>;
-  // biome-ignore lint/suspicious/noExplicitAny: RHI descriptors are opaque here
-  createCommandEncoder(desc?: any): Result<any, any>;
-  readonly queue: { submit(buffers: ReadonlyArray<unknown>): Result<void, unknown> };
-};
-
-function recordMipmapBlit<E>(
-  device: MipmapBlitDevice,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture handle
-  texture: any,
-  levels: number,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU pipeline handle
-  pipeline: any,
-  cache: MipmapPipelineCache,
-): Result<void, E> {
-  const encoderRes = device.createCommandEncoder({ label: 'mipmap-encoder' });
-  if (!encoderRes.ok) return encoderRes;
-  const encoder = encoderRes.value;
-  for (let i = 1; i < levels; i++) {
-    const srcViewRes = device.createTextureView(texture, {
-      baseMipLevel: i - 1,
-      mipLevelCount: 1,
-      dimension: '2d',
-    });
-    if (!srcViewRes.ok) return srcViewRes;
-    const dstViewRes = device.createTextureView(texture, {
-      baseMipLevel: i,
-      mipLevelCount: 1,
-      dimension: '2d',
-    });
-    if (!dstViewRes.ok) return dstViewRes;
-    const bindGroupRes = device.createBindGroup({
-      label: `mipmap-bg-${i}`,
-      layout: cache.layout,
-      entries: [
-        { binding: 0, resource: { kind: 'sampler', value: cache.sampler } },
-        { binding: 1, resource: { kind: 'textureView', value: srcViewRes.value } },
-      ],
-    });
-    if (!bindGroupRes.ok) return bindGroupRes;
-    const pass = encoder.beginRenderPass({
-      label: `mipmap-pass-${i}`,
-      colorAttachments: [
-        {
-          view: dstViewRes.value,
-          clearValue: { r: 0, g: 0, b: 0, a: 1 },
-          loadOp: 'clear',
-          storeOp: 'store',
-        },
-      ],
-    });
-    pass.setPipeline(pipeline);
-    pass.setBindGroup(0, bindGroupRes.value);
-    pass.draw(3, 1, 0, 0);
-    pass.end();
-  }
-  const finishRes = encoder.finish();
-  if (!finishRes.ok) return finishRes;
-  return device.queue.submit([finishRes.value]) as Result<void, E>;
-}
-
-export async function generateMipmaps(
-  device: MipmapBlitDevice,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture handle
-  texture: any,
-  descriptor: {
-    readonly format: GPUTextureFormat;
-    readonly width: number;
-    readonly height: number;
-    readonly levels?: number;
-  },
-  asyncCreateShaderModule: MipmapShaderModuleFactory,
-): Promise<Result<void, unknown>> {
-  const levels = descriptor.levels ?? numMipLevels(descriptor);
-  if (levels <= 1) return ok(undefined);
-  const pipelineRes = await getOrCreateMipmapPipeline(
-    device,
-    descriptor.format,
-    asyncCreateShaderModule,
-  );
-  if (!pipelineRes.ok) return pipelineRes;
-  const cache = deviceCache.get(device);
-  if (cache === undefined)
-    return err({ code: 'webgpu-runtime-error', message: 'mipmap cache missing' });
-  return recordMipmapBlit<unknown>(device, texture, levels, pipelineRes.value, cache);
-}
-
-export function blitMipmapsSync(
-  device: MipmapBlitDevice,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture handle
-  texture: any,
-  descriptor: {
-    readonly format: GPUTextureFormat;
-    readonly width: number;
-    readonly height: number;
-    readonly levels?: number;
-  },
-): Result<void, RhiError> {
-  const levels = descriptor.levels ?? numMipLevels(descriptor);
-  if (levels <= 1) return ok(undefined);
-  const cache = deviceCache.get(device);
-  if (cache === undefined) {
-    return err(
-      new RhiError({
-        code: 'rhi-not-available',
-        expected: 'mipmap pipeline cache prewarmed for this device before blitMipmapsSync',
-        hint: 'prewarm the mipmap pipeline before the synchronous record-stage blit',
-      }),
-    );
-  }
-  const pipeline = cache.pipelines.get(descriptor.format);
-  if (pipeline === undefined) {
-    return err(
-      new RhiError({
-        code: 'rhi-not-available',
-        expected: `mipmap pipeline for format ${descriptor.format} prewarmed`,
-        hint: `prewarm format ${descriptor.format} before the synchronous blit`,
-      }),
-    );
-  }
-  return recordMipmapBlit<RhiError>(device, texture, levels, pipeline, cache);
-}