micro-gl 0.1.0

package/src/2d/core/Renderer2d.js

@@ -0,0 +1,353 @@
+import { Shape2d } from './Shape2d.js';
+import { GpuResources2d } from './GpuResources2d.js';
+import {
+  FRAME_UNIFORM_SIZE_2D,
+  OBJECT_UNIFORM_OFFSET_2D,
+} from './Uniforms2d.js';
+import { initWebGpu } from '../../core/initWebGpu.js';
+import { srgbToLinear } from '../../math/color.js';
+import {
+  ANTIALIAS_SAMPLE_COUNT,
+  DEFAULT_CANVAS_HEIGHT,
+  DEFAULT_CANVAS_WIDTH,
+  SINGLE_SAMPLE_COUNT,
+  colorAttachment,
+  drawingBufferSize,
+  linearClearColor,
+} from '../../core/rendererConfig.js';
+import {
+  acquireDeviceLease,
+  releaseDeviceLease,
+} from '../../core/deviceLease.js';
+import {
+  INDEX_FORMAT,
+  SHADER_BIND_GROUP,
+  SHADER_BINDING,
+  VERTEX_BUFFER_SLOT,
+} from '../../core/pipelineConstants.js';
+
+/**
+ * The 2D renderer. Same shape as the 3D Renderer — one render pass,
+ * lazy GPU resources — but with everything a flat scene doesn't need
+ * removed: there is no depth buffer. Draw order comes from sorting
+ * shapes by `zIndex` (painter's algorithm) and alpha blending is on,
+ * so transparent shapes work out of the box.
+ *
+ * Usage:
+ *   const renderer2d = new Renderer2d(canvas);
+ *   await renderer2d.init();
+ *   renderer2d.render(scene2d, camera2d);
+ *
+ * To share a canvas with a 3D Renderer, initialize one of them first
+ * and pass it to the other's `init` so they use the same GPU device:
+ *   await renderer2d.init(renderer3d);
+ */
+export class Renderer2d {
+  /**
+   * @param {HTMLCanvasElement} canvas
+   * @param {object} [options]
+   * @param {boolean} [options.autoResize] follow the canvas's CSS size
+   *   with a ResizeObserver, calling setSize automatically (default
+   *   false — call setSize yourself)
+   * @param {boolean} [options.antialias] draw into a 4x multisampled
+   *   target that resolves to the canvas (default true), smoothing
+   *   edges; set false to render aliased at slightly lower cost
+   */
+  constructor(canvas, { autoResize = false, antialias = true } = {}) {
+    this.canvas = canvas;
+    this.device = null;
+    this.context = null;
+    /** Preferred non-sRGB format used to configure the canvas context. */
+    this.format = null;
+    /** Compatible sRGB view format used by color render passes. */
+    this.colorFormat = null;
+    /** How many shapes the last render() call drew. */
+    this.drawCount = 0;
+
+    this._autoResize = autoResize;
+    this._sampleCount = antialias
+      ? ANTIALIAS_SAMPLE_COUNT
+      : SINGLE_SAMPLE_COUNT;
+    this._resizeObserver = null;
+    this._ownsDevice = false;
+    this._deviceLease = null;
+    this._initPromise = null;
+    this._initVersion = 0;
+    this._resources = null;
+    this._msaaTexture = null;
+    this._msaaView = null;
+    this._targetWidth = 0;
+    this._targetHeight = 0;
+    this._drawList = [];
+  }
+
+  /**
+   * Requests the adapter/device and configures the canvas. Must be
+   * awaited before rendering. Pass another already-initialized renderer
+   * on the same canvas as `shared` to reuse its GPU device.
+   *
+   * @param {{device, context, format, colorFormat}} [shared] another renderer,
+   *   or an initWebGpu() result whose canvas viewFormats remain configured
+   */
+  async init(shared) {
+    // Coalesce overlapping calls so one canvas is never configured with two
+    // newly requested devices. Both callers observe the same result.
+    if (this._initPromise) return this._initPromise;
+    if (this.device) throw new Error('Renderer2d is already initialized');
+
+    const version = ++this._initVersion;
+    const initialization = this._completeInitialization(shared, version);
+    this._initPromise = initialization;
+    try {
+      return await initialization;
+    } finally {
+      if (this._initPromise === initialization) {
+        this._initPromise = null;
+      }
+    }
+  }
+
+  async _completeInitialization(shared, version) {
+    const renderer = await this._initialize(shared, version);
+    if (version !== this._initVersion) {
+      throw new Error(
+        'Renderer2d initialization was cancelled by dispose()',
+      );
+    }
+    return renderer;
+  }
+
+  async _initialize(shared, version) {
+    const gpu = shared || (await initWebGpu(this.canvas));
+    if (version !== this._initVersion) {
+      if (!shared) {
+        gpu.context.unconfigure();
+        gpu.device.destroy();
+      }
+      throw new Error(
+        'Renderer2d initialization was cancelled by dispose()',
+      );
+    }
+
+    let leaseAcquired = false;
+    try {
+      const lease = acquireDeviceLease(this, gpu, shared);
+      leaseAcquired = true;
+      this.device = lease.device;
+      this.context = lease.context;
+      this.format = lease.format;
+      this.colorFormat = lease.colorFormat;
+
+      this._resources = new GpuResources2d(
+        this.device,
+        this.colorFormat,
+        this._sampleCount,
+      );
+
+      this._frameUniformBuffer = this.device.createBuffer({
+        size: FRAME_UNIFORM_SIZE_2D,
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+      });
+      this._frameBindGroup = this.device.createBindGroup({
+        layout: this._resources.frameBindGroupLayout,
+        entries: [
+          {
+            binding: SHADER_BINDING.uniforms,
+            resource: { buffer: this._frameUniformBuffer },
+          },
+        ],
+      });
+
+      this.setSize(
+        this.canvas.clientWidth || DEFAULT_CANVAS_WIDTH,
+        this.canvas.clientHeight || DEFAULT_CANVAS_HEIGHT,
+      );
+      if (this._autoResize && typeof ResizeObserver !== 'undefined') {
+        this._resizeObserver = new ResizeObserver((entries) => {
+          const { width, height } = entries[0].contentRect;
+          if (width > 0 && height > 0) this.setSize(width, height);
+        });
+        this._resizeObserver.observe(this.canvas);
+      }
+      return this;
+    } catch (error) {
+      if (leaseAcquired) {
+        this.dispose();
+      } else if (!shared) {
+        gpu.context.unconfigure();
+        gpu.device.destroy();
+      }
+      throw error;
+    }
+  }
+
+  /** Resizes the drawing buffer. Pass CSS pixel dimensions. */
+  setSize(width, height) {
+    const size = drawingBufferSize(width, height);
+    this.canvas.width = size.width;
+    this.canvas.height = size.height;
+
+    if (!this.device) return;
+    this._recreateRenderTargets();
+  }
+
+  /** Keeps MSAA valid when another renderer resized a shared canvas. */
+  _ensureRenderTargets() {
+    const sizeChanged =
+      this._targetWidth !== this.canvas.width ||
+      this._targetHeight !== this.canvas.height;
+    const attachmentMissing = this._sampleCount > 1 && !this._msaaTexture;
+    if (sizeChanged || attachmentMissing) this._recreateRenderTargets();
+  }
+
+  _recreateRenderTargets() {
+    if (this._msaaTexture) this._msaaTexture.destroy();
+    this._msaaTexture = null;
+    this._msaaView = null;
+    if (this._sampleCount > 1) {
+      // The multisampled color target the pass draws into; it resolves
+      // to the swap chain texture at the end of every render pass.
+      this._msaaTexture = this.device.createTexture({
+        size: [this.canvas.width, this.canvas.height],
+        format: this.colorFormat,
+        sampleCount: this._sampleCount,
+        usage: GPUTextureUsage.RENDER_ATTACHMENT,
+      });
+      this._msaaView = this._msaaTexture.createView();
+    }
+    this._targetWidth = this.canvas.width;
+    this._targetHeight = this.canvas.height;
+  }
+
+  /** Draws one frame of `scene` as seen from `camera`. */
+  render(scene, camera) {
+    if (!this.device) {
+      throw new Error('Renderer2d.init() must complete before render()');
+    }
+    this._ensureRenderTargets();
+    camera.aspect = this.canvas.width / this.canvas.height;
+
+    scene.updateWorldMatrix();
+    camera.updateMatrices();
+
+    this.device.queue.writeBuffer(
+      this._frameUniformBuffer,
+      0,
+      camera.viewProjectionMatrix.elements,
+    );
+
+    const drawList = this._collectShapes(scene);
+
+    const encoder = this.device.createCommandEncoder();
+    const pass = this._beginRenderPass(encoder, scene.background);
+
+    pass.setBindGroup(SHADER_BIND_GROUP.frame, this._frameBindGroup);
+    for (const shape of drawList) {
+      this._drawShape(pass, shape);
+    }
+
+    pass.end();
+    this.device.queue.submit([encoder.finish()]);
+  }
+
+  /** Collects visible shapes in painter's-algorithm order. */
+  _collectShapes(scene) {
+    const drawList = this._drawList;
+    drawList.length = 0;
+    scene.traverseVisible((object) => {
+      if (object instanceof Shape2d) drawList.push(object);
+    });
+    // sort() is stable, so equal zIndex values preserve scene order.
+    drawList.sort((a, b) => a.zIndex - b.zIndex);
+    this.drawCount = drawList.reduce(
+      (count, shape) => count + (shape.isInstanced ? shape.count : 1),
+      0,
+    );
+    return drawList;
+  }
+
+  _beginRenderPass(encoder, background) {
+    const swapView = this.context
+      .getCurrentTexture()
+      .createView({ format: this.colorFormat });
+    return encoder.beginRenderPass({
+      colorAttachments: [
+        colorAttachment(
+          this._msaaView,
+          swapView,
+          linearClearColor(background),
+        ),
+      ],
+    });
+  }
+
+  /**
+   * Releases the resize observer, frame buffer, render targets and this
+   * renderer's per-object buffers. A
+   * managed shared device stays alive until the last renderer using it
+   * is disposed. Geometry and texture caches may be shared; release those
+   * separately with geometry.dispose() and texture.dispose(). Call init()
+   * again before reusing this renderer.
+   */
+  dispose() {
+    // Invalidates an adapter/device request that has not completed yet.
+    this._initVersion++;
+    if (this._resizeObserver) {
+      this._resizeObserver.disconnect();
+      this._resizeObserver = null;
+    }
+    if (this._frameUniformBuffer) this._frameUniformBuffer.destroy();
+    if (this._msaaTexture) this._msaaTexture.destroy();
+    if (this._resources) this._resources.dispose();
+    this._frameUniformBuffer = null;
+    this._msaaTexture = null;
+    this._msaaView = null;
+    this._targetWidth = 0;
+    this._targetHeight = 0;
+    const shouldDestroyDevice = releaseDeviceLease(this);
+    if (shouldDestroyDevice && this.device) {
+      this.context.unconfigure();
+      this.device.destroy();
+    }
+    this.device = null;
+    this.context = null;
+    this.format = null;
+    this.colorFormat = null;
+    this._frameBindGroup = null;
+    this._resources = null;
+    this._drawList.length = 0;
+    this._ownsDevice = false;
+  }
+
+  _drawShape(pass, shape) {
+    const instanced = !!shape.isInstanced;
+    const geometryGPU = this._resources.geometryFor(shape.geometry);
+    const shapeGPU = this._resources.shapeFor(shape);
+    const pipeline = this._resources.pipelineFor(shape.material, instanced);
+
+    // Per-object uniforms: world transform, color.
+    const data = shapeGPU.data;
+    data.set(shape.worldMatrix.elements, OBJECT_UNIFORM_OFFSET_2D.transform);
+    const color = shape.material.color;
+    // Colors are authored in sRGB; shaders and attachment blending use linear
+    // values, then the sRGB color target encodes the stored canvas pixels.
+    const colorOffset = OBJECT_UNIFORM_OFFSET_2D.color;
+    data[colorOffset] = srgbToLinear(color[0]);
+    data[colorOffset + 1] = srgbToLinear(color[1]);
+    data[colorOffset + 2] = srgbToLinear(color[2]);
+    data[colorOffset + 3] = color.length > 3 ? color[3] : 1;
+    this.device.queue.writeBuffer(shapeGPU.uniformBuffer, 0, data);
+
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(SHADER_BIND_GROUP.object, shapeGPU.bindGroup);
+    pass.setVertexBuffer(
+      VERTEX_BUFFER_SLOT.geometry,
+      geometryGPU.vertexBuffer,
+    );
+    if (instanced) {
+      pass.setVertexBuffer(VERTEX_BUFFER_SLOT.instance, shapeGPU.instanceBuffer);
+    }
+    pass.setIndexBuffer(geometryGPU.indexBuffer, INDEX_FORMAT);
+    pass.drawIndexed(shape.geometry.indexCount, instanced ? shape.count : 1);
+  }
+}

