micro-gl 0.1.0

package/src/3d/shaders/shared.js

@@ -0,0 +1,129 @@
+import {
+  SHADER_BIND_GROUP,
+  SHADER_BINDING,
+  SHADOW_BINDING,
+} from '../../core/pipelineConstants.js';
+import { VERTEX_ATTRIBUTE } from './vertexLayout.js';
+import { MAX_POINT_LIGHTS } from '../constants.js';
+
+export { MAX_POINT_LIGHTS };
+
+/** Object-uniform layout shared by color and shadow-depth shader modules. */
+export const OBJECT_UNIFORM_WGSL = /* wgsl */ `
+struct ObjectUniforms {
+  model: mat4x4f,
+  normalMatrix: mat4x4f,
+  color: vec4f,
+  // x: whether this mesh receives the directional shadow.
+  shadowFlags: vec4f,
+};
+`;
+
+/** Directional-shadow uniform layout shared by both render passes. */
+export const SHADOW_UNIFORM_WGSL = /* wgsl */ `
+struct ShadowUniforms {
+  viewProjection: mat4x4f,
+  // x: enabled, y: depth bias, z: normal bias, w: shadow texel size.
+  params: vec4f,
+};
+`;
+
+/** Uniform declarations and shading helpers shared by every 3D shader. */
+export const SHARED_SHADER_CHUNKS = /* wgsl */ `
+struct PointLightUniform {
+  position: vec3f, // world space
+  color: vec3f,    // linear, premultiplied by intensity
+};
+
+struct FrameUniforms {
+  viewProjection: mat4x4f,
+  lightDirection: vec3f,
+  lightColor: vec3f,
+  ambientColor: vec3f,
+  // Packs into ambientColor's 16-byte slot; how many array entries are live.
+  pointLightCount: f32,
+  pointLights: array<PointLightUniform, ${MAX_POINT_LIGHTS}>,
+};
+
+${OBJECT_UNIFORM_WGSL}
+${SHADOW_UNIFORM_WGSL}
+
+@group(${SHADER_BIND_GROUP.frame}) @binding(${SHADER_BINDING.uniforms})
+var<uniform> uFrame: FrameUniforms;
+@group(${SHADER_BIND_GROUP.object}) @binding(${SHADER_BINDING.uniforms})
+var<uniform> uObject: ObjectUniforms;
+@group(${SHADER_BIND_GROUP.shadow}) @binding(${SHADOW_BINDING.uniforms})
+var<uniform> uShadow: ShadowUniforms;
+@group(${SHADER_BIND_GROUP.shadow}) @binding(${SHADOW_BINDING.map})
+var uShadowMap: texture_depth_2d;
+@group(${SHADER_BIND_GROUP.shadow}) @binding(${SHADOW_BINDING.sampler})
+var uShadowSampler: sampler_comparison;
+
+struct VertexIn {
+  @location(${VERTEX_ATTRIBUTE.position}) position: vec3f,
+  @location(${VERTEX_ATTRIBUTE.normal}) normal: vec3f,
+  @location(${VERTEX_ATTRIBUTE.uv}) uv: vec2f,
+};
+
+// Returns the fraction of the 3x3 comparison-filter kernel that can see the
+// directional light. Coordinates outside the configured shadow camera stay
+// fully lit rather than clamping to the map's edge.
+fn directionalShadow(n: vec3f, worldPosition: vec3f) -> f32 {
+  if (uShadow.params.x < 0.5 || uObject.shadowFlags.x < 0.5) {
+    return 1.0;
+  }
+
+  let biasedPosition = worldPosition + n * uShadow.params.z;
+  let clip = uShadow.viewProjection * vec4f(biasedPosition, 1.0);
+  if (clip.w <= 0.0) {
+    return 1.0;
+  }
+
+  let ndc = clip.xyz / clip.w;
+  let uv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
+  if (
+    uv.x < 0.0 || uv.x > 1.0 ||
+    uv.y < 0.0 || uv.y > 1.0 ||
+    ndc.z < 0.0 || ndc.z > 1.0
+  ) {
+    return 1.0;
+  }
+
+  let referenceDepth = ndc.z - uShadow.params.y;
+  var visibility = 0.0;
+  for (var y = -1; y <= 1; y++) {
+    for (var x = -1; x <= 1; x++) {
+      let offset = vec2f(f32(x), f32(y)) * uShadow.params.w;
+      visibility += textureSampleCompareLevel(
+        uShadowMap,
+        uShadowSampler,
+        uv + offset,
+        referenceDepth,
+      );
+    }
+  }
+  return visibility / 9.0;
+}
+
+// Ambient + the directional light + the point lights on a diffuse
+// surface, in linear space. Lit fragment shaders multiply the surface
+// color by this.
+fn diffuseLighting(n: vec3f, worldPosition: vec3f) -> vec3f {
+  var lighting = uFrame.ambientColor;
+  let toLight = normalize(-uFrame.lightDirection);
+  let shadow = directionalShadow(n, worldPosition);
+  lighting += max(dot(n, toLight), 0.0) * uFrame.lightColor * shadow;
+  let count = u32(uFrame.pointLightCount);
+  for (var i = 0u; i < count; i++) {
+    let offset = uFrame.pointLights[i].position - worldPosition;
+    let distanceSq = max(dot(offset, offset), 1e-6);
+    // 1 / (1 + d^2) falloff: intensity is the brightness right at the
+    // light, fading smoothly and never blowing up at zero distance.
+    let attenuation = 1.0 / (1.0 + distanceSq);
+    let direction = offset * inverseSqrt(distanceSq);
+    lighting += max(dot(n, direction), 0.0) * attenuation
+      * uFrame.pointLights[i].color;
+  }
+  return lighting;
+}
+`;

