@forgeax/engine-render 0.1.2

package/src/gpu-resource.ts

@@ -0,0 +1,159 @@
+// @forgeax/engine-runtime / gpu-resource
+//
+// feat-20260612-rhi-destroy-renderer-dispose-gpu-lifecycle / M2 / w7 + w8.
+//
+// Runtime-side wrappers around RHI Buffer / Texture opaque handles that
+// expose an explicit `.destroy()` lifecycle and an `isDestroyed` flag.
+//
+// Design rationale (charter + plan-strategy + architecture-principles):
+//
+//   - SSOT (architecture-principles §1): the lifecycle bookkeeping (the
+//     "is this handle destroyed yet?" fact) lives once in the RHI shim
+//     layer (rhi-webgpu device.ts: BUFFER_META_MAP / TEXTURE_META_MAP;
+//     rhi-wgpu device.ts: same shape over the wgpu wasm boundary). The
+//     runtime wrapper does NOT keep its own destroyed: Set; it forwards
+//     to `device.destroyBuffer(handle)` / `device.destroyTexture(handle)`
+//     and lets the RHI shim be the authority. The local `destroyed`
+//     boolean is a derived view (architecture-principles §2 Derive,
+//     Don't Duplicate) for the synchronous `isDestroyed` getter --
+//     flipped on the success branch of the forward, never on the err
+//     branch (so a second destroy preserves the prior `true`).
+//
+//   - Concept compression (charter F1 / AGENTS.md design axiom): a
+//     single union `type GpuResource = GpuBuffer | GpuTexture` covers
+//     both buffer and texture lifecycles so AI-user-facing code that
+//     just wants "any GPU resource I need to dispose" reaches one
+//     symbol. Parallel classes (not a runtime-tagged generic
+//     `GpuResource<'buffer' | 'texture'>`) so the shape mirrors the
+//     RHI opaque-handle taxonomy verbatim and TS narrowing on
+//     instanceof / `'data' in r` keeps each branch typed end-to-end
+//     (plan-strategy D-2).
+//
+//   - v1 single-owner immortal (requirements §Constraints 8): no refcount,
+//     no shared ownership, no move semantics. The wrapper holds the
+//     handle once; whoever constructed it disposes it. A future
+//     refcount layer (if needed) wraps GpuResource externally without
+//     re-entering this file.
+//
+//   - Plain boolean isDestroyed (plan-strategy D-5): no typed-state
+//     narrowing (i.e. no `Live<GpuBuffer>` / `Destroyed<GpuBuffer>`
+//     compile-time partition). The check happens at runtime via the
+//     getter; the RHI fail-fast on second destroy is the structural
+//     guard. Keeps the public type surface flat (charter F1: one
+//     symbol, not three states).
+//
+//   - RHI stays spec-aligned and opaque-handle-only (requirements
+//     §Constraints 3): GpuResource is a runtime concept; the RHI package
+//     exports no wrapper class.
+//
+// Failure paths (forwarded verbatim from RhiDevice):
+//   - second `.destroy()` on the same wrapper -> `Result.err({ code:
+//     'destroy-after-destroy', ... })` (RHI errors.ts §RhiErrorCode;
+//     introduced in feat-20260612 M1 / w1).
+
+import type { Buffer, Result, RhiDevice, RhiError, Texture } from '@forgeax/engine-rhi';
+
+/**
+ * Runtime wrapper around an RHI `Buffer` opaque handle that exposes
+ * an explicit `.destroy()` lifecycle.
+ *
+ * Holds the device by reference (no clone); the device's own lifetime
+ * outlives the buffer. After `.destroy()` returns ok, `isDestroyed`
+ * flips to true; a second `.destroy()` returns err code
+ * `'destroy-after-destroy'` forwarded from `device.destroyBuffer(...)`.
+ *
+ * @example
+ *   import { GpuBuffer } from '@forgeax/engine-render/internal';
+ *   const created = device.createBuffer({ size: 64, usage: GPUBufferUsage.STORAGE });
+ *   if (!created.ok) return;
+ *   const gpuBuf = new GpuBuffer(device, created.value);
+ *   // ... use gpuBuf.handle in RHI calls ...
+ *   const r = gpuBuf.destroy();
+ *   if (!r.ok) {
+ *     // r.error.code is one of the RhiErrorCode union members,
+ *     // typically 'destroy-after-destroy' on a stale handle.
+ *   }
+ */
+export class GpuBuffer {
+  readonly device: RhiDevice;
+  readonly handle: Buffer;
+  // SSOT note: the canonical destroyed: boolean lives on the RHI shim's
+  // BUFFER_META_MAP. This local flag is a derived view written only on
+  // the success branch of `device.destroyBuffer(...)`; charter §F1.
+  private destroyed = false;
+
+  constructor(device: RhiDevice, handle: Buffer) {
+    this.device = device;
+    this.handle = handle;
+  }
+
+  get isDestroyed(): boolean {
+    return this.destroyed;
+  }
+
+  /**
+   * Destroy the underlying GPU buffer. Forwards to
+   * `device.destroyBuffer(handle)`; on ok flips `isDestroyed` to true,
+   * on err leaves the flag unchanged so a downstream second destroy
+   * still surfaces the underlying RHI fail-fast.
+   */
+  destroy(): Result<void, RhiError> {
+    const r = this.device.destroyBuffer(this.handle);
+    if (r.ok) {
+      this.destroyed = true;
+    }
+    return r;
+  }
+}
+
+/**
+ * Runtime wrapper around an RHI `Texture` opaque handle that exposes
+ * an explicit `.destroy()` lifecycle. Mirrors `GpuBuffer` exactly --
+ * the only difference is the underlying RHI surface
+ * (`device.destroyTexture` instead of `device.destroyBuffer`) and the
+ * handle brand. Same SSOT rationale: the destroyed bookkeeping lives
+ * on the RHI shim's TEXTURE_META_MAP; the local flag is a derived view.
+ *
+ * @example
+ *   import { GpuTexture } from '@forgeax/engine-render/internal';
+ *   const r = device.createTexture({ size: [w, h, 1], format: 'rgba8unorm', usage: ... });
+ *   if (!r.ok) return;
+ *   const gpuTex = new GpuTexture(device, r.value);
+ *   // ... use gpuTex.handle in RHI calls ...
+ *   gpuTex.destroy();
+ */
+export class GpuTexture {
+  readonly device: RhiDevice;
+  readonly handle: Texture;
+  private destroyed = false;
+
+  constructor(device: RhiDevice, handle: Texture) {
+    this.device = device;
+    this.handle = handle;
+  }
+
+  get isDestroyed(): boolean {
+    return this.destroyed;
+  }
+
+  /**
+   * Destroy the underlying GPU texture. Forwards to
+   * `device.destroyTexture(handle)`; ok branch sets `isDestroyed=true`.
+   */
+  destroy(): Result<void, RhiError> {
+    const r = this.device.destroyTexture(this.handle);
+    if (r.ok) {
+      this.destroyed = true;
+    }
+    return r;
+  }
+}
+
+/**
+ * Union of runtime-managed GPU resources requiring explicit
+ * `.destroy()`. AI-user-facing code that needs to dispose "any GPU
+ * resource" types its parameter as `GpuResource` and lets TS narrow
+ * via `instanceof GpuBuffer / GpuTexture` if branch-specific access
+ * is required. Charter F1 single-entry indexability.
+ */
+export type GpuResource = GpuBuffer | GpuTexture;

