micro-gl 0.1.0

package/src/3d/core/DirectionalShadowMap.js

@@ -0,0 +1,283 @@
+import { Mat4 } from '../../math/Mat4.js';
+import { Vec3 } from '../../math/Vec3.js';
+import {
+  INDEX_FORMAT,
+  SHADER_BIND_GROUP,
+  SHADER_BINDING,
+  SHADOW_BINDING,
+  VERTEX_BUFFER_SLOT,
+} from '../../core/pipelineConstants.js';
+import {
+  DIRECTIONAL_SHADOW_DEPTH_FORMAT,
+  SHADOW_SAMPLE_COUNT,
+} from '../constants.js';
+import { ShadowPipelines } from './ShadowPipelines.js';
+
+const FLOAT_BYTES = Float32Array.BYTES_PER_ELEMENT;
+const MAT4_FLOATS = 16;
+const PARAM_FLOATS = 4;
+const SHADOW_UNIFORM_FLOATS = MAT4_FLOATS + PARAM_FLOATS;
+const SHADOW_UNIFORM_SIZE = SHADOW_UNIFORM_FLOATS * FLOAT_BYTES;
+const SHADOW_MAP_FALLBACK_SIZE = 1;
+const SHADOW_DEPTH_CLEAR_VALUE = 1;
+const DIRECTION_EPSILON = 1e-12;
+
+export const SHADOW_UNIFORM_OFFSET = Object.freeze({
+  viewProjection: 0,
+  enabled: MAT4_FLOATS,
+  bias: MAT4_FLOATS + 1,
+  normalBias: MAT4_FLOATS + 2,
+  texelSize: MAT4_FLOATS + 3,
+});
+
+/**
+ * Renderer-local depth texture, uniforms and render pass for the first
+ * directional light in a scene. Lights only retain CPU configuration, so the
+ * same scene can be rendered safely by different GPU devices.
+ */
+export class DirectionalShadowMap {
+  constructor(device, samplingLayout, objectLayout) {
+    this.device = device;
+    this.enabled = false;
+    this._mapSize = 0;
+    this._data = new Float32Array(SHADOW_UNIFORM_FLOATS);
+    this._identity = new Mat4();
+    this._direction = new Vec3();
+    this._uniformBuffer = null;
+    this._texture = null;
+
+    try {
+      this._uniformBuffer = device.createBuffer({
+        label: 'Directional shadow uniforms',
+        size: SHADOW_UNIFORM_SIZE,
+        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+      });
+      this._shadowUniformLayout = device.createBindGroupLayout({
+        label: 'Directional shadow pass uniforms',
+        entries: [
+          {
+            binding: SHADER_BINDING.uniforms,
+            visibility: GPUShaderStage.VERTEX,
+            buffer: {},
+          },
+        ],
+      });
+      this._shadowUniformBindGroup = device.createBindGroup({
+        label: 'Directional shadow pass uniforms',
+        layout: this._shadowUniformLayout,
+        entries: [
+          {
+            binding: SHADER_BINDING.uniforms,
+            resource: { buffer: this._uniformBuffer },
+          },
+        ],
+      });
+      this._sampler = device.createSampler({
+        label: 'Directional shadow comparison sampler',
+        addressModeU: 'clamp-to-edge',
+        addressModeV: 'clamp-to-edge',
+        minFilter: 'linear',
+        magFilter: 'linear',
+        compare: 'less-equal',
+      });
+      this._samplingLayout = samplingLayout;
+      this._pipelines = new ShadowPipelines(
+        device,
+        this._shadowUniformLayout,
+        objectLayout,
+      );
+      this._replaceTexture(SHADOW_MAP_FALLBACK_SIZE);
+      this._writeDisabledUniforms();
+    } catch (error) {
+      this.dispose();
+      throw error;
+    }
+  }
+
+  /** Sampling bind group bound by the renderer's color pass. */
+  get bindGroup() {
+    return this._samplingBindGroup;
+  }
+
+  /**
+   * Validates the light's configuration, resizes the map if necessary and
+   * uploads the light-camera transform. Returns whether a depth pass is needed.
+   */
+  update(light) {
+    if (!light || !light.castShadow) {
+      const wasEnabled = this.enabled;
+      this.enabled = false;
+      if (wasEnabled) this._writeDisabledUniforms();
+      return false;
+    }
+
+    const shadow = light.shadow;
+    validateShadow(shadow, this.device.limits?.maxTextureDimension2D);
+    if (shadow.mapSize !== this._mapSize) {
+      this._replaceTexture(shadow.mapSize);
+    }
+
+    const camera = shadow.camera;
+    const directionLength = light.direction.length();
+    if (Number.isFinite(directionLength) && directionLength > DIRECTION_EPSILON) {
+      this._direction.copy(light.direction).multiplyScalar(1 / directionLength);
+    } else {
+      this._direction.set(0, -1, 0);
+    }
+
+    const distance = (camera.near + camera.far) / 2;
+    camera.position.copy(camera.target);
+    camera.position.x -= this._direction.x * distance;
+    camera.position.y -= this._direction.y * distance;
+    camera.position.z -= this._direction.z * distance;
+    camera.aspect = 1;
+    camera.updateMatrices();
+
+    this._data.set(
+      camera.viewProjectionMatrix.elements,
+      SHADOW_UNIFORM_OFFSET.viewProjection,
+    );
+    this._data[SHADOW_UNIFORM_OFFSET.enabled] = 1;
+    this._data[SHADOW_UNIFORM_OFFSET.bias] = shadow.bias;
+    this._data[SHADOW_UNIFORM_OFFSET.normalBias] = shadow.normalBias;
+    this._data[SHADOW_UNIFORM_OFFSET.texelSize] = 1 / shadow.mapSize;
+    this.device.queue.writeBuffer(this._uniformBuffer, 0, this._data);
+    this.enabled = true;
+    return true;
+  }
+
+  /** Encodes and returns the number of caster instances drawn. */
+  render(encoder, casters) {
+    if (!this.enabled) return 0;
+
+    const pass = encoder.beginRenderPass({
+      label: 'Directional shadow pass',
+      colorAttachments: [],
+      depthStencilAttachment: {
+        view: this._textureView,
+        depthClearValue: SHADOW_DEPTH_CLEAR_VALUE,
+        depthLoadOp: 'clear',
+        depthStoreOp: 'store',
+      },
+    });
+    pass.setBindGroup(SHADER_BIND_GROUP.frame, this._shadowUniformBindGroup);
+
+    let drawCount = 0;
+    for (const { mesh, geometryGPU, meshGPU } of casters) {
+      const instanced = !!mesh.isInstanced;
+      pass.setPipeline(this._pipelines.pipelineFor(mesh.material, instanced));
+      pass.setBindGroup(SHADER_BIND_GROUP.object, meshGPU.shadowBindGroup);
+      pass.setVertexBuffer(
+        VERTEX_BUFFER_SLOT.geometry,
+        geometryGPU.vertexBuffer,
+      );
+      if (instanced) {
+        pass.setVertexBuffer(
+          VERTEX_BUFFER_SLOT.instance,
+          meshGPU.instanceBuffer,
+        );
+      }
+      pass.setIndexBuffer(geometryGPU.indexBuffer, INDEX_FORMAT);
+      pass.drawIndexed(mesh.geometry.indexCount, instanced ? mesh.count : 1);
+      drawCount += instanced ? mesh.count : 1;
+    }
+    pass.end();
+    return drawCount;
+  }
+
+  dispose() {
+    if (this._texture) this._texture.destroy();
+    if (this._uniformBuffer) this._uniformBuffer.destroy();
+    this._texture = null;
+    this._textureView = null;
+    this._uniformBuffer = null;
+    this._samplingBindGroup = null;
+    this.enabled = false;
+  }
+
+  _writeDisabledUniforms() {
+    this._data.set(
+      this._identity.elements,
+      SHADOW_UNIFORM_OFFSET.viewProjection,
+    );
+    this._data.fill(0, SHADOW_UNIFORM_OFFSET.enabled);
+    this._data[SHADOW_UNIFORM_OFFSET.texelSize] = 1 / this._mapSize;
+    this.device.queue.writeBuffer(this._uniformBuffer, 0, this._data);
+  }
+
+  _replaceTexture(mapSize) {
+    const texture = this.device.createTexture({
+      label: 'Directional shadow map',
+      size: [mapSize, mapSize],
+      format: DIRECTIONAL_SHADOW_DEPTH_FORMAT,
+      sampleCount: SHADOW_SAMPLE_COUNT,
+      usage:
+        GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+    });
+    let textureView;
+    let samplingBindGroup;
+    try {
+      textureView = texture.createView();
+      samplingBindGroup = this.device.createBindGroup({
+        label: 'Directional shadow sampling',
+        layout: this._samplingLayout,
+        entries: [
+          {
+            binding: SHADOW_BINDING.uniforms,
+            resource: { buffer: this._uniformBuffer },
+          },
+          { binding: SHADOW_BINDING.map, resource: textureView },
+          { binding: SHADOW_BINDING.sampler, resource: this._sampler },
+        ],
+      });
+    } catch (error) {
+      texture.destroy();
+      throw error;
+    }
+
+    const previousTexture = this._texture;
+    this._texture = texture;
+    this._textureView = textureView;
+    this._samplingBindGroup = samplingBindGroup;
+    this._mapSize = mapSize;
+    if (previousTexture) previousTexture.destroy();
+  }
+}
+
+function validateShadow(shadow, maxTextureDimension) {
+  if (!shadow || !shadow.camera) {
+    throw new TypeError('DirectionalLight.shadow must be a DirectionalShadow');
+  }
+  if (!Number.isInteger(shadow.mapSize) || shadow.mapSize < 1) {
+    throw new RangeError('DirectionalShadow.mapSize must be a positive integer');
+  }
+  if (
+    Number.isFinite(maxTextureDimension) &&
+    shadow.mapSize > maxTextureDimension
+  ) {
+    throw new RangeError(
+      `DirectionalShadow.mapSize cannot exceed ${maxTextureDimension}`,
+    );
+  }
+  if (!Number.isFinite(shadow.bias) || !Number.isFinite(shadow.normalBias)) {
+    throw new RangeError('Directional shadow biases must be finite numbers');
+  }
+
+  const { camera } = shadow;
+  if (!Number.isFinite(camera.size) || camera.size <= 0) {
+    throw new RangeError('Directional shadow camera size must be positive');
+  }
+  if (!Number.isFinite(camera.zoom) || camera.zoom <= 0) {
+    throw new RangeError('Directional shadow camera zoom must be positive');
+  }
+  if (
+    !Number.isFinite(camera.near) ||
+    !Number.isFinite(camera.far) ||
+    camera.near < 0 ||
+    camera.far <= camera.near
+  ) {
+    throw new RangeError(
+      'Directional shadow camera requires 0 <= near < far',
+    );
+  }
+}

