@zephyr3d/scene 0.9.26 → 0.10.0

package/dist/material/hairstrand.js

@@ -2,34 +2,34 @@ import { HairMaterial } from './hair.js';
 import { ShaderHelper } from './shader/helper.js';
 import { Vector4 } from '@zephyr3d/base';
 
-/**
- * Hair material that expands strand control points into ribbons on the GPU.
- *
- * @remarks
- * Where {@link HairMaterial} shades ribbon geometry that something else built,
- * this material builds the ribbon itself. The vertex shader derives which strand,
- * which segment and which corner it is drawing from the vertex index alone, reads
- * the control points from a storage buffer, and emits a camera-facing quad. No
- * position, normal, tangent or texture coordinate attribute is read.
- *
- * Two things fall out of that, and both are the reason to do it:
- *
- * - **Memory.** A CPU-built ribbon mesh for a full 69k-strand hair set costs
- *   around 266 MB of vertex data. The control points it is built from are about
- *   20 MB, and that is all this material needs resident.
- * - **Orientation.** A stored ribbon has a fixed plane, so there is a viewing
- *   angle at which it degenerates to an edge, and a whole coplanar group of
- *   strands can vanish at once. A quad expanded toward the camera never does.
- *
- * Lighting is inherited unchanged from {@link HairMaterial}, so the two paths
- * shade identically and can be compared against each other.
- *
- * Control points are read in the drawing node's local space and put through its
- * world matrix, so a groom follows the node it hangs off - a head bone, say -
- * and several nodes can share one set of strands at different transforms.
- *
- * Requires storage buffers in the vertex stage, which means WebGPU.
- * @public
+/**
+ * Hair material that expands strand control points into ribbons on the GPU.
+ *
+ * @remarks
+ * Where {@link HairMaterial} shades ribbon geometry that something else built,
+ * this material builds the ribbon itself. The vertex shader derives which strand,
+ * which segment and which corner it is drawing from the vertex index alone, reads
+ * the control points from a storage buffer, and emits a camera-facing quad. No
+ * position, normal, tangent or texture coordinate attribute is read.
+ *
+ * Two things fall out of that, and both are the reason to do it:
+ *
+ * - **Memory.** A CPU-built ribbon mesh for a full 69k-strand hair set costs
+ *   around 266 MB of vertex data. The control points it is built from are about
+ *   20 MB, and that is all this material needs resident.
+ * - **Orientation.** A stored ribbon has a fixed plane, so there is a viewing
+ *   angle at which it degenerates to an edge, and a whole coplanar group of
+ *   strands can vanish at once. A quad expanded toward the camera never does.
+ *
+ * Lighting is inherited unchanged from {@link HairMaterial}, so the two paths
+ * shade identically and can be compared against each other.
+ *
+ * Control points are read in the drawing node's local space and put through its
+ * world matrix, so a groom follows the node it hangs off - a head bone, say -
+ * and several nodes can share one set of strands at different transforms.
+ *
+ * Requires storage buffers in the vertex stage, which means WebGPU.
+ * @public
  */ class HairStrandMaterial extends HairMaterial {
     /** @internal Enables per-strand distance decimation in the vertex shader. */ static FEATURE_STRAND_LOD = this.defineFeature();
     /** @internal Samples a second point buffer to build motion vectors. */ static FEATURE_STRAND_MOTION = this.defineFeature();
@@ -46,8 +46,8 @@ import { Vector4 } from '@zephyr3d/base';
     /** @internal Scratch vector, so applying uniforms allocates nothing. */ _strandScratch;
     /** @internal Scratch vector for the LOD uniform. */ _lodScratch;
     /** @internal Scratch vector for the shape uniform. */ _shapeScratch;
-    /**
-   * Creates a GPU strand material.
+    /**
+   * Creates a GPU strand material.
    */ constructor(){
         super();
         this._strands = null;
@@ -114,13 +114,13 @@ import { Vector4 } from '@zephyr3d/base';
             this.uniformChanged();
         }
     }