package/src/3d/shaders/vertexLayout.js

@@ -0,0 +1,85 @@
+import { VERTEX_STRIDE } from '../geometries/Geometry.js';
+import { INSTANCE_SIZE } from '../constants.js';
+import { INSTANCE_STEP_MODE } from '../../core/pipelineConstants.js';
+
+const FLOAT_BYTES = Float32Array.BYTES_PER_ELEMENT;
+const VEC2_BYTES = 2 * FLOAT_BYTES;
+const VEC3_BYTES = 3 * FLOAT_BYTES;
+const VEC4_BYTES = 4 * FLOAT_BYTES;
+const MAT4_BYTES = 4 * VEC4_BYTES;
+
+/** Vertex input locations shared by WGSL and the GPU buffer descriptors. */
+export const VERTEX_ATTRIBUTE = Object.freeze({
+  position: 0,
+  normal: 1,
+  uv: 2,
+  instanceMatrix0: 3,
+  instanceMatrix1: 4,
+  instanceMatrix2: 5,
+  instanceMatrix3: 6,
+  instanceColor: 7,
+});
+
+export const GEOMETRY_VERTEX_BUFFER_LAYOUT = Object.freeze({
+  arrayStride: VERTEX_STRIDE,
+  attributes: Object.freeze([
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE.position,
+      offset: 0,
+      format: 'float32x3',
+    }),
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE.normal,
+      offset: VEC3_BYTES,
+      format: 'float32x3',
+    }),
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE.uv,
+      offset: 2 * VEC3_BYTES,
+      format: 'float32x2',
+    }),
+  ]),
+});
+
+export const INSTANCE_VERTEX_BUFFER_LAYOUT = Object.freeze({
+  arrayStride: INSTANCE_SIZE * FLOAT_BYTES,
+  stepMode: INSTANCE_STEP_MODE,
+  attributes: Object.freeze([
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE.instanceMatrix0,
+      offset: 0,
+      format: 'float32x4',
+    }),
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE.instanceMatrix1,
+      offset: VEC4_BYTES,
+      format: 'float32x4',
+    }),
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE.instanceMatrix2,
+      offset: 2 * VEC4_BYTES,
+      format: 'float32x4',
+    }),
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE.instanceMatrix3,
+      offset: 3 * VEC4_BYTES,
+      format: 'float32x4',
+    }),
+    Object.freeze({
+      shaderLocation: VERTEX_ATTRIBUTE.instanceColor,
+      offset: MAT4_BYTES,
+      format: 'float32x4',
+    }),
+  ]),
+});
+
+const STANDARD_VERTEX_BUFFERS = Object.freeze([GEOMETRY_VERTEX_BUFFER_LAYOUT]);
+const INSTANCED_VERTEX_BUFFERS = Object.freeze([
+  GEOMETRY_VERTEX_BUFFER_LAYOUT,
+  INSTANCE_VERTEX_BUFFER_LAYOUT,
+]);
+
+/** GPU vertex buffer layouts for a regular or instanced mesh pipeline. */
+export function vertexBufferLayouts(instanced) {
+  return instanced ? INSTANCED_VERTEX_BUFFERS : STANDARD_VERTEX_BUFFERS;
+}