package/src/2d/core/Scene2d.js

@@ -0,0 +1,13 @@
+import { Object2d } from './Object2d.js';
+
+/**
+ * Root of the 2D scene graph. Add shapes to it, then pass it to
+ * `renderer2d.render(scene, camera)`.
+ */
+export class Scene2d extends Object2d {
+  constructor() {
+    super();
+    /** sRGB clear color as [r, g, b, a] in the 0..1 range. */
+    this.background = [0.05, 0.06, 0.09, 1];
+  }
+}

package/src/2d/core/Shape2d.js

@@ -0,0 +1,13 @@
+import { Object2d } from './Object2d.js';
+
+/**
+ * A renderable 2D object: a Geometry2d (the outline) combined with a
+ * Material2d (how it is filled) — the 2D counterpart of Mesh.
+ */
+export class Shape2d extends Object2d {
+  constructor(geometry, material) {
+    super();
+    this.geometry = geometry;
+    this.material = material;
+  }
+}

package/src/2d/core/Uniforms2d.js

@@ -0,0 +1,13 @@
+const FLOAT_BYTES = Float32Array.BYTES_PER_ELEMENT;
+const VEC4_FLOATS = 4;
+const MAT3_COLUMNS = 3;
+const PADDED_MAT3_FLOATS = MAT3_COLUMNS * VEC4_FLOATS;
+
+export const FRAME_UNIFORM_SIZE_2D = PADDED_MAT3_FLOATS * FLOAT_BYTES;
+export const OBJECT_UNIFORM_SIZE_2D =
+  (PADDED_MAT3_FLOATS + VEC4_FLOATS) * FLOAT_BYTES;
+
+export const OBJECT_UNIFORM_OFFSET_2D = Object.freeze({
+  transform: 0,
+  color: PADDED_MAT3_FLOATS,
+});

