@bloopjs/toodle 0.0.103 → 0.1.1

package/src/backends/IRenderBackend.ts

@@ -0,0 +1,118 @@
+import type { Color } from "../coreTypes/Color";
+import type { EngineUniform } from "../coreTypes/EngineUniform";
+import type { Size } from "../coreTypes/Size";
+import type { Limits } from "../limits";
+import type { CpuTextureAtlas } from "../textures/types";
+import type { IBackendShader, QuadShaderCreationOpts } from "./IBackendShader";
+import type { ITextureAtlas, TextureAtlasOptions } from "./ITextureAtlas";
+
+export type BackendType = "webgpu" | "webgl2";
+
+export type BlendFactor =
+  | "one"
+  | "zero"
+  | "src-alpha"
+  | "one-minus-src-alpha"
+  | "dst-alpha"
+  | "one-minus-dst-alpha";
+export type BlendOperation = "add" | "subtract" | "reverse-subtract";
+
+export type BlendMode = {
+  color: {
+    srcFactor: BlendFactor;
+    dstFactor: BlendFactor;
+    operation: BlendOperation;
+  };
+  alpha: {
+    srcFactor: BlendFactor;
+    dstFactor: BlendFactor;
+    operation: BlendOperation;
+  };
+};
+
+/**
+ * The render backend interface abstracts WebGPU and WebGL differences.
+ *
+ * Implementations handle GPU-specific operations like texture management,
+ * shader creation, and frame lifecycle.
+ */
+export interface IRenderBackend {
+  /** The type of backend ("webgpu" or "webgl2") */
+  readonly type: BackendType;
+
+  /** Engine limits (texture size, instance count, etc.) */
+  readonly limits: Limits;
+
+  /** Size of the default texture atlas */
+  readonly atlasSize: Size;
+
+  /** Default atlas ID (always "default") */
+  readonly defaultAtlasId: string;
+
+  /**
+   * Begin a new frame.
+   * WebGPU: Creates command encoder and render pass
+   * WebGL: Clears the canvas if loadOp is "clear"
+   */
+  startFrame(clearColor: Color, loadOp: "clear" | "load"): void;
+
+  /**
+   * End the current frame and submit to GPU.
+   * WebGPU: Ends render pass and submits command buffer
+   * WebGL: Flushes pending operations
+   */
+  endFrame(): void;
+
+  /**
+   * Update engine uniforms (view-projection matrix, resolution).
+   * Called once per frame before shader processing.
+   */
+  updateEngineUniform(uniform: EngineUniform): void;
+
+  /**
+   * Upload a CPU texture atlas to a GPU texture array layer.
+   * @param atlas - The CPU-side atlas data to upload
+   * @param layerIndex - Which layer in the texture array to upload to
+   * @param atlasId - Which atlas to upload to (default: "default")
+   */
+  uploadAtlas(
+    atlas: CpuTextureAtlas,
+    layerIndex: number,
+    atlasId?: string,
+  ): Promise<void>;
+
+  /**
+   * Create a new texture atlas.
+   * @param id - Unique identifier for this atlas
+   * @param options - Atlas configuration (format, layers, size)
+   */
+  createTextureAtlas(id: string, options?: TextureAtlasOptions): ITextureAtlas;
+
+  /**
+   * Get a texture atlas by ID.
+   * @param id - Atlas identifier or defaults to "default"
+   * @returns The atlas, or null if not found
+   */
+  getTextureAtlas(id?: string): ITextureAtlas | null;
+
+  /**
+   * Destroy a texture atlas and free GPU resources.
+   * @param id - Atlas identifier
+   */
+  destroyTextureAtlas(id: string): void;
+
+  /**
+   * Create a quad shader for instanced rendering.
+   */
+  createQuadShader(opts: QuadShaderCreationOpts): IBackendShader;
+
+  /**
+   * Handle canvas resize.
+   */
+  resize(width: number, height: number): void;
+
+  /**
+   * Clean up GPU resources.
+   */
+  destroy(): void;
+}

package/src/backends/ITextureAtlas.ts

@@ -0,0 +1,35 @@
+/**
+ * Supported texture atlas formats.
+ */
+export type TextureAtlasFormat = "rgba8unorm" | "rg8unorm";
+
+/**
+ * Options for creating a texture atlas.
+ */
+export type TextureAtlasOptions = {
+  /** Texture format (default: "rgba8unorm") */
+  format?: TextureAtlasFormat;
+  /** Number of array layers (default: limits.textureArrayLayers) */
+  layers?: number;
+  /** Atlas size in pixels (default: limits.textureSize) */
+  size?: number;
+};
+
+/**
+ * Backend-agnostic texture atlas interface.
+ *
+ * Texture atlases are GPU texture arrays that store multiple textures.
+ * Each backend manages its atlases and provides this common interface.
+ */
+export interface ITextureAtlas {
+  /** Unique identifier for this atlas */
+  readonly id: string;
+  /** Texture format */
+  readonly format: TextureAtlasFormat;
+  /** Number of array layers */
+  readonly layers: number;
+  /** Size in pixels (width = height) */
+  readonly size: number;
+  /** Underlying GPU handle (GPUTexture for WebGPU, WebGLTexture for WebGL) */
+  readonly handle: unknown;
+}

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";
+  }
+}