@opsydyn/effect-three-foldkit 0.0.0-stage → 0.1.0

package/src/dom/webgl.ts

@@ -0,0 +1,216 @@
+/**
+ * The WebGL2 renderer behind the core's backend-neutral renderer contract.
+ *
+ * @module
+ */
+import type { RendererFactory, RenderSettings, RenderTarget } from '@opsydyn/effect-three';
+import { webglKit } from '@opsydyn/effect-three/webgl';
+import {
+  type Camera,
+  HalfFloatType,
+  LinearFilter,
+  type Object3D,
+  PMREMGenerator,
+  type Scene,
+  Vector2,
+  WebGLRenderer,
+  type WebGLRendererParameters,
+  WebGLRenderTarget,
+} from 'three';
+import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
+
+import { createPostProcessing } from './postprocessing.ts';
+import {
+  colorSpaces,
+  forgetPresentable,
+  recompileMaterials,
+  registerPresentable,
+  shadowTypes,
+  toneMappings,
+} from './renderSettings.ts';
+
+/** Options passed through to three's `WebGLRenderer`. The canvas is always the scene's own. */
+export type WebGLOptions = Omit<WebGLRendererParameters, 'canvas'>;
+
+/**
+ * Applies scene render settings; a change of shadow mode re-renders the shadow maps.
+ * Returns whether shadows were switched on or off, which materials must be recompiled for.
+ */
+const configure = (renderer: WebGLRenderer, settings: RenderSettings): boolean => {
+  const shadowMap = renderer.shadowMap;
+  const enabled = settings.shadows !== 'off';
+  const switched = shadowMap.enabled !== enabled;
+  const type = enabled ? shadowTypes[settings.shadows] : shadowMap.type;
+  if (switched || shadowMap.type !== type) shadowMap.needsUpdate = true;
+  shadowMap.enabled = enabled;
+  shadowMap.type = type;
+  renderer.toneMapping = toneMappings[settings.toneMapping];
+  renderer.toneMappingExposure = settings.exposure;
+  renderer.outputColorSpace = colorSpaces[settings.colorSpace];
+  return switched;
+};
+
+const drawingSize = new Vector2();
+
+/**
+ * A render texture's target, as Drei's `useFBO` makes one for `RenderTexture` (drei
+ * `bf6f4ad`, `src/core/Fbo.tsx`): half-float colour, linear filtering, multisampled, with
+ * a depth buffer.
+ */
+const createTarget = (
+  targets: WeakMap<RenderTarget, WebGLRenderTarget>,
+  width: number,
+  height: number,
+): RenderTarget => {
+  const target = new WebGLRenderTarget(width, height, {
+    minFilter: LinearFilter,
+    magFilter: LinearFilter,
+    type: HalfFloatType,
+    samples: 8,
+  });
+  const handle = { texture: target.texture, dispose: () => target.dispose() };
+  targets.set(handle, target);
+  return handle;
+};
+
+/**
+ * three.js's `RoomEnvironment`, prefiltered for image-based lighting, as three's examples
+ * set it up (`PMREMGenerator.fromScene(new RoomEnvironment(), 0.04)`).
+ */
+const createRoom = (renderer: WebGLRenderer): RenderTarget => {
+  const generator = new PMREMGenerator(renderer);
+  const room = new RoomEnvironment();
+  const target = generator.fromScene(room, 0.04);
+  room.dispose();
+  generator.dispose();
+  return { texture: target.texture, dispose: () => target.dispose() };
+};
+
+/**
+ * Draws a frame of an immersive session. In AR the room shows through: three clears to
+ * transparent there, but a background (an environment shown as one) would cover it, so it
+ * is left out of the frame.
+ */
+const drawPresenting = (renderer: WebGLRenderer, scene: Scene, camera: Camera): void => {
+  const passthrough = renderer.xr.getEnvironmentBlendMode() !== 'opaque';
+  if (!passthrough || scene.background === null) {
+    renderer.render(scene, camera);
+    return;
+  }
+  const background = scene.background;
+  scene.background = null;
+  renderer.render(scene, camera);
+  scene.background = background;
+};
+
+/** A factory for a WebGL2 renderer drawing into `canvas`. `create` throws if WebGL2 is unavailable. */
+export const webglRendererFactory = (
+  canvas: HTMLCanvasElement,
+  options: WebGLOptions = {},
+): RendererFactory => ({
+  // The GLSL parts of a scene (sky, shader grid, contact shadows) go with this renderer.
+  kit: webglKit,
+  create: () => {
+    const renderer = new WebGLRenderer({ antialias: true, ...options, canvas });
+    registerPresentable(canvas, renderer, {
+      xr: renderer.xr,
+      setXrLoop: (callback) => renderer.xr.setAnimationLoop(callback),
+    });
+    const post = createPostProcessing(renderer);
+    const targets = new WeakMap<RenderTarget, WebGLRenderTarget>();
+    // The pixel ratio is the viewport's, scaled by the scene's resolution setting.
+    let pixelRatio = 1;
+    let resolution = 1;
+    let scissored = false;
+    // Counts shadow switches; each scene drawn (main or render texture) recompiles its
+    // materials once after a switch.
+    let shadowSwitches = 0;
+    const compiledAt = new WeakMap<Object3D, number>();
+    const applyPixelRatio = (): void => {
+      if (renderer.getPixelRatio() !== pixelRatio * resolution) {
+        renderer.setPixelRatio(pixelRatio * resolution);
+      }
+      const { width, height } = renderer.getSize(drawingSize);
+      post.setSize(width, height, pixelRatio * resolution);
+    };
+    return {
+      render: (scene, camera, area, target) => {
+        if (shadowSwitches > 0 && compiledAt.get(scene) !== shadowSwitches) {
+          recompileMaterials(scene);
+          compiledAt.set(scene, shadowSwitches);
+        }
+        const webglTarget = target === undefined ? undefined : targets.get(target);
+        if (webglTarget !== undefined) {
+          // As Drei's RenderTexture draws (src/core/RenderTexture.tsx): into the target, then
+          // back to whatever was bound. A target keeps its own viewport and scissor.
+          // Targets start transparent, whatever the canvas clears to: what the scene does
+          // not cover stays see-through (a render texture without a background, contact
+          // shadows away from objects).
+          // Offscreen passes keep their own camera, even while presenting in XR (three
+          // would otherwise draw them from the headset).
+          const previous = renderer.getRenderTarget();
+          const clearAlpha = renderer.getClearAlpha();
+          const xrEnabled = renderer.xr.enabled;
+          renderer.xr.enabled = false;
+          renderer.setClearAlpha(0);
+          renderer.setRenderTarget(webglTarget);
+          renderer.render(scene, camera);
+          renderer.setRenderTarget(previous);
+          renderer.setClearAlpha(clearAlpha);
+          renderer.xr.enabled = xrEnabled;
+          return;
+        }
+        // Presenting in XR, three draws the headset's views itself: no areas, no effects.
+        if (renderer.xr.isPresenting) {
+          drawPresenting(renderer, scene, camera);
+          return;
+        }
+        const { width, height } = renderer.getSize(drawingSize);
+        if (area === undefined) {
+          if (scissored) {
+            renderer.setScissorTest(false);
+            renderer.setViewport(0, 0, width, height);
+            scissored = false;
+          }
+          if (!post.render(scene, camera)) renderer.render(scene, camera);
+          return;
+        }
+        // three's viewport and scissor origin is the bottom left; areas are from the top.
+        const bottom = height - area.y - area.height;
+        renderer.setViewport(area.x, bottom, area.width, area.height);
+        renderer.setScissor(area.x, bottom, area.width, area.height);
+        renderer.setScissorTest(true);
+        scissored = true;
+        // Effects apply to the single full view only; views draw straight to the screen.
+        renderer.render(scene, camera);
+      },
+      createTarget: (width, height) => createTarget(targets, width, height),
+      createEnvironment: () => createRoom(renderer),
+      configure: (settings) => {
+        if (configure(renderer, settings)) shadowSwitches++;
+        resolution = settings.resolution;
+        post.configure(settings.effects);
+        applyPixelRatio();
+      },
+      setViewport: (viewport) => {
+        pixelRatio = viewport.pixelRatio;
+        applyPixelRatio();
+        renderer.setSize(viewport.width, viewport.height, false);
+        post.setSize(viewport.width, viewport.height, pixelRatio * resolution);
+      },
+      memory: () => ({
+        geometries: renderer.info.memory.geometries,
+        textures: renderer.info.memory.textures,
+      }),
+      // dispose() frees three's GPU objects but not the WebGL context. Browsers cap live
+      // contexts (about 16 in Chromium), so release it now rather than at garbage collection.
+      dispose: () => {
+        forgetPresentable(canvas);
+        void renderer.xr.getSession()?.end();
+        post.dispose();
+        renderer.dispose();
+        renderer.forceContextLoss();
+      },
+    };
+  },
+});

