@motion-core/motion-gpu/dist/core/material.d.ts

Framework-agnostic WebGPU runtime for fullscreen WGSL shaders with explicit Svelte, React, and Vue adapter entrypoints.

import type { MaterialSourceMetadata } from './error-diagnostics.js';
import { resolveUniformLayout } from './uniforms.js';
import { type MaterialLineMap } from './material-preprocess.js';
import type { StorageBufferDefinitionMap, TextureDefinitionMap, UniformMap } from './types.js';
/**
 * Typed compile-time define declaration.
 */
export type TypedMaterialDefineValue = {
    /**
     * WGSL scalar type.
     */
    type: 'bool';
    /**
     * Literal value for the selected WGSL type.
     */
    value: boolean;
} | {
    /**
     * WGSL scalar type.
     */
    type: 'f32' | 'i32' | 'u32';
    /**
     * Literal value for the selected WGSL type.
     */
    value: number;
};
/**
 * Allowed value types for WGSL `const` define injection.
 */
export type MaterialDefineValue = boolean | number | TypedMaterialDefineValue;
/**
 * Define map keyed by uniform-compatible identifier names.
 */
export type MaterialDefines<TKey extends string = string> = Record<TKey, MaterialDefineValue>;
/**
 * Include map keyed by include identifier used in `#include <name>` directives.
 */
export type MaterialIncludes<TKey extends string = string> = Record<TKey, string>;
/**
 * External material input accepted by {@link defineMaterial}.
 */
export interface FragMaterialInput<TUniformKey extends string = string, TTextureKey extends string = string, TDefineKey extends string = string, TIncludeKey extends string = string, TStorageBufferKey extends string = string> {
    /**
     * User WGSL source containing `frag(uv: vec2f) -> vec4f`.
     */
    fragment: string;
    /**
     * Initial uniform values.
     */
    uniforms?: UniformMap<TUniformKey>;
    /**
     * Texture definitions keyed by texture uniform name.
     */
    textures?: TextureDefinitionMap<TTextureKey>;
    /**
     * Optional compile-time define constants injected into WGSL.
     */
    defines?: MaterialDefines<TDefineKey>;
    /**
     * Optional WGSL include chunks used by `#include <name>` directives.
     */
    includes?: MaterialIncludes<TIncludeKey>;
    /**
     * Optional storage buffer definitions for compute shaders.
     */
    storageBuffers?: StorageBufferDefinitionMap<TStorageBufferKey>;
}
/**
 * Normalized and immutable material declaration consumed by `FragCanvas`.
 */
export interface FragMaterial<TUniformKey extends string = string, TTextureKey extends string = string, TDefineKey extends string = string, TIncludeKey extends string = string, TStorageBufferKey extends string = string> {
    /**
     * User WGSL source containing `frag(uv: vec2f) -> vec4f`.
     */
    readonly fragment: string;
    /**
     * Initial uniform values.
     */
    readonly uniforms: Readonly<UniformMap<TUniformKey>>;
    /**
     * Texture definitions keyed by texture uniform name.
     */
    readonly textures: Readonly<TextureDefinitionMap<TTextureKey>>;
    /**
     * Optional compile-time define constants injected into WGSL.
     */
    readonly defines: Readonly<MaterialDefines<TDefineKey>>;
    /**
     * Optional WGSL include chunks used by `#include <name>` directives.
     */
    readonly includes: Readonly<MaterialIncludes<TIncludeKey>>;
    /**
     * Storage buffer definitions for compute shaders. Empty when not provided.
     */
    readonly storageBuffers: Readonly<StorageBufferDefinitionMap<TStorageBufferKey>>;
}
/**
 * Fully resolved, immutable material snapshot used for renderer creation/caching.
 */
export interface ResolvedMaterial<TUniformKey extends string = string, TTextureKey extends string = string, TIncludeKey extends string = string, TStorageBufferKey extends string = string> {
    /**
     * Final fragment WGSL after define injection.
     */
    fragmentWgsl: string;
    /**
     * 1-based map from generated fragment lines to user source lines.
     */
    fragmentLineMap: MaterialLineMap;
    /**
     * Cloned uniforms.
     */
    uniforms: UniformMap<TUniformKey>;
    /**
     * Cloned texture definitions.
     */
    textures: TextureDefinitionMap<TTextureKey>;
    /**
     * Resolved packed uniform layout.
     */
    uniformLayout: ReturnType<typeof resolveUniformLayout>;
    /**
     * Sorted texture keys.
     */
    textureKeys: TTextureKey[];
    /**
     * Deterministic JSON signature for cache invalidation.
     */
    signature: string;
    /**
     * Original user fragment source before preprocessing.
     */
    fragmentSource: string;
    /**
     * Normalized include sources map.
     */
    includeSources: MaterialIncludes<TIncludeKey>;
    /**
     * Deterministic define block source used for diagnostics mapping.
     */
    defineBlockSource: string;
    /**
     * Source metadata used for diagnostics.
     */
    source: Readonly<MaterialSourceMetadata> | null;
    /**
     * Sorted storage buffer keys. Empty array when no storage buffers declared.
     */
    storageBufferKeys: TStorageBufferKey[];
    /**
     * Sorted storage texture keys (textures with storage: true).
     */
    storageTextureKeys: TTextureKey[];
}
/**
 * Creates a stable WGSL define block from the provided map.
 *
 * @param defines - Optional material defines.
 * @returns Joined WGSL const declarations ordered by key.
 */
export declare function buildDefinesBlock(defines: MaterialDefines | undefined): string;
/**
 * Prepends resolved defines to a fragment shader.
 *
 * @param fragment - Raw WGSL fragment source.
 * @param defines - Optional define map.
 * @returns Fragment source with a leading define block when defines are present.
 */
export declare function applyMaterialDefines(fragment: string, defines: MaterialDefines | undefined): string;
/**
 * Creates an immutable material object with validated shader/uniform/texture contracts.
 *
 * @param input - User material declaration.
 * @returns Frozen material object safe to share and cache.
 */
export declare function defineMaterial<TUniformKey extends string = string, TTextureKey extends string = string, TDefineKey extends string = string, TIncludeKey extends string = string, TStorageBufferKey extends string = string>(input: FragMaterialInput<TUniformKey, TTextureKey, TDefineKey, TIncludeKey, TStorageBufferKey>): FragMaterial<TUniformKey, TTextureKey, TDefineKey, TIncludeKey, TStorageBufferKey>;
/**
 * Resolves a material to renderer-ready data and a deterministic signature.
 *
 * @param material - Material input created via {@link defineMaterial}.
 * @returns Resolved material with packed uniform layout, sorted texture keys and cache signature.
 */
export declare function resolveMaterial<TUniformKey extends string = string, TTextureKey extends string = string, TDefineKey extends string = string, TIncludeKey extends string = string, TStorageBufferKey extends string = string>(material: FragMaterial<TUniformKey, TTextureKey, TDefineKey, TIncludeKey, TStorageBufferKey>): ResolvedMaterial<TUniformKey, TTextureKey, TIncludeKey, TStorageBufferKey>;
//# sourceMappingURL=material.d.ts.map