@rosalana/sandbox 0.1.0 → 0.2.1

package/dist/tools/compilable.d.ts

@@ -1,5 +1,6 @@
 import { ShaderFunction, ShaderUniform, WebGLVersion } from "../types";
 import Parser from "./parser";
+import type ModuleRegistry from "./module_registry";
 export default class Compilable {
     /** Flag to track if the shader has been compiled */
     protected isCompiled: boolean;
@@ -29,7 +30,7 @@ export default class Compilable {
     /**
      * Compile the shader source, resolving all imports
      */
-    compile(): string;
+    compile(runtimeModules?: ModuleRegistry): string;
     /**
      * Process all #import directives
      */

package/dist/tools/texture.d.ts

@@ -0,0 +1,64 @@
+import type { TextureOptions, TextureSource, WebGLContext } from "../types";
+/**
+ * Handles a single WebGL texture.
+ * Manages texture creation, pixel upload, binding, and location caching.
+ * Mirrors the Uniform class pattern for consistency.
+ */
+export default class Texture {
+    readonly name: string;
+    private gl;
+    private texture;
+    private location;
+    private locationResolved;
+    private source;
+    private options;
+    private dynamicOverride;
+    private needsUpload;
+    private needsReupload;
+    constructor(gl: WebGLContext, name: string, source: TextureSource, options?: TextureOptions);
+    /**
+     * Update the texture source.
+     * Marks texture for re-upload on next bind.
+     * Respects the original `dynamic` option if explicitly set, otherwise re-infers from source type.
+     */
+    setSource(source: TextureSource): void;
+    /**
+     * Resolve and cache uniform location from program.
+     * Returns null if the sampler uniform doesn't exist in the shader.
+     */
+    resolveLocation(gl: WebGLContext, program: WebGLProgram): WebGLUniformLocation | null;
+    /**
+     * Invalidate cached location (call when program changes).
+     */
+    invalidateLocation(): void;
+    /**
+     * Bind texture to a texture unit and set the sampler uniform.
+     * @param program - Current WebGL program (for location resolution)
+     * @param unit - Texture unit index (0, 1, 2, ...)
+     */
+    upload(program: WebGLProgram, unit: number): void;
+    /**
+     * Cleanup WebGL texture resource.
+     */
+    destroy(): void;
+    /**
+     * Upload pixel data from source and apply texture parameters.
+     */
+    private uploadPixels;
+    /**
+     * Apply texture wrap and filter parameters.
+     */
+    private applyParameters;
+    /**
+     * Resolve wrap mode string to WebGL constant.
+     */
+    private static resolveWrap;
+    /**
+     * Resolve texture options with defaults.
+     */
+    private static resolveOptions;
+    /**
+     * Check if a source is dynamic (needs re-upload every frame).
+     */
+    private static isDynamicSource;
+}

package/dist/tools/textures.d.ts

@@ -0,0 +1,48 @@
+import type { TextureOptions, TextureSource, WebGLContext } from "../types";
+import Texture from "./texture";
+/**
+ * Manages a collection of textures with fluent API.
+ * Assigns texture units sequentially and handles program attachment.
+ * Mirrors the Uniforms class pattern for consistency.
+ */
+export default class Textures {
+    private gl;
+    private program;
+    private textures;
+    constructor(gl: WebGLContext);
+    /**
+     * Attach to a WebGL program.
+     * Invalidates all cached locations since they're program-specific.
+     */
+    attachProgram(program: WebGLProgram): this;
+    /**
+     * Set a texture.
+     * Creates the texture entry if it doesn't exist, updates source if it does.
+     */
+    set(name: string, source: TextureSource, options?: TextureOptions): this;
+    /**
+     * Get a texture by name.
+     */
+    get(name: string): Texture | undefined;
+    /**
+     * Check if a texture exists.
+     */
+    has(name: string): boolean;
+    /**
+     * Remove a texture and free its GPU resources.
+     */
+    delete(name: string): boolean;
+    /**
+     * Upload all textures to their respective texture units.
+     * Units are assigned sequentially (0, 1, 2, ...).
+     */
+    uploadAll(): this;
+    /**
+     * Get texture count.
+     */
+    get size(): number;
+    /**
+     * Cleanup all textures.
+     */
+    destroy(): void;
+}

package/dist/tools/web_gl.d.ts

@@ -1,7 +1,8 @@
-import type { AnyUniformValue, ResolvedSandboxOptions, UniformSchema, WebGLContext, WebGLVersion } from "../types";
+import type { AnyUniformValue, ResolvedSandboxOptions, TextureOptions, TextureSchema, TextureSource, UniformSchema, WebGLContext, WebGLVersion } from "../types";
 import Clock from "./clock";
 import Hooks from "./hooks";
 import Shader from "./shader";
+import ModuleRegistry from "./module_registry";
 /**
  * Main WebGL orchestrator.
  * Manages context, program, geometry, uniforms, and rendering loop.
@@ -15,10 +16,12 @@ export default class WebGL {
     private _program;
     private _geometry;
     private _uniforms;
+    private _textures;
     private _clock;
     private _resolution;
     private _mouse;
     private _version;
+    private _runtimeModules;
     playing: boolean;
     private constructor();
     /**
@@ -59,6 +62,18 @@ export default class WebGL {
      * Get current uniform value.
      */
     getUniform<T extends AnyUniformValue>(name: string): T | undefined;
+    /**
+     * Set a texture.
+     */
+    texture(name: string, source: TextureSource, options?: TextureOptions): this;
+    /**
+     * Set multiple textures from a schema.
+     */
+    texturesFromSchema(schema: TextureSchema): this;
+    /**
+     * Remove a texture.
+     */
+    removeTexture(name: string): this;
     /**
      * Compile and link shaders.
      * Errors are handled via onError callback, never thrown.
@@ -80,6 +95,10 @@ export default class WebGL {
      * Get WebGL context.
      */
     getContext(): WebGLContext;
+    /**
+     * Get registered runtime modules.
+     */
+    getUsingModules(): ModuleRegistry;
     /**
      * Get detected WebGL version.
      */

package/dist/types.d.ts

@@ -30,6 +30,8 @@ export interface SandboxOptions {
     uniforms?: UniformSchema;
     /** Configure used modules behavior */
     modules?: Record<string, Record<string, AnyUniformValue>>;
+    /** Initial textures to bind */
+    textures?: TextureSchema;
 }
 /** Resolved sandbox options with all defaults applied */
 export type ResolvedSandboxOptions = Omit<Required<SandboxOptions>, "vertex" | "fragment"> & {
@@ -121,6 +123,37 @@ export interface UniformEntry {
 export type DrawMode = "TRIANGLES" | "TRIANGLE_STRIP" | "TRIANGLE_FAN";
 /** Render callback signature */
 export type HookCallback = (clock: ClockState) => void | false;
+/** Valid texture source types */
+export type TextureSource = HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | ImageBitmap | ImageData | OffscreenCanvas;
+/** Texture wrapping mode */
+export type TextureWrap = "clamp" | "repeat" | "mirror";
+/** Texture filter mode */
+export type TextureFilter = "nearest" | "linear";
+/** Per-texture configuration */
+export interface TextureOptions {
+    /** Wrapping mode for both axes (shorthand for wrapS + wrapT) */
+    wrap?: TextureWrap;
+    /** Wrapping mode for S (horizontal) axis */
+    wrapS?: TextureWrap;
+    /** Wrapping mode for T (vertical) axis */
+    wrapT?: TextureWrap;
+    /** Minification filter */
+    minFilter?: TextureFilter;
+    /** Magnification filter */
+    magFilter?: TextureFilter;
+    /** Flip texture vertically on upload (default: true) */
+    flipY?: boolean;
+    /** Re-upload pixels every frame for animated sources (default: true for video, false otherwise) */
+    dynamic?: boolean;
+}
+/** Resolved texture options with all defaults applied */
+export type ResolvedTextureOptions = Required<TextureOptions>;
+/** Schema for defining multiple textures at once */
+export interface TextureSchema {
+    [name: string]: TextureSource | ({
+        source: TextureSource;
+    } & TextureOptions);
+}
 /** GLSL uniform types */
 export type GLSLType = "float" | "int" | "bool" | "vec2" | "vec3" | "vec4" | "ivec2" | "ivec3" | "ivec4" | "bvec2" | "bvec3" | "bvec4" | "mat2" | "mat3" | "mat4" | "sampler2D" | "samplerCube";
 export type GLSLVariable = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rosalana/sandbox",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Lightweight WebGL wrapper for simple, beautiful shader effects",
   "keywords": [
     "webgl",