-    /**
-   * Ribbon segments generated per strand.
-   *
-   * @remarks
-   * The primary quality/cost dial, and independent of the control point count:
-   * the shader resamples the curve, so the same 30-point strand can be drawn with
-   * 12 segments up close and 3 far away.
+    /**
+   * Ribbon segments generated per strand.
+   *
+   * @remarks
+   * The primary quality/cost dial, and independent of the control point count:
+   * the shader resamples the curve, so the same 30-point strand can be drawn with
+   * 12 segments up close and 3 far away.
    */ get segmentsPerStrand() {
         return this._segmentsPerStrand;
     }
@@ -150,15 +150,15 @@ import { Vector4 } from '@zephyr3d/base';
             this.uniformChanged();
         }
     }
-    /**
-   * Lower bound on ribbon width in pixels.
-   *
-   * @remarks
-   * A strand narrower than a pixel rasterises to a flickering dotted line,
-   * because whether a given segment covers a sample point changes with subpixel
-   * position. Clamping the quad to about a pixel and scaling alpha by how much it
-   * was widened keeps total energy roughly constant, so the strand reads as
-   * fainter rather than as broken. Set to 0 to disable.
+    /**
+   * Lower bound on ribbon width in pixels.
+   *
+   * @remarks
+   * A strand narrower than a pixel rasterises to a flickering dotted line,
+   * because whether a given segment covers a sample point changes with subpixel
+   * position. Clamping the quad to about a pixel and scaling alpha by how much it
+   * was widened keeps total energy roughly constant, so the strand reads as
+   * fainter rather than as broken. Set to 0 to disable.
    */ get minPixelWidth() {
         return this._minPixelWidth;
     }
@@ -169,45 +169,45 @@ import { Vector4 } from '@zephyr3d/base';
             this.uniformChanged();
         }
     }
-    /**
-   * Trades strand count for strand opacity with distance.
-   *
-   * @remarks
-   * Past the point where a strand is thinner than a pixel, {@link minPixelWidth}
-   * widens it and pays the widening back as alpha, so a distant groom is drawn as
-   * tens of thousands of ribbons each contributing a few percent of a pixel. That
-   * is correct on average and unstable in practice: any per-fragment stochastic
-   * alpha - `alphaDither`, alpha-to-coverage - is sampling a five percent event
-   * once per pixel per frame, and the variance reads as pixel-level crawl that a
-   * temporal filter's short history cannot average away.
-   *
-   * This moves the randomness from the fragment to the strand. Each strand is
-   * kept with a probability equal to the coverage it would have been drawn at and
-   * the survivors are drawn at full coverage, which puts the same quantity of hair
-   * on screen: `N` strands at alpha `a` and `N*a` strands at alpha 1 integrate to
-   * the same image. The difference is that the draw is decided once per strand
-   * from a fixed seed rather than once per fragment per frame, so the result is
-   * stable across frames, and the culled strands cost no fragments at all.
-   *
-   * Off by default: it changes which strands are drawn, so it is opted into
-   * rather than applied to existing grooms silently.
+    /**
+   * Trades strand count for strand opacity with distance.
+   *
+   * @remarks
+   * Past the point where a strand is thinner than a pixel, {@link minPixelWidth}
+   * widens it and pays the widening back as alpha, so a distant groom is drawn as
+   * tens of thousands of ribbons each contributing a few percent of a pixel. That
+   * is correct on average and unstable in practice: any per-fragment stochastic
+   * alpha - `alphaDither`, alpha-to-coverage - is sampling a five percent event
+   * once per pixel per frame, and the variance reads as pixel-level crawl that a
+   * temporal filter's short history cannot average away.
+   *
+   * This moves the randomness from the fragment to the strand. Each strand is
+   * kept with a probability equal to the coverage it would have been drawn at and
+   * the survivors are drawn at full coverage, which puts the same quantity of hair
+   * on screen: `N` strands at alpha `a` and `N*a` strands at alpha 1 integrate to
+   * the same image. The difference is that the draw is decided once per strand
+   * from a fixed seed rather than once per fragment per frame, so the result is
+   * stable across frames, and the culled strands cost no fragments at all.
+   *
+   * Off by default: it changes which strands are drawn, so it is opted into
+   * rather than applied to existing grooms silently.
    */ get strandLOD() {
         return this.featureUsed(HairStrandMaterial.FEATURE_STRAND_LOD);
     }
     set strandLOD(val) {
         this.useFeature(HairStrandMaterial.FEATURE_STRAND_LOD, !!val);
     }