package/src/3d/core/GpuResources.js

@@ -0,0 +1,174 @@
+import { uploadTexture } from '../../core/uploadTexture.js';
+import { SINGLE_SAMPLE_COUNT } from '../../core/rendererConfig.js';
+import { SHADER_BINDING } from '../../core/pipelineConstants.js';
+import { materialUsesMap } from '../../core/materialResources.js';
+import {
+  disposeOwnedObjectGpuResources,
+  trackObjectGpuResource,
+} from '../../core/objectGpuResources.js';
+import { Pipelines } from './Pipelines.js';
+import { OBJECT_UNIFORM_SIZE } from './Uniforms.js';
+
+export { OBJECT_UNIFORM_SIZE } from './Uniforms.js';
+
+/**
+ * Owns the GPU resources the renderer creates on behalf of geometries,
+ * materials and meshes, so scene objects stay plain data:
+ *
+ *   - vertex + index buffers per geometry
+ *   - a GPU texture + sampler per Texture
+ *   - a small uniform buffer + bind group per mesh
+ *
+ * Everything is created lazily on first use. Geometry and texture
+ * resources are cached per GPUDevice; mesh resources are cached per
+ * GpuResources instance because their bind groups use this instance's
+ * layouts. Render pipelines and their shared layouts live in Pipelines.
+ */
+export class GpuResources {
+  constructor(device, format, sampleCount = SINGLE_SAMPLE_COUNT) {
+    this.device = device;
+    this.pipelines = new Pipelines(device, format, sampleCount);
+    this._objectGpuResourceRefs = new Set();
+    // The renderer builds its per-frame bind group against this layout.
+    this.frameBindGroupLayout = this.pipelines.frameBindGroupLayout;
+    this.objectBindGroupLayout = this.pipelines.objectBindGroupLayout;
+    this.shadowBindGroupLayout = this.pipelines.shadowBindGroupLayout;
+  }
+
+  /** The render pipeline for a material + pipeline state — see Pipelines. */
+  pipelineFor(material, instanced = false) {
+    return this.pipelines.pipelineFor(material, instanced);
+  }
+
+  /** GPU texture, view and sampler for a Texture, uploaded on first use. */
+  textureFor(texture) {
+    return uploadTexture(this.device, texture);
+  }
+
+  /**
+   * Vertex and index buffers for a geometry, re-uploaded when its
+   * `needsUpdate` flag is set.
+   */
+  geometryFor(geometry) {
+    const cache = geometry._gpu || (geometry._gpu = new Map());
+    let gpu = cache.get(this.device);
+
+    if (!gpu) {
+      const vertexBuffer = this.device.createBuffer({
+        size: geometry.vertices.byteLength,
+        usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+      });
+      this.device.queue.writeBuffer(vertexBuffer, 0, geometry.vertices);
+
+      const indexBuffer = this.device.createBuffer({
+        size: geometry.indices.byteLength,
+        usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+      });
+      this.device.queue.writeBuffer(indexBuffer, 0, geometry.indices);
+
+      gpu = {
+        vertexBuffer,
+        indexBuffer,
+        revision: geometry._gpuRevision,
+      };
+      cache.set(this.device, gpu);
+    } else if (
+      geometry.needsUpdate ||
+      gpu.revision !== geometry._gpuRevision
+    ) {
+      this.device.queue.writeBuffer(gpu.vertexBuffer, 0, geometry.vertices);
+      this.device.queue.writeBuffer(gpu.indexBuffer, 0, geometry.indices);
+      gpu.revision = geometry._gpuRevision;
+    }
+
+    // Revisions keep the other devices' caches stale until each is drawn,
+    // so clearing this public hint here cannot make them miss an update.
+    geometry.needsUpdate = false;
+    return gpu;
+  }
+
+  /**
+   * Uniform buffer, bind group and staging array for a mesh. The bind
+   * group is rebuilt automatically whenever the material's `map`
+   * changes (a swapped material, a swapped texture, or a Texture
+   * re-uploaded after `dispose()`).
+   */
+  meshFor(mesh) {
+    const cache = mesh._gpu || (mesh._gpu = new Map());
+    let gpu = cache.get(this);
+    if (!gpu) {
+      gpu = {
+        uniformBuffer: this.device.createBuffer({
+          size: OBJECT_UNIFORM_SIZE,
+          usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        }),
+        bindGroup: null,
+        shadowBindGroup: null,
+        mapGpu: null, // the uploaded texture the bind group samples
+        data: new Float32Array(
+          OBJECT_UNIFORM_SIZE / Float32Array.BYTES_PER_ELEMENT,
+        ),
+      };
+      gpu.shadowBindGroup = this.device.createBindGroup({
+        layout: this.pipelines.objectBindGroupLayout,
+        entries: [
+          {
+            binding: SHADER_BINDING.uniforms,
+            resource: { buffer: gpu.uniformBuffer },
+          },
+        ],
+      });
+      if (mesh.isInstanced) {
+        gpu.instanceBuffer = this.device.createBuffer({
+          size: mesh.instanceData.byteLength,
+          usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        gpu.instanceRevision = null; // this fresh buffer has no data yet
+      }
+      cache.set(this, gpu);
+      trackObjectGpuResource(this, mesh, gpu);
+    }
+
+    if (
+      mesh.isInstanced &&
+      (mesh.needsUpdate ||
+        gpu.instanceRevision !== mesh._instanceRevision)
+    ) {
+      this.device.queue.writeBuffer(
+        gpu.instanceBuffer,
+        0,
+        mesh.instanceData,
+      );
+      gpu.instanceRevision = mesh._instanceRevision;
+      mesh.needsUpdate = false;
+    }
+
+    const mapGpu = materialUsesMap(mesh.material)
+      ? this.textureFor(mesh.material.map)
+      : null;
+    if (!gpu.bindGroup || gpu.mapGpu !== mapGpu) {
+      let layout = this.pipelines.objectBindGroupLayout;
+      const entries = [
+        {
+          binding: SHADER_BINDING.uniforms,
+          resource: { buffer: gpu.uniformBuffer },
+        },
+      ];
+      if (mapGpu) {
+        layout = this.pipelines.texturedObjectBindGroupLayout;
+        entries.push(
+          { binding: SHADER_BINDING.map, resource: mapGpu.view },
+          { binding: SHADER_BINDING.sampler, resource: mapGpu.sampler },
+        );
+      }
+      gpu.bindGroup = this.device.createBindGroup({ layout, entries });
+      gpu.mapGpu = mapGpu;
+    }
+    return gpu;
+  }
+
+  /** Releases this manager's per-object buffers and cache entries. */
+  dispose() {
+    disposeOwnedObjectGpuResources(this);
+  }
+}

package/src/3d/core/InstanceMatrix.js

@@ -0,0 +1,55 @@
+import {
+  INSTANCE_MATRIX_COMPONENTS,
+  INSTANCE_SIZE,
+} from '../constants.js';
+
+/** Whether one packed instance contains a finite affine mat4 transform. */
+export function isFiniteAffineInstanceMatrix(data, offset) {
+  if (!hasMatrixComponents(data, offset)) return false;
+  for (
+    let component = 0;
+    component < INSTANCE_MATRIX_COMPONENTS;
+    component++
+  ) {
+    if (!Number.isFinite(data[offset + component])) return false;
+  }
+  return hasAffineRow(data, offset);
+}
+
+/** Copies one packed affine instance transform into a Mat4-like target. */
+export function copyAffineInstanceMatrix(data, instanceId, target) {
+  const offset = instanceId * INSTANCE_SIZE;
+  if (!hasMatrixComponents(data, offset)) return false;
+
+  const elements = target.elements;
+  for (
+    let component = 0;
+    component < INSTANCE_MATRIX_COMPONENTS;
+    component++
+  ) {
+    const value = data[offset + component];
+    if (!Number.isFinite(value)) return false;
+    elements[component] = value;
+  }
+  return hasAffineRow(elements, 0);
+}
+
+function hasMatrixComponents(data, offset) {
+  return (
+    data &&
+    Number.isInteger(offset) &&
+    offset >= 0 &&
+    offset + INSTANCE_MATRIX_COMPONENTS <= data.length
+  );
+}
+
+function hasAffineRow(elements, offset) {
+  // These values are exact for every affine Mat4 produced by the library.
+  // Even a tiny projective term can materially affect homogeneous coordinates.
+  return (
+    elements[offset + 3] === 0 &&
+    elements[offset + 7] === 0 &&
+    elements[offset + 11] === 0 &&
+    elements[offset + 15] === 1
+  );
+}

package/src/3d/core/InstancedBounds.js

@@ -0,0 +1,114 @@
+import { INSTANCE_SIZE } from '../constants.js';
+import { isFiniteAffineInstanceMatrix } from './InstanceMatrix.js';
+
+/**
+ * Builds the mesh-local AABB containing every `instanceMatrix * bounds`.
+ * Returns `null` when custom data cannot be represented safely, which tells
+ * the renderer to keep the batch visible rather than risk a false cull.
+ */
+export function computeInstancedBounds(bounds, instanceData, count) {
+  const min = bounds?.min;
+  const max = bounds?.max;
+  if (!hasFiniteBounds(min, max)) return null;
+  if (!Number.isInteger(count) || count < 0) return null;
+
+  const centerX = (min[0] + max[0]) / 2;
+  const centerY = (min[1] + max[1]) / 2;
+  const centerZ = (min[2] + max[2]) / 2;
+  const extentX = (max[0] - min[0]) / 2;
+  const extentY = (max[1] - min[1]) / 2;
+  const extentZ = (max[2] - min[2]) / 2;
+  const combinedMin = [Infinity, Infinity, Infinity];
+  const combinedMax = [-Infinity, -Infinity, -Infinity];
+
+  for (let instance = 0; instance < count; instance++) {
+    const offset = instance * INSTANCE_SIZE;
+    if (!isFiniteAffineInstanceMatrix(instanceData, offset)) return null;
+
+    const m00 = instanceData[offset];
+    const m10 = instanceData[offset + 1];
+    const m20 = instanceData[offset + 2];
+    const m01 = instanceData[offset + 4];
+    const m11 = instanceData[offset + 5];
+    const m21 = instanceData[offset + 6];
+    const m02 = instanceData[offset + 8];
+    const m12 = instanceData[offset + 9];
+    const m22 = instanceData[offset + 10];
+    const m03 = instanceData[offset + 12];
+    const m13 = instanceData[offset + 13];
+    const m23 = instanceData[offset + 14];
+
+    const transformedCenterX =
+      m00 * centerX + m01 * centerY + m02 * centerZ + m03;
+    const transformedCenterY =
+      m10 * centerX + m11 * centerY + m12 * centerZ + m13;
+    const transformedCenterZ =
+      m20 * centerX + m21 * centerY + m22 * centerZ + m23;
+    const transformedExtentX =
+      Math.abs(m00) * extentX +
+      Math.abs(m01) * extentY +
+      Math.abs(m02) * extentZ;
+    const transformedExtentY =
+      Math.abs(m10) * extentX +
+      Math.abs(m11) * extentY +
+      Math.abs(m12) * extentZ;
+    const transformedExtentZ =
+      Math.abs(m20) * extentX +
+      Math.abs(m21) * extentY +
+      Math.abs(m22) * extentZ;
+    if (
+      !Number.isFinite(transformedCenterX) ||
+      !Number.isFinite(transformedCenterY) ||
+      !Number.isFinite(transformedCenterZ) ||
+      !Number.isFinite(transformedExtentX) ||
+      !Number.isFinite(transformedExtentY) ||
+      !Number.isFinite(transformedExtentZ)
+    ) {
+      return null;
+    }
+
+    expandBounds(
+      combinedMin,
+      combinedMax,
+      transformedCenterX,
+      transformedCenterY,
+      transformedCenterZ,
+      transformedExtentX,
+      transformedExtentY,
+      transformedExtentZ,
+    );
+  }
+  return { min: combinedMin, max: combinedMax };
+}
+
+function hasFiniteBounds(min, max) {
+  if (!min || !max || min.length < 3 || max.length < 3) return false;
+  for (let axis = 0; axis < 3; axis++) {
+    if (
+      !Number.isFinite(min[axis]) ||
+      !Number.isFinite(max[axis]) ||
+      min[axis] > max[axis]
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function expandBounds(
+  min,
+  max,
+  centerX,
+  centerY,
+  centerZ,
+  extentX,
+  extentY,
+  extentZ,
+) {
+  min[0] = Math.min(min[0], centerX - extentX);
+  min[1] = Math.min(min[1], centerY - extentY);
+  min[2] = Math.min(min[2], centerZ - extentZ);
+  max[0] = Math.max(max[0], centerX + extentX);
+  max[1] = Math.max(max[1], centerY + extentY);
+  max[2] = Math.max(max[2], centerZ + extentZ);
+}