@forgeax/engine-render 0.1.3 → 0.1.6

package/dist/chunk-SCRSAK5B.mjs

@@ -0,0 +1,480 @@
+import { defineComponent, Entity } from '@forgeax/engine-ecs';
+import { TONEMAP_SHADER_MODE } from '@forgeax/engine-shader';
+import { projectHierarchy } from '@forgeax/engine-scene';
+
+// src/components/camera.ts
+var CAMERA_PROJECTION_PERSPECTIVE = 0;
+var CAMERA_PROJECTION_ORTHOGRAPHIC = 1;
+function cameraProjectionFromF32(value) {
+  return value === CAMERA_PROJECTION_ORTHOGRAPHIC ? "orthographic" : "perspective";
+}
+var TONEMAP_NONE = TONEMAP_SHADER_MODE.none;
+var TONEMAP_REINHARD_EXTENDED = TONEMAP_SHADER_MODE.reinhardExtended;
+var TONEMAP_REINHARD = TONEMAP_SHADER_MODE.reinhard;
+var TONEMAP_LINEAR = TONEMAP_SHADER_MODE.linear;
+var TONEMAP_CINEON = TONEMAP_SHADER_MODE.cineon;
+var TONEMAP_ACES_FILMIC = TONEMAP_SHADER_MODE.acesFilmic;
+var TONEMAP_AGX = TONEMAP_SHADER_MODE.agx;
+var TONEMAP_NEUTRAL = TONEMAP_SHADER_MODE.neutral;
+function tonemapFromF32(value) {
+  switch (value) {
+    case TONEMAP_REINHARD_EXTENDED:
+      return "reinhard-extended";
+    case TONEMAP_REINHARD:
+      return "reinhard";
+    case TONEMAP_LINEAR:
+      return "linear";
+    case TONEMAP_CINEON:
+      return "cineon";
+    case TONEMAP_ACES_FILMIC:
+      return "aces-filmic";
+    case TONEMAP_AGX:
+      return "agx";
+    case TONEMAP_NEUTRAL:
+      return "neutral";
+    default:
+      return "none";
+  }
+}
+function tonemapToU32(mode) {
+  switch (mode) {
+    case "reinhard-extended":
+      return TONEMAP_REINHARD_EXTENDED;
+    case "reinhard":
+      return TONEMAP_REINHARD;
+    case "linear":
+      return TONEMAP_LINEAR;
+    case "cineon":
+      return TONEMAP_CINEON;
+    case "aces-filmic":
+      return TONEMAP_ACES_FILMIC;
+    case "agx":
+      return TONEMAP_AGX;
+    case "neutral":
+      return TONEMAP_NEUTRAL;
+    case "none":
+      return TONEMAP_NONE;
+  }
+  throw new RangeError(`Invalid tonemap mode: ${String(mode)}.`);
+}
+var ANTIALIAS_NONE = 0;
+var ANTIALIAS_FXAA = 1;
+var ANTIALIAS_MSAA = 2;
+var ANTIALIAS_TAA = 3;
+function antialiasFromF32(value) {
+  if (value === ANTIALIAS_NONE) return "none";
+  if (value === ANTIALIAS_FXAA) return "fxaa";
+  if (value === ANTIALIAS_MSAA) return "msaa";
+  if (value === ANTIALIAS_TAA) return "taa";
+  throw new RangeError(
+    `Invalid antialias value: ${value}. Expected ${ANTIALIAS_NONE} (none), ${ANTIALIAS_FXAA} (fxaa), ${ANTIALIAS_MSAA} (msaa), or ${ANTIALIAS_TAA} (taa).`
+  );
+}
+var BLOOM_DISABLED = 0;
+var BLOOM_ENABLED = 1;
+function bloomEnabledFromF32(value) {
+  if (value === BLOOM_DISABLED) return "off";
+  if (value === BLOOM_ENABLED) return "on";
+  throw new RangeError(
+    `Invalid bloom value: ${value}. Expected ${BLOOM_DISABLED} (off) or ${BLOOM_ENABLED} (on).`
+  );
+}
+var Camera = defineComponent("Camera", {
+  fov: { type: "f32" },
+  aspect: { type: "f32" },
+  near: { type: "f32" },
+  far: { type: "f32" },
+  projection: { type: "f32", default: 0 },
+  left: { type: "f32", default: -1 },
+  right: { type: "f32", default: 1 },
+  bottom: { type: "f32", default: -1 },
+  top: { type: "f32", default: 1 },
+  tonemap: { type: "f32", default: 0 },
+  exposure: { type: "f32", default: 1 },
+  whitePoint: { type: "f32", default: 4 },
+  antialias: { type: "f32", default: 0 },
+  historyVersion: { type: "u32", default: 0 },
+  bloom: { type: "f32", default: 0 },
+  bloomThreshold: { type: "f32", default: 1 },
+  bloomIntensity: { type: "f32", default: 1 },
+  bloomBlurRadius: { type: "f32", default: 4 },
+  // feat-20260709 M3 / D-3: clear-color is one inline `array<f32,4>` column.
+  // The earlier 4-scalar form (clearR/G/B/A) was chosen when this was believed
+  // to be the only SoA-safe shape; the Transform (pos/quat/scale) and light
+  // (direction/color) precedents disprove that -- an `array<f32,N>` IS an
+  // inline stride-N SoA column, read on the hot path as `col[i*N+a]` with zero
+  // allocation, so collapsing four scalars into one column removes three field
+  // names a reader must track without changing the storage layout or read
+  // pattern. The default `[0, 0, 0, 0]` is transparent black; explicit alpha
+  // stays visible through the same public array field.
+  clearColor: { type: "array<f32, 4>", default: new Float32Array([0, 0, 0, 0]) },
+  // feat-20260617-host-engine-contract-and-video-cutscene / M3 / D-4: the
+  // aspect-sync sidecar on the createApp(canvas) path writes
+  // canvas.width / canvas.height into `aspect` every frame when this flag is
+  // true. Reuses the existing `bool` column tier (AnimationPlayer.paused /
+  // AudioSource.playing precedent) -- zero ECS infrastructure change. Default
+  // true so demos that never touch aspect track the canvas automatically
+  // (charter P1 default-is-correct); set false for render-to-texture /
+  // split-screen cameras that drive aspect themselves. Read it via
+  // world.get (readRow narrows bool -> JS boolean); the query-bundle path
+  // returns a raw 0/1 number (the `!== 0` always-true trap).
+  autoAspect: { type: "bool", default: true }
+});
+function cameraPodFromDefaults() {
+  const base = {};
+  for (const [key, field] of Object.entries(Camera.fields)) {
+    if ("default" in field && field.default !== void 0) {
+      base[key] = field.default;
+    }
+  }
+  return base;
+}
+function perspective(opts) {
+  return {
+    // cameraPodFromDefaults() reads autoAspect's schema default (true), so an
+    // omitted opts.autoAspect lands the default-correct value; an explicit
+    // false overrides it below (D-4: factory one-step opt-out, charter P1).
+    ...cameraPodFromDefaults(),
+    fov: opts.fov,
+    aspect: opts.aspect,
+    near: opts.near ?? 0.1,
+    far: opts.far ?? 100,
+    projection: CAMERA_PROJECTION_PERSPECTIVE,
+    ...opts.autoAspect !== void 0 ? { autoAspect: opts.autoAspect } : {}
+  };
+}
+function orthographic(opts) {
+  return {
+    ...cameraPodFromDefaults(),
+    fov: 0,
+    aspect: 1,
+    near: opts.near ?? 0.1,
+    far: opts.far ?? 100,
+    projection: CAMERA_PROJECTION_ORTHOGRAPHIC,
+    left: opts.left,
+    right: opts.right,
+    bottom: opts.bottom,
+    top: opts.top
+  };
+}
+var DirectionalLight = defineComponent("DirectionalLight", {
+  // direction is the ONLY field with no default (D-5): omitting it lands the
+  // array layer-3 all-zero [0,0,0], which the renderer owner rejects -- there is no
+  // universal default direction, so "default is illegal" forces an explicit
+  // non-zero value. color carries an explicit layer-2 default [1,1,1] (white);
+  // the array layer-3 fallback is all-zero, so the default MUST be explicit.
+  direction: { type: "array<f32, 3>" },
+  color: { type: "array<f32, 3>", default: new Float32Array([1, 1, 1]) },
+  intensity: { type: "f32", default: 1 },
+  // Shadow opt-out gate: defaults to true so zero-config spawns get shadows.
+  castShadow: { type: "bool", default: true },
+  // 9 shadow fields migrated from DirectionalLightShadow (feat-20260621 M1).
+  cascadeCount: { type: "f32", default: 4 },
+  splitLambda: { type: "f32", default: 0.75 },
+  cascadeBlend: { type: "f32", default: 0.2 },
+  mapSize: { type: "f32", default: 2048 },
+  depthBias: { type: "f32", default: 5e-3 },
+  normalBias: { type: "f32", default: 0.05 },
+  // Sole shadow coverage knob (feat replaces nearPlane/farPlane). The PSSM
+  // near end derives from the active camera near; shadowDistance is the far
+  // reach. Default 200 world units (matches UE-style "dynamic shadow
+  // distance"; the old farPlane default was 50).
+  shadowDistance: { type: "f32", default: 200 },
+  pcfKernelSize: { type: "f32", default: 3 }
+});
+var Instances = defineComponent("Instances", {
+  transforms: { type: "array<f32>" }
+});
+var Layer = defineComponent("Layer", {
+  value: { type: "i32", default: 0 }
+});
+var MeshFilter = defineComponent("MeshFilter", {
+  assetHandle: { type: "shared<MeshAsset>" }
+});
+var MeshRenderer = defineComponent("MeshRenderer", {
+  materials: { type: "array<shared<MaterialAsset>>", default: [] }
+});
+var PointLight = defineComponent("PointLight", {
+  // color carries an explicit layer-2 default [1,1,1] (white); the array
+  // layer-3 fallback is all-zero, so the default MUST be explicit (D-5).
+  color: { type: "array<f32, 3>", default: new Float32Array([1, 1, 1]) },
+  intensity: { type: "f32", default: 1 },
+  range: { type: "f32", default: 10 }
+});
+var PointLightShadow = defineComponent("PointLightShadow", {
+  mapSize: { type: "f32", default: 512 },
+  depthBias: { type: "f32", default: 5e-3 },
+  normalBias: { type: "f32", default: 0.05 },
+  nearPlane: { type: "f32", default: 0.1 },
+  farPlane: { type: "f32", default: 25 },
+  pcfKernelSize: { type: "f32", default: 3 }
+});
+var schema = {
+  shader: "string",
+  data: "buffer"
+};
+var PostProcessParams = defineComponent("PostProcessParams", schema);
+var SceneInstance = defineComponent(
+  "SceneInstance",
+  {
+    source: { type: "shared<SceneAsset>" },
+    mapping: { type: "array<entity>" },
+    // The unique slot is the ECS storage seam for the instance's structured
+    // runtime payload; keep the nested semantic visible to schema consumers.
+    state: { type: "unique<SceneInstanceState>", shape: "nested" }
+  },
+  { transient: true }
+);
+var SKYBOX_MODE_CUBEMAP = 0;
+var SkyboxBackground = defineComponent("SkyboxBackground", {
+  // The GPU skybox projection is render-owned presentation state; restore
+  // keeps the portable mode/rotation controls and lets the owner re-resolve
+  // the environment asset on the target world.
+  equirect: { type: "shared<EquirectAsset>", simulationTransient: true },
+  mode: { type: "f32", default: SKYBOX_MODE_CUBEMAP },
+  rotation: { type: "array<f32, 4>", default: new Float32Array([0, 0, 0, 1]) }
+});
+var Skylight = defineComponent("Skylight", {
+  // The GPU equirect-to-cubemap projection is render-owned presentation
+  // state. Record/restore preserves the portable lighting controls while the
+  // render owner resolves this asset again on the target world.
+  equirect: { type: "shared<EquirectAsset>", simulationTransient: true },
+  // color carries an explicit layer-2 default [1,1,1] (white); the array
+  // layer-3 fallback is all-zero, so the default MUST be explicit (D-5).
+  color: { type: "array<f32, 3>", default: new Float32Array([1, 1, 1]) },
+  intensity: { type: "f32", default: 1 },
+  rotation: { type: "array<f32, 4>", default: new Float32Array([0, 0, 0, 1]) }
+});
+var SortKey = defineComponent("SortKey", {
+  value: { type: "f32", default: 0 }
+});
+var SpotLight = defineComponent("SpotLight", {
+  // direction has no default (D-5): omitting it lands the array layer-3
+  // all-zero, which validate() rejects. color carries an explicit layer-2
+  // default [1,1,1] (white); the array layer-3 fallback is all-zero.
+  direction: { type: "array<f32, 3>" },
+  color: { type: "array<f32, 3>", default: new Float32Array([1, 1, 1]) },
+  intensity: { type: "f32", default: 1 },
+  range: { type: "f32", default: 10 },
+  innerConeDeg: { type: "f32", default: 0 },
+  outerConeDeg: { type: "f32", default: 45 },
+  // Shadow opt-out gate: defaults to true so zero-config spawns cast shadows.
+  castShadow: { type: "bool", default: true },
+  // 6 shadow fields aligned with DirectionalLight (plan-strategy D-6).
+  mapSize: { type: "f32", default: 2048 },
+  depthBias: { type: "f32", default: 5e-3 },
+  normalBias: { type: "f32", default: 0.05 },
+  nearPlane: { type: "f32", default: 0.1 },
+  farPlane: { type: "f32", default: 50 },
+  pcfKernelSize: { type: "f32", default: 3 }
+});
+var VisibilityStateValue = Object.freeze({
+  inherited: 0,
+  hidden: 1,
+  visible: 2
+});
+function visibilityStateFromU32(value) {
+  switch (value) {
+    case VisibilityStateValue.inherited:
+      return "inherited";
+    case VisibilityStateValue.hidden:
+      return "hidden";
+    case VisibilityStateValue.visible:
+      return "visible";
+    default:
+      return void 0;
+  }
+}
+var Visibility = defineComponent(
+  "Visibility",
+  {
+    state: {
+      type: "enum",
+      default: VisibilityStateValue.inherited,
+      labels: VisibilityStateValue
+    }
+  },
+  {
+    meta: {
+      quickStart: "Attach Visibility to author render participation intent.",
+      diagnostics: "Compare the ECS state with resolveVisibility and renderer.visibilityStats.",
+      recovery: "Use structured ECS write errors and repair the owning scene relation.",
+      boundaries: "Visibility does not own camera, picking, lifecycle, assets, or VFX shadow policy."
+    }
+  }
+);
+
+// src/pipeline/standard-profile.ts
+var STANDARD_PIPELINE_ID = "forgeax::standard";
+var STANDARD_LIGHT_COUNTS = [1, 32, 256];
+var DEFAULT_CLUSTER_GRID = { x: 16, y: 9, z: 24 };
+var CLUSTER_GRID_STRIDE_U32 = 2;
+var LIGHT_INDEX_LIST_CAPACITY = 1048576;
+var MAX_LIGHTS = 256;
+var DEFAULT_STANDARD_PROFILE = Object.freeze({
+  pipelineId: STANDARD_PIPELINE_ID,
+  lightCount: 32,
+  lighting: "direct",
+  shadows: "filtered",
+  pbr: true,
+  ibl: true,
+  ssao: false,
+  bloom: true,
+  tone: "aces-filmic",
+  antialias: "fxaa",
+  sky: true,
+  fallback: "native",
+  postStages: ["transparent-blend", "bloom", "tone", "fxaa", "output"]
+});
+function resolveStandardLane(profile, capabilities) {
+  if (!capabilities.compute || !capabilities.storageBuffer) return "cpu-webgl2";
+  return profile.lighting;
+}
+
+// src/render-contract.ts
+var STANDARD_TONEMAP_FEATURE_ID = "forgeax::standard::tonemap";
+var RENDER_GRAPH_EXECUTION_PHASE_CATALOG = [
+  "record/graph-execute/point-shadow",
+  "record/graph-execute/cluster-binner-upload",
+  "record/graph-execute/g-buffer",
+  "record/graph-execute/g-buffer/geometry-loop",
+  "record/graph-execute/g-buffer/material-bind-groups",
+  "record/graph-execute/g-buffer/pipeline-selection",
+  "record/graph-execute/g-buffer/draw-submit",
+  "record/graph-execute/ssao-calc",
+  "record/graph-execute/ssao-blur",
+  "record/graph-execute/lighting",
+  "record/graph-execute/forward",
+  "record/graph-execute/forward/geometry-loop",
+  "record/graph-execute/forward/material-bind-groups",
+  "record/graph-execute/forward/pipeline-selection",
+  "record/graph-execute/forward/draw-submit",
+  "record/graph-execute/tonemap",
+  "record/graph-execute/debug-overlay",
+  "record/graph-execute/shadow",
+  "record/graph-execute/spot-shadow",
+  "record/graph-execute/skybox",
+  "record/graph-execute/main",
+  "record/graph-execute/fxaa",
+  "record/graph-execute/bloom-bright",
+  "record/graph-execute/bloom-blur-h",
+  "record/graph-execute/bloom-blur-v",
+  "record/graph-execute/bloom-composite",
+  "record/graph-execute/other"
+];
+var RENDER_HDRP_BINNER_PHASE_CATALOG = [
+  "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy",
+  "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/light-aabb",
+  "record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/cluster-occupancy",
+  "record/scene-state/hdrp-cluster/binner/cluster-reserve",
+  "record/scene-state/hdrp-cluster/binner/input-preparation",
+  "record/scene-state/hdrp-cluster/binner/bin-core",
+  "record/scene-state/hdrp-cluster/binner/light-index-write",
+  "record/scene-state/hdrp-cluster/binner/light-index-write/bounds-read",
+  "record/scene-state/hdrp-cluster/binner/light-index-write/cluster-write"
+];
+var RENDER_HDRP_CLUSTER_PHASE_CATALOG = [
+  "record/scene-state/hdrp-cluster/binner",
+  ...RENDER_HDRP_BINNER_PHASE_CATALOG,
+  "record/scene-state/hdrp-cluster/payload-packing",
+  "record/scene-state/hdrp-cluster/buffer-upload"
+];
+var RENDER_SCENE_STATE_PHASE_CATALOG = [
+  "record/scene-state/fold-buckets",
+  "record/scene-state/lighting-prep",
+  "record/scene-state/ambient-resolution",
+  "record/scene-state/directional-shadow-cache",
+  "record/scene-state/hdrp-cluster",
+  ...RENDER_HDRP_CLUSTER_PHASE_CATALOG
+];
+var RENDER_RECORD_PHASE_CATALOG = [
+  "record/scene-state",
+  ...RENDER_SCENE_STATE_PHASE_CATALOG,
+  "record/swapchain",
+  "record/render-graph",
+  "record/target-views",
+  "record/validation",
+  "record/dispatch-plan",
+  "record/uploads",
+  "record/bind-groups",
+  "record/graph-execute",
+  ...RENDER_GRAPH_EXECUTION_PHASE_CATALOG
+];
+var RENDER_PHASE_CATALOG = [
+  "extract",
+  "bind-groups",
+  "features",
+  "sort",
+  "record",
+  ...RENDER_RECORD_PHASE_CATALOG
+];
+function resolveVisibility(world, hierarchy = projectHierarchy(world)) {
+  const query = world.query({ read: [Entity], optional: [Visibility] });
+  let intentCount = 0;
+  let hasAnyHiddenIntent = false;
+  if (query.ok) {
+    for (const row of query.value) {
+      const visibility = row.get(Visibility);
+      if (visibility === void 0) continue;
+      intentCount += 1;
+      if (visibility.state === VisibilityStateValue.hidden) {
+        hasAnyHiddenIntent = true;
+      }
+    }
+  }
+  let resolveEntity;
+  let hasIntent;
+  const ensureResolver = () => {
+    if (resolveEntity !== void 0) return;
+    const intentByEntity = /* @__PURE__ */ new Map();
+    if (query.ok) {
+      for (const row of query.value) {
+        const raw = row.get(Visibility);
+        const intent = raw === void 0 ? void 0 : visibilityStateFromU32(raw.state);
+        if (intent !== void 0) {
+          intentByEntity.set(row.entity, intent);
+        }
+      }
+    }
+    hasIntent = (entity) => intentByEntity.has(entity);
+    const resolved = /* @__PURE__ */ new Map();
+    const resolving = /* @__PURE__ */ new Set();
+    resolveEntity = (entity) => {
+      const existing = resolved.get(entity);
+      if (existing !== void 0) return existing;
+      if (resolving.has(entity)) return void 0;
+      const intent = intentByEntity.get(entity) ?? "inherited";
+      resolving.add(entity);
+      let result;
+      if (intent === "hidden") {
+        result = { intent, effective: "hidden", source: "self" };
+      } else if (intent === "visible") {
+        result = { intent, effective: "visible", source: "self" };
+      } else {
+        const parent = hierarchy.getParent(entity);
+        const parentResult = parent === void 0 ? void 0 : resolveEntity?.(parent);
+        result = parentResult === void 0 ? { intent, effective: "visible", source: "default" } : { intent, effective: parentResult.effective, source: "parent" };
+      }
+      resolving.delete(entity);
+      resolved.set(entity, result);
+      return result;
+    };
+  };
+  return {
+    diagnostics: hierarchy.diagnostics,
+    hasAnyIntent: intentCount > 0,
+    hasAnyHiddenIntent,
+    get(entity) {
+      ensureResolver();
+      return hasIntent?.(entity) ? resolveEntity?.(entity) : void 0;
+    },
+    effective(entity) {
+      ensureResolver();
+      return resolveEntity?.(entity)?.effective ?? "visible";
+    }
+  };
+}
+
+export { ANTIALIAS_FXAA, ANTIALIAS_MSAA, ANTIALIAS_NONE, BLOOM_DISABLED, BLOOM_ENABLED, CAMERA_PROJECTION_ORTHOGRAPHIC, CAMERA_PROJECTION_PERSPECTIVE, CLUSTER_GRID_STRIDE_U32, Camera, DEFAULT_CLUSTER_GRID, DEFAULT_STANDARD_PROFILE, DirectionalLight, Instances, LIGHT_INDEX_LIST_CAPACITY, Layer, MAX_LIGHTS, MeshFilter, MeshRenderer, PointLight, PointLightShadow, PostProcessParams, RENDER_PHASE_CATALOG, SKYBOX_MODE_CUBEMAP, STANDARD_LIGHT_COUNTS, STANDARD_PIPELINE_ID, STANDARD_TONEMAP_FEATURE_ID, SceneInstance, SkyboxBackground, Skylight, SortKey, SpotLight, TONEMAP_ACES_FILMIC, TONEMAP_AGX, TONEMAP_CINEON, TONEMAP_LINEAR, TONEMAP_NEUTRAL, TONEMAP_NONE, TONEMAP_REINHARD, TONEMAP_REINHARD_EXTENDED, Visibility, VisibilityStateValue, antialiasFromF32, bloomEnabledFromF32, cameraProjectionFromF32, orthographic, perspective, resolveStandardLane, resolveVisibility, tonemapFromF32, tonemapToU32, visibilityStateFromU32 };
+//# sourceMappingURL=chunk-SCRSAK5B.mjs.map
+//# sourceMappingURL=chunk-SCRSAK5B.mjs.map