-    /**
-   * Control points as of the previously rendered frame, or null.
-   *
-   * @remarks
-   * Set by {@link HairNode} while a simulation is running. Without it the
-   * previous position is the *current* control point put through the previous
-   * world matrix, which carries the node's motion but none of the strand's own -
-   * so a groom swinging under a still head reports no motion at all, and a
-   * temporal filter blends a history that has nothing to do with the pixel.
-   * Costs four extra point fetches per vertex, hence a feature rather than an
-   * always-on path: a static groom does not need it.
+    /**
+   * Control points as of the previously rendered frame, or null.
+   *
+   * @remarks
+   * Set by {@link HairNode} while a simulation is running. Without it the
+   * previous position is the *current* control point put through the previous
+   * world matrix, which carries the node's motion but none of the strand's own -
+   * so a groom swinging under a still head reports no motion at all, and a
+   * temporal filter blends a history that has nothing to do with the pixel.
+   * Costs four extra point fetches per vertex, hence a feature rather than an
+   * always-on path: a static groom does not need it.
    */ get prevPoints() {
         return this._prevPoints;
     }
@@ -218,14 +218,14 @@ import { Vector4 } from '@zephyr3d/base';
     /** Whether motion vectors follow the control points. @internal */ get strandMotion() {
         return this.featureUsed(HairStrandMaterial.FEATURE_STRAND_MOTION);
     }
-    /**
-   * Floor on the fraction of strands {@link strandLOD} keeps.
-   *
-   * @remarks
-   * Decimation follows coverage, and coverage falls without bound as the groom
-   * recedes, so an unclamped ratio eventually culls every strand and the hair
-   * disappears. This is the point past which thinning stops and the remaining
-   * strands simply fade instead. Defaults to 0.05.
+    /**
+   * Floor on the fraction of strands {@link strandLOD} keeps.
+   *
+   * @remarks
+   * Decimation follows coverage, and coverage falls without bound as the groom
+   * recedes, so an unclamped ratio eventually culls every strand and the hair
+   * disappears. This is the point past which thinning stops and the remaining
+   * strands simply fade instead. Defaults to 0.05.
    */ get minStrandLODRatio() {
         return this._minStrandLODRatio;
     }
@@ -236,25 +236,25 @@ import { Vector4 } from '@zephyr3d/base';
             this.uniformChanged();
         }
     }