package/src/3d/shaders/vertexStages.js

@@ -0,0 +1,70 @@
+import { SHARED_SHADER_CHUNKS } from './shared.js';
+import { VERTEX_ATTRIBUTE } from './vertexLayout.js';
+
+/** Shared chunks plus the regular mesh vertex stage. Append a fragment stage. */
+export const MESH_SHADER_PREFIX =
+  SHARED_SHADER_CHUNKS +
+  /* wgsl */ `
+struct VertexOut {
+  @builtin(position) position: vec4f,
+  @location(0) worldNormal: vec3f,
+  @location(1) uv: vec2f,
+  @location(2) worldPosition: vec3f,
+};
+
+@vertex
+fn vs(input: VertexIn) -> VertexOut {
+  var out: VertexOut;
+  let worldPosition = uObject.model * vec4f(input.position, 1.0);
+  out.position = uFrame.viewProjection * worldPosition;
+  out.worldNormal = (uObject.normalMatrix * vec4f(input.normal, 0.0)).xyz;
+  out.uv = input.uv;
+  out.worldPosition = worldPosition.xyz;
+  return out;
+}
+
+fn objectColor(input: VertexOut) -> vec4f {
+  return uObject.color;
+}
+`;
+
+/** Shared chunks plus the per-instance mesh vertex stage. Append a fragment stage. */
+export const INSTANCED_MESH_SHADER_PREFIX =
+  SHARED_SHADER_CHUNKS +
+  /* wgsl */ `
+struct InstanceIn {
+  @location(${VERTEX_ATTRIBUTE.instanceMatrix0}) im0: vec4f,
+  @location(${VERTEX_ATTRIBUTE.instanceMatrix1}) im1: vec4f,
+  @location(${VERTEX_ATTRIBUTE.instanceMatrix2}) im2: vec4f,
+  @location(${VERTEX_ATTRIBUTE.instanceMatrix3}) im3: vec4f,
+  @location(${VERTEX_ATTRIBUTE.instanceColor}) color: vec4f,
+};
+
+struct VertexOut {
+  @builtin(position) position: vec4f,
+  @location(0) worldNormal: vec3f,
+  @location(1) uv: vec2f,
+  @location(2) color: vec4f,
+  @location(3) worldPosition: vec3f,
+};
+
+@vertex
+fn vs(input: VertexIn, instance: InstanceIn) -> VertexOut {
+  var out: VertexOut;
+  let instanceMatrix = mat4x4f(instance.im0, instance.im1, instance.im2, instance.im3);
+  let worldPosition = uObject.model * instanceMatrix * vec4f(input.position, 1.0);
+  out.position = uFrame.viewProjection * worldPosition;
+  // The instance matrix's upper 3x3 handles rotation + uniform scale
+  // (lighting normalizes); per-instance non-uniform scale skews normals.
+  let rotation = mat3x3f(instance.im0.xyz, instance.im1.xyz, instance.im2.xyz);
+  out.worldNormal = (uObject.normalMatrix * vec4f(rotation * input.normal, 0.0)).xyz;
+  out.uv = input.uv;
+  out.color = instance.color;
+  out.worldPosition = worldPosition.xyz;
+  return out;
+}
+
+fn objectColor(input: VertexOut) -> vec4f {
+  return input.color * uObject.color;
+}
+`;

package/src/core/PointerControls.js