package/src/dom/webgpu.ts

@@ -0,0 +1,204 @@
+/**
+ * three.js's `WebGPURenderer` behind the core's renderer contract: WebGPU where the browser
+ * has it, otherwise its WebGL 2 backend (or always, with `forceWebGL`), drawing the same
+ * node materials either way. It carries the WebGPU render kit (the sky, shader grid and
+ * contact shadows in TSL), post-processes with `RenderPipeline`, and presents in WebXR.
+ * It starts asynchronously (`init()`), which the runtime waits for.
+ *
+ * Not drawn under it: labels, which troika makes from WebGL shaders; a label engine's
+ * labels are silently empty here.
+ *
+ * @module
+ */
+import type { RendererFactory, RenderSettings, RenderTarget } from '@opsydyn/effect-three';
+import { webgpuKit } from '@opsydyn/effect-three/webgpu';
+import {
+  type Camera,
+  HalfFloatType,
+  LinearFilter,
+  type Object3D,
+  RenderTarget as ThreeRenderTarget,
+  type Scene,
+  Vector2,
+} from 'three';
+import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
+import { PMREMGenerator, WebGPURenderer } from 'three/webgpu';
+
+import {
+  colorSpaces,
+  forgetPresentable,
+  recompileMaterials,
+  registerPresentable,
+  shadowTypes,
+  toneMappings,
+} from './renderSettings.ts';
+import { createWebGPUPostProcessing } from './webgpuPostprocessing.ts';
+
+/** Options for three's `WebGPURenderer`. The canvas is always the scene's own. */
+export type WebGPUOptions = {
+  /** Use the WebGL 2 backend even where WebGPU is available. */
+  readonly forceWebGL?: boolean;
+  readonly alpha?: boolean;
+  readonly antialias?: boolean;
+};
+
+/** Applies scene render settings; returns whether shadows were switched on or off. */
+const configure = (renderer: WebGPURenderer, settings: RenderSettings): boolean => {
+  const shadowMap = renderer.shadowMap;
+  const enabled = settings.shadows !== 'off';
+  const switched = shadowMap.enabled !== enabled;
+  shadowMap.enabled = enabled;
+  if (enabled) shadowMap.type = shadowTypes[settings.shadows];
+  renderer.toneMapping = toneMappings[settings.toneMapping];
+  renderer.toneMappingExposure = settings.exposure;
+  renderer.outputColorSpace = colorSpaces[settings.colorSpace];
+  return switched;
+};
+
+const drawingSize = new Vector2();
+
+/**
+ * A render texture's target, as the WebGL renderer makes one (Drei's `useFBO`): half-float
+ * colour, linear filtering, multisampled (4, WebGPU's only multisample count), with depth.
+ */
+const createTarget = (
+  targets: WeakMap<RenderTarget, ThreeRenderTarget>,
+  width: number,
+  height: number,
+): RenderTarget => {
+  const target = new ThreeRenderTarget(width, height, {
+    minFilter: LinearFilter,
+    magFilter: LinearFilter,
+    type: HalfFloatType,
+    samples: 4,
+  });
+  const handle = { texture: target.texture, dispose: () => target.dispose() };
+  targets.set(handle, target);
+  return handle;
+};
+
+/** three.js's `RoomEnvironment`, prefiltered by the WebGPU renderer's PMREM generator. */
+const createRoom = (renderer: WebGPURenderer): RenderTarget => {
+  const generator = new PMREMGenerator(renderer);
+  const room = new RoomEnvironment();
+  const target = generator.fromScene(room, 0.04);
+  room.dispose();
+  generator.dispose();
+  return { texture: target.texture, dispose: () => target.dispose() };
+};
+
+/**
+ * Draws a frame of an immersive session. In AR the room shows through, so a background
+ * (an environment shown as one) is left out of the frame, as the WebGL renderer does.
+ */
+const drawPresenting = (renderer: WebGPURenderer, scene: Scene, camera: Camera): void => {
+  const passthrough = renderer.xr.getEnvironmentBlendMode() !== 'opaque';
+  if (!passthrough || scene.background === null) {
+    renderer.render(scene, camera);
+    return;
+  }
+  const background = scene.background;
+  scene.background = null;
+  renderer.render(scene, camera);
+  scene.background = background;
+};
+
+/** A factory for three's `WebGPURenderer` drawing into `canvas`. */
+export const webgpuRendererFactory = (
+  canvas: HTMLCanvasElement,
+  options: WebGPUOptions = {},
+): RendererFactory => ({
+  // The TSL parts of a scene (sky, shader grid, contact shadows) go with this renderer.
+  kit: webgpuKit,
+  create: () => {
+    // Opaque by default, as three's WebGLRenderer is (WebGPURenderer's own default is alpha).
+    const renderer = new WebGPURenderer({ antialias: true, alpha: false, ...options, canvas });
+    registerPresentable(canvas, renderer, {
+      xr: renderer.xr,
+      setXrLoop: (callback) => {
+        void renderer.setAnimationLoop(callback);
+      },
+    });
+    const post = createWebGPUPostProcessing(renderer);
+    const targets = new WeakMap<RenderTarget, ThreeRenderTarget>();
+    let pixelRatio = 1;
+    let resolution = 1;
+    let scissored = false;
+    let shadowSwitches = 0;
+    const compiledAt = new WeakMap<Object3D, number>();
+    const applyPixelRatio = (): void => {
+      if (renderer.getPixelRatio() !== pixelRatio * resolution) {
+        renderer.setPixelRatio(pixelRatio * resolution);
+      }
+    };
+    return {
+      ready: () => renderer.init().then(() => undefined),
+      render: (scene, camera, area, target) => {
+        if (shadowSwitches > 0 && compiledAt.get(scene) !== shadowSwitches) {
+          recompileMaterials(scene);
+          compiledAt.set(scene, shadowSwitches);
+        }
+        const offscreen = target === undefined ? undefined : targets.get(target);
+        if (offscreen !== undefined) {
+          // As the WebGL renderer: into the target, transparent, never from the headset.
+          const previous = renderer.getRenderTarget();
+          const clearAlpha = renderer.getClearAlpha();
+          const xrEnabled = renderer.xr.enabled;
+          renderer.xr.enabled = false;
+          renderer.setClearAlpha(0);
+          renderer.setRenderTarget(offscreen);
+          renderer.render(scene, camera);
+          renderer.setRenderTarget(previous);
+          renderer.setClearAlpha(clearAlpha);
+          renderer.xr.enabled = xrEnabled;
+          return;
+        }
+        // Presenting in XR, three draws the headset's views itself: no areas, no effects.
+        if (renderer.xr.isPresenting) {
+          drawPresenting(renderer, scene, camera);
+          return;
+        }
+        const { width, height } = renderer.getSize(drawingSize);
+        if (area === undefined) {
+          if (scissored) {
+            renderer.setScissorTest(false);
+            renderer.setViewport(0, 0, width, height);
+            scissored = false;
+          }
+          if (!post.render(scene, camera)) renderer.render(scene, camera);
+          return;
+        }
+        // three's viewport and scissor origin is the bottom left; areas are from the top.
+        const bottom = height - area.y - area.height;
+        renderer.setViewport(area.x, bottom, area.width, area.height);
+        renderer.setScissor(area.x, bottom, area.width, area.height);
+        renderer.setScissorTest(true);
+        scissored = true;
+        renderer.render(scene, camera);
+      },
+      createTarget: (width, height) => createTarget(targets, width, height),
+      createEnvironment: () => createRoom(renderer),
+      configure: (settings) => {
+        if (configure(renderer, settings)) shadowSwitches++;
+        resolution = settings.resolution;
+        post.configure(settings.effects);
+        applyPixelRatio();
+      },
+      setViewport: (viewport) => {
+        pixelRatio = viewport.pixelRatio;
+        applyPixelRatio();
+        renderer.setSize(viewport.width, viewport.height, false);
+      },
+      memory: () => ({
+        geometries: renderer.info.memory.geometries,
+        textures: renderer.info.memory.textures,
+      }),
+      dispose: () => {
+        forgetPresentable(canvas);
+        void renderer.xr.getSession()?.end();
+        post.dispose();
+        void renderer.dispose();
+      },
+    };
+  },
+});

