@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/points-lines/prepare.ts

@@ -0,0 +1,177 @@
+import type { MeshAsset } from '@forgeax/engine-types';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { PointsLinesPrepareFailedError } from '../errors/render';
+import type { PointsLinesExpandedGeometry, PointsLinesExpansionCache } from './expansion-cache';
+import {
+  createPointsLinesLaneContract,
+  type PointsLinesBackend,
+  type PointsLinesLane,
+  type PointsLinesLaneContract,
+} from './record';
+import type { PointsLinesRetainedSnapshot } from './snapshot';
+
+export interface PointsLinesGpuResourceAdapter<Resource> {
+  create(geometry: PointsLinesExpandedGeometry): Result<Resource, Error>;
+  upload(resource: Resource, geometry: PointsLinesExpandedGeometry): Result<number, Error>;
+  validate(resource: Resource, geometry: PointsLinesExpandedGeometry): Result<void, Error>;
+  destroy(resource: Resource): void;
+}
+
+export interface PointsLinesPreparedResource<Resource> {
+  readonly resource: Resource;
+  readonly geometry: PointsLinesExpandedGeometry;
+  readonly snapshot: PointsLinesRetainedSnapshot;
+  readonly uploadedBytes: number;
+  readonly lastKnownGood: true;
+}
+
+export interface PointsLinesPreparationOptions<Resource> {
+  readonly cache: PointsLinesExpansionCache;
+  readonly adapter: PointsLinesGpuResourceAdapter<Resource>;
+}
+
+export interface PointsLinesLanePreparationAdapter<Resource> {
+  readonly contract: PointsLinesLaneContract;
+  prepare(
+    snapshot: PointsLinesRetainedSnapshot,
+    mesh: MeshAsset,
+  ): Result<PointsLinesPreparedResource<Resource>, PointsLinesPrepareFailedError>;
+  resetForDeviceLoss(): void;
+  lastKnownGood(): PointsLinesPreparedResource<Resource> | undefined;
+  inspect(): PointsLinesPreparationInspection<Resource>;
+}
+
+export interface PointsLinesPreparationInspection<Resource> {
+  readonly status: 'empty' | 'resident' | 'rebuild-pending';
+  readonly lastKnownGood: boolean;
+  readonly liveResource: Resource | undefined;
+  readonly liveBytes: number;
+  readonly candidateBytes: number;
+  readonly cacheEntries: number;
+  readonly uploads: number;
+  readonly rebuilds: number;
+  readonly failures: number;
+}
+
+/**
+ * Owns one atomic candidate/LKG pair for a Points/Lines render projection.
+ * GPU resources are supplied by the existing DeviceScope adapter; this class
+ * keeps no backend handle or second resource ledger.
+ */
+export class PointsLinesPreparation<Resource> {
+  private live: PointsLinesPreparedResource<Resource> | undefined;
+  private pendingCandidateBytes = 0;
+  private status: 'empty' | 'resident' | 'rebuild-pending' = 'empty';
+  private uploads = 0;
+  private rebuilds = 0;
+  private failures = 0;
+
+  constructor(private readonly options: PointsLinesPreparationOptions<Resource>) {}
+
+  prepare(
+    snapshot: PointsLinesRetainedSnapshot,
+    mesh: MeshAsset,
+  ): Result<PointsLinesPreparedResource<Resource>, PointsLinesPrepareFailedError> {
+    const geometry = this.options.cache.getOrCreate(snapshot, mesh);
+    if (this.live?.geometry.key === geometry.key) {
+      this.live = {
+        ...this.live,
+        snapshot,
+        uploadedBytes: 0,
+      };
+      this.status = 'resident';
+      return ok(this.live);
+    }
+
+    this.pendingCandidateBytes = geometry.derivedBytes;
+    const created = this.options.adapter.create(geometry);
+    if (!created.ok) return this.fail(snapshot, created.error);
+    const candidate = created.value;
+    const uploaded = this.options.adapter.upload(candidate, geometry);
+    if (!uploaded.ok) {
+      this.options.adapter.destroy(candidate);
+      return this.fail(snapshot, uploaded.error);
+    }
+    this.uploads += 1;
+    const validated = this.options.adapter.validate(candidate, geometry);
+    if (!validated.ok) {
+      this.options.adapter.destroy(candidate);
+      return this.fail(snapshot, validated.error);
+    }
+
+    const previous = this.live;
+    this.live = {
+      resource: candidate,
+      geometry,
+      snapshot,
+      uploadedBytes: uploaded.value,
+      lastKnownGood: true,
+    };
+    this.pendingCandidateBytes = 0;
+    this.status = 'resident';
+    this.rebuilds += 1;
+    if (previous !== undefined) this.options.adapter.destroy(previous.resource);
+    return ok(this.live);
+  }
+
+  resetForDeviceLoss(): void {
+    if (this.live !== undefined) this.options.adapter.destroy(this.live.resource);
+    this.live = undefined;
+    this.pendingCandidateBytes = 0;
+    this.status = 'rebuild-pending';
+  }
+
+  lastKnownGood(): PointsLinesPreparedResource<Resource> | undefined {
+    return this.live;
+  }
+
+  inspect(): PointsLinesPreparationInspection<Resource> {
+    return {
+      status: this.status,
+      lastKnownGood: this.live?.lastKnownGood ?? false,
+      liveResource: this.live?.resource,
+      liveBytes: this.live?.geometry.derivedBytes ?? 0,
+      candidateBytes: this.pendingCandidateBytes,
+      cacheEntries: this.options.cache.size,
+      uploads: this.uploads,
+      rebuilds: this.rebuilds,
+      failures: this.failures,
+    };
+  }
+
+  private fail(
+    snapshot: PointsLinesRetainedSnapshot,
+    cause: Error,
+  ): Result<never, PointsLinesPrepareFailedError> {
+    this.pendingCandidateBytes = 0;
+    this.failures += 1;
+    return err(
+      new PointsLinesPrepareFailedError({
+        owner: 'points-lines',
+        generation: snapshot.meshGeneration,
+        stage: 'prepare',
+        cause: cause.message,
+        lastKnownGood: this.live !== undefined,
+      }),
+    );
+  }
+}
+
+/**
+ * Binds the existing atomic preparation owner to a lane contract. It carries
+ * no RHI handle and does not add a second cache or recovery owner.
+ */
+export function createPointsLinesLanePreparationAdapter<Resource>(
+  lane: PointsLinesLane,
+  backend: PointsLinesBackend,
+  options: PointsLinesPreparationOptions<Resource>,
+): PointsLinesLanePreparationAdapter<Resource> {
+  const preparation = new PointsLinesPreparation(options);
+  return {
+    contract: createPointsLinesLaneContract(lane, backend),
+    prepare: (snapshot, mesh) => preparation.prepare(snapshot, mesh),
+    resetForDeviceLoss: () => preparation.resetForDeviceLoss(),
+    lastKnownGood: () => preparation.lastKnownGood(),
+    inspect: () => preparation.inspect(),
+  };
+}

