@forgeax/engine-render 0.1.33 → 0.1.34

package/src/cloud/parameters.ts

@@ -0,0 +1,255 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import {
+  type CloudLayerData,
+  type CloudQuality,
+  CloudQualityValue,
+  cloudQualityFromF32,
+} from '../components/cloud-layer';
+import { type CloudLayerError, CloudLayerInvalidParameterError } from '../errors/cloud';
+
+export interface CloudLayerAuthoring {
+  readonly seed?: number;
+  readonly baseHeight?: number;
+  readonly thickness?: number;
+  readonly scale?: number;
+  readonly coverage?: number;
+  readonly density?: number;
+  readonly wind?: ArrayLike<number>;
+  readonly quality?: CloudQuality | number;
+  readonly shadowRange?: number;
+}
+
+export interface ValidatedCloudLayer {
+  readonly seed: number;
+  readonly baseHeight: number;
+  readonly thickness: number;
+  readonly scale: number;
+  readonly coverage: number;
+  readonly density: number;
+  readonly wind: readonly [number, number, number];
+  readonly quality: CloudQuality;
+  readonly shadowRange: number;
+}
+
+export interface CloudQualityProfile {
+  readonly cacheResolution: number;
+  readonly viewSteps: number;
+  readonly shadowSteps: number;
+  readonly historyWeight: number;
+  /** Renderer-owned sky trace domain in world units; independent of Camera.far. */
+  readonly viewDistance: number;
+}
+
+/**
+ * Quality values are bounded in one place. The values are deliberately
+ * renderer policy, while the component stores only the closed quality code.
+ */
+export const CLOUD_QUALITY_PROFILES: Readonly<Record<CloudQuality, CloudQualityProfile>> =
+  Object.freeze({
+    low: Object.freeze({
+      // Preserve low-profile ray counts while keeping separate puffs from
+      // collapsing into one bilinear cache smear.
+      cacheResolution: 32,
+      viewSteps: 40,
+      shadowSteps: 12,
+      historyWeight: 0.82,
+      viewDistance: 1600,
+    }),
+    medium: Object.freeze({
+      cacheResolution: 40,
+      viewSteps: 64,
+      shadowSteps: 20,
+      historyWeight: 0.9,
+      viewDistance: 2400,
+    }),
+    high: Object.freeze({
+      cacheResolution: 64,
+      viewSteps: 64,
+      shadowSteps: 32,
+      historyWeight: 0.94,
+      viewDistance: 4000,
+    }),
+  });
+
+/**
+ * The spatial cloud-shadow map is intentionally derived from the same quality
+ * profile everywhere: graph allocation, light-space projection and inspection
+ * must agree on one texel grid.  Keep the multiplier here rather than letting
+ * each owner invent a resolution.
+ */
+export function cloudShadowResolutionForQuality(qualityValue: CloudQuality): number {
+  return CLOUD_QUALITY_PROFILES[qualityValue].cacheResolution * 4;
+}
+
+/**
+ * Cloud visibility is a sky-domain concern. It must not inherit the opaque
+ * geometry far plane or the finite receiver-shadow footprint: either value is
+ * commonly much shorter than a ground-view cloud trace and would turn the
+ * distant layer into a flat wall.
+ */
+export function cloudViewDistanceForQuality(qualityValue: CloudQuality): number {
+  return CLOUD_QUALITY_PROFILES[qualityValue].viewDistance;
+}
+
+/** rgba16float is four 16-bit channels (8 bytes per texel). */
+export const CLOUD_SHADOW_BYTES_PER_TEXEL = 8;
+
+/**
+ * Authored density is a normalized formation value. Convert it to a bounded
+ * per-world-unit extinction coefficient only at integration time; otherwise a
+ * long horizon step would become opaque after its first sample and expose
+ * marching bands instead of a participating volume.
+ */
+export const CLOUD_EXTINCTION_COEFFICIENT = 0.03;
+
+export const DEFAULT_CLOUD_LAYER: ValidatedCloudLayer = Object.freeze({
+  seed: 1337,
+  baseHeight: 120,
+  thickness: 80,
+  scale: 0.004,
+  coverage: 0.48,
+  density: 1,
+  wind: Object.freeze([8, 0, 2] as [number, number, number]),
+  quality: 'medium',
+  shadowRange: 512,
+});
+
+function invalid(field: string, value: unknown, expected: string): Result<never, CloudLayerError> {
+  return err(new CloudLayerInvalidParameterError(field, value, expected));
+}
+
+function finiteRange(
+  field: string,
+  value: unknown,
+  min: number,
+  max = Number.POSITIVE_INFINITY,
+): Result<number, CloudLayerError> {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+    const expected = Number.isFinite(max)
+      ? `finite and in [${min}, ${max}]`
+      : `finite and >= ${min}`;
+    return invalid(field, value, expected);
+  }
+  return ok(value);
+}
+
+function quality(value: unknown): Result<CloudQuality, CloudLayerError> {
+  if (typeof value === 'string' && (value === 'low' || value === 'medium' || value === 'high')) {
+    return ok(value);
+  }
+  if (typeof value === 'number') {
+    const resolved = cloudQualityFromF32(value);
+    if (resolved !== undefined) return ok(resolved);
+  }
+  return invalid(
+    'quality',
+    value,
+    `one of low, medium, high (codes ${CloudQualityValue.low}, ${CloudQualityValue.medium}, ${CloudQualityValue.high})`,
+  );
+}
+
+function wind(value: unknown): Result<readonly [number, number, number], CloudLayerError> {
+  if (value === undefined || value === null || typeof value !== 'object') {
+    return invalid('wind', value, 'three finite world-space components');
+  }
+  const source = value as ArrayLike<number>;
+  if (source.length !== 3) return invalid('wind', value, 'three finite world-space components');
+  const result: [number, number, number] = [
+    source[0] ?? Number.NaN,
+    source[1] ?? Number.NaN,
+    source[2] ?? Number.NaN,
+  ];
+  if (result.some((entry) => !Number.isFinite(entry) || Math.abs(entry) > 1000)) {
+    return invalid('wind', value, 'three finite components in [-1000, 1000]');
+  }
+  return ok(Object.freeze(result));
+}
+
+/** Validate one detached CloudLayer POD before deriving cache or graph state. */
+export function validateCloudLayer(
+  input: CloudLayerAuthoring | Partial<CloudLayerData> | undefined,
+): Result<ValidatedCloudLayer, CloudLayerError> {
+  const value = input ?? {};
+  const seed = value.seed ?? DEFAULT_CLOUD_LAYER.seed;
+  if (typeof seed !== 'number' || !Number.isInteger(seed) || seed < 0 || seed > 0xffffffff) {
+    return invalid('seed', seed, 'an integer in [0, 4294967295]');
+  }
+  const baseHeight = finiteRange(
+    'baseHeight',
+    value.baseHeight ?? DEFAULT_CLOUD_LAYER.baseHeight,
+    -100000,
+    1000000,
+  );
+  if (!baseHeight.ok) return baseHeight;
+  const thickness = finiteRange(
+    'thickness',
+    value.thickness ?? DEFAULT_CLOUD_LAYER.thickness,
+    0.001,
+    1000000,
+  );
+  if (!thickness.ok) return thickness;
+  const scale = finiteRange('scale', value.scale ?? DEFAULT_CLOUD_LAYER.scale, 0.000001, 10);
+  if (!scale.ok) return scale;
+  const coverage = finiteRange('coverage', value.coverage ?? DEFAULT_CLOUD_LAYER.coverage, 0, 1);
+  if (!coverage.ok) return coverage;
+  const density = finiteRange('density', value.density ?? DEFAULT_CLOUD_LAYER.density, 0, 32);
+  if (!density.ok) return density;
+  const resolvedWind = wind(value.wind ?? DEFAULT_CLOUD_LAYER.wind);
+  if (!resolvedWind.ok) return resolvedWind;
+  const resolvedQuality = quality(value.quality ?? DEFAULT_CLOUD_LAYER.quality);
+  if (!resolvedQuality.ok) return resolvedQuality;
+  const shadowRange = finiteRange(
+    'shadowRange',
+    value.shadowRange ?? DEFAULT_CLOUD_LAYER.shadowRange,
+    0.001,
+    10000000,
+  );
+  if (!shadowRange.ok) return shadowRange;
+  return ok(
+    Object.freeze({
+      seed,
+      baseHeight: baseHeight.value,
+      thickness: thickness.value,
+      scale: scale.value,
+      coverage: coverage.value,
+      density: density.value,
+      wind: resolvedWind.value,
+      quality: resolvedQuality.value,
+      shadowRange: shadowRange.value,
+    }),
+  );
+}
+
+/** Stable source identity used by cache, history and recovery receipts. */
+export function cloudLayerSourceKey(params: ValidatedCloudLayer): string {
+  return [
+    'cloud-layer-v1',
+    params.seed,
+    params.baseHeight,
+    params.thickness,
+    params.scale,
+    params.coverage,
+    params.density,
+    params.wind[0],
+    params.wind[1],
+    params.wind[2],
+    params.quality,
+    params.shadowRange,
+  ].join(':');
+}
+
+/**
+ * Stable identity for the reusable formation bases. Coverage, density and
+ * wind are evaluation inputs and deliberately do not rebuild the weather,
+ * body or erosion cache when they change continuously.
+ */
+export function cloudLayerFormationKey(params: ValidatedCloudLayer): string {
+  return [
+    'cloud-formation-v5',
+    params.seed,
+    params.baseHeight,
+    params.thickness,
+    params.scale,
+    params.quality,
+  ].join(':');
+}

