@forgeax/engine-render 0.1.2

package/src/mesh-update-errors.ts

@@ -0,0 +1,113 @@
+/** 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

@@ -0,0 +1,244 @@
+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);
+}

package/src/param-schema-projection-census.ts

@@ -0,0 +1,73 @@
+import type {
+  DerivedMaterialInterface,
+  EngineMetrics,
+  ParamSchemaDeriveObservationKind,
+  ParamSchemaDeriveObserver,
+  ParamSchemaEntry,
+} from '@forgeax/engine-types';
+import { derive, deriveObserved } from '@forgeax/engine-types';
+
+export type ParamSchemaProjectionCensusSite =
+  | 'entity-extract'
+  | 'submesh'
+  | 'prepared-material'
+  | 'record-payload'
+  | 'pipeline-bgl';
+
+export type ParamSchemaProjectionCensusKind =
+  | ParamSchemaDeriveObservationKind
+  | 'registered-projection-read'
+  | 'empty-schema-legacy-inference';
+
+export interface ParamSchemaProjectionCensus extends ParamSchemaDeriveObserver {
+  readonly record: (
+    kind: ParamSchemaProjectionCensusKind,
+    site: ParamSchemaProjectionCensusSite,
+  ) => void;
+}
+
+/**
+ * Create the renderer-scoped, debug-only ParamSchema compatibility observer.
+ *
+ * The observer writes only to the existing per-Renderer EngineMetrics map.
+ * When `enabled` is false, both `observe` and `record` are no-ops; callers
+ * continue through the original derive/projection path without a new cache or
+ * content hash. Counter names are intentionally stable so a browser probe can
+ * subtract before/after snapshots without retaining renderer objects.
+ */
+export function createParamSchemaProjectionCensus(
+  metrics: EngineMetrics,
+  enabled: boolean,
+): ParamSchemaProjectionCensus {
+  const record = (kind: ParamSchemaProjectionCensusKind, site: ParamSchemaProjectionCensusSite) => {
+    if (!enabled) return;
+    metrics.increment(`paramschema.${kind}`);
+    metrics.increment(`paramschema.${kind}.${site}`);
+  };
+  return {
+    enabled,
+    observe: (event) => record(event.kind, normalizeSite(event.site)),
+    record,
+  };
+}
+
+function normalizeSite(site: string): ParamSchemaProjectionCensusSite {
+  switch (site) {
+    case 'entity-extract':
+    case 'submesh':
+    case 'prepared-material':
+    case 'record-payload':
+    case 'pipeline-bgl':
+      return site;
+    default:
+      return 'entity-extract';
+  }
+}
+
+export function deriveParamSchemaForCensus(
+  schema: readonly ParamSchemaEntry[],
+  census: ParamSchemaProjectionCensus | undefined,
+  site: ParamSchemaProjectionCensusSite,
+): DerivedMaterialInterface {
+  return census?.enabled ? deriveObserved(schema, census, site) : derive(schema);
+}