@forgeax/engine-render 0.1.6 → 0.1.19

package/src/points-lines/admission.ts

@@ -0,0 +1,238 @@
+import { err, type MaterialAsset, type MeshAsset, ok, type Result } from '@forgeax/engine-types';
+import { type PointShape, PointShapeValue, pointShapeFromU32 } from '../components/points';
+import type {
+  PointsLinesBudgetExceededError,
+  PointsLinesInvalidStyleError,
+  PointsLinesMaterialUnsupportedError,
+  PointsLinesStyleUnsupportedError,
+  PointsLinesTopologyMismatchError,
+} from '../errors/render';
+import {
+  PointsLinesBudgetExceededError as BudgetError,
+  PointsLinesInvalidStyleError as InvalidStyleError,
+  PointsLinesMaterialUnsupportedError as MaterialError,
+  PointsLinesStyleUnsupportedError as StyleError,
+  PointsLinesTopologyMismatchError as TopologyError,
+} from '../errors/render';
+
+export interface PointsStyleInput {
+  readonly sizePx?: number;
+  readonly shape?: number;
+}
+
+export interface LinesStyleInput {
+  readonly widthPx?: number;
+}
+
+export interface PointsLinesAdmissionLimits {
+  readonly maxPoints?: number;
+  readonly maxSegments?: number;
+}
+
+export interface PointsLinesAdmissionInput {
+  readonly entity: number;
+  readonly points?: PointsStyleInput;
+  readonly lines?: LinesStyleInput;
+  readonly mesh: MeshAsset;
+  readonly material: MaterialAsset;
+  readonly limits?: PointsLinesAdmissionLimits;
+  readonly materialId?: string;
+}
+
+export interface PointsLinesAdmission {
+  readonly component: 'Points' | 'Lines';
+  readonly shape?: PointShape;
+  readonly sizePx?: number;
+  readonly widthPx?: number;
+  readonly pointCount: number;
+  readonly segmentCount: number;
+  readonly submeshes: readonly number[];
+}
+
+export type PointsLinesAdmissionError =
+  | PointsLinesInvalidStyleError
+  | PointsLinesTopologyMismatchError
+  | PointsLinesStyleUnsupportedError
+  | PointsLinesMaterialUnsupportedError
+  | PointsLinesBudgetExceededError;
+
+function invalidStyle(
+  input: PointsLinesAdmissionInput,
+  component: 'Points' | 'Lines' | 'Points/Lines',
+  field: string,
+  value: number | string | undefined,
+  expected: string,
+): Result<never, PointsLinesAdmissionError> {
+  return err(new InvalidStyleError({ entity: input.entity, component, field, value, expected }));
+}
+
+function topologyMismatch(
+  input: PointsLinesAdmissionInput,
+  submesh: number,
+  expected: string,
+  actual: string,
+): Result<never, PointsLinesAdmissionError> {
+  return err(new TopologyError({ entity: input.entity, submesh, expected, actual }));
+}
+
+function checkStyle(
+  input: PointsLinesAdmissionInput,
+): Result<
+  { component: 'Points' | 'Lines'; shape?: PointShape; sizePx?: number; widthPx?: number },
+  PointsLinesAdmissionError
+> {
+  const hasPoints = input.points !== undefined;
+  const hasLines = input.lines !== undefined;
+  if (hasPoints && hasLines) {
+    return invalidStyle(
+      input,
+      'Points/Lines',
+      'components',
+      'Points + Lines',
+      'exactly one style component',
+    );
+  }
+  if (!hasPoints && !hasLines) {
+    return invalidStyle(input, 'Points/Lines', 'components', undefined, 'one style component');
+  }
+
+  if (hasPoints) {
+    const sizePx = input.points?.sizePx ?? 4;
+    const shapeValue = input.points?.shape ?? PointShapeValue.square;
+    const shape = pointShapeFromU32(shapeValue);
+    if (!Number.isFinite(sizePx) || sizePx <= 0) {
+      return invalidStyle(input, 'Points', 'sizePx', sizePx, 'finite sizePx > 0');
+    }
+    if (shape === undefined) {
+      return invalidStyle(input, 'Points', 'shape', shapeValue, "shape is 'square' or 'circle'");
+    }
+    return ok({ component: 'Points', shape, sizePx });
+  }
+
+  const widthPx = input.lines?.widthPx ?? 1;
+  if (!Number.isFinite(widthPx) || widthPx <= 0) {
+    return invalidStyle(input, 'Lines', 'widthPx', widthPx, 'finite widthPx > 0');
+  }
+  return ok({ component: 'Lines', widthPx });
+}
+
+function checkTopology(
+  input: PointsLinesAdmissionInput,
+  component: 'Points' | 'Lines',
+): Result<
+  { pointCount: number; segmentCount: number; submeshes: readonly number[] },
+  PointsLinesAdmissionError
+> {
+  const expected = component === 'Points' ? 'point-list' : 'line-list';
+  let pointCount = 0;
+  let segmentCount = 0;
+  const acceptedSubmeshes: number[] = [];
+  let sawNonEmpty = false;
+
+  for (const [submeshIndex, submesh] of input.mesh.submeshes.entries()) {
+    const indexed = input.mesh.indices !== undefined && submesh.indexCount > 0;
+    const elementCount = indexed ? submesh.indexCount : submesh.vertexCount;
+    if (elementCount === 0) continue;
+    sawNonEmpty = true;
+
+    if (component === 'Lines' && submesh.topology === 'line-strip') {
+      return err(
+        new StyleError({
+          lane: 'admission',
+          field: 'topology',
+          member: 'line-strip',
+          supported: ['line-list'],
+        }),
+      );
+    }
+    if (submesh.topology !== expected) {
+      return topologyMismatch(input, submeshIndex, expected, submesh.topology);
+    }
+    if (component === 'Lines' && elementCount % 2 !== 0) {
+      return topologyMismatch(input, submeshIndex, 'line-list pairs', 'line-list odd tail');
+    }
+    acceptedSubmeshes.push(submeshIndex);
+    if (component === 'Points') pointCount += elementCount;
+    else segmentCount += elementCount / 2;
+  }
+
+  if (!sawNonEmpty) return topologyMismatch(input, 0, expected, 'empty-range');
+  return ok({ pointCount, segmentCount, submeshes: acceptedSubmeshes });
+}
+
+function checkMaterial(input: PointsLinesAdmissionInput): Result<void, PointsLinesAdmissionError> {
+  const passes = input.material.passes ?? [];
+  const unlitModules = new Set(['forgeax_material::unlit', 'forgeax::default-unlit']);
+  if (passes.length !== 1 || passes[0] === undefined) {
+    const pass =
+      passes.find(
+        (candidate) => candidate.name === 'deferred' || candidate.name === 'shadow-caster',
+      ) ?? passes[0];
+    return err(
+      new MaterialError({
+        entity: input.entity,
+        material: input.materialId ?? '<anonymous>',
+        pass: pass?.name ?? '<empty>',
+        module: pass?.program.module ?? '<empty>',
+        reason: 'points-lines admission requires one unlit forward pass',
+      }),
+    );
+  }
+  const pass = passes[0];
+  const lightMode = (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode;
+  if (
+    !unlitModules.has(pass.program.module) ||
+    pass.name !== 'forward' ||
+    lightMode === 'ShadowCaster'
+  ) {
+    return err(
+      new MaterialError({
+        entity: input.entity,
+        material: input.materialId ?? '<anonymous>',
+        pass: pass.name,
+        module: pass.program.module,
+        reason: 'points-lines admission requires an engine-owned unlit forward pass',
+      }),
+    );
+  }
+  return ok(undefined);
+}
+
+/** Validate one complete Points/Lines candidate before any renderer publication. */
+export function admitPointsLines(
+  input: PointsLinesAdmissionInput,
+): Result<PointsLinesAdmission, PointsLinesAdmissionError> {
+  const style = checkStyle(input);
+  if (!style.ok) return style;
+  const topology = checkTopology(input, style.value.component);
+  if (!topology.ok) return topology;
+  const material = checkMaterial(input);
+  if (!material.ok) return material;
+
+  if (style.value.component === 'Points' && input.limits?.maxPoints !== undefined) {
+    if (topology.value.pointCount > input.limits.maxPoints) {
+      return err(
+        new BudgetError({
+          lane: 'admission',
+          requested: topology.value.pointCount,
+          limit: input.limits.maxPoints,
+          unit: 'points',
+        }),
+      );
+    }
+  }
+  if (style.value.component === 'Lines' && input.limits?.maxSegments !== undefined) {
+    if (topology.value.segmentCount > input.limits.maxSegments) {
+      return err(
+        new BudgetError({
+          lane: 'admission',
+          requested: topology.value.segmentCount,
+          limit: input.limits.maxSegments,
+          unit: 'segments',
+        }),
+      );
+    }
+  }
+
+  return ok({ ...style.value, ...topology.value });
+}

package/src/points-lines/bounds.ts

@@ -0,0 +1,23 @@
+import type { PointsLinesStyle } from './snapshot';
+
+/**
+ * Expands the local culling envelope by the maximum screen-space raster
+ * radius. The shader applies the exact physical-pixel offset; this envelope
+ * is deliberately conservative so transformed edge primitives are retained.
+ */
+export function expandPointsLinesBounds(
+  bounds: ArrayLike<number>,
+  style: PointsLinesStyle | undefined,
+): Float32Array {
+  if (bounds.length < 6 || style === undefined) return new Float32Array(bounds);
+  const marginPx = style.kind === 'points' ? style.sizePx * 0.5 : style.widthPx * 0.5;
+  if (!Number.isFinite(marginPx) || marginPx <= 0) return new Float32Array(bounds);
+  return new Float32Array([
+    (bounds[0] ?? 0) - marginPx,
+    (bounds[1] ?? 0) - marginPx,
+    (bounds[2] ?? 0) - marginPx,
+    (bounds[3] ?? 0) + marginPx,
+    (bounds[4] ?? 0) + marginPx,
+    (bounds[5] ?? 0) + marginPx,
+  ]);
+}

package/src/points-lines/expansion-cache.ts

@@ -0,0 +1,215 @@
+import type { MeshAsset } from '@forgeax/engine-types';
+import type { PointsLinesRetainedSnapshot } from './snapshot';
+
+export interface PointsLinesExpandedGeometry {
+  readonly key: string;
+  readonly component: 'Points' | 'Lines';
+  /** Source endpoints retained for the M3 triangle-expansion consumer. */
+  readonly positions: Float32Array;
+  /** Interleaved position/otherPosition/corner stream for WGSL. */
+  readonly vertices: Float32Array;
+  /** Six indices per expanded quad. */
+  readonly indices: Uint32Array;
+  readonly sourceVertexCount: number;
+  readonly pointCount: number;
+  readonly segmentCount: number;
+  readonly expandedVertexCount: number;
+  readonly expandedIndexCount: number;
+  readonly sourceBytes: number;
+  readonly derivedBytes: number;
+  readonly bounds: Float32Array;
+}
+
+/** Shared CPU expansion cache. Material generations are not geometry key data. */
+export class PointsLinesExpansionCache {
+  private readonly entries = new Map<string, PointsLinesExpandedGeometry>();
+
+  getOrCreate(snapshot: PointsLinesRetainedSnapshot, mesh: MeshAsset): PointsLinesExpandedGeometry {
+    if (snapshot.component === undefined || snapshot.style === undefined) {
+      return emptyGeometry(snapshot);
+    }
+    const key = expansionKey(snapshot);
+    const cached = this.entries.get(key);
+    if (cached !== undefined) return cached;
+    const geometry = deriveExpandedGeometry(snapshot, mesh, key);
+    this.entries.set(key, geometry);
+    return geometry;
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+}
+
+function expansionKey(snapshot: PointsLinesRetainedSnapshot): string {
+  return `mesh:${snapshot.meshHandle}:${snapshot.meshGeneration}:component=${snapshot.component ?? 'none'}`;
+}
+
+function deriveExpandedGeometry(
+  snapshot: PointsLinesRetainedSnapshot,
+  mesh: MeshAsset,
+  key: string,
+): PointsLinesExpandedGeometry {
+  const component = snapshot.component;
+  const style = snapshot.style;
+  if (component === undefined || style === undefined) return emptyGeometry(snapshot);
+  const sourcePositions = readPositions(mesh);
+  const positions: number[] = [];
+  const vertices: number[] = [];
+  const indices: number[] = [];
+  let sourceCursor = 0;
+  let pointCount = 0;
+  let segmentCount = 0;
+  const expectedTopology = component === 'Points' ? 'point-list' : 'line-list';
+  for (const submesh of mesh.submeshes) {
+    if (submesh.topology !== expectedTopology) {
+      sourceCursor += submesh.vertexCount;
+      continue;
+    }
+    const elements =
+      mesh.indices !== undefined && submesh.indexCount > 0
+        ? Array.from(
+            mesh.indices.slice(submesh.indexOffset, submesh.indexOffset + submesh.indexCount),
+          )
+        : Array.from({ length: submesh.vertexCount }, (_, index) => sourceCursor + index);
+    for (const index of elements) {
+      const offset = index * 3;
+      positions.push(
+        sourcePositions[offset] ?? 0,
+        sourcePositions[offset + 1] ?? 0,
+        sourcePositions[offset + 2] ?? 0,
+      );
+    }
+    if (component === 'Points') {
+      pointCount += elements.length;
+      for (const index of elements) {
+        const offset = index * 3;
+        const position = [
+          sourcePositions[offset] ?? 0,
+          sourcePositions[offset + 1] ?? 0,
+          sourcePositions[offset + 2] ?? 0,
+        ];
+        if (style.kind !== 'points') continue;
+        emitQuad(vertices, indices, position, position);
+      }
+    } else {
+      segmentCount += Math.floor(elements.length / 2);
+      for (let element = 0; element + 1 < elements.length; element += 2) {
+        const startOffset = (elements[element] ?? 0) * 3;
+        const endOffset = (elements[element + 1] ?? 0) * 3;
+        emitQuad(
+          vertices,
+          indices,
+          [
+            sourcePositions[startOffset] ?? 0,
+            sourcePositions[startOffset + 1] ?? 0,
+            sourcePositions[startOffset + 2] ?? 0,
+          ],
+          [
+            sourcePositions[endOffset] ?? 0,
+            sourcePositions[endOffset + 1] ?? 0,
+            sourcePositions[endOffset + 2] ?? 0,
+          ],
+        );
+      }
+    }
+    sourceCursor += submesh.vertexCount;
+  }
+  const expanded = new Float32Array(positions);
+  const expandedVertices = new Float32Array(vertices);
+  const expandedIndices = new Uint32Array(indices);
+  return {
+    key,
+    component,
+    positions: expanded,
+    vertices: expandedVertices,
+    indices: expandedIndices,
+    sourceVertexCount: sourcePositions.length / 3,
+    pointCount,
+    segmentCount,
+    expandedVertexCount: expandedVertices.length / 8,
+    expandedIndexCount: expandedIndices.length,
+    sourceBytes: mesh.vertices.byteLength + (mesh.indices?.byteLength ?? 0),
+    derivedBytes: expandedVertices.byteLength + expandedIndices.byteLength,
+    bounds: boundsOf(expanded),
+  };
+}
+
+function emitQuad(
+  vertices: number[],
+  indices: number[],
+  start: readonly number[],
+  end: readonly number[],
+): void {
+  const base = vertices.length / 8;
+  const corners: readonly (readonly [number, number])[] = [
+    [-1, -1],
+    [-1, 1],
+    [1, -1],
+    [1, 1],
+  ];
+  for (const [x, y] of corners) {
+    vertices.push(
+      start[0] ?? 0,
+      start[1] ?? 0,
+      start[2] ?? 0,
+      end[0] ?? 0,
+      end[1] ?? 0,
+      end[2] ?? 0,
+      x,
+      y,
+    );
+  }
+  indices.push(base, base + 1, base + 2, base + 2, base + 1, base + 3);
+}
+
+function readPositions(mesh: MeshAsset): Float32Array {
+  const attribute = mesh.attributes.position;
+  if (attribute instanceof Float32Array && attribute.length >= 3) {
+    return attribute;
+  }
+  const vertexCount = mesh.vertices.length / 3;
+  const stride = vertexCount > 0 ? mesh.vertices.length / vertexCount : 3;
+  const positions = new Float32Array(vertexCount * 3);
+  for (let vertex = 0; vertex < vertexCount; vertex += 1) {
+    const source = vertex * stride;
+    positions.set(mesh.vertices.subarray(source, source + 3), vertex * 3);
+  }
+  return positions;
+}
+
+function boundsOf(positions: Float32Array): Float32Array {
+  if (positions.length === 0) return new Float32Array(0);
+  const bounds = new Float32Array([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity]);
+  for (let index = 0; index < positions.length; index += 3) {
+    bounds[0] = Math.min(bounds[0] ?? Infinity, positions[index] ?? 0);
+    bounds[1] = Math.min(bounds[1] ?? Infinity, positions[index + 1] ?? 0);
+    bounds[2] = Math.min(bounds[2] ?? Infinity, positions[index + 2] ?? 0);
+    bounds[3] = Math.max(bounds[3] ?? -Infinity, positions[index] ?? 0);
+    bounds[4] = Math.max(bounds[4] ?? -Infinity, positions[index + 1] ?? 0);
+    bounds[5] = Math.max(bounds[5] ?? -Infinity, positions[index + 2] ?? 0);
+  }
+  return bounds;
+}
+
+function emptyGeometry(snapshot: PointsLinesRetainedSnapshot): PointsLinesExpandedGeometry {
+  return {
+    key: `empty:${snapshot.entityKey}`,
+    component: snapshot.component ?? 'Points',
+    positions: new Float32Array(0),
+    vertices: new Float32Array(0),
+    indices: new Uint32Array(0),
+    sourceVertexCount: 0,
+    pointCount: 0,
+    segmentCount: 0,
+    expandedVertexCount: 0,
+    expandedIndexCount: 0,
+    sourceBytes: 0,
+    derivedBytes: 0,
+    bounds: new Float32Array(0),
+  };
+}

package/src/points-lines/inspection.ts

@@ -0,0 +1,97 @@
+import type { RenderError } from '../errors/render';
+import type { PointsLinesRetainedSnapshot, PointsLinesStyle } from './snapshot';
+
+export type PointsLinesSourceError = Extract<
+  RenderError,
+  { readonly code: `points-lines-${string}` }
+>;
+
+export type PointsLinesInspectionLane =
+  | 'pending'
+  | 'refused'
+  | 'direct'
+  | 'clustered'
+  | 'cpu-webgl2';
+
+export interface PointsLinesInspectionCache {
+  readonly hit: boolean;
+  readonly rebuilds: number;
+  readonly evictions: number;
+}
+
+export type PointsLinesInspectionRefusal = Pick<
+  PointsLinesSourceError,
+  'code' | 'expected' | 'hint' | 'detail'
+> & {
+  readonly generation: number;
+  readonly lastKnownGood: boolean;
+};
+
+export interface PointsLinesInspection {
+  readonly entityKey: number;
+  readonly worldId: number;
+  readonly component: 'Points' | 'Lines';
+  readonly meshHandle: number;
+  readonly meshGeneration: number;
+  readonly materialHandle: number;
+  readonly materialGeneration: number;
+  readonly style: PointsLinesStyle;
+  readonly topology: 'point-list' | 'line-list';
+  readonly lane: PointsLinesInspectionLane;
+  readonly pointCount: number;
+  readonly segmentCount: number;
+  readonly sourceBytes: number;
+  readonly derivedBytes: number;
+  readonly cache: PointsLinesInspectionCache;
+  readonly drawCount: number;
+  readonly uploadBytes: number;
+  readonly lastKnownGood: boolean;
+  readonly refusal?: PointsLinesInspectionRefusal;
+}
+
+export interface PointsLinesInspectionInput {
+  readonly snapshot: PointsLinesRetainedSnapshot;
+  readonly topology: 'point-list' | 'line-list';
+  readonly lane: PointsLinesInspectionLane;
+  readonly pointCount: number;
+  readonly segmentCount: number;
+  readonly sourceBytes: number;
+  readonly derivedBytes: number;
+  readonly cache: PointsLinesInspectionCache;
+  readonly drawCount: number;
+  readonly uploadBytes: number;
+  readonly lastKnownGood: boolean;
+  readonly refusal?: PointsLinesInspectionRefusal;
+}
+
+export function inspectPointsLines(input: PointsLinesInspectionInput): PointsLinesInspection {
+  const { snapshot } = input;
+  if (snapshot.component === undefined) {
+    throw new Error('Points/Lines inspection requires a retained style component');
+  }
+  return {
+    entityKey: snapshot.entityKey,
+    worldId: snapshot.worldId,
+    component: snapshot.component,
+    meshHandle: snapshot.meshHandle,
+    meshGeneration: snapshot.meshGeneration,
+    materialHandle: snapshot.materialHandle,
+    materialGeneration: snapshot.materialGeneration,
+    style: snapshot.style ?? { kind: 'lines', widthPx: 0 },
+    topology: input.topology,
+    lane: input.lane,
+    pointCount: input.pointCount,
+    segmentCount: input.segmentCount,
+    sourceBytes: input.sourceBytes,
+    derivedBytes: input.derivedBytes,
+    cache: { ...input.cache },
+    drawCount: input.drawCount,
+    uploadBytes: input.uploadBytes,
+    lastKnownGood: input.lastKnownGood,
+    ...(input.refusal === undefined ? {} : { refusal: { ...input.refusal } }),
+  };
+}
+
+export function pointsLinesInspectionToJson(inspection: PointsLinesInspection): string {
+  return JSON.stringify(inspection);
+}