-    /**
-   * How far the shading normal bends across the ribbon, in [0, 1].
-   *
-   * @remarks
-   * The quad is a stand-in for a cylinder, and this is how much it is shaded like
-   * one. At 1 the normal sweeps a full half turn about the curve tangent between
-   * the two edges, as the visible surface of a fibre does; at 0 it stays the
-   * quad's own normal and every fragment across the width shades identically,
-   * which is the flat ribbon this material drew before.
-   *
-   * It matters more than its size suggests. A flat ribbon has one normal, so the
-   * specular lobes either fire across the strand's whole width or not at all, and
-   * a groom becomes a field of uniformly bright or uniformly dull tape. Bending
-   * the normal puts a narrow highlight down the length of each strand and lets the
-   * edges fall off, which is most of what separates strands from one another when
-   * they are all the same colour.
-   *
-   * Values below 1 keep the highlight but widen it, which reads as a softer,
-   * thicker fibre; artists after a stylised look sometimes want that.
+    /**
+   * How far the shading normal bends across the ribbon, in [0, 1].
+   *
+   * @remarks
+   * The quad is a stand-in for a cylinder, and this is how much it is shaded like
+   * one. At 1 the normal sweeps a full half turn about the curve tangent between
+   * the two edges, as the visible surface of a fibre does; at 0 it stays the
+   * quad's own normal and every fragment across the width shades identically,
+   * which is the flat ribbon this material drew before.
+   *
+   * It matters more than its size suggests. A flat ribbon has one normal, so the
+   * specular lobes either fire across the strand's whole width or not at all, and
+   * a groom becomes a field of uniformly bright or uniformly dull tape. Bending
+   * the normal puts a narrow highlight down the length of each strand and lets the
+   * edges fall off, which is most of what separates strands from one another when
+   * they are all the same colour.
+   *
+   * Values below 1 keep the highlight but widen it, which reads as a softer,
+   * thicker fibre; artists after a stylised look sometimes want that.
    */ get strandRoundness() {
         return this._strandRoundness;
     }
@@ -265,28 +265,28 @@ import { Vector4 } from '@zephyr3d/base';
             this.uniformChanged();
         }
     }
-    /**
-   * 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 lights up as brightly in its
-   * interior as on its surface. That reads as a flat silhouette with no volume,
-   * and it is most obvious on pale hair, where there is little pigment to darken
-   * the interior instead.
-   *
-   * Real occlusion would need to know how much hair sits between a fibre and the
-   * sky. This approximates that by where along the strand the fragment is: roots
-   * grow from the scalp, buried under everything above them, while tips are on
-   * the outside. It is only an approximation - a tip tucked under a fringe is
-   * treated as exposed - but it is free, it needs no texture coordinates, which
-   * this material has none of, and it captures the dominant effect. Set to 0 to
-   * disable.
-   *
-   * Applied to ambient light and the scatter term only. Direct light keeps its
-   * own answer - the shadow map, or DOM's graded transmittance - and multiplying
-   * this on top would count the same blockage twice.
+    /**
+   * 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 lights up as brightly in its
+   * interior as on its surface. That reads as a flat silhouette with no volume,
+   * and it is most obvious on pale hair, where there is little pigment to darken
+   * the interior instead.
+   *
+   * Real occlusion would need to know how much hair sits between a fibre and the
+   * sky. This approximates that by where along the strand the fragment is: roots
+   * grow from the scalp, buried under everything above them, while tips are on
+   * the outside. It is only an approximation - a tip tucked under a fringe is
+   * treated as exposed - but it is free, it needs no texture coordinates, which
+   * this material has none of, and it captures the dominant effect. Set to 0 to
+   * disable.
+   *
+   * Applied to ambient light and the scatter term only. Direct light keeps its
+   * own answer - the shadow map, or DOM's graded transmittance - and multiplying
+   * this on top would count the same blockage twice.
    */ get rootOcclusion() {
         return this._rootOcclusion;
     }
@@ -297,13 +297,13 @@ import { Vector4 } from '@zephyr3d/base';
             this.uniformChanged();
         }
     }
