pixospritz-core 0.10.1 → 1.0.1

package/src/engine/shaders/pxsl/manager.js

@@ -0,0 +1,338 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ *                    PXSL Shader Manager
+ * ═══════════════════════════════════════════════════════════════════════════
+ * Copyright (c) 2020-2025 Kyle Derby MacInnis
+ *
+ * Unified shader management system that supports:
+ *   - PXSL (.pxsl) - PixoSpritz Shader Language
+ *   - GLSL (.glsl, .vert, .frag) - Standard WebGL shaders
+ *   - JavaScript shader functions (legacy support)
+ *
+ * Features:
+ *   - Automatic format detection
+ *   - Shader caching
+ *   - Hot-reload support
+ *   - Error handling with helpful messages
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
+import { PXSLTranspiler } from './transpiler.js';
+
+/**
+ * Shader cache entry
+ * @typedef {Object} CachedShader
+ * @property {string} name - Shader name
+ * @property {string} vs - Vertex shader source
+ * @property {string} fs - Fragment shader source
+ * @property {WebGLProgram} [program] - Compiled program (if compiled)
+ * @property {number} timestamp - Cache timestamp
+ */
+
+/**
+ * Shader Manager - Handles loading, caching, and compiling shaders
+ */
+export class ShaderManager {
+  /**
+   * @param {WebGL2RenderingContext} gl - WebGL context
+   */
+  constructor(gl) {
+    /** @type {WebGL2RenderingContext} */
+    this.gl = gl;
+    
+    /** @type {Map<string, CachedShader>} */
+    this.cache = new Map();
+    
+    /** @type {Map<string, WebGLProgram>} */
+    this.programs = new Map();
+    
+    /** @type {boolean} */
+    this.debug = process.env.NODE_ENV === 'development';
+  }
+
+  /**
+   * Load shader from source code (auto-detects format)
+   * @param {string} name - Shader identifier
+   * @param {string|{vs: string, fs: string}} source - Shader source(s)
+   * @returns {CachedShader}
+   */
+  load(name, source) {
+    // Check cache first
+    if (this.cache.has(name)) {
+      return this.cache.get(name);
+    }
+
+    let shader;
+
+    if (typeof source === 'string') {
+      // Single source - could be PXSL (combined) or needs separate files
+      if (PXSLTranspiler.isPXSL(source)) {
+        // PXSL format - transpile
+        shader = this.loadPXSL(name, source);
+      } else {
+        throw new Error(`ShaderManager: Single source must be PXSL format. Use {vs, fs} for separate GLSL.`);
+      }
+    } else if (source.vs && source.fs) {
+      // Separate vertex and fragment shaders
+      shader = this.loadGLSL(name, source.vs, source.fs);
+    } else {
+      throw new Error(`ShaderManager: Invalid source format for shader "${name}"`);
+    }
+
+    this.cache.set(name, shader);
+    return shader;
+  }
+
+  /**
+   * Load and transpile PXSL shader
+   * @param {string} name - Shader name
+   * @param {string} source - PXSL source code
+   * @returns {CachedShader}
+   */
+  loadPXSL(name, source) {
+    try {
+      const result = PXSLTranspiler.transpile(source);
+      
+      if (this.debug) {
+        console.log(`[ShaderManager] Transpiled PXSL shader "${result.name || name}"`);
+      }
+
+      return {
+        name: result.name || name,
+        vs: result.vs,
+        fs: result.fs,
+        timestamp: Date.now(),
+        format: 'pxsl',
+      };
+    } catch (error) {
+      throw new Error(`PXSL Transpilation Error in "${name}": ${error.message}`);
+    }
+  }
+
+  /**
+   * Load GLSL shaders directly
+   * @param {string} name - Shader name
+   * @param {string} vs - Vertex shader source
+   * @param {string} fs - Fragment shader source
+   * @returns {CachedShader}
+   */
+  loadGLSL(name, vs, fs) {
+    return {
+      name,
+      vs,
+      fs,
+      timestamp: Date.now(),
+      format: 'glsl',
+    };
+  }
+
+  /**
+   * Compile a cached shader into a WebGL program
+   * @param {string} name - Shader name
+   * @returns {WebGLProgram}
+   */
+  compile(name) {
+    // Check if already compiled
+    if (this.programs.has(name)) {
+      return this.programs.get(name);
+    }
+
+    const shader = this.cache.get(name);
+    if (!shader) {
+      throw new Error(`ShaderManager: Shader "${name}" not loaded`);
+    }
+
+    const program = this.createProgram(shader.vs, shader.fs, name);
+    this.programs.set(name, program);
+    
+    return program;
+  }
+
+  /**
+   * Load and compile shader in one step
+   * @param {string} name - Shader name
+   * @param {string|{vs: string, fs: string}} source - Shader source
+   * @returns {WebGLProgram}
+   */
+  loadAndCompile(name, source) {
+    this.load(name, source);
+    return this.compile(name);
+  }
+
+  /**
+   * Create a WebGL shader program from source
+   * @param {string} vsSource - Vertex shader source
+   * @param {string} fsSource - Fragment shader source
+   * @param {string} name - Shader name (for error messages)
+   * @returns {WebGLProgram}
+   */
+  createProgram(vsSource, fsSource, name = 'unnamed') {
+    const { gl } = this;
+
+    // Compile vertex shader
+    const vertexShader = this.compileShader(gl.VERTEX_SHADER, vsSource, `${name}.vert`);
+    
+    // Compile fragment shader
+    const fragmentShader = this.compileShader(gl.FRAGMENT_SHADER, fsSource, `${name}.frag`);
+
+    // Create program
+    const program = gl.createProgram();
+    gl.attachShader(program, vertexShader);
+    gl.attachShader(program, fragmentShader);
+    gl.linkProgram(program);
+
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+      const log = gl.getProgramInfoLog(program);
+      gl.deleteProgram(program);
+      throw new Error(`Shader link error in "${name}": ${log}`);
+    }
+
+    // Clean up individual shaders (they're now part of the program)
+    gl.deleteShader(vertexShader);
+    gl.deleteShader(fragmentShader);
+
+    // Auto-detect and store attribute/uniform locations
+    this.introspectProgram(program);
+
+    return program;
+  }
+
+  /**
+   * Compile a single shader
+   * @param {number} type - gl.VERTEX_SHADER or gl.FRAGMENT_SHADER
+   * @param {string} source - Shader source code
+   * @param {string} name - Shader name for errors
+   * @returns {WebGLShader}
+   */
+  compileShader(type, source, name) {
+    const { gl } = this;
+    const shader = gl.createShader(type);
+    
+    gl.shaderSource(shader, source);
+    gl.compileShader(shader);
+
+    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+      const log = gl.getShaderInfoLog(shader);
+      gl.deleteShader(shader);
+      
+      // Add line numbers to source for debugging
+      const numberedSource = source.split('\n')
+        .map((line, i) => `${(i + 1).toString().padStart(3)}: ${line}`)
+        .join('\n');
+      
+      throw new Error(
+        `Shader compile error in "${name}":\n${log}\n\nSource:\n${numberedSource}`
+      );
+    }
+
+    return shader;
+  }
+
+  /**
+   * Introspect a program to find all attributes and uniforms
+   * @param {WebGLProgram} program - The compiled program
+   */
+  introspectProgram(program) {
+    const { gl } = this;
+
+    // Get active attributes
+    const numAttribs = gl.getProgramParameter(program, gl.ACTIVE_ATTRIBUTES);
+    program._attributes = {};
+    
+    for (let i = 0; i < numAttribs; i++) {
+      const info = gl.getActiveAttrib(program, i);
+      const location = gl.getAttribLocation(program, info.name);
+      program._attributes[info.name] = { location, type: info.type, size: info.size };
+      program[info.name] = location;
+    }
+
+    // Get active uniforms
+    const numUniforms = gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS);
+    program._uniforms = {};
+    
+    for (let i = 0; i < numUniforms; i++) {
+      const info = gl.getActiveUniform(program, i);
+      // Handle array uniforms (name ends with [0])
+      const baseName = info.name.replace(/\[0\]$/, '');
+      const location = gl.getUniformLocation(program, info.name);
+      program._uniforms[baseName] = { location, type: info.type, size: info.size };
+      program[baseName] = location;
+    }
+  }
+
+  /**
+   * Get a compiled program by name
+   * @param {string} name - Shader name
+   * @returns {WebGLProgram|null}
+   */
+  get(name) {
+    return this.programs.get(name) || null;
+  }
+
+  /**
+   * Use a shader program
+   * @param {string|WebGLProgram} nameOrProgram - Shader name or program
+   */
+  use(nameOrProgram) {
+    const program = typeof nameOrProgram === 'string' 
+      ? this.programs.get(nameOrProgram)
+      : nameOrProgram;
+    
+    if (program) {
+      this.gl.useProgram(program);
+    }
+  }
+
+  /**
+   * Reload a shader (for hot-reload support)
+   * @param {string} name - Shader name
+   * @param {string|{vs: string, fs: string}} source - New source
+   * @returns {WebGLProgram}
+   */
+  reload(name, source) {
+    // Delete old program
+    const oldProgram = this.programs.get(name);
+    if (oldProgram) {
+      this.gl.deleteProgram(oldProgram);
+      this.programs.delete(name);
+    }
+
+    // Remove from cache
+    this.cache.delete(name);
+
+    // Load and compile new version
+    return this.loadAndCompile(name, source);
+  }
+
+  /**
+   * Clear all cached shaders and programs
+   */
+  clear() {
+    // Delete all programs
+    for (const program of this.programs.values()) {
+      this.gl.deleteProgram(program);
+    }
+    
+    this.programs.clear();
+    this.cache.clear();
+  }
+
+  /**
+   * Get shader source (for debugging/editing)
+   * @param {string} name - Shader name
+   * @returns {CachedShader|null}
+   */
+  getSource(name) {
+    return this.cache.get(name) || null;
+  }
+
+  /**
+   * List all loaded shaders
+   * @returns {string[]}
+   */
+  list() {
+    return Array.from(this.cache.keys());
+  }
+}
+
+export default ShaderManager;

