@zephyr3d/scene 0.9.24 → 0.9.26

package/dist/scene/hair.js

@@ -0,0 +1,963 @@
+import { applyMixins, DRef, Vector3 } from '@zephyr3d/base';
+import { GraphNode } from './graph_node.js';
+import { mixinDrawable } from '../render/drawable_mixin.js';
+import { QUEUE_OPAQUE } from '../values.js';
+import '../render/render_queue.js';
+import { getEngine } from '../app/api.js';
+import { Primitive } from '../render/primitive.js';
+import '@zephyr3d/device';
+import '../material/shader/helper.js';
+import '../material/lambert.js';
+import '../material/blinn.js';
+import '../material/unlit.js';
+import '../material/particle.js';
+import '../material/subsurfaceprofile.js';
+import '../material/skin.js';
+import '../material/eye.js';
+import '../material/meshmaterial.js';
+import '../material/hair.js';
+import { HairStrandMaterial } from '../material/hairstrand.js';
+import { HairStrandData } from '../material/hairstrand_data.js';
+import '../material/grassmaterial.js';
+import '../material/terrain-cm.js';
+import '../material/pbrmr.js';
+import '../material/pbrsg.js';
+import '../material/mtoon.js';
+import '../material/pbrblueprint.js';
+import '../material/sprite.js';
+import '../material/sprite_std.js';
+import '../utility/blueprint/material/texture.js';
+import '../render/rendergraph/forward_plus_builder.js';
+import '../render/lightpass.js';
+import '../render/sky.js';
+import '../render/clipmap.js';
+import '../render/envlight.js';
+import '../render/dualdepthpeeling_oit.js';
+import '../shaders/atmosphere.js';
+import '../render/rendergraph/scene_render_context.js';
+import { isHairSimulationSupported, GPUHairSimulation } from '../animation/hair/gpu_hair_simulation.js';
+import { parseZHair } from '../asset/loaders/zhair/zhair_format.js';
+import { mergeHairStrandSources, loadZHairStrandSources } from '../asset/loaders/zhair/zhair_loader.js';
+import { BoundingBox } from '../utility/bounding_volume.js';
+
+/**
+ * Hair scene node.
+ *
+ * @remarks
+ * Point it at a `.zhair` asset with {@link HairNode.setHairAsset}, or hand it
+ * control points directly with {@link HairNode.setStrands}. Everything the draw
+ * call needs is derived from them.
+ *
+ * @public
+ */ class HairNode extends applyMixins(GraphNode, mixinDrawable) {
+    /** @internal */ _pickTarget;
+    /** @internal */ _material;
+    /** @internal */ _primitive;
+    /** @internal */ _strands;
+    /** @internal Local-space bounds of the control points, width included. */ _bounds;
+    /** @internal Length of the longest strand, for padding the bounds while simulating. */ _maxStrandLength;
+    /** @internal */ _castShadow;
+    /** @internal Kept so the simulation can be rebuilt from the authored pose. */ _source;
+    /** @internal Path of the `.zhair` asset, empty when strands were set directly. */ _hairAsset;
+    /**
+   * @internal The opened asset, kept so decimation can be changed without
+   * reading the file again.
+   */ _parsedAsset;
+    /** @internal */ _strandStride;
+    /** @internal */ _maxStrands;
+    /** @internal */ _simulation;
+    /** @internal */ _simulationEnabled;
+    /**
+   * @internal Simulation tuning, owned by the node.
+   *
+   * Held here rather than on the simulation because the node outlives it: the
+   * dials survive the simulation being switched off and on, and can be set
+   * before any strands have loaded.
+   */ _simulationOptions;
+    /**
+   * Creates an empty hair node.
+   *
+   * @param scene - Scene the node belongs to.
+   */ constructor(scene){
+        super(scene);
+        this._pickTarget = {
+            node: this
+        };
+        this._material = new DRef(new HairStrandMaterial());
+        this._primitive = new DRef();
+        this._strands = new DRef();
+        this._bounds = null;
+        this._maxStrandLength = 0;
+        this._castShadow = true;
+        this._source = null;
+        this._hairAsset = '';
+        this._parsedAsset = null;
+        this._strandStride = 1;
+        this._maxStrands = 0;
+        this._simulation = null;
+        this._simulationEnabled = false;
+        this._simulationOptions = {
+            gravity: new Vector3(0, -9.8, 0),
+            damping: 0.08,
+            globalStiffness: 0,
+            globalRange: 0,
+            localStiffness: 0.9,
+            localIterations: 2,
+            ftlDamping: 0.7,
+            vspCoeff: 0.8,
+            vspAccelThreshold: 50,
+            substeps: 1,
+            friction: 0.2,
+            maxSpeedFactor: 4
+        };
+    }
+    //
+    // Geometry
+    //
+    /** Path of the `.zhair` asset this node draws, or an empty string. */ get hairAsset() {
+        return this._hairAsset;
+    }
+    /**
+   * Loads a `.zhair` asset.
+   *
+   * @remarks
+   * The opened file is kept, so changing {@link HairNode.strandStride} or
+   * {@link HairNode.maxStrands} afterwards re-decimates what is already in
+   * memory instead of reading it again - and never touches the source archive
+   * the asset was converted from.
+   *
+   * @param path - Asset path, or an empty string to clear the node.
+   */ async setHairAsset(path) {
+        const assetId = path?.trim() ?? '';
+        if (assetId === this._hairAsset) {
+            return;
+        }
+        this._hairAsset = assetId;
+        this._parsedAsset = null;
+        if (!assetId) {
+            this.setStrands(null);
+            return;
+        }
+        let parsed;
+        try {
+            const data = await getEngine().resourceManager.assetManager.fetchBinaryData(assetId);
+            parsed = parseZHair(data);
+        } catch (err) {
+            console.error(`Load hair asset failed: ${assetId}: ${err}`);
+            this.setStrands(null);
+            return;
+        }
+        // A load that was superseded while it was in flight must not overwrite the
+        // asset that replaced it.
+        if (this._hairAsset !== assetId) {
+            return;
+        }
+        this._parsedAsset = parsed;
+        this._applyAssetDecimation();
+    }
+    /**
+   * Draw one strand in every `strandStride`.
+   *
+   * @remarks
+   * A stride rather than a leading slice, so the kept strands stay spread over
+   * the whole scalp instead of leaving a bald patch. Only meaningful when the
+   * strands came from an asset; strands set directly are used as given.
+   */ get strandStride() {
+        return this._strandStride;
+    }
+    set strandStride(val) {
+        const v = val < 1 ? 1 : val | 0;
+        if (v !== this._strandStride) {
+            this._strandStride = v;
+            this._applyAssetDecimation();
+        }
+    }
+    /**
+   * Upper bound on the number of strands drawn, or 0 for no bound.
+   *
+   * @remarks
+   * Applied on top of {@link HairNode.strandStride} by widening the stride
+   * further, so the result stays evenly spread.
+   */ get maxStrands() {
+        return this._maxStrands;
+    }
+    set maxStrands(val) {
+        const v = val < 0 ? 0 : val | 0;
+        if (v !== this._maxStrands) {
+            this._maxStrands = v;
+            this._applyAssetDecimation();
+        }
+    }
+    /** GPU-resident strand geometry, or null when none has been assigned. */ get strands() {
+        return this._strands.get();
+    }
+    /** Number of strands currently drawn. */ get strandCount() {
+        return this._strands.get()?.strandCount ?? 0;
+    }
+    /**
+   * Replaces the strands this node draws.
+   *
+   * @remarks
+   * The direct route, for strands built in code rather than loaded from an
+   * asset. Uploads the control points, sizes the draw call and recomputes the
+   * bounding box; the previous strand data is released and any running
+   * simulation is rebuilt, since its rest pose comes from the strands.
+   *
+   * @param source - Control points and topology, or null to clear the node.
+   */ setStrands(source) {
+        this._disposeSimulation();
+        this._strands.dispose();
+        this._bounds = null;
+        this._maxStrandLength = 0;
+        this._source = null;
+        if (!source) {
+            this.material.strands = null;
+            this._primitive.dispose();
+            this.invalidateBoundingVolume();
+            return;
+        }
+        const data = new HairStrandData(source);
+        this._strands.set(data);
+        this._source = source;
+        this.material.strands = data;
+        const extents = computeStrandExtents(source);
+        this._bounds = extents.bounds;
+        this._maxStrandLength = extents.maxStrandLength;
+        this._ensurePrimitive();
+        this._syncDrawRange();
+        this.invalidateBoundingVolume();
+        if (this._simulationEnabled) {
+            this._createSimulation();
+        }
+    }
+    //
+    // Shading
+    //
+    // The material is an implementation detail of this node - see the class
+    // remarks - so its controls are surfaced here. Only the ones that do something
+    // on the strand path are: the vertex shader emits no texture coordinates, so
+    // the material's albedo, shift and occlusion maps have nothing to sample and
+    // are deliberately left unreachable.
+    //
+    /** Base colour of the strands. */ get albedoColor() {
+        return this.material.albedoColor;
+    }
+    set albedoColor(value) {
+        this.material.albedoColor = value;
+    }
+    /**
+   * Which scattering model shades the hair.
+   *
+   * @remarks
+   * `kajiya-kay` is the art-directed double lobe; `marschner` derives the lobes
+   * from the fibre and is the one that renders back-lighting.
+   */ get shadingModel() {
+        return this.material.shadingModel;
+    }
+    set shadingModel(value) {
+        this.material.shadingModel = value;
+    }
+    /** Colour of the primary, near-white specular lobe. */ get specular1Color() {
+        return this.material.specular1Color;
+    }
+    set specular1Color(value) {
+        this.material.specular1Color = value;
+    }
+    /** Exponent of the primary specular lobe. */ get specular1Power() {
+        return this.material.specular1Power;
+    }
+    set specular1Power(value) {
+        this.material.specular1Power = value;
+    }
+    /** Shift of the primary specular lobe along the strand. */ get specular1Shift() {
+        return this.material.specular1Shift;
+    }
+    set specular1Shift(value) {
+        this.material.specular1Shift = value;
+    }
+    /** Colour of the secondary, tinted specular lobe. */ get specular2Color() {
+        return this.material.specular2Color;
+    }
+    set specular2Color(value) {
+        this.material.specular2Color = value;
+    }
+    /** Exponent of the secondary specular lobe. */ get specular2Power() {
+        return this.material.specular2Power;
+    }
+    set specular2Power(value) {
+        this.material.specular2Power = value;
+    }
+    /** Shift of the secondary specular lobe along the strand. */ get specular2Shift() {
+        return this.material.specular2Shift;
+    }
+    set specular2Shift(value) {
+        this.material.specular2Shift = value;
+    }
+    /** How far diffuse lighting wraps around the fibre. */ get diffuseWrap() {
+        return this.material.diffuseWrap;
+    }
+    set diffuseWrap(value) {
+        this.material.diffuseWrap = value;
+    }
+    /** Colour of light transmitted through the fibre. */ get transmissionColor() {
+        return this.material.transmissionColor;
+    }
+    set transmissionColor(value) {
+        this.material.transmissionColor = value;
+    }
+    /** Strength of back-lit transmission. */ get transmissionIntensity() {
+        return this.material.transmissionIntensity;
+    }
+    set transmissionIntensity(value) {
+        this.material.transmissionIntensity = value;
+    }
+    /** Falloff exponent of back-lit transmission. */ get transmissionPower() {
+        return this.material.transmissionPower;
+    }
+    set transmissionPower(value) {
+        this.material.transmissionPower = value;
+    }
+    /** Colour of multiple scattering within the groom. */ get scatterColor() {
+        return this.material.scatterColor;
+    }
+    set scatterColor(value) {
+        this.material.scatterColor = value;
+    }
+    /** Strength of multiple scattering. */ get scatterIntensity() {
+        return this.material.scatterIntensity;
+    }
+    set scatterIntensity(value) {
+        this.material.scatterIntensity = value;
+    }
+    /** Share of scattering taken as local rather than global. */ get scatterLocal() {
+        return this.material.scatterLocal;
+    }
+    set scatterLocal(value) {
+        this.material.scatterLocal = value;
+    }
+    /** How far scattered light wraps around the fibre. */ get scatterWrap() {
+        return this.material.scatterWrap;
+    }
+    set scatterWrap(value) {
+        this.material.scatterWrap = value;
+    }
+    /** Longitudinal shift of the Marschner lobes. */ get marschnerShift() {
+        return this.material.marschnerShift;
+    }
+    set marschnerShift(value) {
+        this.material.marschnerShift = value;
+    }
+    /** Longitudinal roughness of the Marschner lobes. */ get marschnerRoughness() {
+        return this.material.marschnerRoughness;
+    }
+    set marschnerRoughness(value) {
+        this.material.marschnerRoughness = value;
+    }
+    /** Index of refraction of the fibre. */ get marschnerIOR() {
+        return this.material.marschnerIOR;
+    }
+    set marschnerIOR(value) {
+        this.material.marschnerIOR = value;
+    }
+    /**
+   * How strongly pigmented the fibre is.
+   *
+   * @remarks
+   * A multiplier on the distance transmitted light travels before leaving, so
+   * raising it deepens the colour of the TT and TRT paths without touching the
+   * white surface reflection.
+   */ get marschnerAbsorption() {
+        return this.material.marschnerAbsorption;
+    }
+    set marschnerAbsorption(value) {
+        this.material.marschnerAbsorption = value;
+    }
+    /** Relative weight of the R, TT and TRT lobes. */ get marschnerLobes() {
+        return this.material.marschnerLobes;
+    }
+    set marschnerLobes(value) {
+        this.material.marschnerLobes = value;
+    }
+    //
+    // Strand expansion
+    //
+    /**
+   * Ribbon segments generated per strand.
+   *
+   * @remarks
+   * The main quality dial, and independent of how many control points a strand
+   * has: the shader resamples the curve, so the same 30-point strand can be
+   * drawn with 12 segments close up and 3 far away.
+   */ get segmentsPerStrand() {
+        return this.material.segmentsPerStrand;
+    }
+    set segmentsPerStrand(val) {
+        if (val !== this.material.segmentsPerStrand) {
+            this.material.segmentsPerStrand = val;
+            this._syncDrawRange();
+        }
+    }
+    /** Multiplier on the width stored in the strand data. */ get strandWidthScale() {
+        return this.material.strandWidthScale;
+    }
+    set strandWidthScale(value) {
+        this.material.strandWidthScale = value;
+    }
+    /** Lower bound on ribbon width, in world units. */ get minStrandWidth() {
+        return this.material.minStrandWidth;
+    }
+    set minStrandWidth(value) {
+        this.material.minStrandWidth = value;
+    }
+    /**
+   * Lower bound on ribbon width, in pixels.
+   *
+   * @remarks
+   * Real hair is thinner than a pixel and rasterises to a flickering dotted
+   * line. Widening it to about a pixel and paying the extra coverage back in
+   * alpha keeps distant hair fading rather than breaking up.
+   */ get minPixelWidth() {
+        return this.material.minPixelWidth;
+    }
+    set minPixelWidth(value) {
+        this.material.minPixelWidth = value;
+    }
+    /**
+   * How far the shading normal bends across the ribbon, in [0, 1].
+   *
+   * @remarks
+   * At 0 a strand shades as a flat tape, at 1 as a cylinder.
+   */ get strandRoundness() {
+        return this.material.strandRoundness;
+    }
+    set strandRoundness(value) {
+        this.material.strandRoundness = value;
+    }
+    /**
+   * Strength of the root-depth ambient occlusion, in [0, 1].
+   *
+   * @remarks
+   * Environment irradiance is not attenuated by anything - a shadow map answers
+   * for one light, not for the sky - so without this every strand of a groom
+   * receives the full sky and a dense hairstyle is lit as brightly in its
+   * interior as on its surface, which reads as a flat silhouette with no volume.
+   * Most obvious on pale hair, where there is little pigment to darken the
+   * interior instead. Set to 0 to disable.
+   *
+   * Ambient light only: direct light is already attenuated by the shadow map,
+   * and under DOM by a graded transmittance, so it is left alone.
+   */ get rootOcclusion() {
+        return this.material.rootOcclusion;
+    }
+    set rootOcclusion(value) {
+        this.material.rootOcclusion = value;
+    }
+    /**
+   * How far along a strand the root occlusion reaches, in (0, 1].
+   *
+   * @remarks
+   * Short for a groom whose strands leave the scalp quickly, longer for one
+   * where they lie against each other most of their length.
+   */ get rootOcclusionRange() {
+        return this.material.rootOcclusionRange;
+    }
+    set rootOcclusionRange(value) {
+        this.material.rootOcclusionRange = value;
+    }
+    /** Drop strands with distance, redistributing their coverage to the survivors. */ get strandLOD() {
+        return this.material.strandLOD;
+    }
+    set strandLOD(value) {
+        this.material.strandLOD = value;
+    }
+    /** Floor on the fraction of strands distance decimation keeps. */ get minStrandLODRatio() {
+        return this.material.minStrandLODRatio;
+    }
+    set minStrandLODRatio(value) {
+        this.material.minStrandLODRatio = value;
+    }
+    //
+    // Transparency and shadows
+    //
+    /**
+   * How the strands blend with what is behind them.
+   *
+   * @remarks
+   * The pixel-width floor pays its widening back in alpha, which only means
+   * anything once blending is on; left at `none` every strand covers its pixel
+   * fully and a dense groom reads as a solid shell.
+   */ get blendMode() {
+        return this.material.blendMode;
+    }
+    set blendMode(value) {
+        this.material.blendMode = value;
+    }
+    /** Alpha below which a fragment is discarded. */ get alphaCutoff() {
+        return this.material.alphaCutoff;
+    }
+    set alphaCutoff(value) {
+        this.material.alphaCutoff = value;
+    }
+    /** Dither the alpha test, so a temporal filter resolves the soft edge. */ get alphaDither() {
+        return this.material.alphaDither;
+    }
+    set alphaDither(value) {
+        this.material.alphaDither = value;
+    }
+    /**
+   * Whether a blended groom contributes motion vectors.
+   *
+   * @remarks
+   * Only meaningful with {@link HairNode.blendMode} set to something other than
+   * `none`. Blended geometry is otherwise absent from the prepass, so a groom
+   * carries the velocity of whatever is behind it and a temporal filter smears
+   * it as it swings - the same ghosting the dithered path avoids by being
+   * opaque. On by default, because a groom is dense enough to own its pixels
+   * and there is no reason to want the ghosting.
+   */ get transparentMotionVector() {
+        return this.material.transparentMotionVector;
+    }
+    set transparentMotionVector(value) {
+        this.material.transparentMotionVector = value;
+    }
+    /** Whether the groom is drawn into shadow maps. */ get castShadow() {
+        return this._castShadow;
+    }
+    set castShadow(val) {
+        this._castShadow = !!val;
+    }
+    /** Let the shadow caster pass respect strand alpha, for softer self-shadowing. */ get transparentShadowCaster() {
+        return this.material.transparentShadowCaster;
+    }
+    set transparentShadowCaster(value) {
+        this.material.transparentShadowCaster = value;
+    }
+    /** Alpha below which a fragment casts no shadow. */ get shadowAlphaCutoff() {
+        return this.material.shadowAlphaCutoff;
+    }
+    set shadowAlphaCutoff(value) {
+        this.material.shadowAlphaCutoff = value;
+    }
+    //
+    // Simulation
+    //
+    /**
+   * Whether strand dynamics run on this groom.
+   *
+   * @remarks
+   * WebGPU only. Switching it on with no strands loaded is allowed - the
+   * simulation is built when the strands arrive.
+   */ get simulationEnabled() {
+        return this._simulationEnabled;
+    }
+    set simulationEnabled(val) {
+        const enabled = !!val;
+        if (enabled === this._simulationEnabled) {
+            return;
+        }
+        this._simulationEnabled = enabled;
+        if (enabled) {
+            this._createSimulation();
+        } else {
+            this._disposeSimulation();
+            // Without this the groom keeps whatever pose it was last simulated into,
+            // which reads as a bug rather than as hair that stopped moving.
+            if (this._source) {
+                this._strands.get()?.dispose();
+                this._strands.set(new HairStrandData(this._source));
+                this.material.strands = this._strands.get();
+            }
+            // Back to the tight rest bounds.
+            this.invalidateBoundingVolume();
+        }
+    }
+    /**
+   * The running strand dynamics, or null when they are off or unsupported.
+   *
+   * @remarks
+   * Exposed so a caller can reach past the node's own dials - to set colliders,
+   * for one, which have no serialised form here.
+   */ get simulation() {
+        return this._simulation;
+    }
+    /** World-space gravity acting on the strands. */ get gravity() {
+        return this._simulationOptions.gravity;
+    }
+    set gravity(value) {
+        this._simulationOptions.gravity = new Vector3(value);
+        if (this._simulation) {
+            this._simulation.gravity = this._simulationOptions.gravity;
+        }
+    }
+    /**
+   * How strongly strands keep the shape they were authored with, in [0, 1].
+   *
+   * @remarks
+   * The dial to reach for first. It holds the angle each segment makes with the
+   * one before it, measured against that segment's current direction rather
+   * than a fixed pose, so a groom keeps its curl while remaining free to hang
+   * and swing. It is also what damps a groom: without bending resistance a
+   * strand carries a disturbance up and down its length for seconds.
+   */ get localStiffness() {
+        return this._simulationOptions.localStiffness;
+    }
+    set localStiffness(value) {
+        this._simulationOptions.localStiffness = value;
+        if (this._simulation) {
+            this._simulation.localStiffness = value;
+        }
+    }
+    /** Local shape constraint passes per substep. */ get localIterations() {
+        return this._simulationOptions.localIterations;
+    }
+    set localIterations(value) {
+        this._simulationOptions.localIterations = value;
+        if (this._simulation) {
+            this._simulation.localIterations = value;
+        }
+    }
+    /**
+   * How strongly strands are pulled back to their authored pose, in [0, 1].
+   *
+   * @remarks
+   * Off by default. It anchors a point to a fixed place rather than to its
+   * neighbours, which is a spring, and a groom held by springs reads as one.
+   * {@link HairNode.localStiffness} is what holds styling without that; this is
+   * for grooms that genuinely should not move far from how they were authored,
+   * and wants {@link HairNode.globalRange} set as well.
+   */ get globalStiffness() {
+        return this._simulationOptions.globalStiffness;
+    }
+    set globalStiffness(value) {
+        this._simulationOptions.globalStiffness = value;
+        if (this._simulation) {
+            this._simulation.globalStiffness = value;
+        }
+    }
+    /** Fraction of a strand, from the root, the pose pull acts on, in [0, 1]. */ get globalRange() {
+        return this._simulationOptions.globalRange;
+    }
+    set globalRange(value) {
+        this._simulationOptions.globalRange = value;
+        if (this._simulation) {
+            this._simulation.globalRange = value;
+        }
+    }
+    /**
+   * Share of a point's length correction fed back into its parent, in [0, 1].
+   *
+   * @remarks
+   * What keeps the solver from gaining energy as the node moves. Lowering it
+   * makes a groom livelier and, past a point, makes it whip; 0 removes the
+   * feedback entirely.
+   */ get ftlDamping() {
+        return this._simulationOptions.ftlDamping;
+    }
+    set ftlDamping(value) {
+        this._simulationOptions.ftlDamping = value;
+        if (this._simulation) {
+            this._simulation.ftlDamping = value;
+        }
+    }
+    /** Velocity lost each step, in [0, 1]. */ get damping() {
+        return this._simulationOptions.damping;
+    }
+    set damping(value) {
+        this._simulationOptions.damping = value;
+        if (this._simulation) {
+            this._simulation.damping = value;
+        }
+    }
+    /** Tangential motion removed at a contact, in [0, 1]. */ get friction() {
+        return this._simulationOptions.friction;
+    }
+    set friction(value) {
+        this._simulationOptions.friction = value;
+        if (this._simulation) {
+            this._simulation.friction = value;
+        }
+    }
+    /**
+   * How much of the node's motion strands are carried along by, in [0, 1].
+   *
+   * @remarks
+   * 0 leaves a groom exactly where it was in the world and lets the pinned
+   * roots drag it along, which is what produces lag; 1 carries it rigidly with
+   * the node, so it never lags. Lower values give a livelier, floppier groom.
+   */ get vspCoeff() {
+        return this._simulationOptions.vspCoeff;
+    }
+    set vspCoeff(value) {
+        this._simulationOptions.vspCoeff = value;
+        if (this._simulation) {
+            this._simulation.vspCoeff = value;
+        }
+    }
+    /** Node acceleration above which strands are carried rigidly, in units/s². */ get vspAccelThreshold() {
+        return this._simulationOptions.vspAccelThreshold;
+    }
+    set vspAccelThreshold(value) {
+        this._simulationOptions.vspAccelThreshold = value;
+        if (this._simulation) {
+            this._simulation.vspAccelThreshold = value;
+        }
+    }
+    /**
+   * Per-substep ceiling on how far a point may travel, in segment lengths.
+   *
+   * @remarks
+   * A backstop against a single bad substep, not a dial to shape motion with:
+   * at the default it never engages during ordinary movement.
+   */ get maxSpeedFactor() {
+        return this._simulationOptions.maxSpeedFactor;
+    }
+    set maxSpeedFactor(value) {
+        this._simulationOptions.maxSpeedFactor = value;
+        if (this._simulation) {
+            this._simulation.maxSpeedFactor = value;
+        }
+    }
+    /** Integration substeps per fixed step. */ get substeps() {
+        return this._simulationOptions.substeps;
+    }
+    set substeps(value) {
+        this._simulationOptions.substeps = value;
+        if (this._simulation) {
+            this._simulation.substeps = value;
+        }
+    }
+    //
+    // Scene node and drawable
+    //
+    /**
+   * {@inheritDoc SceneNode.update}
+   *
+   * @remarks
+   * Drives the strand solver. The node re-queues itself every frame, because a
+   * simulation only stands still when it is switched off.
+   */ update(frameId, elapsedInSeconds, deltaInSeconds) {
+        super.update(frameId, elapsedInSeconds, deltaInSeconds);
+        const simulation = this._simulation;
+        if (simulation?.enabled) {
+            simulation.update(deltaInSeconds, this.worldMatrix);
+            this.scene?.queueUpdateNode(this);
+        }
+    }
+    /**
+   * {@inheritDoc SceneNode.computeBoundingVolume}
+   *
+   * @remarks
+   * Derived on the CPU from the control points, because the ribbons are built in
+   * the vertex shader and the engine never sees them. The box is in local space;
+   * the base class applies the world matrix.
+   *
+   * While a simulation runs, the strands swing out of their authored pose, so
+   * the rest bounds are padded by the longest strand: the solver keeps every
+   * point within its strand's length of the pinned root, which bounds any pose
+   * it can produce.
+   */ computeBoundingVolume() {
+        if (!this._bounds) {
+            return null;
+        }
+        const box = new BoundingBox(this._bounds);
+        if (this._simulation) {
+            const pad = this._maxStrandLength;
+            box.minPoint.setXYZ(box.minPoint.x - pad, box.minPoint.y - pad, box.minPoint.z - pad);
+            box.maxPoint.setXYZ(box.maxPoint.x + pad, box.maxPoint.y + pad, box.maxPoint.z + pad);
+        }
+        return box;
+    }
+    /** {@inheritDoc SceneNode.isHair} */ isHair() {
+        return true;
+    }
+    /** {@inheritDoc Drawable.getPickTarget} */ getPickTarget() {
+        return this._pickTarget;
+    }
+    /** {@inheritDoc Drawable.getMaterial} */ getMaterial() {
+        return this._material.get();
+    }
+    /** {@inheritDoc Drawable.getPrimitive} */ getPrimitive() {
+        return this._primitive.get();
+    }
+    /** {@inheritDoc Drawable.getMorphData} */ getMorphData() {
+        return null;
+    }
+    /** {@inheritDoc Drawable.getMorphInfo} */ getMorphInfo() {
+        return null;
+    }
+    /** {@inheritDoc Drawable.getSkinInfluenceData} */ getSkinInfluenceData() {
+        return null;
+    }
+    /** {@inheritDoc Drawable.getQueueType} */ getQueueType() {
+        return this._material.get()?.getQueueType() ?? QUEUE_OPAQUE;
+    }
+    /** {@inheritDoc Drawable.isUnlit} */ isUnlit() {
+        return !this._material.get()?.supportLighting();
+    }
+    /** {@inheritDoc Drawable.needSceneColor} */ needSceneColor() {
+        return this._material.get()?.needSceneColor() ?? false;
+    }
+    /** {@inheritDoc Drawable.needSceneDepth} */ needSceneDepth() {
+        return this._material.get()?.needSceneDepth() ?? false;
+    }
+    /** {@inheritDoc Drawable.draw} */ draw(ctx, renderQueue) {
+        const material = this._material.get();
+        const primitive = this._primitive.get();
+        // An empty groom is a legitimate state - a node exists before its asset has
+        // finished loading - and the draw range is zero until strands arrive.
+        if (material && primitive && material.vertexCount > 0) {
+            this.bind(ctx, renderQueue);
+            material.draw(primitive, ctx);
+        }
+    }
+    onDispose() {
+        super.onDispose();
+        this._disposeSimulation();
+        this._primitive.dispose();
+        this._strands.dispose();
+        this._material.dispose();
+        this._parsedAsset = null;
+        this._source = null;
+        this._bounds = null;
+    }
+    //
+    // Internals
+    //
+    /**
+   * The material, which is an implementation detail of this node.
+   * @internal
+   */ get material() {
+        return this._material.get();
+    }
+    /**
+   * Re-decimates the opened asset into the strands actually drawn.
+   * @internal
+   */ _applyAssetDecimation() {
+        const parsed = this._parsedAsset;
+        if (!parsed) {
+            return;
+        }
+        // A `.zhair` holds one set per source curve object, and an XGen export
+        // routinely carries several spline descriptions for a single hairstyle;
+        // merging lets the whole head draw in one call.
+        this.setStrands(mergeHairStrandSources(loadZHairStrandSources(parsed, {
+            strandStride: this._strandStride,
+            maxStrands: this._maxStrands
+        })));
+    }
+    /**
+   * Starts strand dynamics over the current strands.
+   * @internal
+   */ _createSimulation() {
+        this._disposeSimulation();
+        const data = this._strands.get();
+        if (!data || !this._source || !isHairSimulationSupported()) {
+            return;
+        }
+        const simulation = new GPUHairSimulation(data, this._source, this._simulationOptions);
+        if (simulation.enabled) {
+            this._simulation = simulation;
+            // Motion vectors have to follow the control points once something is
+            // moving them, or a groom swinging under a still head reports no motion
+            // and a temporal filter smears it.
+            this.material.prevPoints = simulation.framePointBuffer;
+            // The bounds widen while a simulation runs - see computeBoundingVolume.
+            this.invalidateBoundingVolume();
+            this.scene?.queueUpdateNode(this);
+        } else {
+            console.warn(simulation.disabledReason ?? 'GPU hair simulation could not start');
+            simulation.dispose();
+        }
+    }
+    /** @internal */ _disposeSimulation() {
+        this.material.prevPoints = null;
+        this._simulation?.dispose();
+        this._simulation = null;
+    }
+    /**
+   * Builds the primitive the draw call is issued against.
+   *
+   * @remarks
+   * No vertex attribute is ever read - the vertex shader derives everything from
+   * the vertex index and the storage buffers - but a draw still needs a vertex
+   * layout to exist, and one float is the smallest buffer that establishes one.
+   * @internal
+   */ _ensurePrimitive() {
+        if (this._primitive.get()) {
+            return;
+        }
+        const primitive = new Primitive();
+        primitive.createAndSetVertexBuffer('position_f32x3', new Float32Array(3));
+        primitive.primitiveType = 'triangle-list';
+        this._primitive.set(primitive);
+    }
+    /**
+   * Points the draw range at however many vertices the material now needs.
+   *
+   * @remarks
+   * Drawing is non-indexed, six vertices per ribbon segment, so the count moves
+   * with both the strand count and {@link HairNode.segmentsPerStrand}.
+   * @internal
+   */ _syncDrawRange() {
+        const primitive = this._primitive.get();
+        if (primitive) {
+            primitive.indexCount = this.material.vertexCount;
+        }
+    }
+}
+/**
+ * Local-space bounds of a strand source, padded by the widest strand, along
+ * with the length of the longest strand.
+ *
+ * @remarks
+ * The ribbon is built around the control point, so half a width would suffice;
+ * a full width is used because {@link HairNode.minPixelWidth} widens sub-pixel
+ * strands beyond their authored size and the box has to survive that.
+ *
+ * The strand length is measured here because the same pass already touches
+ * every point; it pads the bounds while a simulation runs.
+ * @internal
+ */ function computeStrandExtents(source) {
+    const scale = source.scale ?? 1;
+    const positions = source.positions;
+    const box = new BoundingBox();
+    box.beginExtend();
+    let maxStrandLength = 0;
+    let first = 0;
+    for(let s = 0; s < source.pointCounts.length; s++){
+        const count = source.pointCounts[s];
+        let length = 0;
+        for(let i = 0; i < count; i++){
+            const p = (first + i) * 3;
+            const x = positions[p] * scale;
+            const y = positions[p + 1] * scale;
+            const z = positions[p + 2] * scale;
+            box.extend3(x, y, z);
+            if (i > 0) {
+                length += Math.hypot(x - positions[p - 3] * scale, y - positions[p - 2] * scale, z - positions[p - 1] * scale);
+            }
+        }
+        if (length > maxStrandLength) {
+            maxStrandLength = length;
+        }
+        first += count;
+    }
+    let widest = source.defaultWidth ?? 0.0001;
+    if (source.widths) {
+        for(let i = 0; i < source.widths.length; i++){
+            if (source.widths[i] > widest) {
+                widest = source.widths[i];
+            }
+        }
+    }
+    const pad = widest * scale * (source.widthScale ?? 1);
+    box.minPoint.setXYZ(box.minPoint.x - pad, box.minPoint.y - pad, box.minPoint.z - pad);
+    box.maxPoint.setXYZ(box.maxPoint.x + pad, box.maxPoint.y + pad, box.maxPoint.z + pad);
+    return {
+        bounds: box,
+        maxStrandLength
+    };
+}
+
+export { HairNode };
+//# sourceMappingURL=hair.js.map