@rosalana/sandbox 0.0.5 → 0.2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { AnyUniformValue, HookCallback, SandboxOptions, UniformSchema, WebGLVersion } from "./types";
+import type { AnyUniformValue, HookCallback, ModuleDefinition, SandboxOptions, TextureOptions, TextureSchema, TextureSource, UniformSchema, WebGLVersion } from "./types";
 export * from "./types";
 export * from "./errors";
 /**
@@ -50,6 +50,34 @@ export declare class Sandbox {
      * });
      */
     static create(canvas: HTMLCanvasElement, options?: SandboxOptions): Sandbox;
+    /**
+     * Define a shader module that can be imported in shader source with `#import <function> from "module_name"`.
+     * @example
+     * Sandbox.defineModule("my_module", source, { options });
+     * // Then in shader:
+     * // #import myFunc from "my_module"
+     * // void main() {
+     * //   myFunc();
+     * // }
+     */
+    static defineModule(name: ModuleDefinition["name"], source: ModuleDefinition["source"], options?: ModuleDefinition["options"]): void;
+    /**
+     * Get the list of available shader modules that can be used with `#import` in shader source.
+     */
+    static availableModules(): {
+        name: string;
+        methods: string[];
+        uniforms: {
+            name: string;
+            type: import("./types").GLSLType;
+        }[];
+        options: Record<string, Record<string, import("./types").ModuleMethodOption>> | undefined;
+    }[];
+    /**
+     * Compile a shader source with Sandbox's shader preprocessor and return the final GLSL code.
+     * This is useful for debugging shader code or precompiling shaders for production use.
+     */
+    static compile(shaderSource: string): string;
     private resolveOptions;
     private setupListeners;
     private destroyListeners;
@@ -83,6 +111,28 @@ export declare class Sandbox {
      * Get current uniform value.
      */
     getUniform<T extends AnyUniformValue>(name: string): T | undefined;
+    /**
+     * Set a texture for a sampler2D uniform.
+     * @example
+     * sandbox.setTexture("u_texture", imageElement);
+     * sandbox.setTexture("u_texture", imageElement, { wrap: "repeat" });
+     */
+    setTexture(name: string, source: TextureSource, options?: TextureOptions): this;
+    /**
+     * Set multiple textures at once.
+     * @example
+     * sandbox.setTextures({
+     *   u_texture: imageElement,
+     *   u_detail: { source: detailImg, wrap: "repeat" },
+     * });
+     */
+    setTextures(textures: TextureSchema): this;
+    /**
+     * Remove a texture and free its GPU resources.
+     * @example
+     * sandbox.removeTexture("u_texture");
+     */
+    removeTexture(name: string): this;
     /**
      * Update shaders.
      * @example
@@ -95,6 +145,14 @@ export declare class Sandbox {
      * sandbox.setFragment(fragmentSource);
      */
     setFragment(fragment: string): this;
+    /**
+     * Get current fragment shader source.
+     */
+    getFragment(): string;
+    /**
+     * Get current vertex shader source.
+     */
+    getVertex(): string;
     /**
      * Set the max frame rate runtime
      *
@@ -107,6 +165,12 @@ export declare class Sandbox {
      * Add a runtime render hook.
      */
     hook(callback: HookCallback, when?: "before" | "after"): () => void;
+    /**
+     * Runtime configure the module behavior
+     * @example
+     * sandbox.module("my_module", { intensity: 0.5 });
+     */
+    module<T extends Record<string, AnyUniformValue>>(name: string, config: T): this;
     /**
      * Start animation loop.
      */
@@ -155,6 +219,40 @@ export declare class Sandbox {
      * Get canvas element.
      */
     get canvas(): HTMLCanvasElement;
+    /**
+     * Export current frame as a data URL string.
+     * Requires `preserveDrawingBuffer: true` if called while playing.
+     * @example
+     * const url = sandbox.renderAt(1.5).exportAsURL("image/png");
+     */
+    exportAsURL(type?: "image/png" | "image/jpeg", quality?: number): string;
+    /**
+     * Export current frame as a Blob.
+     * Requires `preserveDrawingBuffer: true` if called while playing.
+     * @example
+     * const blob = await sandbox.renderAt(1.5).exportAsBlob("image/png");
+     */
+    exportAsBlob(type?: "image/png" | "image/jpeg", quality?: number): Promise<Blob>;
+    /**
+     * Export current frame as an HTMLImageElement.
+     * Requires `preserveDrawingBuffer: true` if called while playing.
+     * @example
+     * const img = sandbox.renderAt(1.5).exportAsImage("image/png");
+     * img.onload = () => document.body.appendChild(img);
+     */
+    exportAsImage(type?: "image/png" | "image/jpeg", quality?: number): HTMLImageElement;
+    /**
+     * Capture the canvas as a MediaStream for video calls or recording.
+     * @example
+     * // WebRTC video call
+     * const stream = sandbox.stream(30);
+     * peerConnection.addTrack(stream.getVideoTracks()[0], stream);
+     *
+     * @example
+     * // Record to video file
+     * const recorder = new MediaRecorder(sandbox.stream(30));
+     */
+    stream(fps?: number): MediaStream;
     /**
      * Destroy sandbox and release all resources.
      * @example