zincjs 2.4.1-beta.2 → 2.4.1-beta.3

package/src/primitives/pointset.js

@@ -3,7 +3,7 @@ import { Label } from './label';
 import { InstancedPoints } from '../three/InstancedPoints';
 import { ZincObject } from './zincObject';
 import { getCircularTexture, toBufferGeometry } from '../utilities';
-import { createInstancedPointsMaterial } from '../tls/pointsMaterial';
+import { createInstancedPointsMaterial } from '../tsl/pointsMaterial';
 
 //Maximum number of points a programmatically built (addPoints) Pointset can
 //hold - the InstancedMesh backing it is allocated once with this capacity.
@@ -26,28 +26,26 @@ const createPointQuadGeometry = (capacity) => {
 
 /**
  * Extract the per time step, flat [x0, y0, z0, x1, y1, z1, ...] position
- * arrays from a (possibly time varying) BufferGeometry. Index 0 is always
- * the base frame, subsequent entries come from `morphAttributes.position`.
+ * arrays from a (possibly time varying) BufferGeometry.
+
  */
 const extractPositionFrames = (geometry, localTimeEnabled) => {
   const positionAttribute = geometry.getAttribute('position');
-  const frames = [Float32Array.from(positionAttribute.array)];
   const morphPositions = geometry.morphAttributes.position;
   if (localTimeEnabled && morphPositions && morphPositions.length > 0) {
     const relative = geometry.morphTargetsRelative;
-    morphPositions.forEach((attribute) => {
-      if (relative) {
-        const frame = new Float32Array(positionAttribute.array.length);
-        for (let i = 0; i < frame.length; i++) {
-          frame[i] = positionAttribute.array[i] + attribute.array[i];
-        }
-        frames.push(frame);
-      } else {
-        frames.push(Float32Array.from(attribute.array));
+    return morphPositions.map((attribute) => {
+      if (!relative) {
+        return Float32Array.from(attribute.array);
       }
+      const frame = new Float32Array(positionAttribute.array.length);
+      for (let i = 0; i < frame.length; i++) {
+        frame[i] = positionAttribute.array[i] + attribute.array[i];
+      }
+      return frame;
     });
   }
-  return frames;
+  return [Float32Array.from(positionAttribute.array)];
 }
 
 /**
@@ -59,14 +57,7 @@ const extractPositionFrames = (geometry, localTimeEnabled) => {
 const extractColorFrames = (geometry, localMorphColour) => {
   const morphColors = geometry.morphAttributes.color;
   if (localMorphColour && morphColors && morphColors.length > 0) {
-    const colorAttribute = geometry.getAttribute('color');
-    const frames = [];
-    frames.push(colorAttribute ? Float32Array.from(colorAttribute.array) :
-      new Float32Array(morphColors[0].array.length));
-    morphColors.forEach((attribute) => {
-      frames.push(Float32Array.from(attribute.array));
-    });
-    return frames;
+    return morphColors.map((attribute) => Float32Array.from(attribute.array));
   }
   return undefined;
 }

package/src/primitives/textureSlides.js

@@ -1,6 +1,6 @@
 import * as THREE from 'three/webgpu';
 //import * as shader from '../shaders/textureSlide.js';
-import { createWebGPUMaterial } from '../tls/textureSlides.js';
+import { createWebGPUMaterial } from '../tsl/textureSlides.js';
 import { TexturePrimitive } from './texturePrimitive';
 
 
@@ -18,6 +18,8 @@ const cloneData3DTexture = (sourceTex) => {
   targetTex.wrapS = sourceTex.wrapS;
   targetTex.wrapT = sourceTex.wrapT;
   targetTex.wrapR = sourceTex.wrapR;
+  targetTex.colorSpace = sourceTex.colorSpace;
+  targetTex.anisotropy = sourceTex.anisotropy;
   targetTex.needsUpdate = true;
   return targetTex;
 }

package/src/region.js

@@ -125,6 +125,15 @@ let Region = function (parentIn, sceneIn) {
     return parent;
   }
 
+  /**
+   * Get the {@link Scene} this region belongs to.
+   *
+   * @return {Scene}
+   */
+  this.getScene = () => {
+    return scene;
+  }
+
   /**
    * Get the array of each hierarachy from the root region to this region.
    *

package/src/renderer.js

@@ -133,14 +133,20 @@ const Renderer = function (containerIn) {
 			}
       //WebGPURenderer otherwise requests a device with the default
       //maxTextureArrayLayers (256 on many adapters), which is too low for
-      //some currnetly sypported scaffold. We will request the highest possible
-      //on the device
+      //some currnetly sypported scaffold, and the default
+      //maxStorageBuffersPerShaderStage (8 on many adapters), which is too
+      //low for compute passes like glyphset.js's GPU glyph-transform (11
+      //storage buffers). We will request the highest possible on the device
+      //for both.
       if (parameters.device === undefined && parameters.requiredLimits === undefined &&
         typeof navigator !== 'undefined' && navigator.gpu) {
         try {
           const adapter = await navigator.gpu.requestAdapter({ powerPreference: parameters.powerPreference });
           if (adapter) {
-            parameters.requiredLimits = { maxTextureArrayLayers: adapter.limits.maxTextureArrayLayers };
+            parameters.requiredLimits = {
+              maxTextureArrayLayers: adapter.limits.maxTextureArrayLayers,
+              maxStorageBuffersPerShaderStage: adapter.limits.maxStorageBuffersPerShaderStage,
+            };
           }
         } catch (err) {
           //Fall through and let WebGPURenderer's own adapter/device request
@@ -719,10 +725,23 @@ const Renderer = function (containerIn) {
 		}
 	}
 
+  /**
+   * Check if the renderer is running on the WebGL 2 fallback backend.
+   * WebGPURenderer never uses WebGL 1, so this is false when WebGPU is used.
+   *
+   * @return {Boolean}
+   */
   this.isWebGL2 = () => {
-    if (renderer)
-      return renderer.capabilities.isWebGL2;
-    return false;
+    return renderer?.backend?.isWebGLBackend === true;
+  }
+
+  /**
+   * Check if the renderer is running on the WebGPU backend.
+   *
+   * @return {Boolean}
+   */
+  this.isWebGPU = () => {
+    return renderer?.backend?.isWebGPUBackend === true;
   }
 };
 

package/src/scene.js

@@ -9,7 +9,7 @@ import { SceneExporter } from './sceneExporter';
 import { SceneLoader } from './sceneLoader';
 import { Viewport } from './controls';
 import { createPointQuadGeometry } from './primitives/pointset';
-import { createInstancedPointsMaterial } from './tls/pointsMaterial';
+import { createInstancedPointsMaterial } from './tsl/pointsMaterial';
 import {
   createBufferGeometry,
   createNewSpriteText,
@@ -988,8 +988,32 @@ const Scene = function (containerIn, rendererIn) {
     return undefined;
   }
 
+  /**
+   * Check if the renderer is running on the WebGL 2 fallback backend.
+   *
+   * @return {Boolean}
+   */
   this.isWebGL2 = () => {
-    return rendererIn.isWebGL2();
+    return rendererIn?.backend?.isWebGLBackend === true;
+  }
+
+  /**
+   * Check if the renderer is running on the WebGPU backend.
+   *
+   * @return {Boolean}
+   */
+  this.isWebGPU = () => {
+    return rendererIn?.backend?.isWebGPUBackend === true;
+  }
+
+  /**
+   * Get the THREE.WebGPURenderer this scene is being drawn with, for code
+   * that needs to dispatch its own GPU work (e.g. a TSL compute pass).
+   *
+   * @return {THREE.WebGPURenderer}
+   */
+  this.getRenderer = () => {
+    return rendererIn;
   }
 
   /**

package/src/sceneExporter.js

@@ -1,4 +1,49 @@
-import { GLTFExporter } from './three/GLTFExporter';
+import { BufferAttribute } from 'three/webgpu';
+import { GLTFExporter } from 'three/examples/jsm/exporters/GLTFExporter';
+
+/*
+ * GLTFExporter only writes POSITION and NORMAL morph targets. glTF allows
+ * COLOR_n morph targets as well (GLTFLoader reads them), so add them to the
+ * targets the exporter has already written. Like other glTF morph targets
+ * they are stored relative to the base attribute.
+ */
+class GLTFMorphColourPlugin {
+  constructor(writer) {
+    this.writer = writer;
+    this.name = 'ZINC_morph_colour';
+  }
+
+  writeMesh(mesh, meshDef) {
+    const geometry = mesh.geometry;
+    const morphColours = geometry && geometry.morphAttributes ?
+      geometry.morphAttributes.color : undefined;
+    const baseColour = geometry ? geometry.attributes.color : undefined;
+    const primitive = meshDef.primitives ? meshDef.primitives[0] : undefined;
+    if (!morphColours || !baseColour || !primitive || !primitive.targets)
+      return;
+    // All primitives of a mesh share the same targets array.
+    const targets = primitive.targets;
+    const itemSize = baseColour.itemSize;
+    const count = baseColour.count;
+    for (let i = 0; i < targets.length && i < morphColours.length; i++) {
+      const attribute = morphColours[i];
+      if (attribute.itemSize !== itemSize || attribute.count < count) {
+        console.warn('GLTFExporter: Colour morph target does not match the base colour, skipped.');
+        return;
+      }
+      const array = new Float32Array(count * itemSize);
+      for (let j = 0; j < count; j++) {
+        for (let a = 0; a < itemSize; a++) {
+          const value = attribute.getComponent(j, a);
+          array[j * itemSize + a] = geometry.morphTargetsRelative ?
+            value : value - baseColour.getComponent(j, a);
+        }
+      }
+      targets[i].COLOR_0 = this.writer.processAccessor(
+        new BufferAttribute(array, itemSize), geometry);
+    }
+  }
+}
 
 /**
  * Provides an object which uses for exporting the scene
@@ -10,22 +55,59 @@ import { GLTFExporter } from './three/GLTFExporter';
 const SceneExporter = function (sceneIn) {
   const scene = sceneIn;
 
-	this.exportGLTF = (binary) => {
+  // Matches the exporter's onlyVisible pruning - animations targeting a
+  // hidden node would otherwise produce channels with no target node.
+  const isVisible = (object) => {
+    for (let current = object; current; current = current.parent) {
+      if (current.visible === false) return false;
+    }
+    return true;
+  };
+
+	this.exportGLTF = async (binary) => {
     const rootRegion = scene.getRootRegion();
     const zincObjects = rootRegion.getAllObjects(true);
     const animations = [];
-    zincObjects.forEach(zincObject => {
-      if (zincObject.animationClip) {
-        animations.push({clip: zincObject.animationClip[0], mesh: zincObject.getMorph()});
+    const glyphsetsToRestore = [];
+    for (const zincObject of zincObjects) {
+      if (zincObject.animationClip && zincObject.animationClip[0]) {
+        const mesh = zincObject.getMorph();
+        if (mesh && isVisible(mesh)) {
+          // The exporter resolves tracks against the scene root, but morph
+          // clips target '' (the mesh itself), so retarget them by uuid.
+          const clip = zincObject.animationClip[0].clone();
+          clip.tracks.forEach(track => { track.name = mesh.uuid + track.name; });
+          animations.push(clip);
+        }
+      }
+      // Glyphsets with GPU-compute-driven colour intentionally keep
+      // instanceColor null during normal rendering (see glyphset.js's
+      // prepareColorForExport() for why) - populate it just for this
+      // export, then undo it again afterwards.
+      if (zincObject.isGlyphset && zincObject.prepareColorForExport) {
+        await zincObject.prepareColorForExport();
+        glyphsetsToRestore.push(zincObject);
       }
-    });
+    }
     const exporter = new GLTFExporter();
-    const options = { binary, animations };
-    return new Promise((resolve, reject) => {
-      exporter.parse( scene.getThreeJSScene(), function ( gltf ) {
-        resolve(gltf);
-      }, options );
-    });
+    exporter.register(writer => new GLTFMorphColourPlugin(writer));
+    const options = { binary, animations, onlyVisible: true };
+    try {
+      return await new Promise((resolve, reject) => {
+        exporter.parse(
+          scene.getThreeJSScene(),
+          function ( gltf ) {
+            resolve(gltf);
+          },
+          function ( error ) {
+            console.error("Unable to export GLTF.", error);
+            reject(error);
+          },
+          options );
+      });
+    } finally {
+      glyphsetsToRestore.forEach(zincObject => zincObject.clearColorExportState());
+    }
 	}
 }
 

package/src/tsl/glyphRenderMaterial.js

@@ -0,0 +1,53 @@
+import * as THREE from 'three/webgpu';
+import { Fn, instanceIndex, positionGeometry, materialColor, materialOpacity, vec4 } from 'three/tsl';
+import { NODE_MATERIAL_CLASSES } from './morphColorMaterial';
+
+/**
+ * Builds a NodeMaterial that renders each glyph instance's transform and
+ * colour read directly from a glyphCompute's (see ../tsl/glyphTransform.js)
+ * GPU output buffers, via a custom positionNode/colorNode - i.e. no
+ * instanceMatrix/instanceColor CPU sync is involved in producing what gets
+ * drawn. This is what lets Glyphset render every frame of an animation
+ * straight from the compute pass's output with zero GPU->CPU readback.
+ *
+ * Per NodeMaterial.setupPosition(), setting `positionNode` fully replaces
+ * (not composes with) the automatic per-instance instanceMatrix transform a
+ * stock THREE.InstancedMesh would otherwise apply - so instanceMatrix is
+ * simply irrelevant to rendering once this is set, no double-transform risk.
+ * (instanceMatrix is still kept in sync separately, when paused, purely so
+ * Glyphset's existing bounding-box/raycast code - which does need a
+ * CPU-side transform to read - keeps working unmodified.)
+ *
+ * @param {THREE.Material} sourceMaterial - the material JSONLoader produced
+ *   for this glyph geometry; converted to its NodeMaterial equivalent.
+ * @param {Object} glyphCompute - return value of createGlyphTransformCompute().
+ * @returns {THREE.NodeMaterial}
+ */
+function createGlyphInstancedMaterial(sourceMaterial, glyphCompute) {
+  let material = sourceMaterial;
+  if (!material || !material.isNodeMaterial) {
+    const NodeMaterialClass = (sourceMaterial && NODE_MATERIAL_CLASSES[sourceMaterial.type]) || THREE.MeshPhongNodeMaterial;
+    material = new NodeMaterialClass();
+    if (sourceMaterial) material.copy(sourceMaterial);
+  }
+
+  const { position, axis1, axis2, axis3, color } = glyphCompute.outputs;
+
+  material.positionNode = Fn(() => {
+    const idx = instanceIndex;
+    return position.element(idx)
+      .add(axis1.element(idx).mul(positionGeometry.x))
+      .add(axis2.element(idx).mul(positionGeometry.y))
+      .add(axis3.element(idx).mul(positionGeometry.z));
+  })();
+
+  if (color) {
+    material.colorNode = Fn(() => {
+      return vec4(color.element(instanceIndex).mul(materialColor), materialOpacity);
+    })();
+  }
+
+  return material;
+}
+
+export { createGlyphInstancedMaterial };

package/src/tsl/glyphTransform.js

@@ -0,0 +1,306 @@
+import * as THREE from 'three/webgpu';
+import {
+  Fn,
+  If,
+  attributeArray,
+  instanceIndex,
+  int,
+  float,
+  vec3,
+  uniform,
+  mix,
+  select,
+  max,
+} from 'three/tsl';
+
+/**
+ * Mirrors the string repeat_mode values used throughout glyphset.js as small
+ * integers, since TSL uniforms/comparisons work with numeric types.
+ */
+const REPEAT_MODE = { NONE: 0, MIRROR: 1, AXES_2D: 2, AXES_3D: 3 };
+
+const repeatModeToInt = (repeat_mode) => {
+  switch (repeat_mode) {
+    case "MIRROR": return REPEAT_MODE.MIRROR;
+    case "AXES_2D": return REPEAT_MODE.AXES_2D;
+    case "AXES_3D": return REPEAT_MODE.AXES_3D;
+    default: return REPEAT_MODE.NONE;
+  }
+}
+
+const multiplierForRepeatMode = (repeat_mode) => {
+  if (repeat_mode == "AXES_2D" || repeat_mode == "MIRROR") return 2;
+  if (repeat_mode == "AXES_3D") return 3;
+  return 1;
+}
+
+/**
+ * GPU port of Glyphset's resolve_glyph_axes() + the per-frame keyframe
+ * interpolation from updateMorphGlyphsets(). This is only used for the
+ * recurring, per-frame time-varying animation path - the one-time,
+ * load-time glyph transform/colour computation still runs on the CPU (see
+ * glyphset.js).
+ *
+ * baseSize/offset/scaleFactors/globalScale/repeat_mode are fixed for the
+ * lifetime of a glyphset, so they're baked in as uniforms once here rather
+ * than re-passed on every dispatch; bottomFrame/topFrame/proportion are the
+ * only per-frame-changing uniforms (see uniforms.bottomFrame etc. on the
+ * returned object).
+ *
+ * @param {Object} params
+ * @param {number} params.baseCount - number of raw (pre-repeat_mode-expansion)
+ *   glyph records per keyframe (positions.length/3 for a single frame).
+ * @param {number} params.numberOfTimeSteps - number of keyframes.
+ * @param {number} params.outputCount - final instance count after
+ *   repeat_mode expansion (glyphset.js's numberOfVertices).
+ * @param {string} params.repeat_mode - "NONE" | "MIRROR" | "AXES_2D" | "AXES_3D".
+ * @param {Float32Array} params.positionsData - flattened [time][record][xyz].
+ * @param {Float32Array} params.axis1Data
+ * @param {Float32Array} params.axis2Data
+ * @param {Float32Array} params.axis3Data
+ * @param {Float32Array} params.scaleData
+ * @param {Float32Array} [params.colorData] - flattened [time][record][rgb],
+ *   omitted when the glyphset has no colours.
+ * @param {Array<number>} params.baseSize
+ * @param {Array<number>} params.offset
+ * @param {Array<number>} params.scaleFactors
+ * @returns {Object} { uniforms, compute, outputs } - update
+ *   uniforms.bottomFrame/topFrame/proportion.value then pass `compute` to
+ *   renderer.compute()/computeAsync(); read results back from
+ *   outputs.position/axis1/axis2/axis3/color (each a StorageBufferNode -
+ *   the raw attribute to read back is `outputs.position.value` etc).
+ */
+function createGlyphTransformCompute({
+  baseCount,
+  outputCount,
+  repeat_mode,
+  positionsData,
+  axis1Data,
+  axis2Data,
+  axis3Data,
+  scaleData,
+  colorData,
+  baseSize,
+  offset,
+  scaleFactors,
+  globalScale,
+}) {
+  const multiplier = multiplierForRepeatMode(repeat_mode);
+
+  const positionsBuffer = attributeArray(positionsData, 'vec3');
+  const axis1Buffer = attributeArray(axis1Data, 'vec3');
+  const axis2Buffer = attributeArray(axis2Data, 'vec3');
+  const axis3Buffer = attributeArray(axis3Data, 'vec3');
+  const scaleBuffer = attributeArray(scaleData, 'vec3');
+  const colorBuffer = colorData ? attributeArray(colorData, 'vec3') : undefined;
+
+  const outPosition = attributeArray(outputCount, 'vec3');
+  const outAxis1 = attributeArray(outputCount, 'vec3');
+  const outAxis2 = attributeArray(outputCount, 'vec3');
+  const outAxis3 = attributeArray(outputCount, 'vec3');
+  const outColor = colorData ? attributeArray(outputCount, 'vec3') : undefined;
+
+  const uniforms = {
+    bottomFrame: uniform(0, 'int'),
+    topFrame: uniform(0, 'int'),
+    proportion: uniform(1),
+    repeatMode: uniform(repeatModeToInt(repeat_mode), 'int'),
+    baseSize: uniform(new THREE.Vector3(...baseSize)),
+    offset: uniform(new THREE.Vector3(...offset)),
+    scaleFactors: uniform(new THREE.Vector3(...scaleFactors)),
+    globalScale: uniform(globalScale),
+  };
+
+  const computeFn = Fn(() => {
+
+    const outIdx = int(instanceIndex);
+    const inputIdx = outIdx.div(int(multiplier));
+    const copyIdx = outIdx.mod(int(multiplier));
+
+    const bottomIdx = uniforms.bottomFrame.mul(int(baseCount)).add(inputIdx);
+    const topIdx = uniforms.topFrame.mul(int(baseCount)).add(inputIdx);
+
+    // Matches updateMorphGlyphsets(): bottom*proportion + top*(1-proportion).
+    const point = mix(positionsBuffer.element(topIdx), positionsBuffer.element(bottomIdx), uniforms.proportion);
+    const axis1 = mix(axis1Buffer.element(topIdx), axis1Buffer.element(bottomIdx), uniforms.proportion);
+    const axis2 = mix(axis2Buffer.element(topIdx), axis2Buffer.element(bottomIdx), uniforms.proportion);
+    const axis3 = mix(axis3Buffer.element(topIdx), axis3Buffer.element(bottomIdx), uniforms.proportion);
+    const scale = mix(scaleBuffer.element(topIdx), scaleBuffer.element(bottomIdx), uniforms.proportion);
+
+    // NOTE: each branch below assigns straight into the output storage
+    // buffer elements (outPosition.element(outIdx).assign(...) etc.),
+    // rather than into a shared vec3(0).toVar() declared before the
+    // If/Else and read back afterwards - that pattern (var declared
+    // outside an If().Else(), written in both branches, read after)
+    // reliably crashes this three.js version's WGSL codegen (verified via
+    // a native crash bisected down to exactly that shape in
+    // test/glyphTransformCompute.test.js's development). Writing directly
+    // to the output buffer inside each branch avoids it.
+
+    const isNoneOrMirror = uniforms.repeatMode.equal(int(REPEAT_MODE.NONE))
+      .or(uniforms.repeatMode.equal(int(REPEAT_MODE.MIRROR)));
+
+    If(isNoneOrMirror, () => {
+
+      // resolve_glyph_axes(): NONE / MIRROR branch.
+      const signVec = vec3(
+        select(scale.x.lessThan(0), float(-1), float(1)),
+        select(scale.y.lessThan(0), float(-1), float(1)),
+        select(scale.z.lessThan(0), float(-1), float(1)),
+      );
+      const axisScale = signVec.mul(uniforms.baseSize).add(scale.mul(uniforms.scaleFactors)).mul(uniforms.globalScale);
+      const baseAxis1 = axis1.mul(axisScale.x);
+      const baseAxis2 = axis2.mul(axisScale.y);
+      const baseAxis3 = axis3.mul(axisScale.z);
+      const basePoint = point
+        .add(baseAxis1.mul(uniforms.offset.x))
+        .add(baseAxis2.mul(uniforms.offset.y))
+        .add(baseAxis3.mul(uniforms.offset.z));
+
+      const isMirrorCopy = uniforms.repeatMode.equal(int(REPEAT_MODE.MIRROR)).and(copyIdx.equal(int(1)));
+
+      const a1 = select(isMirrorCopy, baseAxis1.negate(), baseAxis1).toVar();
+      const a2 = select(isMirrorCopy, baseAxis2.negate(), baseAxis2).toVar();
+      const a3 = select(isMirrorCopy, baseAxis3.negate(), baseAxis3).toVar();
+      const p = basePoint.toVar();
+
+      If(uniforms.repeatMode.equal(int(REPEAT_MODE.MIRROR)).and(scale.x.lessThan(0)), () => {
+        // shift glyph origin to end of axis1
+        p.subAssign(a1);
+      });
+
+      // reverse axis3 if required to maintain a right-handed coordinate system
+      const triple = a3.dot(a1.cross(a2));
+      If(triple.lessThan(0), () => {
+        a3.assign(a3.negate());
+      });
+
+      outPosition.element(outIdx).assign(p);
+      outAxis1.element(outIdx).assign(a1);
+      outAxis2.element(outIdx).assign(a2);
+      outAxis3.element(outIdx).assign(a3);
+
+    }).Else(() => {
+
+      // resolve_glyph_axes(): AXES_2D / AXES_3D branch.
+      const signVec = vec3(
+        select(scale.x.lessThan(0), float(-1), float(1)),
+        select(scale.y.lessThan(0), float(-1), float(1)),
+        select(scale.z.lessThan(0), float(-1), float(1)),
+      );
+      const axisScale = signVec.mul(uniforms.baseSize.x).add(scale.mul(uniforms.scaleFactors.x)).mul(uniforms.globalScale);
+      const finalPoint = point
+        .add(axis1.mul(axisScale.x).mul(uniforms.offset.x))
+        .add(axis2.mul(axisScale.y).mul(uniforms.offset.y))
+        .add(axis3.mul(axisScale.z).mul(uniforms.offset.z));
+
+      const useScale = select(copyIdx.equal(int(0)), scale.x,
+        select(copyIdx.equal(int(1)), scale.y, scale.z));
+
+      const isAxes2D = uniforms.repeatMode.equal(int(REPEAT_MODE.AXES_2D));
+
+      const useAxis1 = select(copyIdx.equal(int(0)), axis1,
+        select(copyIdx.equal(int(1)), axis2, axis3));
+      const useAxis2 = select(copyIdx.equal(int(0)), axis2,
+        select(copyIdx.equal(int(1)), select(isAxes2D, axis1, axis3), axis1));
+
+      const finalScale1 = uniforms.baseSize.x.add(useScale.mul(uniforms.scaleFactors.x)).mul(uniforms.globalScale);
+      const finalAxis1 = useAxis1.mul(finalScale1);
+
+      const axis3Raw = finalAxis1.cross(useAxis2);
+      const mag1 = axis3Raw.length();
+      let scaling1 = uniforms.baseSize.z.add(useScale.mul(uniforms.scaleFactors.z)).mul(uniforms.globalScale)
+        .div(max(mag1, 1e-8));
+      scaling1 = select(isAxes2D.and(copyIdx.greaterThan(int(0))), scaling1.mul(-1), scaling1);
+      const finalAxis3 = select(mag1.greaterThan(0), axis3Raw.mul(scaling1), axis3Raw);
+
+      const axis2Raw = finalAxis3.cross(finalAxis1);
+      const mag2 = axis2Raw.length();
+      const scaling2 = uniforms.baseSize.y.add(useScale.mul(uniforms.scaleFactors.y)).mul(uniforms.globalScale)
+        .div(max(mag2, 1e-8));
+      const finalAxis2 = select(mag2.greaterThan(0), axis2Raw.mul(scaling2), axis2Raw);
+
+      outPosition.element(outIdx).assign(finalPoint);
+      outAxis1.element(outIdx).assign(finalAxis1);
+      outAxis2.element(outIdx).assign(finalAxis2);
+      outAxis3.element(outIdx).assign(finalAxis3);
+
+    });
+
+    if (colorBuffer) {
+      const color = mix(colorBuffer.element(topIdx), colorBuffer.element(bottomIdx), uniforms.proportion);
+      outColor.element(outIdx).assign(color);
+    }
+
+  } )().compute( outputCount );
+
+  return {
+    uniforms,
+    compute: computeFn,
+    outputs: {
+      position: outPosition,
+      axis1: outAxis1,
+      axis2: outAxis2,
+      axis3: outAxis3,
+      color: outColor,
+    },
+  };
+}
+
+/**
+ * Reads a glyph-transform compute pass's output buffers back to the CPU,
+ * without dispatching a new renderer.compute() call first - i.e. assumes
+ * the buffers already hold the desired result from a previous compute()
+ * dispatch (see dispatchAndReadbackGlyphTransform, or a bare
+ * renderer.compute(glyphCompute.compute) call). Split out from
+ * dispatchAndReadbackGlyphTransform so a caller that already dispatched
+ * recently (e.g. Glyphset's debounced accurate resync, which reuses the
+ * buffers its own immediately-preceding fast/no-readback dispatch just
+ * wrote) doesn't have to pay for - or risk - a second, redundant
+ * renderer.compute() call right on top of the first: back-to-back compute
+ * dispatches in close succession have been observed to reliably crash the
+ * (Node-only, test-time) WebGPU native backend.
+ *
+ * @param {THREE.WebGPURenderer} renderer
+ * @param {Object} glyphCompute - return value of createGlyphTransformCompute().
+ * @returns {Promise<Object>} { position, axis1, axis2, axis3, color } -
+ *   plain Float32Arrays, one vec3 per output glyph instance (color only
+ *   present when the glyphset has colours).
+ */
+async function readbackGlyphTransform(renderer, glyphCompute) {
+  const { position, axis1, axis2, axis3, color } = glyphCompute.outputs;
+  // Read sequentially rather than Promise.all-ing these - concurrent
+  // getArrayBufferAsync() calls against the same device have been observed
+  // to crash the (Node-only, test-time) WebGPU native backend; one at a
+  // time is the safe pattern here.
+  const positionResult = new Float32Array(await renderer.getArrayBufferAsync(position.value));
+  const axis1Result = new Float32Array(await renderer.getArrayBufferAsync(axis1.value));
+  const axis2Result = new Float32Array(await renderer.getArrayBufferAsync(axis2.value));
+  const axis3Result = new Float32Array(await renderer.getArrayBufferAsync(axis3.value));
+  const colorResult = color ? new Float32Array(await renderer.getArrayBufferAsync(color.value)) : undefined;
+
+  return {
+    position: positionResult,
+    axis1: axis1Result,
+    axis2: axis2Result,
+    axis3: axis3Result,
+    color: colorResult,
+  };
+}
+
+/**
+ * Dispatches a glyph-transform compute pass built by
+ * createGlyphTransformCompute() and reads its output buffers back to the
+ * CPU. Update `glyphCompute.uniforms.bottomFrame/topFrame/proportion(/
+ * globalScale).value` before calling this.
+ *
+ * @param {THREE.WebGPURenderer} renderer
+ * @param {Object} glyphCompute - return value of createGlyphTransformCompute().
+ * @returns {Promise<Object>} see readbackGlyphTransform().
+ */
+async function dispatchAndReadbackGlyphTransform(renderer, glyphCompute) {
+  renderer.compute(glyphCompute.compute);
+  return readbackGlyphTransform(renderer, glyphCompute);
+}
+
+export { createGlyphTransformCompute, dispatchAndReadbackGlyphTransform, readbackGlyphTransform, REPEAT_MODE };