micro-gl 0.1.0

package/src/core/createMaterialPipelineLayouts.js

@@ -0,0 +1,114 @@
+import {
+  SHADER_BIND_GROUP,
+  SHADER_BINDING,
+  SHADOW_BINDING,
+} from './pipelineConstants.js';
+
+/**
+ * Creates the bind-group and pipeline layouts shared by the material system.
+ * The 2D and 3D engines differ only in which stages can read frame uniforms.
+ */
+export function createMaterialPipelineLayouts(
+  device,
+  frameVisibility,
+  { shadows = false } = {},
+) {
+  const objectVisibility =
+    GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT;
+
+  const frameBindGroupLayout = device.createBindGroupLayout({
+    entries: [
+      {
+        binding: SHADER_BINDING.uniforms,
+        visibility: frameVisibility,
+        buffer: {},
+      },
+    ],
+  });
+
+  const objectBindGroupLayout = device.createBindGroupLayout({
+    entries: [
+      {
+        binding: SHADER_BINDING.uniforms,
+        visibility: objectVisibility,
+        buffer: {},
+      },
+    ],
+  });
+
+  const texturedObjectBindGroupLayout = device.createBindGroupLayout({
+    entries: [
+      {
+        binding: SHADER_BINDING.uniforms,
+        visibility: objectVisibility,
+        buffer: {},
+      },
+      {
+        binding: SHADER_BINDING.map,
+        visibility: GPUShaderStage.FRAGMENT,
+        texture: {},
+      },
+      {
+        binding: SHADER_BINDING.sampler,
+        visibility: GPUShaderStage.FRAGMENT,
+        sampler: {},
+      },
+    ],
+  });
+
+  const shadowBindGroupLayout = shadows
+    ? device.createBindGroupLayout({
+        entries: [
+          {
+            binding: SHADOW_BINDING.uniforms,
+            visibility: GPUShaderStage.FRAGMENT,
+            buffer: {},
+          },
+          {
+            binding: SHADOW_BINDING.map,
+            visibility: GPUShaderStage.FRAGMENT,
+            texture: { sampleType: 'depth' },
+          },
+          {
+            binding: SHADOW_BINDING.sampler,
+            visibility: GPUShaderStage.FRAGMENT,
+            sampler: { type: 'comparison' },
+          },
+        ],
+      })
+    : null;
+
+  return {
+    frameBindGroupLayout,
+    objectBindGroupLayout,
+    texturedObjectBindGroupLayout,
+    shadowBindGroupLayout,
+    pipelineLayout: createPipelineLayout(
+      device,
+      frameBindGroupLayout,
+      objectBindGroupLayout,
+      shadowBindGroupLayout,
+    ),
+    texturedPipelineLayout: createPipelineLayout(
+      device,
+      frameBindGroupLayout,
+      texturedObjectBindGroupLayout,
+      shadowBindGroupLayout,
+    ),
+  };
+}
+
+function createPipelineLayout(
+  device,
+  frameLayout,
+  objectLayout,
+  shadowLayout,
+) {
+  const bindGroupLayouts = [];
+  bindGroupLayouts[SHADER_BIND_GROUP.frame] = frameLayout;
+  bindGroupLayouts[SHADER_BIND_GROUP.object] = objectLayout;
+  if (shadowLayout) {
+    bindGroupLayouts[SHADER_BIND_GROUP.shadow] = shadowLayout;
+  }
+  return device.createPipelineLayout({ bindGroupLayouts });
+}

package/src/core/deviceLease.js