-    /**
-   * How far along a strand the root occlusion reaches, in (0, 1].
-   *
-   * @remarks
-   * The fraction of the strand's length over which occlusion fades from full at
-   * the root to none. Short for a groom whose strands leave the scalp quickly,
-   * longer for one where they lie against each other most of their length.
+    /**
+   * How far along a strand the root occlusion reaches, in (0, 1].
+   *
+   * @remarks
+   * The fraction of the strand's length over which occlusion fades from full at
+   * the root to none. 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._rootOcclusionRange;
     }
@@ -314,24 +314,24 @@ import { Vector4 } from '@zephyr3d/base';
             this.uniformChanged();
         }
     }
-    /**
-   * Vertex count needed to draw the current strand set.
-   *
-   * @remarks
-   * Assign this to the primitive's `indexCount`. Drawing is non-indexed, with six
-   * vertices per ribbon segment forming two triangles.
+    /**
+   * Vertex count needed to draw the current strand set.
+   *
+   * @remarks
+   * Assign this to the primitive's `indexCount`. Drawing is non-indexed, with six
+   * vertices per ribbon segment forming two triangles.
    */ get vertexCount() {
         return this._strands ? this._strands.strandCount * this._segmentsPerStrand * 6 : 0;
     }
-    /**
-   * Albedo, with alpha scaled by how much the ribbon was widened to meet the
-   * pixel floor.
-   *
-   * @remarks
-   * Widening a sub-pixel strand to a pixel adds coverage that is not physically
-   * there. Scaling alpha by the inverse keeps the strand's contribution roughly
-   * constant, so distant hair thins out in opacity instead of breaking into a
-   * flickering dotted line.
+    /**
+   * Albedo, with alpha scaled by how much the ribbon was widened to meet the
+   * pixel floor.
+   *
+   * @remarks
+   * Widening a sub-pixel strand to a pixel adds coverage that is not physically
+   * there. Scaling alpha by the inverse keeps the strand's contribution roughly
+   * constant, so distant hair thins out in opacity instead of breaking into a
+   * flickering dotted line.
    */ calculateAlbedoColor(scope, uv) {
         const pb = scope.$builder;
         const albedo = super.calculateAlbedoColor(scope, uv);
@@ -385,36 +385,36 @@ import { Vector4 } from '@zephyr3d/base';
         }
         ShaderHelper.setClipSpacePosition(scope, pb.mul(ShaderHelper.getViewProjectionMatrix(scope), pb.vec4(scope.strand.worldPos, 1)));
     }
-    /**
-   * Rebuilds the cylinder normal the flat quad stands for.
-   *
-   * @remarks
-   * The quad's own normal points at the camera everywhere on it, so every fragment
-   * across a strand's width shades the same and the strand reads as tape. A real
-   * fibre presents a curved surface: at the centre of the visible side its normal
-   * faces the viewer, and by the silhouette edges it has turned a quarter turn to
-   * lie perpendicular to the view. With `a` the interpolated sine of that angle,
-   * the normal is `side * a + faceNormal * cos`, and `cos = sqrt(1 - a * a)`.
-   *
-   * Built from the varyings rather than from the interpolated TBN on purpose. The
-   * TBN may be flipped for back faces, and the sine carried alongside it would not
-   * be, which would turn the fibre inside out; the varyings need no flip, because
-   * a camera-facing quad's normal already points at the camera by construction.
-   * @internal
-   */ /**
-   * Ambient occlusion from how deep in the groom the fragment sits.
-   *
-   * @remarks
-   * Stands in for the occlusion map the inherited path uses, which this material
-   * cannot sample: it emits no texture coordinates. See
-   * {@link HairStrandMaterial.rootOcclusion} for why an approximation is worth
-   * having at all.
-   *
-   * Only the ambient hook is overridden. The inherited direct hook resolves to
-   * one here - there is no occlusion map - which is correct: the geometric term
-   * describes being buried in the groom, and for direct light that is exactly
-   * what the shadow map already measures.
-   * @internal
+    /**
+   * Rebuilds the cylinder normal the flat quad stands for.
+   *
+   * @remarks
+   * The quad's own normal points at the camera everywhere on it, so every fragment
+   * across a strand's width shades the same and the strand reads as tape. A real
+   * fibre presents a curved surface: at the centre of the visible side its normal
+   * faces the viewer, and by the silhouette edges it has turned a quarter turn to
+   * lie perpendicular to the view. With `a` the interpolated sine of that angle,
+   * the normal is `side * a + faceNormal * cos`, and `cos = sqrt(1 - a * a)`.
+   *
+   * Built from the varyings rather than from the interpolated TBN on purpose. The
+   * TBN may be flipped for back faces, and the sine carried alongside it would not
+   * be, which would turn the fibre inside out; the varyings need no flip, because
+   * a camera-facing quad's normal already points at the camera by construction.
+   * @internal
+   */ /**
+   * Ambient occlusion from how deep in the groom the fragment sits.
+   *
+   * @remarks
+   * Stands in for the occlusion map the inherited path uses, which this material
+   * cannot sample: it emits no texture coordinates. See
+   * {@link HairStrandMaterial.rootOcclusion} for why an approximation is worth
+   * having at all.
+   *
+   * Only the ambient hook is overridden. The inherited direct hook resolves to
+   * one here - there is no occlusion map - which is correct: the geometric term
+   * describes being buried in the groom, and for direct light that is exactly
+   * what the shadow map already measures.
+   * @internal
    */ calculateHairOcclusion(scope) {
         const pb = scope.$builder;
         // Evaluated at the vertex stage and interpolated, the same way the roundness
@@ -495,12 +495,12 @@ import { Vector4 } from '@zephyr3d/base';
             bindGroup.setValue('zStrandLOD', this._lodScratch.setXYZW(this._minStrandLODRatio, 0, 0, 0));
         }
     }