package/src/engine/shaders/pxsl/specification.js

@@ -0,0 +1,363 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ *                    PXSL - PixoSpritz Shader Language
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * A user-friendly domain-specific language for WebGL shaders.
+ * PXSL transpiles to standard GLSL while providing:
+ *   - Simplified syntax
+ *   - Built-in common operations
+ *   - Automatic uniform/varying management
+ *   - Human-readable effect names
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ *                            LANGUAGE SPECIFICATION
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * FILE EXTENSION: .pxsl
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * SHADER DECLARATION
+ * ───────────────────────────────────────────────────────────────────────────
+ *
+ *   @vertex                          // Marks start of vertex shader
+ *   @fragment                        // Marks start of fragment shader
+ *   @shader "name"                   // Combined shader with name
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * VARIABLE DECLARATIONS
+ * ───────────────────────────────────────────────────────────────────────────
+ *
+ *   input position: vec3             // Vertex attribute (in vertex shader)
+ *   input normal: vec3               // Automatically creates aVertexNormal
+ *   input uv: vec2                   // Texture coordinates
+ *
+ *   uniform modelMatrix: mat4        // Uniform from JavaScript
+ *   uniform time: float              // Animation time
+ *   uniform color: vec3              // Material color
+ *
+ *   output fragColor: vec4           // Fragment output
+ *   output worldPos: vec3            // Passed to fragment shader (varying)
+ *
+ *   const PI = 3.14159               // Constants
+ *   let temp: vec3                   // Local variable
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * BUILT-IN FUNCTIONS (Simplified Names)
+ * ───────────────────────────────────────────────────────────────────────────
+ *
+ *   // Lighting
+ *   diffuse(normal, lightDir)                    -> dot(normal, lightDir)
+ *   specular(normal, lightDir, viewDir, power)   -> Blinn-Phong specular
+ *   fresnel(normal, viewDir, power)              -> Fresnel effect
+ *   
+ *   // Color Operations
+ *   brighten(color, amount)                      -> color * (1 + amount)
+ *   darken(color, amount)                        -> color * (1 - amount)
+ *   saturate(color, amount)                      -> Adjust saturation
+ *   contrast(color, amount)                      -> Adjust contrast
+ *   tint(color, tintColor, amount)               -> Mix with tint
+ *
+ *   // Effects
+ *   fog(color, depth, fogColor, density)         -> Apply fog
+ *   glow(color, intensity)                       -> Add bloom/glow
+ *   outline(uv, texture, color, width)           -> Edge detection
+ *   pixelate(uv, resolution)                     -> Pixelation effect
+ *
+ *   // Math Helpers
+ *   remap(value, inMin, inMax, outMin, outMax)   -> Remap range
+ *   smoothstep(edge0, edge1, x)                  -> Smooth interpolation
+ *   pulse(value, frequency)                      -> sin-based pulse
+ *   noise(uv)                                    -> Simple noise
+ *   fbm(uv, octaves)                             -> Fractal Brownian Motion
+ *
+ *   // Transforms
+ *   rotateUV(uv, angle, center)                  -> Rotate UVs
+ *   scaleUV(uv, scale, center)                   -> Scale UVs
+ *   waveUV(uv, amplitude, frequency, time)       -> Wave distortion
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * EFFECTS (Automatic Shader Generation)
+ * ───────────────────────────────────────────────────────────────────────────
+ *
+ *   @effect "water" {
+ *     wave: { amplitude: 0.1, frequency: 2.0 }
+ *     reflection: 0.5
+ *     transparency: 0.3
+ *   }
+ *
+ *   @effect "fire" {
+ *     distortion: 0.2
+ *     colorGradient: [orange, red, yellow]
+ *     speed: 1.5
+ *   }
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * EXAMPLE SHADER
+ * ───────────────────────────────────────────────────────────────────────────
+ *
+ *   @shader "glow_effect"
+ *
+ *   @vertex
+ *   input position: vec3
+ *   input uv: vec2
+ *   uniform modelMatrix: mat4
+ *   uniform viewMatrix: mat4
+ *   uniform projectionMatrix: mat4
+ *   output vUV: vec2
+ *
+ *   main {
+ *     vUV = uv
+ *     gl_Position = projectionMatrix * viewMatrix * modelMatrix * vec4(position, 1.0)
+ *   }
+ *
+ *   @fragment
+ *   input vUV: vec2
+ *   uniform texture: sampler2D
+ *   uniform time: float
+ *   uniform glowColor: vec3
+ *   uniform glowIntensity: float
+ *   output fragColor: vec4
+ *
+ *   main {
+ *     let baseColor = sample(texture, vUV)
+ *     let glow = pulse(time, 2.0) * glowIntensity
+ *     fragColor = baseColor + vec4(glowColor * glow, 0.0)
+ *   }
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
+// Built-in GLSL snippets that get injected based on usage
+export const PXSL_BUILTINS = {
+  // ─────────────────────────────────────────────────────────────────────────
+  // Lighting Functions
+  // ─────────────────────────────────────────────────────────────────────────
+  diffuse: `
+float pxsl_diffuse(vec3 normal, vec3 lightDir) {
+  return max(dot(normalize(normal), normalize(lightDir)), 0.0);
+}`,
+
+  specular: `
+float pxsl_specular(vec3 normal, vec3 lightDir, vec3 viewDir, float power) {
+  vec3 n = normalize(normal);
+  vec3 l = normalize(lightDir);
+  vec3 v = normalize(viewDir);
+  vec3 h = normalize(l + v);
+  return pow(max(dot(n, h), 0.0), power);
+}`,
+
+  fresnel: `
+float pxsl_fresnel(vec3 normal, vec3 viewDir, float power) {
+  return pow(1.0 - max(dot(normalize(normal), normalize(viewDir)), 0.0), power);
+}`,
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Color Functions
+  // ─────────────────────────────────────────────────────────────────────────
+  brighten: `
+vec3 pxsl_brighten(vec3 color, float amount) {
+  return color * (1.0 + amount);
+}
+vec4 pxsl_brighten(vec4 color, float amount) {
+  return vec4(color.rgb * (1.0 + amount), color.a);
+}`,
+
+  darken: `
+vec3 pxsl_darken(vec3 color, float amount) {
+  return color * (1.0 - clamp(amount, 0.0, 1.0));
+}
+vec4 pxsl_darken(vec4 color, float amount) {
+  return vec4(color.rgb * (1.0 - clamp(amount, 0.0, 1.0)), color.a);
+}`,
+
+  saturate: `
+vec3 pxsl_saturate(vec3 color, float amount) {
+  float gray = dot(color, vec3(0.299, 0.587, 0.114));
+  return mix(vec3(gray), color, amount);
+}`,
+
+  contrast: `
+vec3 pxsl_contrast(vec3 color, float amount) {
+  return (color - 0.5) * amount + 0.5;
+}`,
+
+  tint: `
+vec3 pxsl_tint(vec3 color, vec3 tintColor, float amount) {
+  return mix(color, color * tintColor, amount);
+}`,
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Effect Functions
+  // ─────────────────────────────────────────────────────────────────────────
+  fog: `
+vec3 pxsl_fog(vec3 color, float depth, vec3 fogColor, float density) {
+  float fogFactor = 1.0 - exp(-density * depth);
+  return mix(color, fogColor, clamp(fogFactor, 0.0, 1.0));
+}
+vec4 pxsl_fog(vec4 color, float depth, vec3 fogColor, float density) {
+  float fogFactor = 1.0 - exp(-density * depth);
+  return vec4(mix(color.rgb, fogColor, clamp(fogFactor, 0.0, 1.0)), color.a);
+}`,
+
+  glow: `
+vec3 pxsl_glow(vec3 color, float intensity) {
+  float luminance = dot(color, vec3(0.299, 0.587, 0.114));
+  return color + color * luminance * intensity;
+}
+vec4 pxsl_glow(vec4 color, float intensity) {
+  float luminance = dot(color.rgb, vec3(0.299, 0.587, 0.114));
+  return vec4(color.rgb + color.rgb * luminance * intensity, color.a);
+}`,
+
+  outline: `
+vec4 pxsl_outline(vec2 uv, sampler2D tex, vec3 outlineColor, float width) {
+  vec2 texelSize = vec2(1.0 / 512.0); // Adjust based on texture size
+  vec4 center = texture2D(tex, uv);
+  float edge = 0.0;
+  edge += texture2D(tex, uv + vec2(-width, 0.0) * texelSize).a;
+  edge += texture2D(tex, uv + vec2(width, 0.0) * texelSize).a;
+  edge += texture2D(tex, uv + vec2(0.0, -width) * texelSize).a;
+  edge += texture2D(tex, uv + vec2(0.0, width) * texelSize).a;
+  edge = clamp(edge - center.a * 4.0, 0.0, 1.0);
+  return mix(center, vec4(outlineColor, 1.0), edge * (1.0 - center.a));
+}`,
+
+  pixelate: `
+vec2 pxsl_pixelate(vec2 uv, float resolution) {
+  return floor(uv * resolution) / resolution;
+}`,
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Math Helpers
+  // ─────────────────────────────────────────────────────────────────────────
+  remap: `
+float pxsl_remap(float value, float inMin, float inMax, float outMin, float outMax) {
+  return outMin + (value - inMin) * (outMax - outMin) / (inMax - inMin);
+}`,
+
+  pulse: `
+float pxsl_pulse(float value, float frequency) {
+  return (sin(value * frequency * 6.28318) + 1.0) * 0.5;
+}`,
+
+  noise: `
+float pxsl_noise(vec2 uv) {
+  return fract(sin(dot(uv, vec2(12.9898, 78.233))) * 43758.5453);
+}`,
+
+  fbm: `
+float pxsl_fbm(vec2 uv, int octaves) {
+  float value = 0.0;
+  float amplitude = 0.5;
+  float frequency = 1.0;
+  for(int i = 0; i < 8; i++) {
+    if(i >= octaves) break;
+    value += amplitude * pxsl_noise(uv * frequency);
+    amplitude *= 0.5;
+    frequency *= 2.0;
+  }
+  return value;
+}`,
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // UV Transform Functions
+  // ─────────────────────────────────────────────────────────────────────────
+  rotateUV: `
+vec2 pxsl_rotateUV(vec2 uv, float angle, vec2 center) {
+  float s = sin(angle);
+  float c = cos(angle);
+  uv -= center;
+  return vec2(uv.x * c - uv.y * s, uv.x * s + uv.y * c) + center;
+}`,
+
+  scaleUV: `
+vec2 pxsl_scaleUV(vec2 uv, vec2 scale, vec2 center) {
+  return (uv - center) * scale + center;
+}`,
+
+  waveUV: `
+vec2 pxsl_waveUV(vec2 uv, float amplitude, float frequency, float time) {
+  return uv + vec2(
+    sin(uv.y * frequency + time) * amplitude,
+    sin(uv.x * frequency + time) * amplitude
+  );
+}`,
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Utility Functions
+  // ─────────────────────────────────────────────────────────────────────────
+  linearizeDepth: `
+float pxsl_linearizeDepth(float depth, float near, float far) {
+  float z = depth * 2.0 - 1.0;
+  return (2.0 * near * far) / (far + near - z * (far - near));
+}`,
+
+  sample: `
+#define pxsl_sample(tex, uv) texture2D(tex, uv)`,
+};
+
+// Standard precision and version headers
+export const PXSL_HEADERS = {
+  vertex: `precision mediump float;
+precision mediump int;
+`,
+  fragment: `precision mediump float;
+precision mediump int;
+`,
+};
+
+// Type mappings for cleaner syntax
+export const PXSL_TYPE_ALIASES = {
+  float: 'float',
+  int: 'int',
+  bool: 'bool',
+  vec2: 'vec2',
+  vec3: 'vec3',
+  vec4: 'vec4',
+  mat2: 'mat2',
+  mat3: 'mat3',
+  mat4: 'mat4',
+  sampler: 'sampler2D',
+  samplerCube: 'samplerCube',
+  // User-friendly aliases
+  color: 'vec4',
+  color3: 'vec3',
+  point: 'vec3',
+  point2: 'vec2',
+  direction: 'vec3',
+  normal: 'vec3',
+  matrix: 'mat4',
+  texture: 'sampler2D',
+  cubemap: 'samplerCube',
+};
+
+// Standard input name mappings (what user writes -> what GLSL expects)
+export const PXSL_INPUT_MAPPINGS = {
+  position: 'aVertexPosition',
+  normal: 'aVertexNormal',
+  uv: 'aTextureCoord',
+  texcoord: 'aTextureCoord',
+  color: 'aVertexColor',
+  tangent: 'aVertexTangent',
+};
+
+// Standard uniform name mappings
+export const PXSL_UNIFORM_MAPPINGS = {
+  modelMatrix: 'uModelMatrix',
+  viewMatrix: 'uViewMatrix',
+  projectionMatrix: 'uProjectionMatrix',
+  normalMatrix: 'uNormalMatrix',
+  cameraPosition: 'uCameraPosition',
+  time: 'uTime',
+  resolution: 'uResolution',
+  // Lights are auto-handled
+};
+
+export default {
+  PXSL_BUILTINS,
+  PXSL_HEADERS,
+  PXSL_TYPE_ALIASES,
+  PXSL_INPUT_MAPPINGS,
+  PXSL_UNIFORM_MAPPINGS,
+};