@driftengine/core 4.8.7 → 4.10.0

package/src/render/backend/api.ts

@@ -7,7 +7,8 @@ import type { ProbeBakeOptions } from '../reflectionProbe.ts';
 import type { Renderer, TranslucentMeshOptions } from './webgl2/renderer.ts';
 import type { InstancedOptions, MeshInstances } from '../instances.ts';
 import type { SurfaceMaterial } from '../surfaceTexture.ts';
-import type { SurfaceSource } from '../compressedSource.ts';
+import type { SurfaceOverlay } from '../surfaceOverlay.ts';
+import type { CompressedTextureSource, SurfaceSource } from '../compressedSource.ts';
 import type { LightmapPage } from '../lightmap.ts';
 import type { DeviceParticles } from '../particlePool.ts';
 import type { ClothBindingData } from '../clothBindingData.ts';
@@ -311,6 +312,7 @@ export type RendererApi = Omit<
   | 'disposeSurfaceTexture'
   | 'setSurfaceTexture'
   | 'setMaterial'
+  | 'setSurfaceOverlay'
   | 'createClothBinding'
   | 'createClothParticles'
   | 'updateClothParticles'
@@ -341,6 +343,13 @@ export type RendererApi = Omit<
   setCloth(binding: ClothBindingHandle | null, particles?: ClothParticlesHandle | null): void;
   disposeClothBinding(binding: ClothBindingHandle): void;
   disposeClothParticles(particles: ClothParticlesHandle): void;
+  /**
+   * What the following draws lay over their surfaces beyond their materials — a rim of light, a
+   * dissolve with a glowing edge, wrinkle normals by region — or null for none, which every pass
+   * starts with. Per draw, so one character's whole set of materials changes together. Its images
+   * are regions of one atlas (`SurfaceOverlay.maps`). See `surfaceOverlay.ts`.
+   */
+  setSurfaceOverlay(overlay: SurfaceOverlay | null): void;
   /**
    * Upload a caller's image, or a BC image's blocks with their stored chain where
    * `compressedFormats` has the format. See `SurfaceTextureHandle` for the boundary this guards.
@@ -406,12 +415,22 @@ export type RendererApi = Omit<
   ): boolean;
 
   /**
-   * Replace a texture's pixels, keeping the GPU object and its sampler state.
+   * Replace a texture's pixels, keeping the handle and its sampler state.
    *
    * The binding a draw loop already holds stays valid, so the swap is a swap rather than a
    * rebuild. Not a hot path: it re-uploads the whole image and rebuilds the mip chain.
+   *
+   * **Blocks may replace an image**, at the format's own size and with the chain they carry: the
+   * same picture at a fraction of the memory, which is how a loader that first showed a decoded
+   * image hands the device the blocks it encoded afterwards. Read in the colour space the texture
+   * was made with, and refused as `createSurfaceTexture` refuses them where the device does not take
+   * that format (`compressedFormats`). **The way back is refused**: a texture holding blocks takes
+   * no image, since nothing could say what its chain should become.
    */
-  updateSurfaceTexture(texture: SurfaceTextureHandle, source: TexImageSource): void;
+  updateSurfaceTexture(
+    texture: SurfaceTextureHandle,
+    source: TexImageSource | CompressedTextureSource,
+  ): void;
 
   disposeSurfaceTexture(texture: SurfaceTextureHandle): void;
 

package/src/render/backend/createRenderer.ts

@@ -5,6 +5,7 @@ import { BACKEND_TIMEOUT_MS, forcedBackend, selectBackend } from './select.ts';
 import { TIMED_OUT, withDeadline } from './deadline.ts';
 import { mountSplash, type MountedSplash, type SplashOptions } from '../../ui/splash.ts';
 import { gpuDrivenRefusal, gpuDrivenSupported } from '../gpudriven/pipeline.ts';
+import { browserHighDynamicRange, chooseDisplayRange } from '../displayRange.ts';
 
 /**
  * Which of the two pipelines is drawing.
@@ -149,6 +150,12 @@ export interface CreateRendererOptions {
    * badge is looked at on a deployed build.
    */
   readonly splash?: boolean | SplashOptions;