package/src/2d/geometries/CircleGeometry.js

@@ -0,0 +1,27 @@
+import { Geometry2d } from './Geometry2d.js';
+
+/**
+ * A circle centered on the origin, built as a triangle fan.
+ */
+export class CircleGeometry extends Geometry2d {
+  constructor(radius = 0.5, segments = 32) {
+    // Center vertex, then one vertex per rim segment.
+    const vertices = [0, 0, 0.5, 0.5];
+    const indices = [];
+    for (let i = 0; i < segments; i++) {
+      const angle = (i / segments) * Math.PI * 2;
+      const c = Math.cos(angle),
+        s = Math.sin(angle);
+      vertices.push(radius * c, radius * s, 0.5 + c * 0.5, 0.5 + s * 0.5);
+      indices.push(0, 1 + i, 1 + ((i + 1) % segments));
+    }
+
+    super(vertices, indices);
+    this.radius = radius;
+  }
+
+  /** Exact circle test — tighter than the bounding-box default. */
+  containsPoint(x, y) {
+    return x * x + y * y <= this.radius * this.radius;
+  }
+}

package/src/2d/geometries/Geometry2d.js

@@ -0,0 +1,108 @@
+/**
+ * Holds the raw 2D shape data on the CPU side.
+ *
+ * Vertices are interleaved as 4 floats each:
+ *   position (x, y), uv (u, v)
+ * so one GPU vertex buffer with a 16-byte stride serves both attributes
+ * (half the data of a 3D vertex — no z, no normal).
+ *
+ * Renderers lazily create GPU buffers the first time the geometry is
+ * drawn. `_gpu` holds one cache entry per GPUDevice, so the same CPU
+ * geometry can safely be shared by independently initialized renderers.
+ */
+export class Geometry2d {
+  /**
+   * @param {Float32Array|number[]} vertices interleaved vertex data
+   * @param {Uint32Array|number[]}  indices  triangle indices
+   */
+  constructor(vertices, indices) {
+    this.vertices =
+      vertices instanceof Float32Array ? vertices : new Float32Array(vertices);
+    this.indices =
+      indices instanceof Uint32Array ? indices : new Uint32Array(indices);
+    this._gpu = null;
+    this._bounds = null;
+    this._needsUpdate = false;
+    // Each cache entry records the revision it last uploaded. A revision
+    // cannot be replaced by one boolean when several devices share this data.
+    this._gpuRevision = 0;
+  }
+
+  /**
+   * Set to true after editing `vertices` or `indices` in place: the
+   * renderer re-uploads the GPU buffers on the next draw and the cached
+   * bounds are recomputed. The arrays must keep their length — to
+   * change the vertex or index count, make a new geometry.
+   */
+  get needsUpdate() {
+    return this._needsUpdate;
+  }
+
+  set needsUpdate(value) {
+    this._needsUpdate = Boolean(value);
+    if (this._needsUpdate) {
+      this._gpuRevision++;
+      this._bounds = null;
+    }
+  }
+
+  /**
+   * Local-space axis-aligned bounding box `{ min, max }`, computed from
+   * the vertex positions on first access. Used for picking.
+   */
+  get bounds() {
+    if (!this._bounds) {
+      const min = [Infinity, Infinity];
+      const max = [-Infinity, -Infinity];
+      for (let i = 0; i < this.vertices.length; i += VERTEX_SIZE_2D) {
+        for (let a = 0; a < 2; a++) {
+          const v = this.vertices[i + a];
+          if (v < min[a]) min[a] = v;
+          if (v > max[a]) max[a] = v;
+        }
+      }
+      this._bounds = { min, max };
+    }
+    return this._bounds;
+  }
+
+  /**
+   * Whether a local-space point lies inside the shape. The base class
+   * tests the bounding box; subclasses can be exact (see CircleGeometry).
+   * This is all 2D picking needs — no raycaster required.
+   */
+  containsPoint(x, y) {
+    const { min, max } = this.bounds;
+    return x >= min[0] && x <= max[0] && y >= min[1] && y <= max[1];
+  }
+
+  get vertexCount() {
+    return this.vertices.length / VERTEX_SIZE_2D;
+  }
+
+  get indexCount() {
+    return this.indices.length;
+  }
+
+  /**
+   * Destroys the GPU vertex/index buffers (if any), releasing the
+   * memory right away instead of waiting for GC. Call it when nothing
+   * draws this geometry anymore; drawing it again re-uploads.
+   */
+  dispose() {
+    if (this._gpu) {
+      for (const { vertexBuffer, indexBuffer } of this._gpu.values()) {
+        vertexBuffer.destroy();
+        indexBuffer.destroy();
+      }
+      this._gpu = null;
+    }
+    return this;
+  }
+}
+
+/** Number of floats per vertex (2 position + 2 uv). */
+export const VERTEX_SIZE_2D = 4;
+/** Byte stride of one vertex in the GPU buffer. */
+export const VERTEX_STRIDE_2D =
+  VERTEX_SIZE_2D * Float32Array.BYTES_PER_ELEMENT;