@@ -0,0 +1,67 @@
+/**
+ * Coordinates renderers that deliberately share one canvas configuration and
+ * GPU device. Ownership moves to another live renderer when the original
+ * owner is disposed, and the device is destroyed only after the last member.
+ */
+
+export function acquireDeviceLease(renderer, gpu, shared = null) {
+  const sourceCanvas =
+    shared?.canvas || gpu?.canvas || gpu?.context?.canvas || null;
+  if (sourceCanvas && sourceCanvas !== renderer.canvas) {
+    throw new Error('Shared renderers must use the same canvas');
+  }
+  if (!gpu?.device || !gpu.context || !gpu.format) {
+    throw new Error('The shared renderer must be initialized before it is used');
+  }
+  if (!gpu.colorFormat) {
+    throw new Error(
+      'Shared WebGPU setups must provide an sRGB colorFormat configured in ' +
+        'the canvas context viewFormats',
+    );
+  }
+
+  if (shared?._deviceLease) {
+    const lease = shared._deviceLease;
+    lease.members.add(renderer);
+    renderer._deviceLease = lease;
+    renderer._ownsDevice = false;
+    return lease;
+  }
+
+  const managed = !shared;
+  const lease = {
+    device: gpu.device,
+    context: gpu.context,
+    format: gpu.format,
+    colorFormat: gpu.colorFormat,
+    canvas: renderer.canvas,
+    managed,
+    members: new Set([renderer]),
+  };
+  renderer._deviceLease = lease;
+  renderer._ownsDevice = managed;
+  return lease;
+}
+
+/**
+ * Releases one renderer's membership.
+ * @returns {boolean} whether this renderer must destroy/unconfigure the device
+ */
+export function releaseDeviceLease(renderer) {
+  const lease = renderer._deviceLease;
+  renderer._deviceLease = null;
+
+  // Supports renderers constructed manually in tests or older integrations.
+  if (!lease) return !!renderer._ownsDevice;
+
+  lease.members.delete(renderer);
+  if (!lease.managed || !renderer._ownsDevice) return false;
+
+  const successor = lease.members.values().next().value;
+  if (successor) {
+    successor._ownsDevice = true;
+    renderer._ownsDevice = false;
+    return false;
+  }
+  return true;
+}

package/src/core/generateMipmaps.js

@@ -0,0 +1,115 @@
+// WebGPU has no built-in mipmap generation, so we do the standard
+// trick: for each mip level, run a tiny render pass that draws a
+// fullscreen triangle sampling the previous level with linear
+// filtering. The pipeline is created once per device and cached.
+
+import { SHADER_ENTRY_POINT } from './pipelineConstants.js';
+
+const MIPMAP_BIND_GROUP = 0;
+const MIPMAP_BINDING = Object.freeze({
+  source: 0,
+  sampler: 1,
+});
+
+const MIPMAP_WGSL = /* wgsl */ `
+struct VertexOut {
+  @builtin(position) position: vec4f,
+  @location(0) uv: vec2f,
+};
+
+// One triangle that covers the whole target: uvs (0,0) (2,0) (0,2)
+// mapped so uv (0,0) lands on the destination's top-left texel.
+@vertex
+fn vs(@builtin(vertex_index) index: u32) -> VertexOut {
+  var out: VertexOut;
+  let uv = vec2f(f32((index << 1u) & 2u), f32(index & 2u));
+  out.position = vec4f(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, 0.0, 1.0);
+  out.uv = uv;
+  return out;
+}
+
+@group(${MIPMAP_BIND_GROUP}) @binding(${MIPMAP_BINDING.source})
+var src: texture_2d<f32>;
+@group(${MIPMAP_BIND_GROUP}) @binding(${MIPMAP_BINDING.sampler})
+var srcSampler: sampler;
+
+@fragment
+fn fs(input: VertexOut) -> @location(0) vec4f {
+  return textureSample(src, srcSampler, input.uv);
+}
+`;
+
+// device -> { module, sampler, pipelines: Map(texture format -> pipeline) }
+const generators = new WeakMap();
+
+/** Mip levels needed to take a width x height image down to 1x1. */
+export function mipLevelCount(width, height) {
+  return Math.floor(Math.log2(Math.max(width, height))) + 1;
+}
+
+/**
+ * Fills mip levels 1..levels-1 of `texture` (a GPUTexture of the given
+ * format whose level 0 is already written) by downsampling level by
+ * level. The texture must have TEXTURE_BINDING and RENDER_ATTACHMENT
+ * usage — the ones uploadTexture creates already do. For an '-srgb'
+ * format the samples decode to linear and the render target re-encodes,
+ * so the filtering itself happens in linear space.
+ */
+export function generateMipmaps(device, texture, levels, format) {
+  let generator = generators.get(device);
+  if (!generator) {
+    generator = {
+      module: device.createShaderModule({ code: MIPMAP_WGSL }),
+      sampler: device.createSampler({ minFilter: 'linear' }),
+      pipelines: new Map(),
+    };
+    generators.set(device, generator);
+  }
+  let pipeline = generator.pipelines.get(format);
+  if (!pipeline) {
+    pipeline = device.createRenderPipeline({
+      layout: 'auto',
+      vertex: {
+        module: generator.module,
+        entryPoint: SHADER_ENTRY_POINT.vertex,
+      },
+      fragment: {
+        module: generator.module,
+        entryPoint: SHADER_ENTRY_POINT.fragment,
+        targets: [{ format }],
+      },
+    });
+    generator.pipelines.set(format, pipeline);
+  }
+
+  const encoder = device.createCommandEncoder();
+  for (let level = 1; level < levels; level++) {
+    const bindGroup = device.createBindGroup({
+      layout: pipeline.getBindGroupLayout(0),
+      entries: [
+        {
+          binding: MIPMAP_BINDING.source,
+          resource: texture.createView({
+            baseMipLevel: level - 1,
+            mipLevelCount: 1,
+          }),
+        },
+        { binding: MIPMAP_BINDING.sampler, resource: generator.sampler },
+      ],
+    });
+    const pass = encoder.beginRenderPass({
+      colorAttachments: [
+        {
+          view: texture.createView({ baseMipLevel: level, mipLevelCount: 1 }),
+          loadOp: 'clear',
+          storeOp: 'store',
+        },
+      ],
+    });
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(MIPMAP_BIND_GROUP, bindGroup);
+    pass.draw(3);
+    pass.end();
+  }
+  device.queue.submit([encoder.finish()]);
+}