-    /**
-   * Declares the strand storage buffers and expansion parameters.
-   *
-   * @remarks
-   * Group 2 is the material's own bind group, matching the inherited uniforms.
-   * @internal
+    /**
+   * Declares the strand storage buffers and expansion parameters.
+   *
+   * @remarks
+   * Group 2 is the material's own bind group, matching the inherited uniforms.
+   * @internal
    */ declareStrandBindings(scope) {
         const pb = scope.$builder;
         scope.zStrandHeaders = pb.uint[0]().storageBufferReadonly(2);
@@ -514,9 +514,9 @@ import { Vector4 } from '@zephyr3d/base';
             scope.zStrandLOD = pb.vec4().uniform(2);
         }
     }
-    /**
-   * Reads one control point as position in xyz and width in w.
-   * @internal
+    /**
+   * Reads one control point as position in xyz and width in w.
+   * @internal
    */ fetchStrandPoint(scope, index, prev = false) {
         const pb = scope.$builder;
         const funcName = prev ? 'Z_strandPointPrev' : 'Z_strandPoint';
@@ -537,30 +537,30 @@ import { Vector4 } from '@zephyr3d/base';
         });
         return pb.getGlobalScope()[funcName](index);
     }
-    /**
-   * Evaluates a strand at parameter `t`, returning position, width and tangent.
-   *
-   * @remarks
-   * A Catmull-Rom spline through the control points, not the control polygon
-   * itself, and both quantities come from the same curve: the sample is the
-   * spline's value, the tangent its analytic derivative.
-   *
-   * The reason is the tangent. A polyline's derivative is constant within a span
-   * and jumps at every control point, and the anisotropic lobes are a function of
-   * that direction raised to a large power, so what is a slight kink in the
-   * silhouette becomes a hard step in the highlight - each span of a strand shading
-   * as its own uniformly bright or dark facet. Interpolating the position more
-   * accurately is the lesser half of the change.
-   *
-   * The curve matters too once {@link segmentsPerStrand} is below the control
-   * point count, which is the normal case: the default draws 8 segments from
-   * strands carrying 30 points, so a polyline reading cuts the corner across three
-   * points at a time and quietly straightens out every curl in the groom. A spline
-   * sampled at the same rate keeps the bend.
-   *
-   * Costs four control point fetches against the three the polyline reading of
-   * position and tangent needed between them.
-   * @internal
+    /**
+   * Evaluates a strand at parameter `t`, returning position, width and tangent.
+   *
+   * @remarks
+   * A Catmull-Rom spline through the control points, not the control polygon
+   * itself, and both quantities come from the same curve: the sample is the
+   * spline's value, the tangent its analytic derivative.
+   *
+   * The reason is the tangent. A polyline's derivative is constant within a span
+   * and jumps at every control point, and the anisotropic lobes are a function of
+   * that direction raised to a large power, so what is a slight kink in the
+   * silhouette becomes a hard step in the highlight - each span of a strand shading
+   * as its own uniformly bright or dark facet. Interpolating the position more
+   * accurately is the lesser half of the change.
+   *
+   * The curve matters too once {@link segmentsPerStrand} is below the control
+   * point count, which is the normal case: the default draws 8 segments from
+   * strands carrying 30 points, so a polyline reading cuts the corner across three
+   * points at a time and quietly straightens out every curl in the groom. A spline
+   * sampled at the same rate keeps the bend.
+   *
+   * Costs four control point fetches against the three the polyline reading of
+   * position and tangent needed between them.
+   * @internal
    */ evaluateStrand(scope, firstPoint, pointCount, t, prev = false) {
         const pb = scope.$builder;
         const that = this;
@@ -622,19 +622,19 @@ import { Vector4 } from '@zephyr3d/base';
         });
         return pb.getGlobalScope()[funcName](firstPoint, pointCount, t);
     }