package/src/2d/geometries/RectGeometry.js

@@ -0,0 +1,23 @@
+import { Geometry2d } from './Geometry2d.js';
+
+/**
+ * A rectangle centered on the origin.
+ */
+export class RectGeometry extends Geometry2d {
+  constructor(width = 1, height = 1) {
+    const w = width / 2;
+    const h = height / 2;
+
+    // prettier-ignore
+    const vertices = [
+      // position   uv
+      -w, -h, 0, 0,
+      w, -h, 1, 0,
+      w, h, 1, 1,
+      -w, h, 0, 1,
+    ];
+    const indices = [0, 1, 2, 0, 2, 3];
+
+    super(vertices, indices);
+  }
+}

package/src/2d/materials/BasicMaterial2d.js

@@ -0,0 +1,12 @@
+import { Material2d } from './Material2d.js';
+import { BASIC_FRAGMENT_SHADER_2D } from '../shaders/fragments.js';
+
+/**
+ * Fills the shape with a flat color. Alpha below 1 shows through to
+ * whatever was drawn underneath.
+ */
+export class BasicMaterial2d extends Material2d {
+  get fragmentShader() {
+    return BASIC_FRAGMENT_SHADER_2D;
+  }
+}

package/src/2d/materials/Material2d.js

@@ -0,0 +1,78 @@
+import {
+  DEFAULT_CULL_MODE_2D,
+  DEFAULT_FRONT_FACE,
+  DEFAULT_PRIMITIVE_TOPOLOGY,
+} from '../../core/pipelineConstants.js';
+import {
+  INSTANCED_SHAPE_SHADER_PREFIX,
+  SHAPE_SHADER_PREFIX,
+} from '../shaders/vertexStages.js';
+
+/**
+ * Base class for 2D materials. It owns per-object parameters and pipeline
+ * state; reusable WGSL stages live in `2d/shaders`.
+ *
+ * Every 2D shader shares the same uniform interface:
+ *   @group(0) — per-frame data (the camera's view-projection Mat3)
+ *   @group(1) — per-object data (world transform + color)
+ * There are no lights or normals. Mat3 uniforms use WGSL's padded
+ * 16-byte column layout, which is the layout `Mat3.elements` stores.
+ */
+export class Material2d {
+  /**
+   * @param {object} [options]
+   * @param {number[]} [options.color] [r, g, b] or [r, g, b, a] in 0..1 —
+   *   alpha below 1 blends with what is behind
+   * @param {Texture} [options.map] texture the shader can sample at the
+   *   shape's uvs — only used when `usesMap` is true
+   * @param {boolean} [options.usesMap] whether the fragment shader declares
+   *   the map and sampler bindings. It defaults to whether `map` was supplied
+   *   for compatibility; custom material subclasses should set it explicitly.
+   *   It is fixed for the material's lifetime so replacing or clearing `map`
+   *   cannot silently change its pipeline layout
+   * @param {GPUPrimitiveTopology} [options.topology]
+   *   'triangle-list' (default), 'triangle-strip', 'line-list',
+   *   'line-strip' or 'point-list'
+   * @param {GPUCullMode} [options.cullMode] 'none' (default — a negative
+   *   scale flips a shape's winding and it should stay visible), 'back'
+   *   or 'front'; only applies to triangle topologies
+   * @param {GPUFrontFace} [options.frontFace] 'ccw' (default) or 'cw'
+   */
+  constructor({
+    color = [1, 1, 1],
+    map = null,
+    usesMap = map !== null,
+    topology = DEFAULT_PRIMITIVE_TOPOLOGY,
+    cullMode = DEFAULT_CULL_MODE_2D,
+    frontFace = DEFAULT_FRONT_FACE,
+  } = {}) {
+    this.color = color;
+    this.map = map;
+    Object.defineProperty(this, 'usesMap', {
+      value: Boolean(usesMap),
+      enumerable: true,
+    });
+    this.topology = topology;
+    this.cullMode = cullMode;
+    this.frontFace = frontFace;
+  }
+
+  /** Full WGSL source with `vs` and `fs` entry points. */
+  get shaderCode() {
+    return Material2d.SHARED_WGSL + this.fragmentShader;
+  }
+
+  /** Full WGSL source whose vertex stage reads per-instance data. */
+  get instancedShaderCode() {
+    return Material2d.INSTANCED_WGSL + this.fragmentShader;
+  }
+
+  /** Fragment-stage WGSL supplied by a concrete material. */
+  get fragmentShader() {
+    throw new Error('Material2d subclasses must implement fragmentShader');
+  }
+
+  // Mutable for compatibility with code that customized these fields directly.
+  static SHARED_WGSL = SHAPE_SHADER_PREFIX;
+  static INSTANCED_WGSL = INSTANCED_SHAPE_SHADER_PREFIX;
+}

package/src/2d/materials/SpriteMaterial2d.js

@@ -0,0 +1,28 @@
+import { Material2d } from './Material2d.js';
+import { SPRITE_FRAGMENT_SHADER_2D } from '../shaders/fragments.js';
+
+/**
+ * Fills the shape with a texture sampled at its uvs, tinted by `color` —
+ * the 2D sprite workhorse. The texture's alpha blends like the color
+ * alpha in BasicMaterial2d. Requires the map: the shader's texture
+ * bindings must exist when the pipeline is created.
+ *
+ * RectGeometry's v axis points up while images store their top row
+ * first, so image sprites usually want the texture created with
+ * `flipY: true`.
+ */
+export class SpriteMaterial2d extends Material2d {
+  /** @param {{map: Texture, color?: number[]}} options see Material2d for the rest */
+  constructor(options = {}) {
+    super({ ...options, usesMap: true });
+    // Compatibility alias retained for existing material introspection.
+    this.requiresMap = true;
+    if (!this.map) {
+      throw new Error('SpriteMaterial2d requires a `map` texture');
+    }
+  }
+
+  get fragmentShader() {
+    return SPRITE_FRAGMENT_SHADER_2D;
+  }
+}