@forgeax/engine-render 0.1.6 → 0.1.7

package/src/record/render-context.ts

@@ -40,6 +40,16 @@ import type { SkylightFallback } from '../ibl/skylight-bind-group';
 import type { HealthListenerRegistry, RhiErrorListenerRegistry } from '../lifecycle';
 import type { StandardProfile } from '../pipeline/standard-profile';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
+import type { PointsLinesInspection } from '../points-lines/inspection';
+import type { PointsLinesRecordPlan } from '../points-lines/record';
+
+export interface PointsLinesRecordSubmission {
+  readonly plan: PointsLinesRecordPlan;
+  readonly vertexBuffer: Buffer;
+  readonly indexBuffer: Buffer;
+  readonly layoutProjection: VertexLayoutProjection;
+}
+
 import type {
   RenderDebugOverlay,
   RenderPipelineContext,
@@ -103,6 +113,14 @@ export interface RenderSystemRuntime {
   readonly dynamicTextureStore?: DynamicTextureStore | undefined;
 }
 
+/** Renderer-owned bridge from retained Points/Lines facts into main geometry. */
+export interface PointsLinesRecordOwner {
+  prepare(entry: ValidatedRenderable, clustered: boolean): PointsLinesRecordSubmission | undefined;
+  beginFrame(): void;
+  resetForDeviceLoss(): void;
+  inspections(): readonly PointsLinesInspection[];
+}
+
 export interface PerPassResources {
   depthTexture: Texture | null;
   depthTextureView: TextureView | null;
@@ -184,6 +202,7 @@ export interface PipelineState {
   readonly materialBindGroupLayout: BindGroupLayout;
   readonly meshBindGroupLayout: BindGroupLayout;
   readonly viewUniformBuffer: Buffer;
+  readonly pointsLinesViewBuffer?: Buffer;
   readonly shadowCasterCascadeBuffer: Buffer;
   readonly materialUniformBuffer: { readonly buffer: Buffer; readonly sizeInBytes: number };
   readonly meshStorageBuffer: { readonly buffer: Buffer; readonly sizeInBytes: number };
@@ -281,6 +300,7 @@ export interface _StandardForwardSceneView {
   readonly materialSlots: readonly MaterialSnapshot[];
   readonly materialSlotOwners: readonly number[];
   readonly materialSlotCount: number;
+  readonly pointsLines: PointsLinesRecordOwner | undefined;
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
   materialUboPayloadCache?: {
     readonly materialSlots: readonly MaterialSnapshot[];

package/src/record/shadow-pass.ts

@@ -29,7 +29,7 @@ import {
 } from './mesh-ssbo';
 import type { _InternalRenderPipelineContext } from './render-context';
 import { STANDARD_PBR_UBO_SIZE } from './render-context';
-import { pointShadowViewOffset, VIEW_UNIFORM_BYTES } from './view-ubo';
+import { POINTS_LINES_VIEW_BYTES, pointShadowViewOffset, VIEW_UNIFORM_BYTES } from './view-ubo';
 
 export const SHADOW_CASTER_SLOT_STRIDE = 256;
 export const SHADOW_CASTER_BUFFER_SIZE = SHADOW_CASTER_SLOT_STRIDE * 8;
@@ -88,6 +88,7 @@ function ensureTypedShadowViewBg(
         pipelineState.shadowParamsBuffer,
         pipelineState.shadowCasterCascadeBuffer,
         pipelineState.shadowFallbackTextureView,
+        pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
       ],
       variant,
       () => {
@@ -140,7 +141,7 @@ function ensureTypedShadowViewBg(
                 value: {
                   buffer: pipelineState.shadowCasterCascadeBuffer,
                   offset: cascadeOffset,
-                  size: 80,
+                  size: POINTS_LINES_VIEW_BYTES,
                 },
               },
             },
@@ -148,6 +149,16 @@ function ensureTypedShadowViewBg(
               binding: 8,
               resource: { kind: 'textureView', value: pipelineState.shadowFallbackTextureView },
             },
+            {
+              binding: 10,
+              resource: {
+                kind: 'buffer',
+                value: {
+                  buffer: pipelineState.pointsLinesViewBuffer ?? pipelineState.viewUniformBuffer,
+                  size: 80,
+                },
+              },
+            },
           ],
         });
         if (!created.ok) throw created.error;
@@ -207,7 +218,7 @@ export function encodeDirectionalShadowPass(
   c.frameState.directionalShadowCacheRecorded = true;
   pass.setViewport(viewport.x, viewport.y, viewport.w, viewport.h, 0, 1);
   pass.setPipeline(pipeline);
-  pass.setBindGroup(0, viewBg);
+  pass.setBindGroup(0, viewBg, [0]);
   pass.setBindGroup(1, materialBg, [0]);
   recordShadowCasterDraws(
     c,
@@ -237,7 +248,7 @@ export function encodePointShadowPass(
   const materialBg = ensureSpotShadowMaterialBg(c);
   if (pipeline === null || viewBg === null || materialBg === null) return;
   pass.setPipeline(pipeline);
-  pass.setBindGroup(0, viewBg);
+  pass.setBindGroup(0, viewBg, [0]);
   pass.setBindGroup(1, materialBg, [0]);
   recordShadowCasterDraws(
     c,
@@ -285,7 +296,7 @@ export function encodeSpotShadowPass(
     1,
   );
   pass.setPipeline(pipeline);
-  pass.setBindGroup(0, viewBg);
+  pass.setBindGroup(0, viewBg, [0]);
   pass.setBindGroup(1, materialBg, [0]);
   // Reuse the shared caster recorder. The compact spot-only loop used to
   // depend on instance bindings created by a directional pass, so a scene

package/src/record/skybox-post-pass.ts

@@ -4,6 +4,7 @@ import { toShared } from '@forgeax/engine-types';
 import { buildBeginRenderPassDescriptor } from '../pipeline-spec';
 import { getOrCreateFromChain } from './mesh-ssbo';
 import type { _InternalRenderPipelineContext } from './render-context';
+import { VIEW_UNIFORM_BYTES } from './view-ubo';
 
 /**
  * feat-20260531-skybox-env-background M2 / w8: skybox pass recording stub.
@@ -111,7 +112,7 @@ export function recordSkyboxPass(
             binding: 2,
             resource: {
               kind: 'buffer',
-              value: { buffer: pipelineState.viewUniformBuffer },
+              value: { buffer: pipelineState.viewUniformBuffer, size: VIEW_UNIFORM_BYTES },
             },
           },
           {

package/src/record/typed-frame-graph.ts

@@ -4,7 +4,6 @@ import {
   RenderGraphBuilder,
 } from '@forgeax/engine-render-graph';
 import type {
-  BindGroup,
   BindGroupLayout,
   CommandBuffer,
   RenderPipeline,
@@ -20,7 +19,10 @@ import {
 } from '../features/host';
 import { type RenderFeaturePlannedFrame, renderFeaturePlanSignature } from '../features/plan';
 import { projectRenderFeaturePlans as projectPlanExecutions } from '../features/render-graph-contribution';
-import type { RenderFeatureGraphTargetResolver } from '../features/render-graph-raster';
+import type {
+  RenderFeatureGraphBindingsResolution,
+  RenderFeatureGraphTargetResolver,
+} from '../features/render-graph-raster';
 import { isRenderFeatureTargetHandle } from '../features/targets';
 import type { PreparedGpuDrivenFrame } from '../gpu-driven/production-raster';
 import { STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
@@ -251,7 +253,7 @@ function resolveTargetBindings(input: {
   };
   readonly resources: GraphResourceResolver;
   readonly resolveTarget: RenderFeatureGraphTargetResolver;
-}): BindGroup | undefined {
+}): RenderFeatureGraphBindingsResolution | undefined {
   const frame = input.frame as import('./render-context')._InternalRenderPipelineContext;
   const descriptor = input.binding.descriptor;
   const pipeline = input.binding.pipeline as
@@ -294,19 +296,18 @@ function resolveTargetBindings(input: {
     return created.value;
   }
   if (sceneDepth === undefined) {
-    return (
-      buildPerFrameBindGroups(
-        frame.runtime as RenderSystemInternals,
-        frame.frameState,
-        frame.pipelineState,
-        frame.validated.length > 0,
-        frame.bindGroupCounts,
-        {
-          directionalShadow: frame.frameState.currentDirectionalShadowView ?? undefined,
-          spotShadow: frame.frameState.currentSpotShadowView ?? undefined,
-        },
-      ).viewBindGroup ?? undefined
-    );
+    const viewBindGroup = buildPerFrameBindGroups(
+      frame.runtime as RenderSystemInternals,
+      frame.frameState,
+      frame.pipelineState,
+      frame.validated.length > 0,
+      frame.bindGroupCounts,
+      {
+        directionalShadow: frame.frameState.currentDirectionalShadowView ?? undefined,
+        spotShadow: frame.frameState.currentSpotShadowView ?? undefined,
+      },
+    ).viewBindGroup;
+    return viewBindGroup === null ? undefined : { handle: viewBindGroup, dynamicOffsets: [0] };
   }
   const target = input.resolveTarget(sceneDepth);
   if (target === undefined) return undefined;

package/src/record/view-ubo.ts

@@ -8,6 +8,7 @@
 
 import { mat4 } from '@forgeax/engine-math';
 import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
+import type { PointsLinesStyle } from '../points-lines/snapshot';
 import type { CameraSnapshot } from '../render-contract';
 import type {
   DirectionalLightSnapshot,
@@ -18,6 +19,11 @@ import { clampPcfKernelSize } from './frame-snapshot';
 import { computeProjectionMatrix, computeViewMatrix } from './helpers';
 
 export const VIEW_UNIFORM_BYTES = 960;
+export const POINTS_LINES_VIEW_BYTES = 160;
+export const POINTS_LINES_VIEW_SLOT_STRIDE = 256;
+export const POINTS_LINES_VIEW_SLOT_COUNT = 1024;
+export const POINTS_LINES_VIEW_BUFFER_SIZE =
+  POINTS_LINES_VIEW_SLOT_STRIDE * POINTS_LINES_VIEW_SLOT_COUNT;
 export const VIEW_UNIFORM_SLOT_STRIDE = 1024;
 export const POINT_SHADOW_VIEW_SLOT_COUNT = 24;
 export const VIEW_UNIFORM_BUFFER_SIZE =
@@ -27,6 +33,47 @@ export function pointShadowViewOffset(layer: number, face: number): number {
   return VIEW_UNIFORM_SLOT_STRIDE * (1 + layer * 6 + face);
 }
 
+export function writePointsLinesViewUbo(
+  queue: RhiQueue,
+  buffer: Buffer,
+  camera: CameraSnapshot,
+  width: number,
+  height: number,
+  model?: ArrayLike<number>,
+  style?: PointsLinesStyle,
+  byteOffset = 0,
+): void {
+  const projection = computeProjectionMatrix(camera);
+  const view = computeViewMatrix(camera);
+  const worldViewProj = mat4.create();
+  mat4.multiply(worldViewProj, projection, view);
+  const payload = new Float32Array(40);
+  payload.set(worldViewProj);
+  if (model === undefined) {
+    payload[16] = 1;
+    payload[21] = 1;
+    payload[26] = 1;
+    payload[31] = 1;
+  } else {
+    for (let index = 0; index < 16; index += 1) {
+      payload[16 + index] = model[index] ?? 0;
+    }
+  }
+  payload[32] = width;
+  payload[33] = height;
+  if (style?.kind === 'points') {
+    payload[36] = style.sizePx;
+    payload[38] = style.shape === 'circle' ? 1 : 0;
+  } else if (style?.kind === 'lines') {
+    payload[36] = style.widthPx;
+    payload[37] = 1;
+  } else {
+    payload[36] = 1;
+  }
+  const uploaded = queue.writeBuffer(buffer, byteOffset, payload);
+  if (!uploaded.ok) throw uploaded.error;
+}
+
 /**
  * feat-20260704 M3/w18: assemble + upload the per-frame View UBO payload.
  *

package/src/render-contract.ts

@@ -24,9 +24,12 @@ import type { ImageError } from '@forgeax/engine-types';
 import type { RhiBackendInstrumentation } from './assembly/backend-contract';
 import type { Antialias, BloomEnabled, Tonemap } from './components/camera';
 import type { RenderError } from './errors/render';
-import type { RenderFeature } from './features/types';
+import type { RenderFeature, RenderFeatureDiagnostics } from './features/types';
 import type { PostProcessShaderEntry } from './fullscreen-post-process-pass';
 import type { RenderSceneInspection } from './inspection-types';
+
+export type { PointsLinesInspection } from './points-lines/inspection';
+
 import type { MeshMaterialBindingObservation } from './mesh-material-bindings';
 import type { StandardProfile } from './pipeline/standard-profile';
 import type { PostProcessError } from './post-process-errors';
@@ -172,7 +175,13 @@ export type RendererEvent =
       readonly previous: RendererState;
       readonly current: RendererState;
     }
-  | { readonly kind: 'error'; readonly error: RenderError };
+  | { readonly kind: 'error'; readonly error: RenderError }
+  /** Emitted only after the renderer's sole submit path returns a receipt. */
+  | {
+      readonly kind: 'frame-submitted';
+      readonly frameId: number;
+      readonly deviceGeneration: number;
+    };
 
 /** Package-local listener alias used by the renderer assembly implementation. */
 export type RendererEventListener = (event: RendererEvent) => void;
@@ -252,6 +261,8 @@ export interface RenderInspection {
     readonly deviceGeneration: number;
   };
   readonly features: readonly string[];
+  /** Truthful lifecycle facts for every registered declarative feature. */
+  readonly featureDiagnostics: readonly RenderFeatureDiagnostics[];
   readonly frustumStats: { readonly culled: number; readonly total: number };
   readonly visibilityStats: { readonly explicitlyHidden: number };
   readonly renderScene: RenderSceneInspection;

package/src/render-system-extract.ts

@@ -159,13 +159,17 @@ import {
   DirectionalLight,
   Instances,
   Layer,
+  Lines,
   MeshFilter,
   MeshRenderer,
   PointLight,
   PointLightShadow,
+  Points,
   PostProcessParams,
+  pointShapeFromU32,
   SkyboxBackground,
   Skylight,
+  SortKey,
   SpotLight,
   SpriteInstances,
   SpriteRegionOverride,
@@ -191,6 +195,8 @@ import {
   resolveMeshMaterialBindings,
 } from './mesh-material-bindings';
 import { isStandardPbrMaterialShader } from './pbr-pipeline';
+import { expandPointsLinesBounds } from './points-lines/bounds';
+import type { PointsLinesRetainedSnapshot, PointsLinesStyle } from './points-lines/snapshot';
 import { type CameraSnapshot, STANDARD_TONEMAP_FEATURE_ID } from './render-contract';
 import { getActiveCamera, selectActiveCameraIndex } from './systems/active-camera';
 import { selectPasses } from './systems/pass-selector';
@@ -598,6 +604,8 @@ export interface RenderableSnapshot {
    * deltas and the record stage only receives this frozen POD snapshot.
    */
   readonly morph?: MorphSnapshot;
+  /** Detached M2 authoring facts for the optional Points/Lines projection. */
+  readonly pointsLines?: PointsLinesRetainedSnapshot;
 }
 
 export interface MorphSnapshot {
@@ -870,7 +878,7 @@ function gpuDrivenMaterialResourceClass(material: MaterialSnapshot): string {
 //
 // Plan-strategy D-3: single dispatch list sorted by queue value,
 // replacing the old three-bucket opaque/transparent/overlay dispatch.
-// Each entry carries the per-pass render-state, defines, and entry-point
+// Each entry carries the per-pass render-state and entry-point
 // data from the resolved MaterialPass so the record stage
 // reads them without re-resolving the material.
 
@@ -948,7 +956,9 @@ function appendMaterialDispatchEntries(
       layer,
       tags: passState.tags ?? {},
       renderState: pipelineRenderState(passState),
-      defines: pass.program.moduleSlots,
+      // Material module identity is already closed in the cooked program.
+      // It must never become a draw-time define map.
+      defines: undefined,
       vertexEntry: pass.program.vertexEntry,
       fragmentEntry: pass.program.fragmentEntry,
       materialShaderId: runtimeMaterialShaderId(pass.program.module, pass.name),
@@ -1405,9 +1415,8 @@ function materialParametersToParamSchema(
     ? ENGINE_INJECTED_TEXTURE_FIELDS
     : undefined;
   return parameters.flatMap((parameter): ParamSchemaEntry[] => {
-    // Static values select a cooked specialization and boolean material
-    // values have no runtime UBO representation in ParamSchemaEntry.
-    if (parameter.static || parameter.type === 'bool') return [];
+    // Boolean material values are runtime-only and have no UBO representation.
+    if (parameter.type === 'bool') return [];
     if (parameter.type === 'texture') {
       if (engineInjectedTextureFields?.has(parameter.name) === true) return [];
       return [{ name: parameter.name, type: 'texture2d' }];
@@ -2387,7 +2396,11 @@ export function extractFrames(
     }
     hiddenEntityReports.push(...f.hiddenEntityReports);
     for (const r of f.renderables) {
-      renderables.push({ ...r, worldId: wId });
+      renderables.push({
+        ...r,
+        worldId: wId,
+        ...(r.pointsLines === undefined ? {} : { pointsLines: { ...r.pointsLines, worldId: wId } }),
+      });
     }
 
     // D-3: dispatch — per-world renderableIndex rebased by base offset.
@@ -3236,6 +3249,9 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         MorphWeights,
         SpriteRegionOverride,
         SpriteInstances,
+        Points,
+        Lines,
+        SortKey,
       ],
     })
     .unwrap();
@@ -3288,6 +3304,11 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     //   - 'sprite-instances-count-mismatch'
     //       (transforms.length / 16 !== regions.length / 4) — stride pair desync.
     const hasSpriteInstances = row.has(SpriteInstances);
+    const points = row.get(Points);
+    const lines = row.get(Lines);
+    const sortKey = row.get(SortKey)?.value;
+    const pointsLinesComponent =
+      points !== undefined ? 'Points' : lines !== undefined ? 'Lines' : undefined;
     const isRenderable = hasTransform && hasMeshFilter;
 
     // feat-20260601 D-3: the resolved world transform is read per-entity from
@@ -4342,6 +4363,38 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           }
         }
 
+        const pointsLinesStyle: PointsLinesStyle | undefined =
+          points !== undefined
+            ? (() => {
+                const shape = pointShapeFromU32(points.shape);
+                return shape === undefined
+                  ? undefined
+                  : { kind: 'points' as const, sizePx: points.sizePx, shape };
+              })()
+            : lines === undefined
+              ? undefined
+              : { kind: 'lines' as const, widthPx: lines.widthPx };
+        const cullingLocalAabb = expandPointsLinesBounds(localAabb ?? [], pointsLinesStyle);
+        const pointsLines =
+          pointsLinesComponent === undefined
+            ? undefined
+            : ({
+                worldId: 0,
+                entityKey: entity,
+                component: pointsLinesComponent,
+                meshHandle: assetHandleRaw,
+                meshGeneration: assets?.catalogEpoch ?? 0,
+                materialHandle: handleRaw,
+                materialGeneration: assets?.catalogEpoch ?? 0,
+                style: pointsLinesStyle,
+                layer: layerVal,
+                sortKey,
+                visible: true,
+                sourceBounds: cullingLocalAabb,
+                viewport: { width: 0, height: 0, dpr: 1 },
+                projection: identityProjection(),
+              } satisfies PointsLinesRetainedSnapshot);
+
         let nonIndexedFirst = 0;
         const gpuDrivenDraws = gpuDrivenSubmeshes.flatMap((submesh) => {
           const drawMaterial = materialsArr[submesh.materialSlot] ?? materialSnap;
@@ -4364,7 +4417,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         const baseRenderable: RenderableSnapshot = {
           assetHandle: Math.round(fAssetHandle ?? 0),
           transform: transformSnap,
-          ...(localAabb !== undefined ? { localAabb } : {}),
+          ...(localAabb !== undefined ? { localAabb: cullingLocalAabb } : {}),
           material: materialSnap,
           materials: materialsArr,
           materialBindingSources,
@@ -4375,6 +4428,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           ...(skinSlice !== undefined ? { skin: skinSlice } : {}),
           ...(morph !== undefined ? { morph } : {}),
           ...(spriteInstancesSnap !== undefined ? { spriteInstances: spriteInstancesSnap } : {}),
+          ...(pointsLines !== undefined ? { pointsLines } : {}),
         };
 
         // feat-20260528-frustum-culling M3 / w10: frustum culling check.
@@ -4388,7 +4442,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           // directly (no compose) -- same source the record stage feeds
           // the mesh SSBO, so cull stays same-source with render (AC-05).
           const worldAabb = box3.create();
-          box3.transformBox3(worldAabb, localAabb, transformSnap.world);
+          box3.transformBox3(worldAabb, cullingLocalAabb, transformSnap.world);
 
           // Test against all cameras. Entity is visible if one camera
           // frustum intersects the world-space AABB (or planes are empty
@@ -4520,3 +4574,12 @@ export function defaultMaterialSnapshot(materialHandle = 0): MaterialSnapshot {
     materialHandle,
   };
 }
+
+function identityProjection(): Float32Array {
+  const projection = new Float32Array(16);
+  projection[0] = 1;
+  projection[5] = 1;
+  projection[10] = 1;
+  projection[15] = 1;
+  return projection;
+}