package/src/points-lines/record.ts

@@ -0,0 +1,125 @@
+import type { PointsLinesExpandedGeometry } from './expansion-cache';
+import type { PointsLinesRetainedSnapshot } from './snapshot';
+
+export const POINTS_LINES_MATERIAL_SHADER_ID = 'forgeax::points-lines';
+
+export type PointsLinesLane = 'direct' | 'clustered' | 'cpu-webgl2';
+export type PointsLinesBackend = 'webgpu' | 'wgpu-webgl2' | 'null';
+
+export interface PointsLinesLaneContract {
+  readonly lane: PointsLinesLane;
+  readonly backend: PointsLinesBackend;
+  readonly authoring: 'shared';
+  readonly evidence: 'runtime' | 'structural-only';
+  readonly material: {
+    readonly source: 'MaterialAsset';
+    readonly shaderId: typeof POINTS_LINES_MATERIAL_SHADER_ID;
+    readonly shadingModel: 'unlit';
+    readonly clusteredLighting: false;
+    readonly lit: false;
+  };
+  readonly graph: {
+    readonly additionalAttachments: 0;
+    readonly additionalPasses: 0;
+  };
+  readonly shadowDrawCount: 0;
+  readonly capabilities: {
+    readonly compute: false;
+    readonly storage: false;
+    readonly indirect: false;
+  };
+}
+
+export interface PointsLinesRecordPlan {
+  readonly lane: PointsLinesLane;
+  readonly backend: PointsLinesBackend;
+  readonly materialShaderId: typeof POINTS_LINES_MATERIAL_SHADER_ID;
+  readonly component: 'Points' | 'Lines';
+  readonly meshGeneration: number;
+  readonly materialGeneration: number;
+  readonly vertexCount: number;
+  readonly indexCount: number;
+  readonly drawCount: 0 | 1;
+  readonly shadowDrawCount: 0;
+  readonly conservativeMarginPx: number;
+  readonly graph: PointsLinesLaneContract['graph'];
+}
+
+/**
+ * Describes the shared lane boundary without selecting a backend in authoring.
+ * Every lane uses CPU-uploaded triangle expansion; capability flags therefore
+ * stay false, including on WebGPU, and the graph remains the existing pass.
+ */
+export function createPointsLinesLaneContract(
+  lane: PointsLinesLane,
+  backend: PointsLinesBackend,
+): PointsLinesLaneContract {
+  return {
+    lane,
+    backend,
+    authoring: 'shared',
+    evidence: backend === 'null' ? 'structural-only' : 'runtime',
+    material: {
+      source: 'MaterialAsset',
+      shaderId: POINTS_LINES_MATERIAL_SHADER_ID,
+      shadingModel: 'unlit',
+      clusteredLighting: false,
+      lit: false,
+    },
+    graph: { additionalAttachments: 0, additionalPasses: 0 },
+    shadowDrawCount: 0,
+    capabilities: { compute: false, storage: false, indirect: false },
+  };
+}
+
+/**
+ * Turns one retained expansion into the bounded draw facts consumed by the
+ * existing record pass. The shader expands one quad per point or segment,
+ * so the limits are exactly four vertices and six indices per primitive.
+ */
+export function createPointsLinesRecordPlan(
+  snapshot: PointsLinesRetainedSnapshot,
+  geometry: PointsLinesExpandedGeometry,
+  contract: PointsLinesLaneContract,
+): PointsLinesRecordPlan {
+  const primitiveCount = geometry.pointCount + geometry.segmentCount;
+  const visible = snapshot.visible && primitiveCount > 0;
+  const conservativeMarginPx =
+    snapshot.style?.kind === 'points'
+      ? snapshot.style.sizePx * 0.5
+      : (snapshot.style?.widthPx ?? 0) * 0.5;
+  return {
+    lane: contract.lane,
+    backend: contract.backend,
+    materialShaderId: POINTS_LINES_MATERIAL_SHADER_ID,
+    component: geometry.component,
+    meshGeneration: snapshot.meshGeneration,
+    materialGeneration: snapshot.materialGeneration,
+    vertexCount: primitiveCount * 4,
+    indexCount: primitiveCount * 6,
+    drawCount: visible ? 1 : 0,
+    shadowDrawCount: 0,
+    conservativeMarginPx,
+    graph: contract.graph,
+  };
+}
+
+export interface PointsLinesLaneAdapter {
+  readonly contract: PointsLinesLaneContract;
+  createRecordPlan(
+    snapshot: PointsLinesRetainedSnapshot,
+    geometry: PointsLinesExpandedGeometry,
+  ): PointsLinesRecordPlan;
+}
+
+export function createPointsLinesLaneAdapter(
+  lane: PointsLinesLane,
+  backend: PointsLinesBackend,
+): PointsLinesLaneAdapter {
+  const contract = createPointsLinesLaneContract(lane, backend);
+  return {
+    contract,
+    createRecordPlan: (snapshot, geometry) =>
+      createPointsLinesRecordPlan(snapshot, geometry, contract),
+  };
+}

