@stevejtrettel/shader-sandbox 0.1.0

package/src/engine/glHelpers.ts

@@ -0,0 +1,432 @@
+/**
+ * Engine Layer - WebGL Helper Functions
+ *
+ * Low-level WebGL utilities for shader compilation, texture creation,
+ * framebuffer management, and VAO setup.
+ *
+ * Based on docs/engine-spec.md
+ */
+
+// =============================================================================
+// Shader Compilation
+// =============================================================================
+
+/**
+ * Compile a shader of given type from source. Throws on error.
+ */
+export function createShader(
+  gl: WebGL2RenderingContext,
+  type: GLenum,
+  source: string
+): WebGLShader {
+  const shader = gl.createShader(type);
+  if (!shader) {
+    throw new Error('Failed to create shader object');
+  }
+
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+
+  const success = gl.getShaderParameter(shader, gl.COMPILE_STATUS);
+  if (!success) {
+    const infoLog = gl.getShaderInfoLog(shader);
+    gl.deleteShader(shader);
+    throw new Error(`Shader compilation failed:\n${infoLog}`);
+  }
+
+  return shader;
+}
+
+/**
+ * Link a program from vertex + fragment source strings.
+ * Throws with a descriptive error if link fails.
+ */
+export function createProgramFromSources(
+  gl: WebGL2RenderingContext,
+  vertexSource: string,
+  fragmentSource: string
+): WebGLProgram {
+  const vertexShader = createShader(gl, gl.VERTEX_SHADER, vertexSource);
+  const fragmentShader = createShader(gl, gl.FRAGMENT_SHADER, fragmentSource);
+
+  const program = gl.createProgram();
+  if (!program) {
+    throw new Error('Failed to create program object');
+  }
+
+  gl.attachShader(program, vertexShader);
+  gl.attachShader(program, fragmentShader);
+  gl.linkProgram(program);
+
+  const success = gl.getProgramParameter(program, gl.LINK_STATUS);
+  if (!success) {
+    const infoLog = gl.getProgramInfoLog(program);
+    gl.deleteProgram(program);
+    gl.deleteShader(vertexShader);
+    gl.deleteShader(fragmentShader);
+    throw new Error(`Program linking failed:\n${infoLog}`);
+  }
+
+  // Clean up shaders (no longer needed after linking)
+  gl.detachShader(program, vertexShader);
+  gl.detachShader(program, fragmentShader);
+  gl.deleteShader(vertexShader);
+  gl.deleteShader(fragmentShader);
+
+  return program;
+}
+
+// =============================================================================
+// Fullscreen Triangle VAO
+// =============================================================================
+
+/**
+ * Create a full-screen triangle VAO.
+ *
+ * Attribute layout:
+ *  - location 0: vec2 position in clip space.
+ *
+ * The triangle covers the entire screen using three vertices:
+ * (-1, -1), (3, -1), (-1, 3)
+ * This ensures all pixels are covered without needing two triangles.
+ */
+export function createFullscreenTriangleVAO(gl: WebGL2RenderingContext): WebGLVertexArrayObject {
+  const vao = gl.createVertexArray();
+  if (!vao) {
+    throw new Error('Failed to create VAO');
+  }
+
+  gl.bindVertexArray(vao);
+
+  // Create VBO with triangle vertices
+  const positions = new Float32Array([
+    -1, -1,  // Bottom-left
+     3, -1,  // Bottom-right (extends beyond viewport)
+    -1,  3,  // Top-left (extends beyond viewport)
+  ]);
+
+  const vbo = gl.createBuffer();
+  if (!vbo) {
+    throw new Error('Failed to create VBO');
+  }
+
+  gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
+  gl.bufferData(gl.ARRAY_BUFFER, positions, gl.STATIC_DRAW);
+
+  // Enable and configure vertex attribute at location 0
+  gl.enableVertexAttribArray(0);
+  gl.vertexAttribPointer(
+    0,        // attribute location
+    2,        // size (vec2)
+    gl.FLOAT, // type
+    false,    // normalized
+    0,        // stride
+    0         // offset
+  );
+
+  // Unbind
+  gl.bindVertexArray(null);
+  gl.bindBuffer(gl.ARRAY_BUFFER, null);
+
+  return vao;
+}
+
+// =============================================================================
+// Texture Creation
+// =============================================================================
+
+/**
+ * Create a float RGBA texture (no data) for use as a render target.
+ * This MUST use an internal format compatible with EXT_color_buffer_float.
+ *
+ * Per spec: ALL render targets MUST be RGBA32F.
+ */
+export function createRenderTargetTexture(
+  gl: WebGL2RenderingContext,
+  width: number,
+  height: number
+): WebGLTexture {
+  const tex = gl.createTexture();
+  if (!tex) {
+    throw new Error('Failed to create texture');
+  }
+
+  gl.bindTexture(gl.TEXTURE_2D, tex);
+
+  // Allocate RGBA32F texture (float format required by Shadertoy spec)
+  gl.texImage2D(
+    gl.TEXTURE_2D,
+    0,                // mip level
+    gl.RGBA32F,       // internal format (32-bit float per channel)
+    width,
+    height,
+    0,                // border (must be 0)
+    gl.RGBA,          // format
+    gl.FLOAT,         // type
+    null              // no data (allocate only)
+  );
+
+  // Set filtering to NEAREST (common for simulation/compute shaders)
+  // This prevents interpolation artifacts in PDE/physics shaders
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+
+  // Set wrap mode to CLAMP_TO_EDGE (prevent wrap-around at boundaries)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+
+  gl.bindTexture(gl.TEXTURE_2D, null);
+
+  return tex;
+}
+
+/**
+ * Create a framebuffer with a single color attachment at COLOR_ATTACHMENT0.
+ * Throws if framebuffer is not complete.
+ */
+export function createFramebufferWithColorAttachment(
+  gl: WebGL2RenderingContext,
+  texture: WebGLTexture
+): WebGLFramebuffer {
+  const fbo = gl.createFramebuffer();
+  if (!fbo) {
+    throw new Error('Failed to create framebuffer');
+  }
+
+  gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
+
+  // Attach texture to color attachment 0
+  gl.framebufferTexture2D(
+    gl.FRAMEBUFFER,
+    gl.COLOR_ATTACHMENT0,
+    gl.TEXTURE_2D,
+    texture,
+    0  // mip level
+  );
+
+  // Check framebuffer completeness
+  const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+  if (status !== gl.FRAMEBUFFER_COMPLETE) {
+    gl.deleteFramebuffer(fbo);
+    throw new Error(`Framebuffer incomplete: ${getFramebufferStatusString(gl, status)}`);
+  }
+
+  gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+
+  return fbo;
+}
+
+/**
+ * Create a 1x1 black float texture for unused channels.
+ *
+ * Per spec: UNUSED CHANNELS MUST STILL BIND A 1×1 BLACK FLOAT TEXTURE.
+ * This prevents NaN/undefined behavior when sampling unused channels.
+ */
+export function createBlackTexture(gl: WebGL2RenderingContext): WebGLTexture {
+  const tex = gl.createTexture();
+  if (!tex) {
+    throw new Error('Failed to create black texture');
+  }
+
+  gl.bindTexture(gl.TEXTURE_2D, tex);
+
+  // 1x1 black pixel [0, 0, 0, 1] as float
+  const blackPixel = new Float32Array([0, 0, 0, 1]);
+
+  gl.texImage2D(
+    gl.TEXTURE_2D,
+    0,
+    gl.RGBA32F,
+    1,
+    1,
+    0,
+    gl.RGBA,
+    gl.FLOAT,
+    blackPixel
+  );
+
+  // Set filtering
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+
+  // Set wrap mode
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+
+  gl.bindTexture(gl.TEXTURE_2D, null);
+
+  return tex;
+}
+
+/**
+ * Create a 256x3 keyboard state texture.
+ *
+ * Shadertoy keyboard texture format:
+ * - Width: 256 (one column per ASCII keycode)
+ * - Height: 3 (3 rows for different data)
+ * - Row 0 (sample at y=0.25): Current key state (0.0 = up, 1.0 = down)
+ * - Row 1: Unused
+ * - Row 2 (sample at y=0.75): Toggle state (flips between 0.0 and 1.0 on each press)
+ *
+ * Returns the WebGLTexture. Data is initialized to all zeros.
+ * Use updateKeyboardTexture() to update the state.
+ */
+export function createKeyboardTexture(gl: WebGL2RenderingContext): WebGLTexture {
+  const tex = gl.createTexture();
+  if (!tex) {
+    throw new Error('Failed to create keyboard texture');
+  }
+
+  gl.bindTexture(gl.TEXTURE_2D, tex);
+
+  // 256x3 texture, all zeros initially
+  const width = 256;
+  const height = 3;
+  const data = new Float32Array(width * height * 4); // RGBA, all zeros
+
+  gl.texImage2D(
+    gl.TEXTURE_2D,
+    0,
+    gl.RGBA32F,
+    width,
+    height,
+    0,
+    gl.RGBA,
+    gl.FLOAT,
+    data
+  );
+
+  // NEAREST filtering - no interpolation between keys!
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+
+  // CLAMP to edge
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+
+  gl.bindTexture(gl.TEXTURE_2D, null);
+
+  return tex;
+}
+
+/**
+ * Update keyboard texture with current key states.
+ *
+ * @param gl WebGL context
+ * @param texture The keyboard texture to update
+ * @param keyStates Map of keycode -> current state (true = down, false = up)
+ * @param toggleStates Map of keycode -> toggle state (0.0 or 1.0)
+ */
+export function updateKeyboardTexture(
+  gl: WebGL2RenderingContext,
+  texture: WebGLTexture,
+  keyStates: Map<number, boolean>,
+  toggleStates: Map<number, number>
+): void {
+  const width = 256;
+  const height = 3;
+  const data = new Float32Array(width * height * 4);
+
+  // Fill in key states
+  for (let keycode = 0; keycode < 256; keycode++) {
+    const isDown = keyStates.get(keycode) || false;
+    const toggleValue = toggleStates.get(keycode) || 0.0;
+
+    // Row 0 (y=0): Current key state
+    const row0Index = (0 * width + keycode) * 4;
+    data[row0Index + 0] = isDown ? 1.0 : 0.0; // R channel
+    data[row0Index + 1] = isDown ? 1.0 : 0.0; // G channel (redundant but matches Shadertoy)
+    data[row0Index + 2] = isDown ? 1.0 : 0.0; // B channel
+    data[row0Index + 3] = 1.0; // A channel
+
+    // Row 1 (y=1): Unused (keep as zeros)
+
+    // Row 2 (y=2): Toggle state
+    const row2Index = (2 * width + keycode) * 4;
+    data[row2Index + 0] = toggleValue;
+    data[row2Index + 1] = toggleValue;
+    data[row2Index + 2] = toggleValue;
+    data[row2Index + 3] = 1.0;
+  }
+
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  gl.texSubImage2D(
+    gl.TEXTURE_2D,
+    0,
+    0, 0, // x, y offset
+    width, height,
+    gl.RGBA,
+    gl.FLOAT,
+    data
+  );
+  gl.bindTexture(gl.TEXTURE_2D, null);
+}
+
+/**
+ * Create a 2D texture from an HTMLImageElement (or ImageBitmap).
+ * This is used for project textures (dog.png, noise.png, etc.)
+ *
+ * NOTE: actual image loading is done by the App; engine just gets an
+ * already-loaded image object.
+ */
+export function createTextureFromImage(
+  gl: WebGL2RenderingContext,
+  image: HTMLImageElement | ImageBitmap,
+  filter: 'nearest' | 'linear',
+  wrap: 'clamp' | 'repeat'
+): WebGLTexture {
+  const tex = gl.createTexture();
+  if (!tex) {
+    throw new Error('Failed to create texture');
+  }
+
+  gl.bindTexture(gl.TEXTURE_2D, tex);
+
+  // Upload image data
+  gl.texImage2D(
+    gl.TEXTURE_2D,
+    0,
+    gl.RGBA,
+    gl.RGBA,
+    gl.UNSIGNED_BYTE,
+    image
+  );
+
+  // Set filtering
+  const glFilter = filter === 'nearest' ? gl.NEAREST : gl.LINEAR;
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, glFilter);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, glFilter);
+
+  // Set wrap mode
+  const glWrap = wrap === 'clamp' ? gl.CLAMP_TO_EDGE : gl.REPEAT;
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, glWrap);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, glWrap);
+
+  gl.bindTexture(gl.TEXTURE_2D, null);
+
+  return tex;
+}
+
+// =============================================================================
+// Helper Utilities
+// =============================================================================
+
+/**
+ * Get a human-readable string for framebuffer status.
+ */
+function getFramebufferStatusString(gl: WebGL2RenderingContext, status: GLenum): string {
+  switch (status) {
+    case gl.FRAMEBUFFER_INCOMPLETE_ATTACHMENT:
+      return 'FRAMEBUFFER_INCOMPLETE_ATTACHMENT';
+    case gl.FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT:
+      return 'FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT';
+    case gl.FRAMEBUFFER_INCOMPLETE_DIMENSIONS:
+      return 'FRAMEBUFFER_INCOMPLETE_DIMENSIONS';
+    case gl.FRAMEBUFFER_UNSUPPORTED:
+      return 'FRAMEBUFFER_UNSUPPORTED';
+    case gl.FRAMEBUFFER_INCOMPLETE_MULTISAMPLE:
+      return 'FRAMEBUFFER_INCOMPLETE_MULTISAMPLE';
+    default:
+      return `Unknown status: ${status}`;
+  }
+}