@@ -0,0 +1,258 @@
+export const TOUCH_GESTURE = Object.freeze({
+  PAN: 'pan',
+  ROTATE: 'rotate',
+});
+
+const MOUSE_POINTER_TYPE = 'mouse';
+const RIGHT_MOUSE_BUTTON = 2;
+const LEFT_MOUSE_BUTTON = 0;
+const TWO_TOUCHES = 2;
+const NDC_SPAN = 2;
+const CONTEXT_MENU_PAN_THRESHOLD = 3;
+const DEFAULT_ROTATE_SPEED = 0.005;
+const DEFAULT_ZOOM_SPEED = 0.001;
+const touchActionClaims = new WeakMap();
+
+function claimTouchAction(element) {
+  let claim = touchActionClaims.get(element);
+  if (!claim) {
+    claim = { owners: 0, previous: element.style.touchAction };
+    touchActionClaims.set(element, claim);
+  }
+  claim.owners++;
+  element.style.touchAction = 'none';
+}
+
+function releaseTouchAction(element) {
+  const claim = touchActionClaims.get(element);
+  if (!claim) return;
+  claim.owners--;
+  if (claim.owners === 0) {
+    element.style.touchAction = claim.previous;
+    touchActionClaims.delete(element);
+  }
+}
+
+/**
+ * The pointer / wheel plumbing shared by the camera controls
+ * (OrbitControls in 3D, PanZoomControls in 2D). Owns everything about
+ * reading the input device: button roles, pointer capture, keeping the
+ * browser context menu available after a plain right-click, turning
+ * wheel events into zoom factors with the cursor position in NDC, and
+ * the touch gestures.
+ *
+ * Mouse gestures: right-drag pans, Alt + left-drag rotates, scroll
+ * zooms toward the cursor. Touch gestures: a one-finger drag pans or
+ * rotates (see `singleTouchGesture`), a two-finger drag pans, and
+ * pinching zooms toward the midpoint between the fingers.
+ *
+ * Subclasses implement just the camera math:
+ *   _pan(dx, dy)               pan deltas, in pixels
+ *   _rotate(rx, ry)            rotation deltas, pre-scaled by rotateSpeed
+ *   _zoom(factor, ndcX, ndcY)  zoom factor plus the cursor in -1..1 NDC
+ */
+export class PointerControls {
+  constructor(domElement) {
+    this.domElement = domElement;
+
+    /** Set to false to ignore input, e.g. while dragging an object. */
+    this.enabled = true;
+    this.rotateSpeed = DEFAULT_ROTATE_SPEED;
+    this.zoomSpeed = DEFAULT_ZOOM_SPEED;
+    /** Set to false to disable the rotate gesture (pan and zoom still work). */
+    this.enableRotate = true;
+    /**
+     * What a one-finger touch drag does: 'pan' (default) or 'rotate'.
+     * Two-finger gestures always pan and pinch-zoom.
+     */
+    this.singleTouchGesture = TOUCH_GESTURE.PAN;
+
+    this._dragging = false;
+    this._panning = false;
+    this._leftDrag = false;
+    this._panDistance = 0;
+    this._lastX = 0;
+    this._lastY = 0;
+    this._mousePointerId = null;
+    this._touches = new Map(); // pointerId -> {x, y} of active touch points
+    this._pinchDistance = 0;
+    this._disposed = false;
+
+    // Without this the browser claims touch drags for scrolling and
+    // pinches for page zoom before the pointer events reach us.
+    claimTouchAction(domElement);
+
+    this._onPointerDown = this._handlePointerDown.bind(this);
+    this._onPointerMove = this._handlePointerMove.bind(this);
+    this._onPointerUp = this._handlePointerUp.bind(this);
+    this._onContextMenu = this._handleContextMenu.bind(this);
+    this._onWheel = this._handleWheel.bind(this);
+
+    domElement.addEventListener('pointerdown', this._onPointerDown);
+    domElement.addEventListener('pointermove', this._onPointerMove);
+    domElement.addEventListener('pointerup', this._onPointerUp);
+    domElement.addEventListener('pointercancel', this._onPointerUp);
+    domElement.addEventListener('contextmenu', this._onContextMenu);
+    domElement.addEventListener('wheel', this._onWheel, { passive: false });
+  }
+
+  _handlePointerDown(event) {
+    if (!this.enabled) return;
+    if (event.pointerType !== MOUSE_POINTER_TYPE) {
+      this._touches.set(event.pointerId, {
+        x: event.clientX,
+        y: event.clientY,
+      });
+      if (this._touches.size === TWO_TOUCHES) {
+        const [first, second] = this._touches.values();
+        this._pinchDistance = Math.hypot(
+          first.x - second.x,
+          first.y - second.y,
+        );
+      }
+      this.domElement.setPointerCapture(event.pointerId);
+      return;
+    }
+
+    this._dragging = true;
+    this._mousePointerId = event.pointerId;
+    this._panning = event.button === RIGHT_MOUSE_BUTTON;
+    this._leftDrag = event.button === LEFT_MOUSE_BUTTON;
+    if (this._panning) this._panDistance = 0;
+    this._lastX = event.clientX;
+    this._lastY = event.clientY;
+    this.domElement.setPointerCapture(event.pointerId);
+  }
+
+  _handlePointerMove(event) {
+    if (!this.enabled) return;
+    if (event.pointerType !== MOUSE_POINTER_TYPE) {
+      this._touchMove(event);
+      return;
+    }
+    if (!this._dragging || event.pointerId !== this._mousePointerId) return;
+
+    const dx = event.clientX - this._lastX;
+    const dy = event.clientY - this._lastY;
+    this._lastX = event.clientX;
+    this._lastY = event.clientY;
+    if (this._panning) {
+      this._panDistance += Math.abs(dx) + Math.abs(dy);
+      this._pan(dx, dy);
+    } else if (this._leftDrag && event.altKey && this.enableRotate) {
+      // Alt is checked per move event, so pressing it mid-drag starts
+      // rotating and releasing it pauses.
+      this._rotate(dx * this.rotateSpeed, dy * this.rotateSpeed);
+    }
+  }
+
+  _handlePointerUp(event) {
+    if (event.pointerType !== MOUSE_POINTER_TYPE) {
+      this._touches.delete(event.pointerId);
+      // Dropping below two fingers re-arms the pinch for next time.
+      this._pinchDistance = 0;
+    } else {
+      if (event.pointerId !== this._mousePointerId) return;
+      this._dragging = false;
+      this._mousePointerId = null;
+    }
+    this._releasePointer(event.pointerId);
+  }
+
+  _handleContextMenu(event) {
+    if (!this.enabled) return;
+    const wasPanGesture = this._panDistance > CONTEXT_MENU_PAN_THRESHOLD;
+    if (wasPanGesture || this._touches.size > 0) event.preventDefault();
+  }
+
+  _handleWheel(event) {
+    if (!this.enabled) return;
+    event.preventDefault();
+    const factor = Math.exp(event.deltaY * this.zoomSpeed);
+    const ndc = this._toNdc(event.clientX, event.clientY);
+    this._zoom(factor, ndc.x, ndc.y);
+  }
+
+  _releasePointer(pointerId) {
+    if (this.domElement.hasPointerCapture(pointerId)) {
+      this.domElement.releasePointerCapture(pointerId);
+    }
+  }
+
+  /** A client-space position in normalized device coordinates (-1..1). */
+  _toNdc(clientX, clientY) {
+    const rect = this.domElement.getBoundingClientRect();
+    return {
+      x: ((clientX - rect.left) / rect.width) * NDC_SPAN - 1,
+      y: 1 - ((clientY - rect.top) / rect.height) * NDC_SPAN,
+    };
+  }
+
+  _touchMove(e) {
+    const touch = this._touches.get(e.pointerId);
+    if (!touch) return;
+
+    if (this._touches.size === 1) {
+      const dx = e.clientX - touch.x;
+      const dy = e.clientY - touch.y;
+      touch.x = e.clientX;
+      touch.y = e.clientY;
+      if (
+        this.singleTouchGesture === TOUCH_GESTURE.ROTATE &&
+        this.enableRotate
+      ) {
+        this._rotate(dx * this.rotateSpeed, dy * this.rotateSpeed);
+      } else {
+        this._pan(dx, dy);
+      }
+      return;
+    }
+
+    // Two fingers: pan by the midpoint's motion and zoom by the pinch.
+    // Any finger beyond the first two is tracked but ignored.
+    const [a, b] = this._touches.values();
+    const midXBefore = (a.x + b.x) / 2;
+    const midYBefore = (a.y + b.y) / 2;
+    touch.x = e.clientX;
+    touch.y = e.clientY;
+    const midX = (a.x + b.x) / 2;
+    const midY = (a.y + b.y) / 2;
+    this._pan(midX - midXBefore, midY - midYBefore);
+
+    const distance = Math.hypot(a.x - b.x, a.y - b.y);
+    if (this._pinchDistance > 0 && distance > 0) {
+      // Spreading shrinks the factor below 1 (zoom in), matching the
+      // wheel's Math.exp convention.
+      const ndc = this._toNdc(midX, midY);
+      this._zoom(this._pinchDistance / distance, ndc.x, ndc.y);
+    }
+    this._pinchDistance = distance;
+  }
+
+  /* The camera math, provided by subclasses. */
+  _pan(dx, dy) {}
+  _rotate(rx, ry) {}
+  _zoom(factor, ndcX, ndcY) {}
+
+  dispose() {
+    if (this._disposed) return;
+    this._disposed = true;
+    if (this._mousePointerId !== null) {
+      this._releasePointer(this._mousePointerId);
+      this._mousePointerId = null;
+    }
+    for (const pointerId of this._touches.keys()) {
+      this._releasePointer(pointerId);
+    }
+    this._touches.clear();
+    this._dragging = false;
+    this._pinchDistance = 0;
+    releaseTouchAction(this.domElement);
+    this.domElement.removeEventListener('pointerdown', this._onPointerDown);
+    this.domElement.removeEventListener('pointermove', this._onPointerMove);
+    this.domElement.removeEventListener('pointerup', this._onPointerUp);
+    this.domElement.removeEventListener('pointercancel', this._onPointerUp);
+    this.domElement.removeEventListener('contextmenu', this._onContextMenu);
+    this.domElement.removeEventListener('wheel', this._onWheel);
+  }
+}