+  /**
+   * Whether the display shows a high dynamic range, asked only where `highDynamicRange` was. The
+   * browser's `(dynamic-range: high)` query by default; a host with no DOM, or one that knows
+   * better about its own display, answers instead. See `displayRange.ts`.
+   */
+  readonly highDynamicRangeDisplay?: () => boolean;
 }
 
 /** What was built, and which path built it. */
@@ -370,7 +377,17 @@ export async function createRenderer(
         const { createGpuSurface } = await import('./webgpu/device.ts');
         const { WebGPURenderer } = await import('./webgpu/renderer.ts');
         stage = 'creating the surface';
-        const surface = createGpuSurface(canvas, device);
+        const profile = resolveRenderQuality(qualityFor('webgpu'));
+        const surface = createGpuSurface(
+          canvas,
+          device,
+          chooseDisplayRange(
+            profile.highDynamicRange,
+            profile.screenEffects && profile.hdrScene,
+            profile.highDynamicRange &&
+              (options.highDynamicRangeDisplay ?? browserHighDynamicRange)(),
+          ),
+        );
         stage = 'constructing the renderer';
         return { surface, WebGPURenderer };
       })();

package/src/render/backend/select.ts

@@ -248,12 +248,17 @@ async function acquireWebGpu(
       features.push('timestamp-query');
     }
     /*
-     * BC compressed textures, on the same terms: asked for wherever the adapter offers it, because
-     * a device without it still draws — the loader decodes for it — and one with it samples a BC7
-     * texture at a byte a texel instead of four. See `compressedUpload.ts`.
+     * The three block families, on the same terms: each asked for wherever the adapter offers it,
+     * because a device without one still draws — the loader decodes, or encodes ETC2, for it — and
+     * one with it samples a texture at a byte a texel or half of one instead of four. Desktops
+     * offer BC; phones ETC2 and ASTC. See `compressedUpload.ts`.
      */
-    if (adapter.features?.has('texture-compression-bc') === true) {
-      features.push('texture-compression-bc');
+    for (const family of [
+      'texture-compression-bc',
+      'texture-compression-etc2',
+      'texture-compression-astc',
+    ] as const) {
+      if (adapter.features?.has(family) === true) features.push(family);
     }
     const descriptor: GPUDeviceDescriptor = {};
     if (Object.keys(required).length > 0) descriptor.requiredLimits = required;

package/src/render/backend/webgl2/boneAnimations.ts

@@ -0,0 +1,105 @@
+/**
+ * A bone animation's textures on this backend, and a batch's clocks: what
+ * `shaders/boneAnimation.ts` reads with `texelFetch`, made once and never filtered. The twin of
+ * `webgpu/boneAnimations.ts`, at the same formats for the same reason: a turn in half floats jitters
+ * a crowd's hands at the frame's rate.
+ */
+import {
+  CLOCK_TEXTURE_WIDTH,
+  type BoneAnimationHandle,
+  type BoneAnimationTexels,
+} from '../../boneAnimation.ts';
+
+/**
+ * A float texture read by index: one level, nearest, clamped. Bound on unit 0, chosen rather than
+ * inherited, for the reason `oitPass.ts` gives: `bindTexture` binds to whatever unit is active, and
+ * a frame leaves that wherever its last pass finished.
+ */
+function floatTexture(
+  gl: WebGL2RenderingContext,
+  internal: number,
+  width: number,
+  height: number,
+): WebGLTexture {
+  const texture = gl.createTexture();
+  if (texture === null) throw new Error('boneAnimations: createTexture failed');
+  gl.activeTexture(gl.TEXTURE0);
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  gl.texStorage2D(gl.TEXTURE_2D, 1, internal, width, height);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  return texture;
+}
+
+/** A clip on the device, from `createBoneAnimation`. */
+export class GlBoneAnimation implements BoneAnimationHandle {
+  readonly bones: number;
+  readonly frames: number;
+  readonly framesPerSecond: number;
+  readonly boneScale: number;
+  readonly places: WebGLTexture;
+  readonly turns: WebGLTexture;
+  disposed = false;
+
+  constructor(gl: WebGL2RenderingContext, texels: BoneAnimationTexels) {
+    this.bones = texels.bones;
+    this.frames = texels.frames;
+    this.framesPerSecond = texels.framesPerSecond;
+    this.boneScale = texels.boneScale;
+    const make = (data: Float32Array): WebGLTexture => {
+      const texture = floatTexture(gl, gl.RGBA32F, texels.bones, texels.frames);
+      gl.texSubImage2D(
+        gl.TEXTURE_2D,
+        0,
+        0,
+        0,
+        texels.bones,
+        texels.frames,
+        gl.RGBA,
+        gl.FLOAT,
+        data,
+      );
+      return texture;
+    };
+    this.places = make(texels.places);
+    this.turns = make(texels.turns);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    this.disposed = true;
+    gl.deleteTexture(this.places);
+    gl.deleteTexture(this.turns);
+  }
+}
+
+/** A batch's clocks: two floats an instance, wrapped onto rows `CLOCK_TEXTURE_WIDTH` wide. */
+export class GlInstanceClocks {
+  readonly texture: WebGLTexture;
+  readonly staging: Float32Array;
+  private readonly width: number;
+
+  constructor(gl: WebGL2RenderingContext, capacity: number) {
+    this.width = Math.max(1, Math.min(capacity, CLOCK_TEXTURE_WIDTH));
+    const rows = Math.max(1, Math.ceil(capacity / this.width));
+    this.staging = new Float32Array(this.width * rows * 2);
+    this.texture = floatTexture(gl, gl.RG32F, this.width, rows);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+  }
+
+  /** The rows that hold the first `count` instances, from `staging`. */
+  upload(gl: WebGL2RenderingContext, count: number): void {
+    if (count <= 0) return;
+    const rows = Math.ceil(count / this.width);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, this.width, rows, gl.RG, gl.FLOAT, this.staging);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    gl.deleteTexture(this.texture);
+  }
+}