package/src/engine/types.ts

@@ -0,0 +1,118 @@
+/**
+ * Engine Layer - Type Definitions
+ *
+ * Internal types used by ShadertoyEngine for managing WebGL resources.
+ * Based on docs/engine-spec.md
+ */
+
+import type {
+  ShadertoyProject,
+  PassName,
+  Channels,
+} from '../project/types';
+
+// =============================================================================
+// Engine Options
+// =============================================================================
+
+/**
+ * Options for constructing a ShadertoyEngine.
+ *
+ * The App is responsible for creating the WebGL2RenderingContext
+ * and passing it in.
+ */
+export interface EngineOptions {
+  gl: WebGL2RenderingContext;
+  project: ShadertoyProject;
+}
+
+// =============================================================================
+// Per-Pass Uniform Locations
+// =============================================================================
+
+/**
+ * Per-pass uniform locations and metadata.
+ *
+ * NOTE: This is separate from RuntimePass so that we can keep
+ * the GL program + locations together.
+ */
+export interface PassUniformLocations {
+  program: WebGLProgram;
+
+  // Core Shadertoy uniforms
+  iResolution: WebGLUniformLocation | null;
+  iTime: WebGLUniformLocation | null;
+  iTimeDelta: WebGLUniformLocation | null;
+  iFrame: WebGLUniformLocation | null;
+  iMouse: WebGLUniformLocation | null;
+
+  // iChannel0..3
+  iChannel: (WebGLUniformLocation | null)[];
+}
+
+// =============================================================================
+// Runtime Pass Representation
+// =============================================================================
+
+/**
+ * A runtime representation of a pass:
+ * - knows which project pass it corresponds to
+ * - owns two textures (current + previous) for ping-pong
+ * - owns a framebuffer and VAO for drawing
+ */
+export interface RuntimePass {
+  name: PassName;
+  projectChannels: Channels;
+
+  vao: WebGLVertexArrayObject;
+  uniforms: PassUniformLocations;
+
+  framebuffer: WebGLFramebuffer;
+
+  // Ping-pong textures:
+  // - current: where we write this frame
+  // - previous: where we read "previous" from when needed
+  currentTexture: WebGLTexture;
+  previousTexture: WebGLTexture;
+}
+
+// =============================================================================
+// Runtime Texture Representation
+// =============================================================================
+
+/**
+ * Runtime representation of an external 2D texture.
+ * This corresponds 1:1 to ShadertoyTexture2D from the project.
+ */
+export interface RuntimeTexture2D {
+  name: string; // e.g. "tex0" (same as project texture name)
+  texture: WebGLTexture;
+  width: number;
+  height: number;
+}
+
+/**
+ * Keyboard texture representation.
+ * For v1, you can leave this unimplemented or just stub it out.
+ */
+export interface RuntimeKeyboardTexture {
+  texture: WebGLTexture;
+  width: number;
+  height: number;
+}
+
+// =============================================================================
+// Engine Stats
+// =============================================================================
+
+/**
+ * Engine stats (for optional overlay / debugging).
+ */
+export interface EngineStats {
+  frame: number;         // iFrame
+  time: number;          // total time in seconds (iTime)
+  deltaTime: number;     // last frame delta in seconds (iTimeDelta)
+  width: number;
+  height: number;
+}
+

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Shadertoy Runner - Public API
+ *
+ * This module exports everything needed to create a shader playground.
+ */
+
+import './styles/base.css';
+
+export { App } from './app/App';
+export { createLayout } from './layouts';
+export { loadDemo } from './project/loaderHelper';
+export type { ShadertoyProject, ShadertoyConfig, PassName } from './project/types';
+export type { RecompileResult, BaseLayout, LayoutMode, LayoutOptions, RecompileHandler } from './layouts/types';