-    /**
-   * Rotates a strand direction into world space and renormalises it.
-   *
-   * @remarks
-   * The direction is transformed by the world matrix rather than by its inverse
-   * transpose on purpose: this is a tangent, not a normal. The shading normal is
-   * rebuilt from the tangent and the ribbon's side vector after the fact, so a
-   * non-uniform scale reaches the lighting through the frame it actually bends.
-   *
-   * A degenerate scale can collapse the direction entirely, which would leave a
-   * zero-length tangent and produce NaN once it is normalised, so the untransformed
-   * direction stands in for that case.
-   * @internal
+    /**
+   * Rotates a strand direction into world space and renormalises it.
+   *
+   * @remarks
+   * The direction is transformed by the world matrix rather than by its inverse
+   * transpose on purpose: this is a tangent, not a normal. The shading normal is
+   * rebuilt from the tangent and the ribbon's side vector after the fact, so a
+   * non-uniform scale reaches the lighting through the frame it actually bends.
+   *
+   * A degenerate scale can collapse the direction entirely, which would leave a
+   * zero-length tangent and produce NaN once it is normalised, so the untransformed
+   * direction stands in for that case.
+   * @internal
    */ transformStrandDirection(scope, worldMatrix, direction) {
         const pb = scope.$builder;
         const funcName = 'Z_strandDirectionToWorld';
@@ -651,15 +651,15 @@ import { Vector4 } from '@zephyr3d/base';
         });
         return pb.getGlobalScope()[funcName](worldMatrix, direction);
     }
-    /**
-   * Derives this vertex's ribbon corner from the vertex index.
-   *
-   * @remarks
-   * Six vertices per segment form two triangles over a quad whose corners are
-   * indexed by (ring, side). Independent triangles rather than a strip means no
-   * degenerate vertices are needed to cut between strands, and the duplicated
-   * corners cost nothing because corners are computed rather than fetched.
-   * @internal
+    /**
+   * Derives this vertex's ribbon corner from the vertex index.
+   *
+   * @remarks
+   * Six vertices per segment form two triangles over a quad whose corners are
+   * indexed by (ring, side). Independent triangles rather than a strip means no
+   * degenerate vertices are needed to cut between strands, and the duplicated
+   * corners cost nothing because corners are computed rather than fetched.
+   * @internal
    */ expandStrandVertex(scope) {
         const pb = scope.$builder;
         const funcName = 'Z_expandStrandVertex';