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

package/src/extract/visibility.ts

@@ -0,0 +1,120 @@
+import { Entity, type EntityHandle, type World } from '@forgeax/engine-ecs';
+import {
+  projectHierarchy,
+  type SceneHierarchyDiagnostic,
+  type SceneHierarchySnapshot,
+} from '@forgeax/engine-scene';
+import {
+  Visibility,
+  type VisibilityState,
+  VisibilityStateValue,
+  visibilityStateFromU32,
+} from '../components/visibility';
+
+export type VisibilitySource = 'default' | 'self' | 'parent';
+
+export interface VisibilityResolution {
+  /** The component value authored on this entity before inheritance. */
+  readonly intent: VisibilityState;
+  /** The state consumed by render candidates after parent resolution. */
+  readonly effective: 'hidden' | 'visible';
+  /** Explains whether the effective state came from self, parent, or default. */
+  readonly source: VisibilitySource;
+}
+
+export interface VisibilitySnapshot {
+  readonly diagnostics: readonly SceneHierarchyDiagnostic[];
+  readonly hasAnyIntent: boolean;
+  readonly hasAnyHiddenIntent: boolean;
+  get(entity: EntityHandle): VisibilityResolution | undefined;
+  /** Resolve effective visibility for a render candidate, including inherited defaults. */
+  effective(entity: EntityHandle): 'hidden' | 'visible';
+}
+
+interface ResolutionState {
+  readonly intent: VisibilityState;
+  readonly effective: 'hidden' | 'visible';
+  readonly source: VisibilitySource;
+}
+
+/**
+ * Resolve author intent against the scene-owned valid parent projection.
+ * Diagnostics are preserved for callers to repair hierarchy input before retry.
+ */
+export function resolveVisibility(
+  world: World,
+  hierarchy: SceneHierarchySnapshot = projectHierarchy(world),
+): VisibilitySnapshot {
+  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 === undefined) continue;
+      intentCount += 1;
+      if (visibility.state === VisibilityStateValue.hidden) {
+        hasAnyHiddenIntent = true;
+      }
+    }
+  }
+
+  let resolveEntity: ((entity: EntityHandle) => ResolutionState | undefined) | undefined;
+  let hasIntent: ((entity: EntityHandle) => boolean) | undefined;
+  const ensureResolver = (): void => {
+    if (resolveEntity !== undefined) return;
+    const intentByEntity = new Map<EntityHandle, VisibilityState>();
+    if (query.ok) {
+      for (const row of query.value) {
+        const raw = row.get(Visibility);
+        const intent = raw === undefined ? undefined : visibilityStateFromU32(raw.state);
+        if (intent !== undefined) {
+          intentByEntity.set(row.entity, intent);
+        }
+      }
+    }
+    hasIntent = (entity: EntityHandle): boolean => intentByEntity.has(entity);
+    const resolved = new Map<EntityHandle, ResolutionState>();
+    const resolving = new Set<EntityHandle>();
+    resolveEntity = (entity: EntityHandle): ResolutionState | undefined => {
+      const existing = resolved.get(entity);
+      if (existing !== undefined) return existing;
+      if (resolving.has(entity)) return undefined;
+
+      const intent = intentByEntity.get(entity) ?? 'inherited';
+      resolving.add(entity);
+
+      let result: ResolutionState;
+      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 === undefined ? undefined : resolveEntity?.(parent);
+        result =
+          parentResult === undefined
+            ? { 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: EntityHandle): VisibilityResolution | undefined {
+      ensureResolver();
+      return hasIntent?.(entity) ? resolveEntity?.(entity) : undefined;
+    },
+    effective(entity: EntityHandle): 'hidden' | 'visible' {
+      ensureResolver();
+      return resolveEntity?.(entity)?.effective ?? 'visible';
+    },
+  };
+}

package/src/features/fullscreen.ts

@@ -0,0 +1,46 @@
+import { ok } from '@forgeax/engine-types';
+import type {
+  RenderFeatureFullscreenRead,
+  RenderFeaturePlan,
+  RenderFeaturePlanContext,
+} from './plan';
+import type { RenderFeature, RenderFeatureExtractContext } from './types';
+
+/** Host-owned fullscreen effect declaration carried by one RenderFeature. */
+export interface FullscreenRenderFeatureOptions {
+  readonly identity: string;
+  readonly source: string;
+  readonly reads?: readonly RenderFeatureFullscreenRead[];
+  readonly params?: {
+    readonly byteSize: number;
+    readonly defaultValue: Uint8Array;
+  };
+}
+
+/**
+ * Describe a fullscreen effect for the single feature host.
+ * The producer returns this closed feature; GPU registration and lifetime stay
+ * with the renderer host.
+ */
+export function createFullscreenRenderFeature(
+  options: FullscreenRenderFeatureOptions,
+): RenderFeature<undefined> {
+  const resourceName = `fullscreen.${options.identity.replace(/[^a-z0-9.-]/gi, '-').toLowerCase()}`;
+  return Object.freeze({
+    identity: options.identity,
+    extract: (_context: RenderFeatureExtractContext) => ok(undefined),
+    plan: (_data: undefined, _context: RenderFeaturePlanContext) =>
+      ok({
+        resources: [
+          {
+            kind: 'fullscreen-program',
+            name: resourceName,
+            source: options.source,
+            ...(options.reads === undefined ? {} : { reads: options.reads }),
+            ...(options.params === undefined ? {} : { params: options.params }),
+          },
+        ],
+        passes: [],
+      } satisfies RenderFeaturePlan),
+  });
+}