package/src/cloud/resources.ts

@@ -0,0 +1,122 @@
+import type { CloudDensityCache } from './density';
+import type { CloudShadowProjection } from './shadow';
+import type { CloudHistory } from './temporal';
+
+/** Evidence level for bytes owned by the prepared GPU path. */
+export type CloudGpuResourceEvidence = 'unavailable' | 'declared' | 'measured';
+
+/** rgba16float is four 16-bit channels (8 bytes per texel). */
+export const CLOUD_RGBA16FLOAT_BYTES_PER_TEXEL = 8;
+/** Two ping-pong surfaces for each of radiance/transmittance/depth. */
+export const CLOUD_HISTORY_SURFACE_COUNT = 6;
+
+export interface CloudLayerResourceFacts {
+  readonly generation: number;
+  /** CPU-side packed formation payload; this is not GPU residency. */
+  readonly cacheBytes: number;
+  /** Measured GPU bytes, or zero when no prepared-owner receipt was supplied. */
+  readonly shadowBytes: number;
+  readonly historyBytes: number;
+  readonly inFlightBytes: number;
+  readonly residentBytes: number;
+  readonly resourceCount: number;
+  /** Whether the GPU byte fields are measured, only graph-declared, or unknown. */
+  readonly gpuEvidence: CloudGpuResourceEvidence;
+  /** Descriptor-derived allocation sizes, independent from physical residency. */
+  readonly declaredShadowBytes: number;
+  readonly declaredHistoryBytes: number;
+  readonly declaredResidentBytes: number;
+  readonly declaredResourceCount: number;
+  /** Measured GPU resource count, kept separate from logical declarations. */
+  readonly measuredGpuResourceCount: number;
+  readonly cacheResolution: number;
+  readonly shadowResolution: number;
+}
+
+export interface CloudLayerResourceInputs {
+  readonly generation: number;
+  readonly cache?: CloudDensityCache;
+  readonly shadow?: CloudShadowProjection;
+  readonly history?: CloudHistory;
+  /** Bytes reported by the prepared GPU owner; absent means unavailable. */
+  readonly shadowBytes?: number;
+  readonly historyBytes?: number;
+  readonly inFlightBytes?: number;
+}
+
+/** Derive one inspection receipt from the resources owned by the current generation. */
+export function inspectCloudLayerResources(
+  input: CloudLayerResourceInputs,
+): CloudLayerResourceFacts {
+  const cacheBytes = input.cache?.byteLength ?? 0;
+  const shadowResolution = input.shadow?.resolution ?? 0;
+  const declaredShadowBytes =
+    shadowResolution * shadowResolution * CLOUD_RGBA16FLOAT_BYTES_PER_TEXEL;
+  const historyWidth = input.history?.width ?? 0;
+  const historyHeight = input.history?.height ?? 0;
+  const declaredHistoryBytes =
+    historyWidth * historyHeight * CLOUD_HISTORY_SURFACE_COUNT * CLOUD_RGBA16FLOAT_BYTES_PER_TEXEL;
+  const shadowBytes = input.shadowBytes ?? 0;
+  const historyBytes = input.historyBytes ?? 0;
+  const inFlightBytes = Math.max(0, input.inFlightBytes ?? 0);
+  const residentBytes = cacheBytes + shadowBytes + historyBytes;
+  const measuredGpuResourceCount =
+    Number(input.shadowBytes !== undefined) + Number(input.historyBytes !== undefined);
+  const gpuEvidence: CloudGpuResourceEvidence =
+    measuredGpuResourceCount > 0 || input.inFlightBytes !== undefined
+      ? 'measured'
+      : input.shadow !== undefined || input.history !== undefined
+        ? 'declared'
+        : 'unavailable';
+  const resourceCount =
+    Number(input.cache !== undefined) +
+    Number(input.shadow !== undefined) +
+    Number(input.history !== undefined);
+  return Object.freeze({
+    generation: input.generation,
+    cacheBytes,
+    shadowBytes,
+    historyBytes,
+    inFlightBytes,
+    residentBytes,
+    resourceCount,
+    gpuEvidence,
+    declaredShadowBytes,
+    declaredHistoryBytes,
+    declaredResidentBytes: cacheBytes + declaredShadowBytes + declaredHistoryBytes,
+    declaredResourceCount: resourceCount,
+    measuredGpuResourceCount,
+    cacheResolution: input.cache?.resolution ?? 0,
+    shadowResolution,
+  });
+}
+
+export interface CloudLayerGeneration {
+  readonly generation: number;
+  readonly sourceKey: string;
+  readonly resourceFacts: CloudLayerResourceFacts;
+  readonly status: 'candidate' | 'active' | 'lkg' | 'retiring';
+}
+
+/** Candidate -> active transition used by the renderer's existing graph owner. */
+export function acceptCloudLayerGeneration(
+  candidate: CloudLayerGeneration,
+  previous: CloudLayerGeneration | undefined,
+): { readonly active: CloudLayerGeneration; readonly lkg: CloudLayerGeneration | undefined } {
+  return Object.freeze({
+    active: Object.freeze({ ...candidate, status: 'active' as const }),
+    lkg:
+      previous === undefined ? undefined : Object.freeze({ ...previous, status: 'lkg' as const }),
+  });
+}
+
+/** A failed candidate never replaces the LKG; retirement is fence-owned by Render. */
+export function retainCloudLayerAfterFailure(
+  active: CloudLayerGeneration | undefined,
+  candidate: CloudLayerGeneration,
+): { readonly active: CloudLayerGeneration | undefined; readonly retiring: CloudLayerGeneration } {
+  return Object.freeze({
+    active,
+    retiring: Object.freeze({ ...candidate, status: 'retiring' as const }),
+  });
+}

