@bloopjs/toodle 0.0.104 → 0.1.1

package/src/backends/detection.ts

@@ -0,0 +1,46 @@
+import type { BackendType } from "./IRenderBackend";
+
+/**
+ * Detect the best available rendering backend.
+ *
+ * Tries WebGPU first (better performance), falls back to WebGL 2.
+ */
+export async function detectBackend(): Promise<BackendType> {
+  // Check for WebGPU support
+  if (typeof navigator !== "undefined" && "gpu" in navigator) {
+    try {
+      const adapter = await navigator.gpu.requestAdapter();
+      if (adapter) {
+        return "webgpu";
+      }
+    } catch {
+      // WebGPU initialization failed, fall back to WebGL
+    }
+  }
+
+  return "webgl2";
+}
+
+/**
+ * Check if WebGPU is available in the current environment.
+ */
+export function isWebGPUAvailable(): boolean {
+  return typeof navigator !== "undefined" && "gpu" in navigator;
+}
+
+/**
+ * Check if WebGL 2 is available in the current environment.
+ */
+export function isWebGL2Available(): boolean {
+  if (typeof document === "undefined") {
+    return false;
+  }
+
+  try {
+    const canvas = document.createElement("canvas");
+    const gl = canvas.getContext("webgl2");
+    return gl !== null;
+  } catch {
+    return false;
+  }
+}

package/src/backends/mod.ts

@@ -0,0 +1,29 @@
+// Backend abstraction layer
+
+export {
+  detectBackend,
+  isWebGL2Available,
+  isWebGPUAvailable,
+} from "./detection";
+export type { IBackendShader, QuadShaderCreationOpts } from "./IBackendShader";
+export type {
+  BackendType,
+  BlendFactor,
+  BlendMode,
+  BlendOperation,
+  IRenderBackend,
+} from "./IRenderBackend";
+export type {
+  ITextureAtlas,
+  TextureAtlasFormat,
+  TextureAtlasOptions,
+} from "./ITextureAtlas";
+export { defaultFragmentShader as defaultGLSLFragmentShader } from "./webgl2/glsl/quad.glsl";
+export { WebGLBackend } from "./webgl2/WebGLBackend";
+// WebGPU-specific postprocess utilities
+export {
+  type PostProcess,
+  PostProcessDefaults,
+} from "./webgpu/postprocess/mod";
+// Concrete backend implementations
+export { WebGPUBackend } from "./webgpu/WebGPUBackend";

package/src/backends/webgl2/WebGLBackend.ts