package/src/dom/webgpuPostprocessing.ts

@@ -0,0 +1,95 @@
+/**
+ * Post-processing for the WebGPU renderer: three.js's `RenderPipeline` with TSL nodes for
+ * the same effects the WebGL renderer composes (`postprocessing.ts`): bloom
+ * (`tsl/display/BloomNode.js`, added to the scene as three's examples add it), film
+ * (`tsl/display/FilmNode.js`'s grain, written here, with grayscale by luminance as
+ * `FilmPass` offers) and
+ * vignette (three's `VignetteShader`, as TSL). The pipeline's output transform applies
+ * tone mapping and the output colour space, as the WebGL composer's `OutputPass` does.
+ *
+ * @module
+ */
+import { effectsEqual, type PostEffect } from '@opsydyn/effect-three';
+import type { Camera, Scene } from 'three';
+import { bloom } from 'three/addons/tsl/display/BloomNode.js';
+import {
+  clamp,
+  dot,
+  fract,
+  luminance,
+  mix,
+  pass,
+  rand,
+  screenUV,
+  time,
+  uv,
+  vec3,
+  vec4,
+} from 'three/tsl';
+import { type Node, RenderPipeline, type WebGPURenderer } from 'three/webgpu';
+
+import type { PostProcessing } from './postprocessing.ts';
+
+type Colour = Node<'vec4'>;
+
+/** One effect applied to the colour so far. */
+const applied = (input: Colour, effect: PostEffect): Colour => {
+  switch (effect._tag) {
+    case 'Bloom':
+      return input.add(bloom(input, effect.strength, effect.radius, effect.threshold));
+    case 'Vignette': {
+      // three's VignetteShader: towards `1 − darkness` with distance from the middle.
+      const centred = screenUV.sub(0.5).mul(effect.offset);
+      return vec4(mix(input.rgb, vec3(1 - effect.darkness), dot(centred, centred)), input.a);
+    }
+    case 'Film': {
+      // three's FilmNode: noise added in proportion to the colour, mixed in by intensity.
+      const base = input.rgb;
+      const noise = rand(fract(uv().add(time)));
+      const grained = mix(base, base.add(base.mul(clamp(noise.add(0.1), 0, 1))), effect.intensity);
+      return vec4(effect.grayscale ? vec3(luminance(grained)) : grained, input.a);
+    }
+  }
+};
+
+export const createWebGPUPostProcessing = (renderer: WebGPURenderer): PostProcessing => {
+  let effects: ReadonlyArray<PostEffect> = [];
+  let pipeline: RenderPipeline | undefined;
+  // The scene and camera the pipeline's scene pass draws: a new one rebuilds it.
+  let drawn: { readonly scene: Scene; readonly camera: Camera } | undefined;
+
+  const dispose = (): void => {
+    pipeline?.dispose();
+    pipeline = undefined;
+    drawn = undefined;
+  };
+
+  const build = (scene: Scene, camera: Camera): RenderPipeline => {
+    dispose();
+    const output = effects.reduce<Colour>(applied, pass(scene, camera));
+    const next = new RenderPipeline(renderer, output);
+    pipeline = next;
+    drawn = { scene, camera };
+    return next;
+  };
+
+  return {
+    configure: (next) => {
+      if (effectsEqual(next, effects)) return;
+      effects = next;
+      dispose();
+    },
+    // The pipeline follows the renderer's size.
+    setSize: () => undefined,
+    render: (scene, camera) => {
+      if (effects.length === 0) return false;
+      const current =
+        pipeline !== undefined && drawn?.scene === scene && drawn.camera === camera
+          ? pipeline
+          : build(scene, camera);
+      current.render();
+      return true;
+    },
+    dispose,
+  };
+};