package/src/cloud/shadow.ts

@@ -0,0 +1,167 @@
+import type { CloudDensityCache } from './density';
+import { integrateCloudSolarColumn } from './optics';
+import type { ValidatedCloudLayer } from './parameters';
+
+export interface CloudShadowProjection {
+  readonly revision: number;
+  readonly resolution: number;
+  readonly range: number;
+  readonly texelSize: number;
+  readonly center: readonly [number, number, number];
+  readonly origin: readonly [number, number, number];
+  readonly right: readonly [number, number, number];
+  readonly up: readonly [number, number, number];
+  readonly sunDirection: readonly [number, number, number];
+  readonly lowSun: boolean;
+}
+
+export interface CloudShadowSample {
+  readonly transmittance: number;
+  readonly uv: readonly [number, number] | undefined;
+  readonly valid: boolean;
+  readonly fallback: 'none' | 'low-sun' | 'outside-range' | 'empty-coverage';
+  readonly revision: number;
+}
+
+function normalize(vector: ArrayLike<number>): readonly [number, number, number] {
+  const x = vector[0] ?? 0;
+  const y = vector[1] ?? 0;
+  const z = vector[2] ?? 0;
+  const length = Math.hypot(x, y, z);
+  return length <= 1e-8 ? [0, 1, 0] : [x / length, y / length, z / length];
+}
+
+function cross(
+  a: readonly [number, number, number],
+  b: readonly [number, number, number],
+): readonly [number, number, number] {
+  return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+
+function dot(a: ArrayLike<number>, b: ArrayLike<number>): number {
+  return (a[0] ?? 0) * (b[0] ?? 0) + (a[1] ?? 0) * (b[1] ?? 0) + (a[2] ?? 0) * (b[2] ?? 0);
+}
+
+function stableRevision(input: {
+  readonly center: readonly [number, number, number];
+  readonly sunDirection: readonly [number, number, number];
+  readonly range: number;
+  readonly resolution: number;
+}): number {
+  let hash = 2166136261;
+  const values = [...input.center, ...input.sunDirection, input.range, input.resolution];
+  for (const value of values) {
+    const bits = new Float32Array([value]);
+    const bytes = new Uint8Array(bits.buffer);
+    for (const byte of bytes) hash = Math.imul(hash ^ byte, 16777619);
+  }
+  return hash >>> 0;
+}
+
+/**
+ * Build a camera-independent light-space projection. The center is a world
+ * anchor chosen by Render (usually the active scene bounds), and is snapped to
+ * one texel so camera motion cannot crawl the cloud shadow.
+ */
+export function createCloudShadowProjection(input: {
+  readonly center: readonly [number, number, number];
+  readonly sunDirection: readonly [number, number, number];
+  readonly range: number;
+  readonly resolution?: number;
+}): CloudShadowProjection {
+  const sunDirection = normalize(input.sunDirection);
+  const resolution = Math.max(16, Math.floor(input.resolution ?? 1024));
+  const range = Math.max(1, input.range);
+  const texelSize = range / resolution;
+  const reference = Math.abs(sunDirection[1]) < 0.95 ? ([0, 1, 0] as const) : ([1, 0, 0] as const);
+  const right = normalize(cross(reference, sunDirection));
+  const up = normalize(cross(sunDirection, right));
+  const center = input.center;
+  const lightX = dot(center, right);
+  const lightY = dot(center, up);
+  const lightZ = dot(center, sunDirection);
+  const snappedX = Math.floor(lightX / texelSize + 0.5) * texelSize;
+  const snappedY = Math.floor(lightY / texelSize + 0.5) * texelSize;
+  const origin: [number, number, number] = [
+    right[0] * snappedX + up[0] * snappedY + sunDirection[0] * lightZ,
+    right[1] * snappedX + up[1] * snappedY + sunDirection[1] * lightZ,
+    right[2] * snappedX + up[2] * snappedY + sunDirection[2] * lightZ,
+  ];
+  return Object.freeze({
+    revision: stableRevision({ center, sunDirection, range, resolution }),
+    resolution,
+    range,
+    texelSize,
+    center: Object.freeze([...center] as [number, number, number]),
+    origin: Object.freeze(origin),
+    right,
+    up,
+    sunDirection,
+    lowSun: sunDirection[1] <= 0.08,
+  });
+}
+
+export function projectCloudShadowUv(
+  projection: CloudShadowProjection,
+  position: readonly [number, number, number],
+): { readonly uv: readonly [number, number]; readonly inRange: boolean } {
+  const relative: [number, number, number] = [
+    position[0] - projection.origin[0],
+    position[1] - projection.origin[1],
+    position[2] - projection.origin[2],
+  ];
+  const x = dot(relative, projection.right);
+  const y = dot(relative, projection.up);
+  const uv: [number, number] = [0.5 + x / projection.range, 0.5 + y / projection.range];
+  return { uv, inRange: uv[0] >= 0 && uv[0] <= 1 && uv[1] >= 0 && uv[1] <= 1 };
+}
+
+/** Evaluate the stable world-space shadow term used by surface and volume sun paths. */
+export function sampleCloudShadow(
+  params: ValidatedCloudLayer,
+  projection: CloudShadowProjection,
+  worldPosition: readonly [number, number, number],
+  options: { readonly cache?: CloudDensityCache; readonly timeSeconds?: number } = {},
+): CloudShadowSample {
+  const projected = projectCloudShadowUv(projection, worldPosition);
+  if (projection.lowSun) {
+    return {
+      transmittance: 1,
+      uv: projected.uv,
+      valid: false,
+      fallback: 'low-sun',
+      revision: projection.revision,
+    };
+  }
+  if (!projected.inRange) {
+    return {
+      transmittance: 1,
+      uv: projected.uv,
+      valid: false,
+      fallback: 'outside-range',
+      revision: projection.revision,
+    };
+  }
+  if (params.coverage >= 1 || params.density <= 0) {
+    return {
+      transmittance: 1,
+      uv: projected.uv,
+      valid: false,
+      fallback: 'empty-coverage',
+      revision: projection.revision,
+    };
+  }
+  const integrated = integrateCloudSolarColumn(params, worldPosition, projection.sunDirection, {
+    steps: 20,
+    maxDistance: projection.range,
+    ...(options.cache === undefined ? {} : { cache: options.cache }),
+    ...(options.timeSeconds === undefined ? {} : { timeSeconds: options.timeSeconds }),
+  });
+  return {
+    transmittance: integrated.transmittance,
+    uv: projected.uv,
+    valid: integrated.entered,
+    fallback: 'none',
+    revision: projection.revision,
+  };
+}