@babylonjs/loaders 9.26.1 → 9.27.0

package/glTF/2.0/Extensions/KHR_interactivity/interactivityGraphExporter.d.ts

@@ -0,0 +1,243 @@
+import { type IKHRInteractivity } from "babylonjs-gltf2interface";
+import { type AnimationGroup } from "@babylonjs/core/Animations/animationGroup.js";
+import { type FlowGraph } from "@babylonjs/core/FlowGraph/flowGraph.js";
+import { type Material } from "@babylonjs/core/Materials/material.js";
+import { type Node } from "@babylonjs/core/node.js";
+import { type Camera } from "@babylonjs/core/Cameras/camera.js";
+import { type IGLTF } from "../../glTFLoaderInterfaces.js";
+import { type IKHRInteractivityDocument } from "./interactivityGraphModel.js";
+/**
+ * Export support classification for a FlowGraph block or imported composite.
+ */
+export type KHRInteractivityExportClassification = "exact" | "inverse-composite" | "unsupported" | "lossy";
+/**
+ * Structured KHR_interactivity export diagnostic.
+ */
+export interface IKHRInteractivityExportDiagnostic {
+    /** Stable diagnostic code. */
+    code: "GRAPH_SOURCE_MISSING" | "GRAPH_COUNT_MISMATCH" | "NODE_SOURCE_MISSING" | "BLOCK_PROVENANCE_INVALID" | "BLOCK_ROLE_MISSING" | "BLOCK_ROLE_DUPLICATE" | "BLOCK_TYPE_MISMATCH" | "BLOCK_UNSUPPORTED" | "BLOCK_AMBIGUOUS" | "COMPOSITE_CONNECTION_CHANGED" | "SOCKET_PROVENANCE_MISSING" | "SOCKET_CONNECTION_AMBIGUOUS" | "SOCKET_TARGET_UNREPRESENTABLE" | "INPUT_DEFAULT_UNREPRESENTABLE" | "VALUE_UNREPRESENTABLE" | "CONFIGURATION_UNREPRESENTABLE" | "REFERENCE_UNRESOLVED" | "DEPENDENCY_CYCLE" | "GRAPH_INVALID";
+    /** JSON pointer or FlowGraph location associated with the issue. */
+    path: string;
+    /** Human-readable actionable diagnostic. */
+    message: string;
+    /** Diagnostic severity. */
+    severity: "error" | "warning";
+    /** Source graph index, when known. */
+    graphIndex?: number;
+    /** Source node index, when known. */
+    nodeIndex?: number;
+    /** FlowGraph block id, when known. */
+    blockId?: string;
+    /** KHR socket id, when known. */
+    socket?: string;
+}
+/**
+ * Representability result for one logical KHR node or standalone FlowGraph block.
+ */
+export interface IKHRInteractivityNodeExportAnalysis {
+    /** Source graph index. */
+    graphIndex: number;
+    /** Source KHR node index, when this is an imported node. */
+    nodeIndex?: number;
+    /** Full KHR operation name, when known. */
+    operation?: string;
+    /** FlowGraph blocks participating in this logical node. */
+    blockIds: string[];
+    /** Export support classification. */
+    classification: KHRInteractivityExportClassification;
+    /** Diagnostics scoped to this logical node. */
+    diagnostics: IKHRInteractivityExportDiagnostic[];
+}
+/**
+ * Complete representability analysis for a KHR_interactivity export.
+ */
+export interface IKHRInteractivityExportAnalysis {
+    /** True when every graph can be exported without loss or ambiguity. */
+    representable: boolean;
+    /** Per-node classifications in deterministic graph/source order. */
+    nodes: IKHRInteractivityNodeExportAnalysis[];
+    /** All diagnostics in deterministic order. */
+    diagnostics: IKHRInteractivityExportDiagnostic[];
+}
+/**
+ * Indexed glTF root collections that KHR_interactivity references can target.
+ */
+export type KhrInteractivityRootCollection = "nodes" | "animations" | "cameras" | "materials" | "meshes" | "textures" | "images" | "samplers" | "skins" | "scenes";
+/**
+ * Final glTF remapping context supplied by the serializer extension.
+ */
+export interface IKHRInteractivitySerializerContext {
+    /**
+     * Gets the final number of glTF nodes.
+     * @returns final glTF node count
+     */
+    getNodeCount(): number;
+    /**
+     * Gets the final glTF node index for a Babylon node.
+     * @param node Babylon node to resolve
+     * @returns final glTF node index, or undefined when the node was not exported
+     */
+    getNodeIndex(node: Node): number | undefined;
+    /**
+     * Gets the final glTF animation index for a Babylon animation group.
+     * @param animation Babylon animation group to resolve
+     * @returns final glTF animation index, or undefined when the animation was not exported
+     */
+    getAnimationIndex(animation: AnimationGroup): number | undefined;
+    /**
+     * Gets the final glTF camera index for a Babylon camera.
+     * @param camera Babylon camera to resolve
+     * @returns final glTF camera index, or undefined when the camera was not exported
+     */
+    getCameraIndex(camera: Camera): number | undefined;
+    /**
+     * Gets the final glTF material index for a Babylon material.
+     * @param material Babylon material to resolve
+     * @returns final glTF material index, or undefined when the material was not exported
+     */
+    getMaterialIndex(material: Material): number | undefined;
+    /**
+     * Gets the final glTF index for an imported Babylon entity in a root collection.
+     * @param collection target glTF root collection
+     * @param entity imported Babylon entity associated with the source entry
+     * @returns final glTF index, or undefined when the entity was not exported uniquely
+     */
+    getRootIndex?(collection: KhrInteractivityRootCollection, entity: object): number | undefined;
+    /**
+     * Writes a companion extension on an already-exported glTF node.
+     * @param nodeIndex final glTF node index
+     * @param extensionName companion extension name
+     * @param value companion extension payload
+     */
+    setNodeExtension(nodeIndex: number, extensionName: string, value: unknown): void;
+}
+/**
+ * Provider consumed by the KHR_interactivity serializer extension.
+ */
+export interface IKHRInteractivityExportProvider {
+    /** Whether KHR_interactivity must be listed in extensionsRequired. */
+    readonly required: boolean;
+    /** Other extensions referenced or emitted by the interactivity export. */
+    readonly additionalExtensionsUsed: readonly string[];
+    /** Other extensions that must be listed in extensionsRequired. */
+    readonly additionalExtensionsRequired: readonly string[];
+    /**
+     * Gets the detached representability analysis.
+     * @returns current export analysis
+     */
+    analyze(): IKHRInteractivityExportAnalysis;
+    /**
+     * Builds the canonical extension after glTF entity indices are finalized.
+     * @param context final serializer remapping context
+     * @returns ratified KHR_interactivity extension payload
+     */
+    build(context: IKHRInteractivitySerializerContext): IKHRInteractivity;
+}
+/**
+ * Options used to create a KHR_interactivity export plan.
+ */
+export interface IKHRInteractivityExportOptions {
+    /** Canonical Phase 1 document associated with the FlowGraphs. Required for a lossless export. */
+    document?: IKHRInteractivityDocument;
+    /** Loader glTF tree used to resolve original entity references. */
+    sourceGLTF?: IGLTF;
+    /** Root default graph index. Defaults to the canonical document selection or zero. */
+    defaultGraphIndex?: number;
+    /** Target animation frame rate used by imported animation composites. Defaults to 60. */
+    targetFps?: number;
+    /** Whether the emitted KHR_interactivity extension is required. Defaults to true. */
+    required?: boolean;
+    /** Additional extensions that must be required together with the behavior graph. */
+    additionalExtensionsRequired?: readonly string[];
+}
+/**
+ * Error thrown when export cannot preserve the authored behavior graph.
+ */
+export declare class KHRInteractivityExportError extends Error {
+    readonly diagnostics: readonly IKHRInteractivityExportDiagnostic[];
+    /**
+     * @param diagnostics precise export diagnostics
+     */
+    constructor(diagnostics: readonly IKHRInteractivityExportDiagnostic[]);
+}
+/**
+ * Detached representability and export plan for one or more FlowGraphs.
+ */
+export declare class KHRInteractivityExportPlan implements IKHRInteractivityExportProvider {
+    private readonly _flowGraphs;
+    private readonly _options;
+    private _analysis;
+    private _graphAnalyses;
+    private _additionalExtensionsUsed;
+    private readonly _rootDiagnostics;
+    private _isPreflight;
+    /** Whether KHR_interactivity is required in the exported asset. */
+    readonly required: boolean;
+    /** Additional operation/companion extensions referenced by the exported graphs. */
+    get additionalExtensionsUsed(): readonly string[];
+    /** Additional extensions explicitly required by the caller. */
+    readonly additionalExtensionsRequired: readonly string[];
+    /**
+     * @param _flowGraphs FlowGraphs to analyze without mutating them
+     * @param _options canonical source and export settings
+     */
+    constructor(_flowGraphs: readonly FlowGraph[], _options?: IKHRInteractivityExportOptions);
+    private _refreshAnalysis;
+    private _mergeBuildDiagnostics;
+    /**
+     * Gets the detached representability analysis.
+     * @returns current analysis
+     */
+    analyze(): IKHRInteractivityExportAnalysis;
+    /**
+     * Builds the extension after final glTF entity remapping is available.
+     * @param context serializer remapping context
+     * @returns canonical KHR_interactivity payload
+     */
+    build(context: IKHRInteractivitySerializerContext): IKHRInteractivity;
+    private _getSourceGraph;
+    private _validateBuildWithSourceIndices;
+    private _analyzeGraphs;
+    private _classifyStandaloneBlock;
+    private _analyzeImportedNodes;
+    private _validateUnsupportedExtensionBlock;
+    private _validateMappedBlocks;
+    private _buildGraph;
+    private _rebuildNode;
+    private _getMappingObject;
+    private _inferSocketProvenance;
+    private _isNoOpFlowTarget;
+    private _isEffectiveFlowInput;
+    private _isEffectiveFlowOutput;
+    private _getAllowedDynamicFlowSockets;
+    private _resolveValueTypeIndex;
+    private _resolveOutputTypeIndex;
+    private _isEffectiveValueInput;
+    private _rebuildInputValue;
+    private _unwrapAnimationTimeHelper;
+    private _rebuildConfiguration;
+    private _remapPointerTemplateInputs;
+    private _updateVariables;
+    private _remapValueArray;
+    private _topologicallyOrderNodes;
+    private _remapGraphReferences;
+    private _getVariableReferenceCollection;
+    private _getPointerReferenceCollection;
+    private _getRemappedRootIndex;
+    private _getSourceRootObjects;
+    private _getSourceRootIndex;
+    private _getExportedObjectIndex;
+    private _remapReferenceToCollection;
+    private _remapReference;
+    private _validateExtensionReferencePreservation;
+    private _collectAdditionalExtensions;
+    private _writeCompanionNodeExtensions;
+    private _sortDiagnostics;
+}
+/**
+ * Creates a detached KHR_interactivity export plan without mutating the FlowGraphs.
+ * @param flowGraphs graphs to export in root graph order
+ * @param options canonical source and serializer settings
+ * @returns reusable representability/export provider
+ */
+export declare function CreateKHRInteractivityExportPlan(flowGraphs: readonly FlowGraph[], options?: IKHRInteractivityExportOptions): KHRInteractivityExportPlan;