@babylonjs/loaders 9.26.1 → 9.27.0

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

@@ -0,0 +1,193 @@
+import { type IKHRInteractivity, type IKHRInteractivity_Declaration, type IKHRInteractivity_Graph, type IKHRInteractivity_OutputSocketReference, type IKHRInteractivity_Variable } from "babylonjs-gltf2interface";
+import { FlowGraphTypes } from "@babylonjs/core/FlowGraph/flowGraphRichTypes.js";
+/**
+ * Ratified KHR_interactivity specification baseline used by this importer.
+ */
+export declare const KHR_INTERACTIVITY_SPECIFICATION_COMMIT = "f798712c5685bc9223a628140fba707db8889300";
+/**
+ * Runtime representation of every ratified built-in KHR_interactivity type.
+ */
+export declare const gltfTypeToBabylonType: {
+    [key: string]: {
+        length: number;
+        flowGraphType: FlowGraphTypes;
+        elementType: "number" | "boolean" | "string" | "any";
+    };
+};
+/**
+ * Classification of a KHR_interactivity declaration.
+ */
+export type KHRInteractivityDeclarationSupport = "core" | "extension" | "unsupported-extension" | "unknown-core";
+/**
+ * A structured KHR_interactivity import diagnostic.
+ */
+export interface IKHRInteractivityDiagnostic {
+    /** JSON pointer identifying the source location. */
+    path: string;
+    /** Human-readable diagnostic text. */
+    message: string;
+    /** Diagnostic severity. */
+    severity: "error" | "warning";
+}
+/**
+ * Stable source identity retained on every FlowGraph block lowered from a KHR_interactivity node.
+ */
+export interface IKHRInteractivityBlockProvenance {
+    /** Source graph index. */
+    graphIndex: number;
+    /** Source node index. */
+    nodeIndex: number;
+    /** Source declaration index. */
+    declarationIndex: number;
+    /** Full operation name. */
+    operation: string;
+    /** Role of this block in a one-to-many mapping. Negative roles identify generated helper blocks. */
+    role: number;
+    /** Stable JSON pointer to the source node. */
+    sourcePath: string;
+    /** Original and lowered configuration values used for safe inverse transforms. */
+    configuration?: Record<string, IKHRInteractivityConfigurationProvenance>;
+    /** Importer-generated primitive configuration that must remain unchanged for inverse export. */
+    generatedConfiguration?: Record<string, unknown>;
+    /** Runtime fingerprints for generated configuration that changes representation while parsing. */
+    generatedConfigurationRuntime?: Record<string, IKHRInteractivityInputDefaultProvenance>;
+    /** Importer-generated unconnected input defaults that have no authored KHR socket representation. */
+    generatedInputDefaults?: Record<string, IKHRInteractivityInputDefaultProvenance>;
+}
+/**
+ * Import-time value retained for an unconnected FlowGraph input that is not represented by an authored KHR socket.
+ */
+export interface IKHRInteractivityInputDefaultProvenance {
+    /** Type-tagged JSON-stable fingerprint of the normalized runtime input value. */
+    runtimeValueFingerprint?: string;
+    /** Whether the import-time value could not be fingerprinted safely. */
+    unrepresentable?: true;
+}
+/**
+ * Provenance for a transformed KHR configuration value.
+ */
+export interface IKHRInteractivityConfigurationProvenance {
+    /** Exact source configuration array. */
+    sourceValue?: unknown[];
+    /** Lowered FlowGraph configuration value immediately after import. */
+    runtimeValue?: unknown;
+}
+/** @internal */
+export declare function _NormalizeKHRInteractivityRuntimeValue(value: unknown): unknown[] | undefined;
+/** @internal */
+export declare function _CreateKHRInteractivityRuntimeValueSnapshot(value: unknown): IKHRInteractivityInputDefaultProvenance;
+/**
+ * Stable source identity retained on a FlowGraph connection lowered from a KHR_interactivity socket.
+ */
+export interface IKHRInteractivitySocketProvenance extends IKHRInteractivityBlockProvenance {
+    /** Socket category. */
+    kind: "value" | "flow";
+    /** Whether the socket is consumed by or produced from the logical KHR node. */
+    direction: "input" | "output";
+    /** Exact source KHR socket identifier. */
+    socket: string;
+    /** Exact canonical source value, when this is an input value socket. */
+    sourceValue?: IKHRInteractivity_Variable | IKHRInteractivity_OutputSocketReference;
+    /** Lowered inline runtime value immediately after import. */
+    runtimeValue?: unknown[];
+    /** Type-tagged runtime fingerprint used to distinguish parsing precision changes from edits. */
+    runtimeValueSnapshot?: IKHRInteractivityInputDefaultProvenance;
+}
+/**
+ * Canonical source retained on a FlowGraph lowered from KHR_interactivity.
+ */
+export interface IKHRInteractivityGraphProvenance {
+    /** Source graph index. */
+    graphIndex: number;
+    /** Ratified specification revision used by the importer. */
+    specificationCommit: string;
+    /** Detached canonical source graph. */
+    source: IKHRInteractivity_Graph;
+    /** Explicit editor-authored variable defaults keyed by canonical variable index. */
+    authoredVariableValues?: Record<number, unknown[]>;
+    /** Explicit editor-authored FlowGraph variable types keyed by canonical variable index. */
+    authoredVariableTypes?: Record<number, string>;
+    /** True when variables were explicitly added, renamed, or deleted in the editor. */
+    authoredVariableStructureChanged?: boolean;
+}
+/**
+ * Canonical declaration information retained during import.
+ */
+export interface IKHRInteractivityDeclarationModel {
+    /** Declaration index in the source graph. */
+    index: number;
+    /** Full operation name, including the defining extension when present. */
+    operation: string;
+    /** Whether Babylon can execute the declaration. */
+    support: KHRInteractivityDeclarationSupport;
+    /** Exact source declaration. */
+    source: IKHRInteractivity_Declaration;
+}
+/**
+ * Canonical graph information retained during import.
+ */
+export interface IKHRInteractivityGraphModel {
+    /** Graph index in the root extension. */
+    index: number;
+    /** Stable source path. */
+    path: string;
+    /** Human-readable graph name. */
+    name: string;
+    /** Exact source graph, including extension and extras payloads. */
+    source: IKHRInteractivity_Graph;
+    /** Executable graph with specification defaults and fallbacks applied. */
+    effectiveSource: IKHRInteractivity_Graph;
+    /** Canonical declarations in source order. */
+    declarations: IKHRInteractivityDeclarationModel[];
+    /** Validation diagnostics for this graph. */
+    diagnostics: IKHRInteractivityDiagnostic[];
+    /** Whether this graph is valid and can be lowered to FlowGraph. */
+    valid: boolean;
+}
+/**
+ * Lossless canonical representation of a KHR_interactivity root extension.
+ */
+export interface IKHRInteractivityDocument {
+    /** Ratified specification revision used for validation. */
+    specificationCommit: string;
+    /** Exact source extension, including unknown extensions and extras. */
+    source: IKHRInteractivity;
+    /** Default graph index, or -1 when the source selection is invalid. */
+    defaultGraphIndex: number;
+    /** Canonical graph models in source order. */
+    graphs: IKHRInteractivityGraphModel[];
+    /** Root-level validation diagnostics. */
+    diagnostics: IKHRInteractivityDiagnostic[];
+}
+/**
+ * Creates a detached JSON copy of a KHR_interactivity graph.
+ * @param graph source graph
+ * @returns a lossless JSON copy
+ */
+export declare function CloneKHRInteractivityGraph(graph: IKHRInteractivity_Graph): IKHRInteractivity_Graph;
+/**
+ * Creates the executable graph view with all ratified configuration defaults and fallback rules
+ * applied without modifying the lossless source graph.
+ * @param graph source graph
+ * @param declarations canonical declarations
+ * @param assetNodeCount number of glTF nodes in the containing asset
+ * @returns normalized executable graph
+ */
+export declare function CreateEffectiveKHRInteractivityGraph(graph: IKHRInteractivity_Graph, declarations: readonly IKHRInteractivityDeclarationModel[], assetNodeCount?: number): IKHRInteractivity_Graph;
+/**
+ * Creates and validates a canonical copy of one KHR_interactivity graph.
+ * @param graph source graph
+ * @param index graph index in the root extension
+ * @param supportedExtensions enabled extensions that may provide executable operations
+ * @param assetNodeCount number of nodes in the containing glTF asset
+ * @returns the canonical graph model
+ */
+export declare function CreateKHRInteractivityGraphModel(graph: IKHRInteractivity_Graph | null | undefined, index?: number, supportedExtensions?: ReadonlySet<string>, assetNodeCount?: number): IKHRInteractivityGraphModel;
+/**
+ * Creates an immutable canonical KHR_interactivity document and validates all graph-local references.
+ * @param extension source extension object from the glTF document
+ * @param supportedExtensions enabled extensions that may provide executable operations
+ * @param assetNodeCount number of nodes in the containing glTF asset
+ * @returns the canonical document
+ */
+export declare function CreateKHRInteractivityDocument(extension: IKHRInteractivity, supportedExtensions?: ReadonlySet<string>, assetNodeCount?: number): IKHRInteractivityDocument;