package/src/core/Texture.js

@@ -0,0 +1,87 @@
+/**
+ * An image a shader can sample, plus its sampler settings — plain data,
+ * like geometries and materials. Assign one to a material's `map` and
+ * the renderer uploads it lazily on first draw (see GpuResources /
+ * GpuResources2d, which cache the GPU side per device on `_gpu`).
+ *
+ * `source` is anything copyExternalImageToTexture accepts: an
+ * ImageBitmap, HTMLCanvasElement, OffscreenCanvas or HTMLImageElement.
+ * Use `Texture.load(url)` to get one from an image file.
+ *
+ * One Texture can be shared by renderers on the same or different
+ * devices. Each device receives its own GPU texture and sampler.
+ */
+export class Texture {
+  /**
+   * @param {ImageBitmap|HTMLCanvasElement|OffscreenCanvas|HTMLImageElement} source
+   * @param {object} [options]
+   * @param {GPUFilterMode}  [options.magFilter]    'linear' (default) or 'nearest'
+   * @param {GPUFilterMode}  [options.minFilter]    'linear' (default) or 'nearest'
+   * @param {GPUAddressMode} [options.addressModeU] 'clamp-to-edge' (default),
+   *   'repeat' or 'mirror-repeat' — what happens outside 0..1 UVs
+   * @param {GPUAddressMode} [options.addressModeV] same, for v
+   * @param {boolean} [options.flipY] flip the image vertically on upload;
+   *   useful when a geometry's v axis points up (e.g. RectGeometry) so
+   *   images would otherwise appear upside down
+   * @param {boolean} [options.mipmaps] generate a full mip chain on
+   *   upload (default true) so minified sampling doesn't alias; turn
+   *   off for textures that never shrink on screen (UI, full-screen)
+   * @param {boolean} [options.srgb] the image holds sRGB-encoded colors
+   *   (default true — the normal case for pictures): the GPU decodes
+   *   samples to linear for shading, and mipmaps are filtered in linear
+   *   space. Turn off for data textures whose values aren't colors
+   */
+  constructor(
+    source,
+    {
+      magFilter = 'linear',
+      minFilter = 'linear',
+      addressModeU = 'clamp-to-edge',
+      addressModeV = 'clamp-to-edge',
+      flipY = false,
+      mipmaps = true,
+      srgb = true,
+    } = {},
+  ) {
+    this.source = source;
+    this.magFilter = magFilter;
+    this.minFilter = minFilter;
+    this.addressModeU = addressModeU;
+    this.addressModeV = addressModeV;
+    this.flipY = flipY;
+    this.mipmaps = mipmaps;
+    this.srgb = srgb;
+    this._gpu = null;
+  }
+
+  get width() {
+    return this.source.width;
+  }
+
+  get height() {
+    return this.source.height;
+  }
+
+  /**
+   * Destroys every uploaded GPU texture (if any), releasing its memory
+   * right away instead of waiting for GC. The next draw on each device
+   * uploads it again, and meshes/shapes rebuild their bind groups.
+   */
+  dispose() {
+    if (this._gpu) {
+      for (const { texture } of this._gpu.values()) texture.destroy();
+      this._gpu = null;
+    }
+    return this;
+  }
+
+  /** Fetches an image file and wraps it in a Texture. */
+  static async load(url, options) {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`Texture.load: ${url} responded ${response.status}`);
+    }
+    const bitmap = await createImageBitmap(await response.blob());
+    return new Texture(bitmap, options);
+  }
+}