package/src/render/backend/webgl2/instanced.ts

@@ -8,6 +8,8 @@ import {
 import type { MeshInstances } from '../../instances.ts';
 import type { Mesh } from '../../mesh.ts';
 import type { FrustumPlanes } from '../../../math/frustum.ts';
+import { packInstanceClocks } from '../../boneAnimation.ts';
+import { GlInstanceClocks, type GlBoneAnimation } from './boneAnimations.ts';
 
 /**
  * One batch of a mesh: its per-instance buffer and a vertex array of its own.
@@ -42,10 +44,22 @@ export class InstancedBatch {
     readonly instances: MeshInstances;
   } | null;
 
-  constructor(gl: WebGL2RenderingContext, mesh: Mesh, capacity: number, cull = false) {
+  /** The bone animation every instance plays, and its clocks; null for a batch that plays none. */
+  readonly animation: GlBoneAnimation | null;
+  readonly clocks: GlInstanceClocks | null;
+
+  constructor(
+    gl: WebGL2RenderingContext,
+    mesh: Mesh,
+    capacity: number,
+    cull = false,
+    animation: GlBoneAnimation | null = null,
+  ) {
     this.mesh = mesh;
     this.capacity = capacity;
     this.cull = cull;
+    this.animation = animation;
+    this.clocks = animation === null ? null : new GlInstanceClocks(gl, capacity);
     this.staging = new Float32Array(capacity * INSTANCE_FLOATS);
     this.buffer = allocate(gl, capacity);
     this.vao = mesh.createInstanceArray(gl, this.buffer, INSTANCE_STRIDE);
@@ -68,6 +82,10 @@ export class InstancedBatch {
     packInstances(data, this.staging);
     gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
     gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.staging, 0, count * INSTANCE_FLOATS);
+    if (this.clocks !== null) {
+      packInstanceClocks(data, this.clocks.staging);
+      this.clocks.upload(gl, count);
+    }
   }
 
   /** Draw the first `count` uploaded instances: every draw but a culling camera draw. */
@@ -102,6 +120,7 @@ export class InstancedBatch {
   dispose(gl: WebGL2RenderingContext): void {
     gl.deleteVertexArray(this.vao);
     gl.deleteBuffer(this.buffer);
+    this.clocks?.dispose(gl);
     if (this.kept !== null) {
       gl.deleteVertexArray(this.kept.vao);
       gl.deleteBuffer(this.kept.buffer);