@@ -0,0 +1,256 @@
+import type { Color } from "../../coreTypes/Color";
+import type { EngineUniform } from "../../coreTypes/EngineUniform";
+import type { Size } from "../../coreTypes/Size";
+import type { Limits, LimitsOptions } from "../../limits";
+import { DEFAULT_LIMITS } from "../../limits";
+import type { CpuTextureAtlas } from "../../textures/types";
+import { assert } from "../../utils/assert";
+import type { IBackendShader, QuadShaderCreationOpts } from "../IBackendShader";
+import type { IRenderBackend } from "../IRenderBackend";
+import type {
+  ITextureAtlas,
+  TextureAtlasFormat,
+  TextureAtlasOptions,
+} from "../ITextureAtlas";
+import { WebGLQuadShader } from "./WebGLQuadShader";
+
+export type WebGLBackendOptions = {
+  limits?: LimitsOptions;
+  format?: "rgba8unorm" | "rg8unorm";
+};
+
+/**
+ * WebGL 2 implementation of the render backend.
+ */
+export class WebGLBackend implements IRenderBackend {
+  readonly type = "webgl2" as const;
+  readonly limits: Limits;
+  readonly atlasSize: Size;
+  readonly defaultAtlasId = "default";
+
+  #atlases = new Map<string, ITextureAtlas>();
+  #gl: WebGL2RenderingContext;
+  #canvas: HTMLCanvasElement;
+
+  private constructor(
+    gl: WebGL2RenderingContext,
+    canvas: HTMLCanvasElement,
+    limits: Limits,
+  ) {
+    this.#gl = gl;
+    this.#canvas = canvas;
+    this.limits = limits;
+    this.atlasSize = {
+      width: limits.textureSize,
+      height: limits.textureSize,
+    };
+  }
+
+  /**
+   * Create a WebGL 2 backend attached to a canvas.
+   */
+  static async create(
+    canvas: HTMLCanvasElement,
+    options: WebGLBackendOptions = {},
+  ): Promise<WebGLBackend> {
+    const gl = canvas.getContext("webgl2", {
+      alpha: true,
+      antialias: false,
+      premultipliedAlpha: true,
+    });
+
+    if (!gl) {
+      throw new Error("WebGL 2 not supported");
+    }
+
+    const limits: Limits = {
+      ...DEFAULT_LIMITS,
+      ...options.limits,
+    };
+
+    const backend = new WebGLBackend(gl, canvas, limits);
+
+    // Create the default texture atlas
+    backend.createTextureAtlas("default", {
+      format: options.format ?? "rgba8unorm",
+      layers: limits.textureArrayLayers,
+      size: limits.textureSize,
+    });
+
+    return backend;
+  }
+
+  startFrame(clearColor: Color, loadOp: "clear" | "load"): void {
+    const gl = this.#gl;
+
+    // Set viewport to canvas size
+    gl.viewport(0, 0, this.#canvas.width, this.#canvas.height);
+
+    if (loadOp === "clear") {
+      gl.clearColor(clearColor.r, clearColor.g, clearColor.b, clearColor.a);
+      gl.clear(gl.COLOR_BUFFER_BIT);
+    }
+
+    // Enable blending
+    gl.enable(gl.BLEND);
+    gl.blendFuncSeparate(
+      gl.SRC_ALPHA,
+      gl.ONE_MINUS_SRC_ALPHA,
+      gl.ONE,
+      gl.ONE_MINUS_SRC_ALPHA,
+    );
+  }
+
+  endFrame(): void {
+    const gl = this.#gl;
+    gl.flush();
+  }
+
+  updateEngineUniform(_uniform: EngineUniform): void {
+    // Uniforms are updated per-shader in WebGL, not at the backend level
+  }
+
+  async uploadAtlas(
+    atlas: CpuTextureAtlas,
+    layerIndex: number,
+    atlasId?: string,
+  ): Promise<void> {
+    const gl = this.#gl;
+    const targetAtlas = this.getTextureAtlas(atlasId ?? "default");
+    assert(targetAtlas, `Atlas "${atlasId ?? "default"}" not found`);
+    const texture = targetAtlas.handle as WebGLTexture;
+
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+
+    if (atlas.rg8Bytes) {
+      // Upload raw bytes for RG8 format
+      gl.texSubImage3D(
+        gl.TEXTURE_2D_ARRAY,
+        0, // mip level
+        0,
+        0,
+        layerIndex, // x, y, z offset
+        targetAtlas.size,
+        targetAtlas.size,
+        1, // width, height, depth
+        gl.RG,
+        gl.UNSIGNED_BYTE,
+        atlas.rg8Bytes,
+      );
+    } else {
+      // Upload ImageBitmap for RGBA format
+      gl.texSubImage3D(
+        gl.TEXTURE_2D_ARRAY,
+        0,
+        0,
+        0,
+        layerIndex,
+        atlas.texture.width,
+        atlas.texture.height,
+        1,
+        gl.RGBA,
+        gl.UNSIGNED_BYTE,
+        atlas.texture,
+      );
+    }
+
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+  }
+
+  createQuadShader(opts: QuadShaderCreationOpts): IBackendShader {
+    return new WebGLQuadShader(
+      opts.label,
+      this,
+      opts.instanceCount,
+      opts.userCode,
+      opts.atlasId,
+    );
+  }
+
+  createTextureAtlas(id: string, options?: TextureAtlasOptions): ITextureAtlas {
+    if (this.#atlases.has(id)) {
+      throw new Error(`Atlas "${id}" already exists`);
+    }
+
+    const gl = this.#gl;
+    const format: TextureAtlasFormat = options?.format ?? "rgba8unorm";
+    const layers = options?.layers ?? this.limits.textureArrayLayers;
+    const size = options?.size ?? this.limits.textureSize;
+
+    const texture = gl.createTexture();
+    assert(texture, "Failed to create WebGL texture");
+
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+
+    // Configure texture parameters
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+
+    // Allocate storage for texture array
+    const internalFormat = format === "rg8unorm" ? gl.RG8 : gl.RGBA8;
+
+    gl.texStorage3D(
+      gl.TEXTURE_2D_ARRAY,
+      1, // mip levels
+      internalFormat,
+      size,
+      size,
+      layers,
+    );
+
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+
+    const atlas: ITextureAtlas = { id, format, layers, size, handle: texture };
+    this.#atlases.set(id, atlas);
+    return atlas;
+  }
+
+  getTextureAtlas(id: string): ITextureAtlas | null {
+    return this.#atlases.get(id) ?? null;
+  }
+
+  destroyTextureAtlas(id: string): void {
+    const atlas = this.#atlases.get(id);
+    if (atlas) {
+      this.#gl.deleteTexture(atlas.handle as WebGLTexture);
+      this.#atlases.delete(id);
+    }
+  }
+
+  /**
+   * Get the default texture atlas handle.
+   * @deprecated Use getTextureAtlas("default").handle instead
+   */
+  get textureArrayHandle(): WebGLTexture {
+    return this.getTextureAtlas("default")!.handle as WebGLTexture;
+  }
+
+  resize(_width: number, _height: number): void {
+    // Canvas resize is handled by the application
+  }
+
+  destroy(): void {
+    const gl = this.#gl;
+    // Destroy all atlases
+    for (const atlas of this.#atlases.values()) {
+      gl.deleteTexture(atlas.handle as WebGLTexture);
+    }
+    this.#atlases.clear();
+  }
+
+  /**
+   * Get the WebGL 2 rendering context.
+   */
+  get gl(): WebGL2RenderingContext {
+    return this.#gl;
+  }
+
+  /**
+   * Get the presentation format (of the default atlas).
+   */
+  get presentationFormat(): TextureAtlasFormat {
+    return this.getTextureAtlas("default")?.format ?? "rgba8unorm";
+  }
+}

package/src/backends/webgl2/WebGLQuadShader.ts

@@ -0,0 +1,278 @@
+import type { EngineUniform } from "../../coreTypes/EngineUniform";
+import type { SceneNode } from "../../scene/SceneNode";
+import { assert } from "../../utils/assert";
+import type { IBackendShader } from "../IBackendShader";
+import type { ITextureAtlas } from "../ITextureAtlas";
+import { fragmentShader, vertexShader } from "./glsl/quad.glsl";
+import type { WebGLBackend } from "./WebGLBackend";
+
+// Instance data size in floats (must match WGSL shader)
+// model (12) + tint (4) + uvOffsetAndScale (4) + cropOffsetAndScale (4) + atlasIndex (1) + padding (3) = 28
+const INSTANCE_FLOATS = 28;
+const INSTANCE_BYTES = INSTANCE_FLOATS * Float32Array.BYTES_PER_ELEMENT;
+
+/**
+ * WebGL 2 implementation of quad shader for instanced rendering.
+ */
+export class WebGLQuadShader implements IBackendShader {
+  readonly label: string;
+
+  #backend: WebGLBackend;
+  #atlas: ITextureAtlas;
+  #program: WebGLProgram;
+  #vao: WebGLVertexArrayObject;
+  #instanceBuffer: WebGLBuffer;
+  #cpuBuffer: Float32Array;
+  #instanceCount: number;
+  #instanceIndex = 0;
+
+  // Uniform locations
+  #uViewProjection: WebGLUniformLocation | null = null;
+  #uResolution: WebGLUniformLocation | null = null;
+  #uTextureArray: WebGLUniformLocation | null = null;
+
+  constructor(
+    label: string,
+    backend: WebGLBackend,
+    instanceCount: number,
+    userFragmentShader?: string,
+    atlasId?: string,
+  ) {
+    const atlas = backend.getTextureAtlas(atlasId ?? "default");
+    if (!atlas) {
+      throw new Error(`Atlas "${atlasId ?? "default"}" not found`);
+    }
+
+    this.#atlas = atlas;
+    this.label = label;
+    this.#backend = backend;
+    this.#instanceCount = instanceCount;
+
+    const gl = backend.gl;
+
+    // Compile shaders
+    const vs = this.#compileShader(gl, gl.VERTEX_SHADER, vertexShader);
+    const fs = this.#compileShader(
+      gl,
+      gl.FRAGMENT_SHADER,
+      userFragmentShader ?? fragmentShader,
+    );
+
+    // Create program
+    const program = gl.createProgram();
+    assert(program, "Failed to create WebGL program");
+    gl.attachShader(program, vs);
+    gl.attachShader(program, fs);
+    gl.linkProgram(program);
+
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+      const info = gl.getProgramInfoLog(program);
+      throw new Error(`Failed to link shader program: ${info}`);
+    }
+
+    this.#program = program;
+
+    // Get uniform locations
+    this.#uViewProjection = gl.getUniformLocation(program, "u_viewProjection");
+    this.#uResolution = gl.getUniformLocation(program, "u_resolution");
+    this.#uTextureArray = gl.getUniformLocation(program, "u_textureArray");
+
+    // Create VAO
+    const vao = gl.createVertexArray();
+    assert(vao, "Failed to create WebGL VAO");
+    this.#vao = vao;
+
+    // Create instance buffer
+    const instanceBuffer = gl.createBuffer();
+    assert(instanceBuffer, "Failed to create WebGL instance buffer");
+    this.#instanceBuffer = instanceBuffer;
+
+    // Allocate CPU buffer
+    this.#cpuBuffer = new Float32Array(instanceCount * INSTANCE_FLOATS);
+
+    // Set up VAO
+    gl.bindVertexArray(vao);
+    gl.bindBuffer(gl.ARRAY_BUFFER, instanceBuffer);
+    gl.bufferData(
+      gl.ARRAY_BUFFER,
+      instanceCount * INSTANCE_BYTES,
+      gl.DYNAMIC_DRAW,
+    );
+
+    // Set up instance attributes
+    // Each vec4 attribute takes up 16 bytes
+    // model0 at location 0
+    gl.enableVertexAttribArray(0);
+    gl.vertexAttribPointer(0, 4, gl.FLOAT, false, INSTANCE_BYTES, 0);
+    gl.vertexAttribDivisor(0, 1);
+
+    // model1 at location 1
+    gl.enableVertexAttribArray(1);
+    gl.vertexAttribPointer(1, 4, gl.FLOAT, false, INSTANCE_BYTES, 16);
+    gl.vertexAttribDivisor(1, 1);
+
+    // model2 at location 2
+    gl.enableVertexAttribArray(2);
+    gl.vertexAttribPointer(2, 4, gl.FLOAT, false, INSTANCE_BYTES, 32);
+    gl.vertexAttribDivisor(2, 1);
+
+    // tint at location 3
+    gl.enableVertexAttribArray(3);
+    gl.vertexAttribPointer(3, 4, gl.FLOAT, false, INSTANCE_BYTES, 48);
+    gl.vertexAttribDivisor(3, 1);
+
+    // uvOffsetAndScale at location 4
+    gl.enableVertexAttribArray(4);
+    gl.vertexAttribPointer(4, 4, gl.FLOAT, false, INSTANCE_BYTES, 64);
+    gl.vertexAttribDivisor(4, 1);
+
+    // cropOffsetAndScale at location 5
+    gl.enableVertexAttribArray(5);
+    gl.vertexAttribPointer(5, 4, gl.FLOAT, false, INSTANCE_BYTES, 80);
+    gl.vertexAttribDivisor(5, 1);
+
+    // atlasIndex at location 6 (integer attribute - use vertexAttribIPointer)
+    gl.enableVertexAttribArray(6);
+    gl.vertexAttribIPointer(6, 1, gl.UNSIGNED_INT, INSTANCE_BYTES, 96);
+    gl.vertexAttribDivisor(6, 1);
+
+    gl.bindVertexArray(null);
+    gl.bindBuffer(gl.ARRAY_BUFFER, null);
+
+    // Cleanup shaders (they're linked to the program now)
+    gl.deleteShader(vs);
+    gl.deleteShader(fs);
+  }
+
+  #cachedUniform: EngineUniform | null = null;
+
+  startFrame(uniform: EngineUniform): void {
+    this.#instanceIndex = 0;
+    // Cache uniform for use in processBatch - WebGL state is global,
+    // so we need to set program/uniforms/textures right before drawing
+    this.#cachedUniform = uniform;
+  }
+
+  #bindState(): void {
+    const gl = this.#backend.gl;
+    const uniform = this.#cachedUniform;
+    if (!uniform)
+      throw new Error("Tried to bind state but engine uniform is not set");
+
+    gl.useProgram(this.#program);
+
+    // Set uniforms
+    if (this.#uViewProjection) {
+      // wgpu-matrix mat3 is stored as 12 floats (3 columns × 4 floats with padding)
+      // WebGL uniformMatrix3fv expects 9 floats, so extract the relevant values
+      const m = uniform.viewProjectionMatrix;
+      const mat3x3 = new Float32Array([
+        m[0],
+        m[1],
+        m[2], // column 0
+        m[4],
+        m[5],
+        m[6], // column 1
+        m[8],
+        m[9],
+        m[10], // column 2
+      ]);
+      gl.uniformMatrix3fv(this.#uViewProjection, false, mat3x3);
+    }
+
+    if (this.#uResolution) {
+      gl.uniform2f(
+        this.#uResolution,
+        uniform.resolution.width,
+        uniform.resolution.height,
+      );
+    }
+
+    // Bind texture array to texture unit 0
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.#atlas.handle as WebGLTexture);
+    if (this.#uTextureArray) {
+      gl.uniform1i(this.#uTextureArray, 0);
+    }
+  }
+
+  processBatch(nodes: SceneNode[]): number {
+    const gl = this.#backend.gl;
+
+    // Bind program, uniforms, and textures right before drawing
+    // (WebGL state is global, so this must happen per-batch)
+    this.#bindState();
+
+    if (nodes.length > this.#instanceCount) {
+      throw new Error(
+        `ToodleInstanceCap: ${nodes.length} instances enqueued, max is ${this.#instanceCount} for ${this.label} shader`,
+      );
+    }
+
+    let instanceCount = 0;
+
+    // WebGL2 doesn't support firstInstance in drawArraysInstanced,
+    // so we always write starting at offset 0 for each batch
+    for (let i = 0; i < nodes.length; i++) {
+      const instance = nodes[i];
+      assert(instance.renderComponent, "instance has no render component");
+      const floatOffset = instanceCount * INSTANCE_FLOATS;
+
+      instanceCount += instance.renderComponent.writeInstance(
+        instance,
+        this.#cpuBuffer,
+        floatOffset,
+      );
+    }
+
+    // Upload instance data to GPU starting at offset 0
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.#instanceBuffer);
+
+    gl.bufferSubData(
+      gl.ARRAY_BUFFER,
+      0,
+      this.#cpuBuffer,
+      0,
+      instanceCount * INSTANCE_FLOATS,
+    );
+
+    // Draw instances from offset 0
+    gl.bindVertexArray(this.#vao);
+    gl.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 4, instanceCount);
+    gl.bindVertexArray(null);
+
+    return 1;
+  }
+
+  endFrame(): void {
+    // Nothing to do
+  }
+
+  #compileShader(
+    gl: WebGL2RenderingContext,
+    type: number,
+    source: string,
+  ): WebGLShader {
+    const shader = gl.createShader(type);
+    assert(shader, "Failed to create WebGL shader");
+
+    gl.shaderSource(shader, source);
+    gl.compileShader(shader);
+
+    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+      const info = gl.getShaderInfoLog(shader);
+      const typeStr = type === gl.VERTEX_SHADER ? "vertex" : "fragment";
+      gl.deleteShader(shader);
+      throw new Error(`Failed to compile ${typeStr} shader: ${info}`);
+    }
+
+    return shader;
+  }
+
+  destroy(): void {
+    const gl = this.#backend.gl;
+    gl.deleteProgram(this.#program);
+    gl.deleteVertexArray(this.#vao);
+    gl.deleteBuffer(this.#instanceBuffer);
+  }
+}