@xifu/shader-graph-glsl 0.1.0

package/dist/runtime/index.d.ts

@@ -0,0 +1,403 @@
+import { S as ShaderConfig, b as UniformValues } from '../ShaderConfig-RGrO5cST.js';
+export { P as ParameterConfig, c as ShaderCompileOptions, d as SubGraphConfig, T as TextureBinding, e as UniformDataType, U as UniformMeta, a as UniformValue } from '../ShaderConfig-RGrO5cST.js';
+
+/**
+ * RuntimeProgram — 着色器程序编译与管理 (无 Three.js 依赖)
+ */
+
+/** 编译后的着色器程序 */
+interface RuntimeProgram {
+    /** WebGL 程序 */
+    program: WebGLProgram;
+    /** uniform location 缓存 */
+    uniforms: Record<string, WebGLUniformLocation | null>;
+    /** attribute location 缓存 */
+    attribs: Record<string, number>;
+    /** 关联的 ShaderConfig */
+    config: ShaderConfig;
+    /** 纹理单元追踪 */
+    textureUnitMap: Record<string, number>;
+}
+
+/**
+ * RuntimeRenderer — 独立运行时引擎主类
+ *
+ * 无 Three.js 依赖，通过 ShaderConfig 完成渲染。
+ * 提供对编辑器/预览场景适配的 Three.js 粘合层。
+ */
+
+interface VertexAttribute$1 {
+    data: Float32Array;
+    size: number;
+    normalized?: boolean;
+    stride?: number;
+    offset?: number;
+}
+interface RuntimeGeometry {
+    attributes: Record<string, VertexAttribute$1>;
+    index?: Uint16Array | Uint32Array;
+    vertexCount: number;
+}
+interface RuntimeMesh {
+    geometry: RuntimeGeometry;
+    program: RuntimeProgram;
+    uniforms: UniformValues;
+    mode?: number;
+}
+declare class RuntimeRenderer {
+    gl: WebGL2RenderingContext;
+    private programs;
+    private currentProgram;
+    private defaultVAO;
+    private textureUnitCounter;
+    private textureCache;
+    private canvas;
+    clearColor: [number, number, number, number];
+    viewport: [number, number, number, number];
+    scissor: [number, number, number, number];
+    constructor(canvas: HTMLCanvasElement, options?: WebGLContextAttributes);
+    /** 从 ShaderConfig 加载程序 */
+    loadProgram(config: ShaderConfig, key?: string): RuntimeProgram;
+    /** 获取已缓存的程序 */
+    getProgram(key: string): RuntimeProgram | undefined;
+    /** 加载纹理 (支持 URL 或 HTMLImageElement) */
+    loadTexture(url: string): Promise<WebGLTexture>;
+    /** 绑定纹理到 uniform */
+    bindTexture(uniformName: string, texture: WebGLTexture, unit: number): void;
+    /** 创建几何体 VAO */
+    createGeometry(geo: RuntimeGeometry): WebGLVertexArrayObject;
+    /** 清屏 */
+    clear(): void;
+    /** 渲染单次绘制调用 */
+    drawMesh(mesh: RuntimeMesh): void;
+    /** 调整大小 */
+    resize(width: number, height: number): void;
+    /** 销毁 */
+    dispose(): void;
+}
+
+/**
+ * @xifu/shader-graph-glsl/runtime — 公共类型定义
+ */
+
+/** 顶点属性 */
+interface VertexAttribute {
+    /** 顶点数据 */
+    data: Float32Array;
+    /** 每分量元素数 (1=float, 2=vec2, 3=vec3, 4=vec4) */
+    size: number;
+    /** 是否归一化 */
+    normalized?: boolean;
+    /** 步长 */
+    stride?: number;
+    /** 偏移 */
+    offset?: number;
+}
+/** 几何体描述 */
+interface GeometryDescriptor {
+    /** 顶点属性集合 */
+    attributes: Record<string, VertexAttribute>;
+    /** 索引缓冲区 (可选) */
+    index?: Uint16Array | Uint32Array;
+    /** 顶点数 */
+    vertexCount: number;
+}
+/** 渲染状态 */
+interface RenderState {
+    /** 清除颜色 */
+    clearColor?: [number, number, number, number];
+    /** 是否启用深度测试 */
+    depthTest?: boolean;
+    /** 深度测试函数 */
+    depthFunc?: 'never' | 'less' | 'equal' | 'lequal' | 'greater' | 'notequal' | 'gequal' | 'always';
+    /** 是否启用混合 */
+    blend?: boolean;
+    /** 混合源因子 */
+    blendSrc?: number;
+    /** 混合目标因子 */
+    blendDst?: number;
+    /** 视口 */
+    viewport?: [number, number, number, number];
+}
+/** 网格渲染描述 */
+interface MeshDescriptor {
+    /** 几何体 */
+    geometry: GeometryDescriptor;
+    /** 着色器程序句柄 */
+    program: RuntimeProgram;
+    /** uniform 值 */
+    uniforms: UniformValues;
+    /** 绘制模式 (gl.TRIANGLES / gl.LINES 等，默认 gl.TRIANGLES) */
+    mode?: number;
+    /** 渲染状态覆盖 */
+    renderState?: RenderState;
+}
+
+/**
+ * ShaderGraphRuntime — 独立 WebGL2 着色器运行时引擎
+ *
+ * # 概述
+ *
+ * 纯 WebGL2 运行时，无任何第三方框架依赖。
+ * 可直接加载由 ShaderGraphEditor 编译产出的 ShaderConfig 并渲染。
+ *
+ * 子图支持:
+ * 子图在编译时已内联到主图的 vertCode/fragCode 中，运行时通过
+ * `linkSubGraph()` 或 `loadWithSubGraphs()` 将子图的 uniform 元数据
+ * 关联到主程序，使运行时能正确管理所有 uniform。
+ *
+ * # 快速开始
+ *
+ * ```ts
+ * import { ShaderGraphRuntime } from '@xifu/shader-graph-glsl/runtime';
+ *
+ * const canvas = document.getElementById('canvas') as HTMLCanvasElement;
+ * const runtime = new ShaderGraphRuntime(canvas);
+ *
+ * // 加载主图 + 关联子图
+ * const program = runtime.loadWithSubGraphs(mainConfig, {
+ *   'mySub': subConfig
+ * });
+ *
+ * // 或分步: 先加载主图, 再关联子图
+ * // const program = runtime.load(mainConfig);
+ * // runtime.linkSubGraph(program, 'mySub', subConfig);
+ *
+ * // 设置 uniform
+ * runtime.uniforms(program).set('uColor', [1, 0, 0, 1]);
+ *
+ * // 每帧渲染
+ * runtime.play((time) => {
+ *   runtime.uniforms(program).set('uTime', time);
+ *   runtime.draw({ geometry, program, uniforms: {} });
+ * });
+ * ```
+ *
+ * # 与 Three.js 集成
+ *
+ * ```ts
+ * // ShaderConfig.vertCode / fragCode 可直接用于 RawShaderMaterial
+ * const material = new THREE.RawShaderMaterial({
+ *   vertexShader: config.vertCode,
+ *   fragmentShader: config.fragCode,
+ *   uniforms: { uTime: { value: 0 } },
+ * });
+ * ```
+ *
+ * @module
+ */
+
+/** 运行时选项 */
+interface RuntimeOptions {
+    /** WebGL context 属性 */
+    contextAttributes?: WebGLContextAttributes;
+    /** 默认清除颜色 (默认 [0,0,0,0]) */
+    clearColor?: [number, number, number, number];
+}
+/** 动画帧回调 */
+type FrameCallback = (time: number, delta: number) => void;
+/** 程序句柄 */
+type ProgramHandle = RuntimeProgram;
+/** Uniform 绑定器 — 链式调用 */
+interface UniformBinder {
+    set(name: string, value: number | number[]): UniformBinder;
+    setMany(values: UniformValues): UniformBinder;
+    texture(name: string, source: TexImageSource, unit?: number): UniformBinder;
+    commit(): void;
+}
+/**
+ * ShaderGraphRuntime 主类
+ *
+ * ## 特性
+ * - 无第三方依赖，纯 WebGL2
+ * - 支持 ShaderConfig 直接加载
+ * - 内置动画循环
+ * - 纹理管理
+ * - 渲染状态控制
+ */
+declare class ShaderGraphRuntime {
+    /** 底层渲染器 */
+    readonly renderer: RuntimeRenderer;
+    /** WebGL 上下文 */
+    readonly gl: WebGL2RenderingContext;
+    /** 画布 */
+    readonly canvas: HTMLCanvasElement;
+    /** 子图关联表: programKey → { subGraphId → ShaderConfig } */
+    private subGraphLinks;
+    private animFrameId;
+    private lastTime;
+    private frameCallback;
+    private _isPlaying;
+    /**
+     * 构造运行时
+     *
+     * @param canvas  - HTMLCanvasElement
+     * @param options - 运行时选项
+     */
+    constructor(canvas: HTMLCanvasElement, options?: RuntimeOptions);
+    /**
+     * 加载着色器配置
+     *
+     * @param config - 由编辑器编译产出的 ShaderConfig
+     * @param key    - 缓存键 (默认使用 config.id)
+     * @returns 程序句柄
+     *
+     * @example
+     * ```ts
+     * const program = runtime.load(shaderConfig);
+     * ```
+     */
+    load(config: ShaderConfig, key?: string): ProgramHandle;
+    /**
+     * 获取已缓存的程序
+     *
+     * @param key - 缓存键
+     */
+    get(key: string): ProgramHandle | undefined;
+    /**
+     * 卸载着色器程序
+     *
+     * @param handle - 程序句柄
+     */
+    unload(handle: ProgramHandle): void;
+    /**
+     * 关联子图配置到主程序
+     *
+     * 子图在编译时已内联到主图的 vertCode/fragCode 中。
+     * 此方法将子图的 uniform 元数据注册到主程序，使运行时
+     * 能正确管理所有由子图引入的 uniform 变量。
+     *
+     * @param program    - 主程序句柄 (由 load() 返回)
+     * @param subGraphId - 子图 ID (与主图 SubGraph 节点的 asset.id 对应)
+     * @param config     - 子图的 ShaderConfig
+     *
+     * @example
+     * ```ts
+     * const mainProg = runtime.load(mainConfig);
+     * runtime.linkSubGraph(mainProg, 'flowMap', flowMapSubConfig);
+     * ```
+     */
+    linkSubGraph(program: ProgramHandle, subGraphId: string, config: ShaderConfig): void;
+    /**
+     * 批量关联子图
+     *
+     * @param program   - 主程序句柄
+     * @param subGraphs - { [subGraphId]: ShaderConfig }
+     */
+    linkSubGraphs(program: ProgramHandle, subGraphs: Record<string, ShaderConfig>): void;
+    /**
+     * 加载主图并同时关联其子图
+     *
+     * 等价于依次调用 load() + linkSubGraphs()。
+     *
+     * @param config     - 主图 ShaderConfig
+     * @param subGraphs  - 子图配置表 { subGraphId: ShaderConfig }
+     * @param key        - 缓存键 (可选)
+     * @returns 主程序句柄
+     *
+     * @example
+     * ```ts
+     * const program = runtime.loadWithSubGraphs(mainConfig, {
+     *   'flowMap': flowMapSubConfig,
+     *   'noise': noiseSubConfig,
+     * });
+     * ```
+     */
+    loadWithSubGraphs(config: ShaderConfig, subGraphs: Record<string, ShaderConfig>, key?: string): ProgramHandle;
+    /**
+     * 获取程序关联的子图列表
+     *
+     * @param program - 程序句柄
+     * @returns 子图 ID 列表
+     */
+    getLinkedSubGraphs(program: ProgramHandle): string[];
+    /**
+     * 获取程序关联的子图配置
+     *
+     * @param program    - 程序句柄
+     * @param subGraphId - 子图 ID
+     * @returns ShaderConfig 或 undefined
+     */
+    getSubGraphConfig(program: ProgramHandle, subGraphId: string): ShaderConfig | undefined;
+    /**
+     * 获取 Uniform 绑定器
+     *
+     * 提供链式 API 方便批量设置 uniform。
+     *
+     * @param handle - 程序句柄
+     * @returns UniformBinder
+     *
+     * @example
+     * ```ts
+     * runtime.uniforms(program)
+     *   .set('uColor', [1, 0, 0, 1])
+     *   .set('uTime', 0.5)
+     *   .texture('uMainTex', img)
+     *   .commit();
+     * ```
+     */
+    uniforms(handle: ProgramHandle): UniformBinder;
+    /**
+     * 清除缓冲区
+     *
+     * 先应用设置的清除颜色，再清除缓冲区。
+     *
+     * @param mask - 清除掩码 (默认 gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT)
+     */
+    clear(mask?: number): void;
+    /**
+     * 设置清除颜色
+     */
+    setClearColor(r: number, g: number, b: number, a: number): void;
+    /**
+     * 绘制网格
+     *
+     * @param mesh - 网格渲染描述
+     *
+     * @example
+     * ```ts
+     * runtime.draw({
+     *   geometry: { attributes: { aPosition: { data, size: 3 } }, vertexCount: 3 },
+     *   program: myProgram,
+     *   uniforms: { uColor: [1, 0, 0, 1] },
+     * });
+     * ```
+     */
+    draw(mesh: MeshDescriptor): void;
+    /**
+     * 开始动画循环
+     *
+     * @param callback - 每帧回调 (time, delta)
+     *
+     * @example
+     * ```ts
+     * runtime.play((time, delta) => {
+     *   runtime.uniforms(program).set('uTime', time).commit();
+     *   runtime.draw(mesh);
+     * });
+     * ```
+     */
+    play(callback?: FrameCallback): void;
+    /** 是否正在播放动画 */
+    get isPlaying(): boolean;
+    /**
+     * 停止动画循环
+     */
+    stop(): void;
+    /**
+     * 调整画布尺寸 (自动同步 viewport)
+     *
+     * @param width  - 像素宽度
+     * @param height - 像素高度
+     */
+    resize(width: number, height: number): void;
+    /**
+     * 释放所有资源
+     *
+     * 清理着色器程序、纹理、停止动画。
+     * 调用后不可再使用此实例。
+     */
+    dispose(): void;
+}
+
+export { type FrameCallback, type GeometryDescriptor, type MeshDescriptor, type ProgramHandle, type RenderState, type RuntimeOptions, ShaderConfig, ShaderGraphRuntime, type UniformBinder, UniformValues, type VertexAttribute };