package/src/gpu-scene-schema.ts

@@ -0,0 +1,224 @@
+export type GpuSceneScalar = 'u32' | 'i32' | 'f32';
+
+/**
+ * Renderer-owned mobility fact. `unknown` is intentional: a renderer must not
+ * infer staticness from how often an entity happened to move in one frame.
+ * Authoring/pack producers may provide the other two values explicitly.
+ */
+export type SceneMobility = 'static' | 'dynamic' | 'unknown';
+
+/**
+ * Explicit shadow-caster eligibility. `unknown` is not an eligible state; it
+ * keeps missing authoring/pack data visible to the later visibility owner.
+ */
+export type SceneCasterEligibility = 'eligible' | 'ineligible' | 'unknown';
+
+export type SceneFactRevisionDomain =
+  | 'transform'
+  | 'geometry'
+  | 'material'
+  | 'eligibility'
+  | 'space'
+  | 'batch'
+  | 'resource';
+
+export interface SceneFactRevisions {
+  readonly transform: number;
+  readonly geometry: number;
+  readonly material: number;
+  readonly eligibility: number;
+  readonly space: number;
+  readonly batch: number;
+  readonly resource: number;
+}
+
+/** Optional producer-owned facts carried by a RenderableSnapshot. */
+export interface RenderSceneFactInput {
+  readonly mobility?: SceneMobility;
+  readonly casterEligibility?: SceneCasterEligibility;
+  readonly revisions?: Partial<SceneFactRevisions>;
+}
+
+export type SceneBoundsFact =
+  | {
+      readonly status: 'present';
+      /** [minX, minY, minZ, maxX, maxY, maxZ] in world space. */
+      readonly worldAabb: Float32Array;
+      /** [minX, minY, minZ, maxX, maxY, maxZ] in local space. */
+      readonly localAabb: Float32Array;
+    }
+  | {
+      readonly status: 'missing';
+      readonly reason: 'missing-local-aabb' | 'invalid-local-aabb' | 'invalid-world-transform';
+    };
+
+export interface RenderSceneFact {
+  readonly slot: number;
+  readonly generation: number;
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly bounds: SceneBoundsFact;
+  readonly mobility: SceneMobility;
+  readonly casterEligibility: SceneCasterEligibility;
+  readonly revisions: SceneFactRevisions;
+}
+
+export type SceneFactDiagnosticCode = 'missing-bounds' | 'invalid-revision' | 'stale-generation';
+
+export interface SceneFactDiagnostic {
+  readonly code: SceneFactDiagnosticCode;
+  readonly slot?: number;
+  readonly generation?: number;
+  readonly worldId?: number;
+  readonly entityKey?: number;
+  readonly expectedGeneration?: number;
+  readonly actualGeneration?: number;
+  readonly domain?: SceneFactRevisionDomain;
+  readonly reason?: string;
+}
+
+/** Stable primitive flag bits; the extra fact bits do not change the table ABI. */
+export const GPU_SCENE_PRIMITIVE_FLAGS = Object.freeze({
+  active: 1,
+  hasBounds: 2,
+  gpuDriven: 4,
+  static: 8,
+  dynamic: 16,
+  casterEligible: 32,
+  casterIneligible: 64,
+  casterUnknown: 128,
+});
+
+const TYPE_LAYOUT = {
+  u32: { size: 4, alignment: 4 },
+  i32: { size: 4, alignment: 4 },
+  f32: { size: 4, alignment: 4 },
+  'vec4<f32>': { size: 16, alignment: 16 },
+  'mat4x4<f32>': { size: 64, alignment: 16 },
+} satisfies Readonly<Record<string, { readonly size: number; readonly alignment: number }>>;
+
+export type GpuSceneFieldType = keyof typeof TYPE_LAYOUT;
+
+export interface GpuSceneField {
+  readonly name: string;
+  readonly type: GpuSceneFieldType;
+}
+
+export interface GpuSceneTableSchema {
+  readonly name: string;
+  readonly fields: readonly GpuSceneField[];
+}
+
+export interface GpuSceneFieldLayout extends GpuSceneField {
+  readonly offset: number;
+  readonly size: number;
+  readonly alignment: number;
+}
+
+export interface GpuSceneTableLayout {
+  readonly name: string;
+  readonly stride: number;
+  readonly fields: readonly GpuSceneFieldLayout[];
+}
+
+function align(value: number, alignment: number): number {
+  return Math.ceil(value / alignment) * alignment;
+}
+
+export function deriveGpuSceneTableLayout(schema: GpuSceneTableSchema): GpuSceneTableLayout {
+  let cursor = 0;
+  let tableAlignment = 4;
+  const fields = schema.fields.map((field) => {
+    const typeLayout = TYPE_LAYOUT[field.type];
+    cursor = align(cursor, typeLayout.alignment);
+    tableAlignment = Math.max(tableAlignment, typeLayout.alignment);
+    const layout: GpuSceneFieldLayout = { ...field, offset: cursor, ...typeLayout };
+    cursor += typeLayout.size;
+    return layout;
+  });
+  return { name: schema.name, stride: align(cursor, tableAlignment), fields };
+}
+
+export function gpuSceneFieldOffset(layout: GpuSceneTableLayout, name: string): number {
+  const field = layout.fields.find((candidate) => candidate.name === name);
+  if (field === undefined) throw new RangeError(`${layout.name} has no field named ${name}`);
+  return field.offset;
+}
+
+export function gpuSceneWgsl(layout: GpuSceneTableLayout): string {
+  const fields = layout.fields.map((field) => `  ${field.name}: ${field.type},`).join('\n');
+  return `struct ${layout.name} {\n${fields}\n};`;
+}
+
+export const GPU_SCENE_SCHEMAS = Object.freeze({
+  primitive: {
+    name: 'GpuScenePrimitive',
+    fields: [
+      { name: 'generation', type: 'u32' },
+      { name: 'flags', type: 'u32' },
+      { name: 'transformIndex', type: 'u32' },
+      { name: 'materialIndex', type: 'u32' },
+      { name: 'drawTemplateIndex', type: 'u32' },
+      { name: 'instanceStart', type: 'u32' },
+      { name: 'instanceCount', type: 'u32' },
+      { name: 'assetHandle', type: 'u32' },
+      { name: 'localBoundsMin', type: 'vec4<f32>' },
+      { name: 'localBoundsMax', type: 'vec4<f32>' },
+    ],
+  },
+  instance: {
+    name: 'GpuSceneInstance',
+    fields: [
+      { name: 'primitiveIndex', type: 'u32' },
+      { name: 'transformIndex', type: 'u32' },
+      { name: 'customDataStart', type: 'u32' },
+      { name: 'flags', type: 'u32' },
+    ],
+  },
+  transform: {
+    name: 'GpuSceneTransform',
+    fields: [
+      { name: 'currentWorld', type: 'mat4x4<f32>' },
+      { name: 'previousWorld', type: 'mat4x4<f32>' },
+    ],
+  },
+  drawTemplate: {
+    name: 'GpuSceneDrawTemplate',
+    fields: [
+      { name: 'pipelineClass', type: 'u32' },
+      { name: 'materialIndex', type: 'u32' },
+      { name: 'firstIndex', type: 'u32' },
+      { name: 'indexCount', type: 'u32' },
+      { name: 'baseVertex', type: 'i32' },
+      { name: 'firstInstance', type: 'u32' },
+      { name: 'passFlags', type: 'u32' },
+      { name: 'reserved', type: 'u32' },
+    ],
+  },
+  material: {
+    name: 'GpuSceneMaterial',
+    fields: [
+      { name: 'params0', type: 'vec4<f32>' },
+      { name: 'params1', type: 'vec4<f32>' },
+      { name: 'params2', type: 'vec4<f32>' },
+      { name: 'params3', type: 'vec4<f32>' },
+      { name: 'resource0', type: 'u32' },
+      { name: 'resource1', type: 'u32' },
+      { name: 'resource2', type: 'u32' },
+      { name: 'resource3', type: 'u32' },
+    ],
+  },
+} satisfies Readonly<Record<string, GpuSceneTableSchema>>);
+
+export const GPU_SCENE_LAYOUTS = Object.freeze(
+  Object.fromEntries(
+    Object.entries(GPU_SCENE_SCHEMAS).map(([name, schema]) => [
+      name,
+      deriveGpuSceneTableLayout(schema),
+    ]),
+  ) as {
+    readonly [Name in keyof typeof GPU_SCENE_SCHEMAS]: GpuSceneTableLayout;
+  },
+);
+
+export const GPU_SCENE_WGSL = Object.values(GPU_SCENE_LAYOUTS).map(gpuSceneWgsl).join('\n\n');