package/src/layouts/DefaultLayout.ts

@@ -0,0 +1,40 @@
+/**
+ * Default Layout
+ *
+ * Centered canvas with rounded corners and drop shadow.
+ * Default layout mode for a polished presentation.
+ */
+
+import './default.css';
+
+import { BaseLayout, LayoutOptions } from './types';
+
+export class DefaultLayout implements BaseLayout {
+  private container: HTMLElement;
+  private root: HTMLElement;
+  private canvasContainer: HTMLElement;
+
+  constructor(opts: LayoutOptions) {
+    this.container = opts.container;
+
+    // Create root layout container
+    this.root = document.createElement('div');
+    this.root.className = 'layout-default';
+
+    // Create canvas container
+    this.canvasContainer = document.createElement('div');
+    this.canvasContainer.className = 'canvas-container';
+
+    // Assemble and append to DOM
+    this.root.appendChild(this.canvasContainer);
+    this.container.appendChild(this.root);
+  }
+
+  getCanvasContainer(): HTMLElement {
+    return this.canvasContainer;
+  }
+
+  dispose(): void {
+    this.container.innerHTML = '';
+  }
+}

package/src/layouts/FullscreenLayout.ts

@@ -0,0 +1,40 @@
+/**
+ * Fullscreen Layout
+ *
+ * Canvas fills entire viewport, no padding or styling.
+ * Used for immersive shader experiences.
+ */
+
+import './fullscreen.css';
+
+import { BaseLayout, LayoutOptions } from './types';
+
+export class FullscreenLayout implements BaseLayout {
+  private container: HTMLElement;
+  private root: HTMLElement;
+  private canvasContainer: HTMLElement;
+
+  constructor(opts: LayoutOptions) {
+    this.container = opts.container;
+
+    // Create root layout container
+    this.root = document.createElement('div');
+    this.root.className = 'layout-fullscreen';
+
+    // Create canvas container
+    this.canvasContainer = document.createElement('div');
+    this.canvasContainer.className = 'canvas-container';
+
+    // Assemble and append to DOM
+    this.root.appendChild(this.canvasContainer);
+    this.container.appendChild(this.root);
+  }
+
+  getCanvasContainer(): HTMLElement {
+    return this.canvasContainer;
+  }
+
+  dispose(): void {
+    this.container.innerHTML = '';
+  }
+}