@@ -11,6 +11,30 @@ import {
1111 Vector3 ,
1212} from 'three' ;
1313
14+ /**
15+ * @module BufferGeometryUtils
16+ * @three_import import * as BufferGeometryUtils from 'three/addons/utils/BufferGeometryUtils.js';
17+ */
18+
19+ /**
20+ * Computes vertex tangents using the MikkTSpace algorithm. MikkTSpace generates the same tangents consistently,
21+ * and is used in most modelling tools and normal map bakers. Use MikkTSpace for materials with normal maps,
22+ * because inconsistent tangents may lead to subtle visual issues in the normal map, particularly around mirrored
23+ * UV seams.
24+ *
25+ * In comparison to this method, {@link BufferGeometry#computeTangents} (a custom algorithm) generates tangents that
26+ * probably will not match the tangents in other software. The custom algorithm is sufficient for general use with a
27+ * custom material, and may be faster than MikkTSpace.
28+ *
29+ * Returns the original BufferGeometry. Indexed geometries will be de-indexed. Requires position, normal, and uv attributes.
30+ *
31+ * @param {BufferGeometry } geometry - The geometry to compute tangents for.
32+ * @param {Object } MikkTSpace - Instance of `examples/jsm/libs/mikktspace.module.js`, or `mikktspace` npm package.
33+ * Await `MikkTSpace.ready` before use.
34+ * @param {boolean } [negateSign=true] - Whether to negate the sign component (.w) of each tangent.
35+ * Required for normal map conventions in some formats, including glTF.
36+ * @return {BufferGeometry } The updated geometry.
37+ */
1438function computeMikkTSpaceTangents ( geometry , MikkTSpace , negateSign = true ) {
1539
1640 if ( ! MikkTSpace || ! MikkTSpace . isReady ) {
@@ -100,9 +124,11 @@ function computeMikkTSpaceTangents( geometry, MikkTSpace, negateSign = true ) {
100124}
101125
102126/**
103- * @param {Array<BufferGeometry> } geometries
104- * @param {Boolean } useGroups
105- * @return {BufferGeometry }
127+ * Merges a set of geometries into a single instance. All geometries must have compatible attributes.
128+ *
129+ * @param {Array<BufferGeometry> } geometries - The geometries to merge.
130+ * @param {boolean } [useGroups=false] - Whether to use groups or not.
131+ * @return {?BufferGeometry } The merged geometry. Returns `null` if the merge does not succeed.
106132 */
107133function mergeGeometries ( geometries , useGroups = false ) {
108134
@@ -296,8 +322,11 @@ function mergeGeometries( geometries, useGroups = false ) {
296322}
297323
298324/**
299- * @param {Array<BufferAttribute> } attributes
300- * @return {BufferAttribute }
325+ * Merges a set of attributes into a single instance. All attributes must have compatible properties and types.
326+ * Instances of {@link InterleavedBufferAttribute} are not supported.
327+ *
328+ * @param {Array<BufferAttribute> } attributes - The attributes to merge.
329+ * @return {?BufferAttribute } The merged attribute. Returns `null` if the merge does not succeed.
301330 */
302331function mergeAttributes ( attributes ) {
303332
@@ -389,10 +418,12 @@ function mergeAttributes( attributes ) {
389418}
390419
391420/**
392- * @param {BufferAttribute }
393- * @return {BufferAttribute }
421+ * Performs a deep clone of the given buffer attribute.
422+ *
423+ * @param {BufferAttribute } attribute - The attribute to clone.
424+ * @return {BufferAttribute } The cloned attribute.
394425 */
395- export function deepCloneAttribute ( attribute ) {
426+ function deepCloneAttribute ( attribute ) {
396427
397428 if ( attribute . isInstancedInterleavedBufferAttribute || attribute . isInterleavedBufferAttribute ) {
398429
@@ -411,8 +442,11 @@ export function deepCloneAttribute( attribute ) {
411442}
412443
413444/**
414- * @param {Array<BufferAttribute> } attributes
415- * @return {Array<InterleavedBufferAttribute> }
445+ * Interleaves a set of attributes and returns a new array of corresponding attributes that share a
446+ * single {@link InterleavedBuffer} instance. All attributes must have compatible types.
447+ *
448+ * @param {Array<BufferAttribute> } attributes - The attributes to interleave.
449+ * @return {Array<InterleavedBufferAttribute> } An array of interleaved attributes. If interleave does not succeed, the method returns `null`.
416450 */
417451function interleaveAttributes ( attributes ) {
418452
@@ -475,8 +509,13 @@ function interleaveAttributes( attributes ) {
475509
476510}
477511
478- // returns a new, non-interleaved version of the provided attribute
479- export function deinterleaveAttribute ( attribute ) {
512+ /**
513+ * Returns a new, non-interleaved version of the given attribute.
514+ *
515+ * @param {InterleavedBufferAttribute } attribute - The interleaved attribute.
516+ * @return {BufferAttribute } The non-interleaved attribute.
517+ */
518+ function deinterleaveAttribute ( attribute ) {
480519
481520 const cons = attribute . data . array . constructor ;
482521 const count = attribute . count ;
@@ -523,8 +562,12 @@ export function deinterleaveAttribute( attribute ) {
523562
524563}
525564
526- // deinterleaves all attributes on the geometry
527- export function deinterleaveGeometry ( geometry ) {
565+ /**
566+ * Deinterleaves all attributes on the given geometry.
567+ *
568+ * @param {BufferGeometry } geometry - The geometry to deinterleave.
569+ */
570+ function deinterleaveGeometry ( geometry ) {
528571
529572 const attributes = geometry . attributes ;
530573 const morphTargets = geometry . morphTargets ;
@@ -567,8 +610,10 @@ export function deinterleaveGeometry( geometry ) {
567610}
568611
569612/**
570- * @param {BufferGeometry } geometry
571- * @return {number }
613+ * Returns the amount of bytes used by all attributes to represent the geometry.
614+ *
615+ * @param {BufferGeometry } geometry - The geometry.
616+ * @return {number } The estimate bytes used.
572617 */
573618function estimateBytesUsed ( geometry ) {
574619
@@ -590,9 +635,11 @@ function estimateBytesUsed( geometry ) {
590635}
591636
592637/**
593- * @param {BufferGeometry } geometry
594- * @param {number } tolerance
595- * @return {BufferGeometry }
638+ * Returns a new geometry with vertices for which all similar vertex attributes (within tolerance) are merged.
639+ *
640+ * @param {BufferGeometry } geometry - The geometry to merge vertices for.
641+ * @param {number } [tolerance=1e-4] - The tolerance value.
642+ * @return {BufferGeometry } - The new geometry with merged vertices.
596643 */
597644function mergeVertices ( geometry , tolerance = 1e-4 ) {
598645
@@ -753,9 +800,12 @@ function mergeVertices( geometry, tolerance = 1e-4 ) {
753800}
754801
755802/**
756- * @param {BufferGeometry } geometry
757- * @param {number } drawMode
758- * @return {BufferGeometry }
803+ * Returns a new indexed geometry based on `TrianglesDrawMode` draw mode.
804+ * This mode corresponds to the `gl.TRIANGLES` primitive in WebGL.
805+ *
806+ * @param {BufferGeometry } geometry - The geometry to convert.
807+ * @param {number } drawMode - The current draw mode.
808+ * @return {BufferGeometry } The new geometry using `TrianglesDrawMode`.
759809 */
760810function toTrianglesDrawMode ( geometry , drawMode ) {
761811
@@ -864,9 +914,13 @@ function toTrianglesDrawMode( geometry, drawMode ) {
864914
865915/**
866916 * Calculates the morphed attributes of a morphed/skinned BufferGeometry.
867- * Helpful for Raytracing or Decals.
868- * @param {Mesh | Line | Points } object An instance of Mesh, Line or Points.
869- * @return {Object } An Object with original position/normal attributes and morphed ones.
917+ *
918+ * Helpful for Raytracing or Decals (i.e. a `DecalGeometry` applied to a morphed Object with a `BufferGeometry`
919+ * will use the original `BufferGeometry`, not the morphed/skinned one, generating an incorrect result.
920+ * Using this function to create a shadow `Object3`D the `DecalGeometry` can be correctly generated).
921+ *
922+ * @param {Mesh|Line|Points } object - The 3D object to compute morph attributes for.
923+ * @return {Object } An object with original position/normal attributes and morphed ones.
870924 */
871925function computeMorphedAttributes ( object ) {
872926
@@ -1142,6 +1196,12 @@ function computeMorphedAttributes( object ) {
11421196
11431197}
11441198
1199+ /**
1200+ * Merges the {@link BufferGeometry#groups} for the given geometry.
1201+ *
1202+ * @param {BufferGeometry } geometry - The geometry to modify.
1203+ * @return {BufferGeometry } - The updated geometry
1204+ */
11451205function mergeGroups ( geometry ) {
11461206
11471207 if ( geometry . groups . length === 0 ) {
@@ -1244,15 +1304,14 @@ function mergeGroups( geometry ) {
12441304
12451305}
12461306
1247-
12481307/**
12491308 * Modifies the supplied geometry if it is non-indexed, otherwise creates a new,
12501309 * non-indexed geometry. Returns the geometry with smooth normals everywhere except
12511310 * faces that meet at an angle greater than the crease angle.
12521311 *
1253- * @param {BufferGeometry } geometry
1254- * @param {number } [creaseAngle]
1255- * @return {BufferGeometry }
1312+ * @param {BufferGeometry } geometry - The geometry to modify.
1313+ * @param {number } [creaseAngle=Math.PI/3] - The crease angle in radians.
1314+ * @return {BufferGeometry } - The updated geometry
12561315 */
12571316function toCreasedNormals ( geometry , creaseAngle = Math . PI / 3 /* 60 degrees */ ) {
12581317
@@ -1363,6 +1422,9 @@ export {
13631422 computeMikkTSpaceTangents ,
13641423 mergeGeometries ,
13651424 mergeAttributes ,
1425+ deepCloneAttribute ,
1426+ deinterleaveAttribute ,
1427+ deinterleaveGeometry ,
13661428 interleaveAttributes ,
13671429 estimateBytesUsed ,
13681430 mergeVertices ,
0 commit comments