package/src/core/indexedTriangles.js

@@ -0,0 +1,53 @@
+import {
+  DEFAULT_PRIMITIVE_TOPOLOGY,
+  isTriangleTopology,
+} from './pipelineConstants.js';
+
+const UINT32_PRIMITIVE_RESTART = 0xffffffff;
+
+/**
+ * Visits indexed triangles in the same order and winding as WebGPU.
+ * Returning true from `visit` stops traversal early.
+ */
+export function forEachIndexedTriangle(indices, topology, visit) {
+  if (topology === DEFAULT_PRIMITIVE_TOPOLOGY) {
+    for (let offset = 0; offset + 2 < indices.length; offset += 3) {
+      if (visit(indices[offset], indices[offset + 1], indices[offset + 2])) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  if (!isTriangleTopology(topology)) return false;
+
+  let first = null;
+  let second = null;
+  let triangleIndex = 0;
+  for (const index of indices) {
+    if (index === UINT32_PRIMITIVE_RESTART) {
+      first = null;
+      second = null;
+      triangleIndex = 0;
+      continue;
+    }
+    if (first === null) {
+      first = index;
+      continue;
+    }
+    if (second === null) {
+      second = index;
+      continue;
+    }
+
+    const stopped =
+      triangleIndex % 2 === 0
+        ? visit(first, second, index)
+        : visit(second, first, index);
+    if (stopped) return true;
+    first = second;
+    second = index;
+    triangleIndex++;
+  }
+  return false;
+}

package/src/core/initWebGpu.js

@@ -0,0 +1,65 @@
+import { srgbColorFormat } from './rendererConfig.js';
+
+/**
+ * Requests the GPU adapter/device and configures the canvas for WebGPU.
+ * Shared by Renderer (3D) and Renderer2d so both engines can drive the
+ * same canvas: a canvas context can only be configured for one device,
+ * so two renderers on one canvas must share the result of a single
+ * initWebGpu call (see `renderer.init(shared)`).
+ *
+ * `format` is the canvas's base format; `colorFormat` is the compatible sRGB
+ * view used by render pipelines so blending, clears and MSAA resolve in linear
+ * space before the attachment encodes the stored canvas pixels.
+ *
+ * @returns {Promise<{device: GPUDevice, context: GPUCanvasContext,
+ *   format: GPUTextureFormat, colorFormat: GPUTextureFormat,
+ *   canvas: HTMLCanvasElement}>}
+ */
+export async function initWebGpu(canvas) {
+  if (!navigator.gpu) {
+    throw new Error('WebGPU is not supported in this browser.');
+  }
+  const adapter = await navigator.gpu.requestAdapter();
+  if (!adapter) {
+    throw new Error('No suitable GPU adapter found.');
+  }
+  const device = await adapter.requestDevice();
+  let context = null;
+  try {
+    context = canvas.getContext('webgpu');
+    if (!context) throw new Error('Could not create a WebGPU canvas context.');
+    const format = navigator.gpu.getPreferredCanvasFormat();
+    const colorFormat = srgbColorFormat(format);
+    context.configure({
+      device,
+      format,
+      viewFormats: [colorFormat],
+      alphaMode: 'opaque',
+    });
+
+    // Driver resets and GPU-process crashes otherwise freeze rendering
+    // silently; say what happened and how to recover. 'destroyed' is the
+    // deliberate renderer.dispose() path, not a failure.
+    device.lost.then((info) => {
+      if (info.reason !== 'destroyed') {
+        console.error(
+          `micro-gl: GPU device lost (${info.reason || 'unknown'}): ` +
+            `${info.message} Rendering has stopped. To recover, create and ` +
+            'initialize a new Renderer; scene resources upload ' +
+            'automatically when first drawn on the replacement device.',
+        );
+      }
+    });
+
+    return { device, context, format, colorFormat, canvas };
+  } catch (error) {
+    // A device was already allocated, so canvas-setup failure must not leak it.
+    try {
+      if (context) context.unconfigure();
+    } catch {
+      // Preserve the original setup error if the context also rejects cleanup.
+    }
+    device.destroy();
+    throw error;
+  }
+}

package/src/core/materialResources.js

@@ -0,0 +1,18 @@
+/**
+ * Returns whether a material's shader declares texture-map bindings.
+ *
+ * `usesMap` describes the shader interface and deliberately does not depend
+ * on the current value of `map`: changing a resource must not silently change
+ * the pipeline layout. A textured material without its resource is therefore
+ * reported as a clear application error before WebGPU validation runs.
+ */
+export function materialUsesMap(material) {
+  if (!material.usesMap && !material.requiresMap) return false;
+  if (material.map) return true;
+
+  throw new Error(
+    `${material.constructor.name}: \`map\` was cleared, but this material ` +
+      'always samples its texture — assign a Texture or switch to a ' +
+      'material without a map',
+  );
+}

package/src/core/objectGpuResources.js

@@ -0,0 +1,68 @@
+const orphanedResourceRegistry = new FinalizationRegistry(
+  ({ owner, resourceRef }) => {
+    owner._objectGpuResourceRefs.delete(resourceRef);
+  },
+);
+
+/**
+ * Registers one manager-owned GPU record without strongly retaining the
+ * record or its scene object. Their normal garbage-collection fallback stays
+ * intact when an application drops a transient object without dispose().
+ */
+export function trackObjectGpuResource(owner, object, gpu) {
+  gpu.owner = owner;
+  gpu.objectRef = new WeakRef(object);
+  gpu.resourceRef = new WeakRef(gpu);
+  gpu.disposed = false;
+  owner._objectGpuResourceRefs.add(gpu.resourceRef);
+  orphanedResourceRegistry.register(
+    gpu,
+    { owner, resourceRef: gpu.resourceRef },
+    gpu.resourceRef,
+  );
+}
+
+/** Destroys one mesh/shape record and unregisters it from its owner. */
+export function destroyObjectGpuResource(gpu) {
+  if (!gpu || gpu.disposed) return;
+  gpu.uniformBuffer.destroy();
+  if (gpu.instanceBuffer) gpu.instanceBuffer.destroy();
+  gpu.disposed = true;
+  if (gpu.resourceRef) {
+    orphanedResourceRegistry.unregister(gpu.resourceRef);
+    if (gpu.owner) {
+      gpu.owner._objectGpuResourceRefs.delete(gpu.resourceRef);
+    }
+  }
+  gpu.owner = null;
+  gpu.resourceRef = null;
+}
+
+/** Releases all renderer-manager records attached to one scene object. */
+export function disposeObjectGpuResources(object) {
+  if (!object._gpu) return;
+  for (const gpu of object._gpu.values()) destroyObjectGpuResource(gpu);
+  object._gpu = null;
+}
+
+/**
+ * Releases only the records owned by one resource manager. Other renderers'
+ * cache entries on the same scene objects remain valid.
+ */
+export function disposeOwnedObjectGpuResources(owner) {
+  for (const resourceRef of [...owner._objectGpuResourceRefs]) {
+    const gpu = resourceRef.deref();
+    if (!gpu) {
+      orphanedResourceRegistry.unregister(resourceRef);
+      owner._objectGpuResourceRefs.delete(resourceRef);
+      continue;
+    }
+    const object = gpu.objectRef.deref();
+    destroyObjectGpuResource(gpu);
+    if (object?._gpu?.get(owner) === gpu) {
+      object._gpu.delete(owner);
+      if (object._gpu.size === 0) object._gpu = null;
+    }
+  }
+  owner._objectGpuResourceRefs.clear();
+}

package/src/core/pipelineConstants.js

@@ -0,0 +1,68 @@
+/**
+ * Names shared by the JavaScript pipeline descriptors and WGSL modules.
+ * Keeping the interface in one place prevents a shader binding or entry
+ * point from silently drifting away from its matching WebGPU descriptor.
+ */
+export const SHADER_BIND_GROUP = Object.freeze({
+  frame: 0,
+  object: 1,
+  shadow: 2,
+});
+
+export const SHADER_BINDING = Object.freeze({
+  uniforms: 0,
+  map: 1,
+  sampler: 2,
+});
+
+/** Bindings in the directional-shadow sampling group. */
+export const SHADOW_BINDING = Object.freeze({
+  uniforms: 0,
+  map: 1,
+  sampler: 2,
+});
+
+export const SHADER_ENTRY_POINT = Object.freeze({
+  vertex: 'vs',
+  fragment: 'fs',
+  shadowVertex: 'vsShadow',
+  shadowInstancedVertex: 'vsShadowInstanced',
+});
+
+export const VERTEX_BUFFER_SLOT = Object.freeze({
+  geometry: 0,
+  instance: 1,
+});
+
+export const DEFAULT_PRIMITIVE_TOPOLOGY = 'triangle-list';
+export const DEFAULT_FRONT_FACE = 'ccw';
+export const DEFAULT_CULL_MODE_3D = 'back';
+export const DEFAULT_CULL_MODE_2D = 'none';
+export const DEFAULT_DEPTH_COMPARE = 'less';
+export const INDEX_FORMAT = 'uint32';
+export const INSTANCE_STEP_MODE = 'instance';
+
+const STRIP_TOPOLOGIES = new Set(['triangle-strip', 'line-strip']);
+const TRIANGLE_TOPOLOGIES = new Set(['triangle-list', 'triangle-strip']);
+
+/** Whether an indexed primitive topology needs `stripIndexFormat`. */
+export function isStripTopology(topology) {
+  return STRIP_TOPOLOGIES.has(topology);
+}
+
+/** Whether a primitive can contribute polygonal depth to a shadow map. */
+export function isTriangleTopology(topology) {
+  return TRIANGLE_TOPOLOGIES.has(topology);
+}
+
+/** Straight-alpha blending shared by transparent 3D and all 2D pipelines. */
+export const STRAIGHT_ALPHA_BLEND = Object.freeze({
+  color: Object.freeze({
+    srcFactor: 'src-alpha',
+    dstFactor: 'one-minus-src-alpha',
+  }),
+  alpha: Object.freeze({
+    srcFactor: 'one',
+    dstFactor: 'one-minus-src-alpha',
+  }),
+});

package/src/core/rendererConfig.js

@@ -0,0 +1,66 @@
+import { srgbToLinear } from '../math/color.js';
+
+/** Shared renderer defaults and WebGPU attachment formats. */
+export const DEFAULT_CANVAS_WIDTH = 300;
+export const DEFAULT_CANVAS_HEIGHT = 150;
+export const MAX_PIXEL_RATIO = 2;
+export const ANTIALIAS_SAMPLE_COUNT = 4;
+export const SINGLE_SAMPLE_COUNT = 1;
+export const DEPTH_FORMAT = 'depth24plus';
+export const DEPTH_CLEAR_VALUE = 1;
+
+/** Returns the sRGB view format compatible with a preferred canvas format. */
+export function srgbColorFormat(canvasFormat) {
+  switch (canvasFormat) {
+    case 'bgra8unorm':
+      return 'bgra8unorm-srgb';
+    case 'rgba8unorm':
+      return 'rgba8unorm-srgb';
+    default:
+      throw new Error(`Unsupported canvas format: ${canvasFormat}`);
+  }
+}
+
+/** Decodes an authored sRGB clear color for an sRGB render attachment. */
+export function linearClearColor(color) {
+  return [
+    srgbToLinear(color[0]),
+    srgbToLinear(color[1]),
+    srgbToLinear(color[2]),
+    color[3],
+  ];
+}
+
+/** Returns a bounded device-pixel ratio that is also safe in test environments. */
+export function getPixelRatio() {
+  return Math.min(globalThis.devicePixelRatio || 1, MAX_PIXEL_RATIO);
+}
+
+/** Converts CSS dimensions into a valid WebGPU drawing-buffer extent. */
+export function drawingBufferSize(width, height) {
+  const pixelRatio = getPixelRatio();
+  return {
+    width: Math.max(1, Math.floor(width * pixelRatio)),
+    height: Math.max(1, Math.floor(height * pixelRatio)),
+  };
+}
+
+/** Builds the color attachment shared by both renderers. */
+export function colorAttachment(msaaView, swapView, clearValue) {
+  if (!msaaView) {
+    return {
+      view: swapView,
+      clearValue,
+      loadOp: 'clear',
+      storeOp: 'store',
+    };
+  }
+  return {
+    view: msaaView,
+    resolveTarget: swapView,
+    clearValue,
+    loadOp: 'clear',
+    // Only the resolved image reaches the canvas.
+    storeOp: 'discard',
+  };
+}

package/src/core/uploadTexture.js

@@ -0,0 +1,57 @@
+import { generateMipmaps, mipLevelCount } from './generateMipmaps.js';
+
+const SRGB_TEXTURE_FORMAT = 'rgba8unorm-srgb';
+const LINEAR_TEXTURE_FORMAT = 'rgba8unorm';
+
+/**
+ * GPU texture, view and sampler for a Texture, uploaded on first use
+ * and cached per GPUDevice on `texture._gpu`. Shared by GpuResources and
+ * GpuResources2d — texture upload is device-level plumbing, identical
+ * for both engines. A Texture can therefore be used by renderers on the
+ * same device or on independent devices.
+ */
+export function uploadTexture(device, texture) {
+  const cache = texture._gpu || (texture._gpu = new Map());
+  let gpu = cache.get(device);
+
+  if (!gpu) {
+    const size = [texture.width, texture.height];
+    const levels = texture.mipmaps
+      ? mipLevelCount(texture.width, texture.height)
+      : 1;
+    // An sRGB format makes the GPU decode samples to linear (and
+    // re-encode when the mipmap pass renders into a level), so shading
+    // and mip filtering happen in linear space.
+    const format = texture.srgb ? SRGB_TEXTURE_FORMAT : LINEAR_TEXTURE_FORMAT;
+    const gpuTexture = device.createTexture({
+      size,
+      mipLevelCount: levels,
+      format,
+      // copyExternalImageToTexture requires RENDER_ATTACHMENT usage.
+      usage:
+        GPUTextureUsage.TEXTURE_BINDING |
+        GPUTextureUsage.COPY_DST |
+        GPUTextureUsage.RENDER_ATTACHMENT,
+    });
+    device.queue.copyExternalImageToTexture(
+      { source: texture.source, flipY: texture.flipY },
+      { texture: gpuTexture },
+      size,
+    );
+    if (levels > 1) generateMipmaps(device, gpuTexture, levels, format);
+    const sampler = device.createSampler({
+      magFilter: texture.magFilter,
+      minFilter: texture.minFilter,
+      mipmapFilter: texture.mipmaps ? 'linear' : 'nearest',
+      addressModeU: texture.addressModeU,
+      addressModeV: texture.addressModeV,
+    });
+    gpu = {
+      texture: gpuTexture,
+      view: gpuTexture.createView(),
+      sampler,
+    };
+    cache.set(device, gpu);
+  }
+  return gpu;
+}