package/src/points-lines/snapshot.ts

@@ -0,0 +1,130 @@
+import type { PointShape } from '../components/points';
+
+export interface PointsLinesViewport {
+  readonly width: number;
+  readonly height: number;
+  readonly dpr: number;
+}
+
+export type PointsLinesStyle =
+  | { readonly kind: 'points'; readonly sizePx: number; readonly shape: PointShape }
+  | { readonly kind: 'lines'; readonly widthPx: number };
+
+export type PointsLinesInvalidation = 'none' | 'mesh' | 'material' | 'style' | 'view' | 'scene';
+
+/**
+ * Detached facts retained between frames for the Points/Lines owner.
+ *
+ * The snapshot deliberately contains no World, ECS row, AssetRegistry, GPU
+ * handle, or derived triangle data. Mesh and material generations are the
+ * producer-owned fences used by prepare; viewport and projection are the
+ * only camera-owned facts in this projection.
+ */
+export interface PointsLinesRetainedSnapshot {
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly component: 'Points' | 'Lines' | undefined;
+  readonly meshHandle: number;
+  readonly meshGeneration: number;
+  readonly materialHandle: number;
+  readonly materialGeneration: number;
+  readonly style: PointsLinesStyle | undefined;
+  readonly layer: number;
+  readonly sortKey: number | undefined;
+  readonly visible: boolean;
+  readonly sourceBounds: Float32Array;
+  readonly viewport: PointsLinesViewport;
+  readonly projection: Float32Array;
+  readonly dedicatedResourceBytes?: number;
+}
+
+export interface PointsLinesSnapshotInput
+  extends Omit<
+    PointsLinesRetainedSnapshot,
+    'sourceBounds' | 'viewport' | 'projection' | 'sortKey'
+  > {
+  readonly sortKey?: number | undefined;
+  readonly sourceBounds: ArrayLike<number>;
+  readonly viewport: PointsLinesViewport;
+  readonly projection: ArrayLike<number>;
+}
+
+export function createPointsLinesSnapshot(
+  input: PointsLinesSnapshotInput,
+): PointsLinesRetainedSnapshot {
+  return {
+    worldId: input.worldId,
+    entityKey: input.entityKey,
+    component: input.component,
+    meshHandle: input.meshHandle,
+    meshGeneration: input.meshGeneration,
+    materialHandle: input.materialHandle,
+    materialGeneration: input.materialGeneration,
+    style: input.style === undefined ? undefined : { ...input.style },
+    layer: input.layer,
+    sortKey: input.sortKey,
+    visible: input.visible,
+    sourceBounds: new Float32Array(input.sourceBounds),
+    viewport: { ...input.viewport },
+    projection: new Float32Array(input.projection),
+    ...(input.component === undefined ? { dedicatedResourceBytes: 0 } : {}),
+  };
+}
+
+export function comparePointsLinesSnapshots(
+  previous: PointsLinesRetainedSnapshot,
+  next: PointsLinesRetainedSnapshot,
+): PointsLinesInvalidation {
+  if (
+    previous.meshHandle !== next.meshHandle ||
+    previous.meshGeneration !== next.meshGeneration ||
+    !sameArray(previous.sourceBounds, next.sourceBounds)
+  ) {
+    return 'mesh';
+  }
+  if (
+    previous.materialHandle !== next.materialHandle ||
+    previous.materialGeneration !== next.materialGeneration
+  ) {
+    return 'material';
+  }
+  if (!sameValue(previous.style, next.style)) return 'style';
+  if (
+    previous.viewport.width !== next.viewport.width ||
+    previous.viewport.height !== next.viewport.height ||
+    previous.viewport.dpr !== next.viewport.dpr ||
+    !sameArray(previous.projection, next.projection)
+  ) {
+    return 'view';
+  }
+  if (
+    previous.worldId !== next.worldId ||
+    previous.entityKey !== next.entityKey ||
+    previous.layer !== next.layer ||
+    previous.sortKey !== next.sortKey ||
+    previous.visible !== next.visible
+  ) {
+    return 'scene';
+  }
+  return 'none';
+}
+
+function sameArray(left: ArrayLike<number>, right: ArrayLike<number>): boolean {
+  if (left.length !== right.length) return false;
+  for (let index = 0; index < left.length; index += 1) {
+    if (left[index] !== right[index]) return false;
+  }
+  return true;
+}
+
+function sameValue(
+  left: PointsLinesStyle | undefined,
+  right: PointsLinesStyle | undefined,
+): boolean {
+  if (left?.kind !== right?.kind) return false;
+  if (left === undefined || right === undefined) return left === right;
+  if (left.kind === 'points' && right.kind === 'points') {
+    return left.sizePx === right.sizePx && left.shape === right.shape;
+  }
+  return left.kind === 'lines' && right.kind === 'lines' && left.widthPx === right.widthPx;
+}