mrdoob · cstegel · May 26, 2023 · Jun 9, 2023 · Jun 9, 2023 · Jun 9, 2023
diff --git a/docs/api/en/constants/Loaders.html b/docs/api/en/constants/Loaders.html
@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<base href="../../../" />
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		<h1>Loader Constants</h1>
+
+		<h2>Skinning Modes</h2>
+
+		Controls whether or not a SkinnedMesh will create and use a bone index/weights texture instead of a vertex buffer. 
+
+		<code>
+THREE.BoneIndexWeightsTextureNever
+THREE.BoneIndexWeightsTextureAlways
+THREE.BoneIndexWeightsTextureAllow
+		</code>
+		<p>
+			[page:constant BoneIndexWeightsTextureNever] Never uses a bone index/weights texture. A single vertex buffer -- up to 4 weights per-vertex -- will always be used. If a SkinnedMesh has more than 4 weights per-vertex, the 4 highest-weighted bones will be used for each vertex.<br />
+			[page:constant BoneIndexWeightsTextureAlways] Always use a bone index/weights texture instead of a vertex buffer. Any number of vertex weights is supported per-vertex.<br />
+			[page:constant BoneIndexWeightsTextureAllow] (Default) Use a bone index/weights texture instead of a vertex buffer if a mesh has more than 4 weights per-vertex.<br />
+		</p>
+
+		<h2>Source</h2>
+
+		<p>
+			[link:https://github.com/mrdoob/three.js/blob/master/src/constants.js src/constants.js]
+		</p>
+	</body>
+</html>
diff --git a/docs/api/en/objects/SkinnedMesh.html b/docs/api/en/objects/SkinnedMesh.html
@@ -86,12 +86,13 @@ <h2>Code Example</h2>
 
 		<h2>Constructor</h2>
 		<h3>
-			[name]( [param:BufferGeometry geometry], [param:Material material] )
+			[name]( [param:BufferGeometry geometry], [param:Material material], [param:Constant useBoneIndexWeightsTexture] )
 		</h3>
 		<p>
 			[page:BufferGeometry geometry] - an instance of [page:BufferGeometry].<br />
 			[page:Material material] - (optional) an instance of [page:Material].
 			Default is a new [page:MeshBasicMaterial].
+			[page:Constant useBoneIndexWeightsTexture] — (optional) Controls whether or not a bone weights texture will be created and used instead of a vertex buffer for skinning. Defaults to [page:Loaders THREE.BoneIndexWeightsTextureAllow].
 		</p>
 
 		<h2>Properties</h2>

diff --git a/docs/examples/en/loaders/GLTFLoader.html b/docs/examples/en/loaders/GLTFLoader.html
@@ -177,9 +177,13 @@ <h2>Custom extensions</h2>
 
 		<h2>Constructor</h2>
 
-		<h3>[name]( [param:LoadingManager manager] )</h3>
+		<h3>[name]( [param:LoadingManager manager], [param:Object options] )</h3>
 		<p>
 		[page:LoadingManager manager] — The [page:LoadingManager loadingManager] for the loader to use. Default is [page:LoadingManager THREE.DefaultLoadingManager].
+		[page:Object options] — (optional) Change loading behavior. Properties:<br/>
+		<ul>
+			<li>useBoneIndexWeightsTexture — (optional) Controls whether or not a [page:SkinnedMesh SkinnedMesh] will create and use a bone weights texture instead of a vertex buffer. Defaults to [page:Loaders THREE.BoneIndexWeightsTextureAllow].</li>
+		</ul>
 		</p>
 		<p>
 		Creates a new [name].

diff --git a/docs/examples/en/loaders/MMDLoader.html b/docs/examples/en/loaders/MMDLoader.html
@@ -68,9 +68,13 @@ <h2>Examples</h2>
 
 		<h2>Constructor</h2>
 
-		<h3>[name]( [param:LoadingManager manager] )</h3>
+		<h3>[name]( [param:LoadingManager manager], [param:Object options] )</h3>
 		<p>
 		[page:LoadingManager manager] — The [page:LoadingManager loadingManager] for the loader to use. Default is [page:LoadingManager THREE.DefaultLoadingManager].
+		[page:Object options] — (optional) Change loading behavior. Properties:<br/>
+		<ul>
+			<li>useBoneIndexWeightsTexture — (optional) Controls whether or not a [page:SkinnedMesh SkinnedMesh] will create and use a bone weights texture instead of a vertex buffer. Defaults to [page:Loaders THREE.BoneIndexWeightsTextureAllow].</li>
+		</ul>
 		</p>
 		<p>
 		Creates a new [name].

diff --git a/docs/list.json b/docs/list.json
@@ -72,6 +72,7 @@
 				"Core": "api/en/constants/Core",
 				"CustomBlendingEquation": "api/en/constants/CustomBlendingEquations",
 				"BufferAttributeUsage": "api/en/constants/BufferAttributeUsage",
+				"Loaders": "api/en/constants/Loaders",
 				"Materials": "api/en/constants/Materials",
 				"Renderer": "api/en/constants/Renderer",
 				"Textures": "api/en/constants/Textures"

diff --git a/examples/files.json b/examples/files.json
@@ -4,7 +4,9 @@
 		"webgl_animation_skinning_blending",
 		"webgl_animation_skinning_additive_blending",
 		"webgl_animation_skinning_ik",
+		"webgl_animation_skinning_weight-texture",
 		"webgl_animation_skinning_morph",
+		"webgl_animation_skinning_performance",
 		"webgl_animation_multiple",
 		"webgl_camera",
 		"webgl_camera_array",

diff --git a/examples/jsm/loaders/ColladaLoader.js b/examples/jsm/loaders/ColladaLoader.js
@@ -42,9 +42,10 @@ import { TGALoader } from '../loaders/TGALoader.js';
 
 class ColladaLoader extends Loader {
 
-	constructor( manager ) {
+	constructor( manager, options = {} ) {
 
 		super( manager );
+		this.options = options;
 
 	}
 
@@ -86,6 +87,8 @@ class ColladaLoader extends Loader {
 
 	parse( text, path ) {
 
+		const options = this.options;
+
 		function getElementsByTagName( xml, name ) {
 
 			// Non recursive xml.getElementsByTagName() ...
@@ -3632,7 +3635,6 @@ class ColladaLoader extends Loader {
 					if ( object.isSkinnedMesh ) {
 
 						object.bind( skeleton, controller.skin.bindMatrix );
-						object.normalizeSkinWeights();
 
 					}
 
@@ -3820,7 +3822,9 @@ class ColladaLoader extends Loader {
 					case 'polylist':
 						if ( skinning ) {
 
-							object = new SkinnedMesh( geometry.data, material );
+							object = new SkinnedMesh( geometry.data, material, {
+								useBoneIndexWeightsTexture: options.useBoneIndexWeightsTexture
+							} );
 
 						} else {
 

diff --git a/examples/jsm/loaders/FBXLoader.js b/examples/jsm/loaders/FBXLoader.js
@@ -66,9 +66,10 @@ let sceneGraph;
 
 class FBXLoader extends Loader {
 
-	constructor( manager ) {
+	constructor( manager, options = {} ) {
 
 		super( manager );
+		this.options = options;
 
 	}
 
@@ -140,7 +141,7 @@ class FBXLoader extends Loader {
 
 		const textureLoader = new TextureLoader( this.manager ).setPath( this.resourcePath || path ).setCrossOrigin( this.crossOrigin );
 
-		return new FBXTreeParser( textureLoader, this.manager ).parse( fbxTree );
+		return new FBXTreeParser( textureLoader, this.manager, this.options ).parse( fbxTree );
 
 	}
 
@@ -149,10 +150,11 @@ class FBXLoader extends Loader {
 // Parse the FBXTree object returned by the BinaryParser or TextParser and return a Group
 class FBXTreeParser {
 
-	constructor( textureLoader, manager ) {
+	constructor( textureLoader, manager, options = {} ) {
 
 		this.textureLoader = textureLoader;
 		this.manager = manager;
+		this.options = options;
 
 	}
 
@@ -1270,7 +1272,7 @@ class FBXTreeParser {
 
 		} else {
 
-			material = new MeshPhongMaterial( { 
+			material = new MeshPhongMaterial( {
 				name: Loader.DEFAULT_MATERIAL_NAME,
 				color: 0xcccccc
 			} );
@@ -1290,8 +1292,9 @@ class FBXTreeParser {
 
 		if ( geometry.FBX_Deformer ) {
 
-			model = new SkinnedMesh( geometry, material );
-			model.normalizeSkinWeights();
+			model = new SkinnedMesh( geometry, material, {
+				useBoneIndexWeightsTexture: this.options.useBoneIndexWeightsTexture
+			} );
 
 		} else {
 

diff --git a/examples/jsm/loaders/GLTFLoader.js b/examples/jsm/loaders/GLTFLoader.js
@@ -1,6 +1,7 @@
 import {
 	AnimationClip,
 	Bone,
+	BoneIndexWeightsTextureAllow,
 	Box3,
 	BufferAttribute,
 	BufferGeometry,
@@ -66,10 +67,13 @@ import { toTrianglesDrawMode } from '../utils/BufferGeometryUtils.js';
 
 class GLTFLoader extends Loader {
 
-	constructor( manager ) {
+	constructor( manager, options = {} ) {
 
 		super( manager );
 
+		this.useBoneIndexWeightsTexture =
+			options.useBoneIndexWeightsTexture ?? BoneIndexWeightsTextureAllow;
+
 		this.dracoLoader = null;
 		this.ktx2Loader = null;
 		this.meshoptDecoder = null;
@@ -350,7 +354,8 @@ class GLTFLoader extends Loader {
 			requestHeader: this.requestHeader,
 			manager: this.manager,
 			ktx2Loader: this.ktx2Loader,
-			meshoptDecoder: this.meshoptDecoder
+			meshoptDecoder: this.meshoptDecoder,
+			useBoneIndexWeightsTexture: this.useBoneIndexWeightsTexture
 
 		} );
 
@@ -1819,15 +1824,15 @@ class GLTFDracoMeshCompressionExtension {
 
 		for ( const attributeName in gltfAttributeMap ) {
 
-			const threeAttributeName = ATTRIBUTES[ attributeName ] || attributeName.toLowerCase();
+			const threeAttributeName = getThreeAttributeName( attributeName );
 
 			threeAttributeMap[ threeAttributeName ] = gltfAttributeMap[ attributeName ];
 
 		}
 
 		for ( const attributeName in primitive.attributes ) {
 
-			const threeAttributeName = ATTRIBUTES[ attributeName ] || attributeName.toLowerCase();
+			const threeAttributeName = getThreeAttributeName( attributeName );
 
 			if ( gltfAttributeMap[ attributeName ] !== undefined ) {
 
@@ -2106,8 +2111,6 @@ const ATTRIBUTES = {
 	TEXCOORD_2: 'uv2',
 	TEXCOORD_3: 'uv3',
 	COLOR_0: 'color',
-	WEIGHTS_0: 'skinWeight',
-	JOINTS_0: 'skinIndex',
 };
 
 const PATH_PROPERTIES = {
@@ -2130,6 +2133,28 @@ const ALPHA_MODES = {
 	BLEND: 'BLEND'
 };
 
+function getThreeAttributeName( gltfAttributeName ) {
+
+	if ( ATTRIBUTES[ gltfAttributeName ] !== undefined) {
+
+		return ATTRIBUTES[ gltfAttributeName ];
+
+	} else if ( gltfAttributeName.startsWith( 'JOINTS_' ) ) {
+
+		const index = gltfAttributeName.substring(7);
+		return 'skinIndex' + ( index === '0' ? '' : index );
+
+	} else if ( gltfAttributeName.startsWith( 'WEIGHTS_' ) ) {
+
+		const index = gltfAttributeName.substring(8);
+		return 'skinWeight' + ( index === '0' ? '' : index );
+
+	}
+
+	return gltfAttributeName.toLowerCase();
+
+}
+
 /**
  * Specification: https://github.com/KhronosGroup/glTF/blob/master/specification/2.0/README.md#default-material
  */
@@ -3648,16 +3673,11 @@ class GLTFParser {
 
 					// .isSkinnedMesh isn't in glTF spec. See ._markDefs()
 					mesh = meshDef.isSkinnedMesh === true
-						? new SkinnedMesh( geometry, material )
+						? new SkinnedMesh( geometry, material, {
+								useBoneIndexWeightsTexture: parser.options.useBoneIndexWeightsTexture
+						} )
 						: new Mesh( geometry, material );
 
-					if ( mesh.isSkinnedMesh === true ) {
-
-						// normalize skin weights to fix malformed assets (see #15319)
-						mesh.normalizeSkinWeights();
-
-					}
-
 					if ( primitive.mode === WEBGL_CONSTANTS.TRIANGLE_STRIP ) {
 
 						mesh.geometry = toTrianglesDrawMode( mesh.geometry, TriangleStripDrawMode );
@@ -4483,7 +4503,7 @@ function addPrimitiveAttributes( geometry, primitiveDef, parser ) {
 
 	for ( const gltfAttributeName in attributes ) {
 
-		const threeAttributeName = ATTRIBUTES[ gltfAttributeName ] || gltfAttributeName.toLowerCase();
+		const threeAttributeName = getThreeAttributeName( gltfAttributeName );
 
 		// Skip attributes already provided by e.g. Draco extension.
 		if ( threeAttributeName in geometry.attributes ) continue;

diff --git a/examples/jsm/loaders/MMDLoader.js b/examples/jsm/loaders/MMDLoader.js
@@ -75,14 +75,14 @@ import { MMDParser } from '../libs/mmdparser.module.js';
  */
 class MMDLoader extends Loader {
 
-	constructor( manager ) {
+	constructor( manager, options = {} ) {
 
 		super( manager );
 
 		this.loader = new FileLoader( this.manager );
 
 		this.parser = null; // lazy generation
-		this.meshBuilder = new MeshBuilder( this.manager );
+		this.meshBuilder = new MeshBuilder( this.manager, options );
 		this.animationBuilder = new AnimationBuilder();
 
 	}
@@ -413,11 +413,12 @@ const NON_ALPHA_CHANNEL_FORMATS = [
  */
 class MeshBuilder {
 
-	constructor( manager ) {
+	constructor( manager, options = {} ) {
 
 		this.crossOrigin = 'anonymous';
 		this.geometryBuilder = new GeometryBuilder();
 		this.materialBuilder = new MaterialBuilder( manager );
+		this.options = options;
 
 	}
 
@@ -447,7 +448,9 @@ class MeshBuilder {
 			.setResourcePath( resourcePath )
 			.build( data, geometry, onProgress, onError );
 
-		const mesh = new SkinnedMesh( geometry, material );
+		const mesh = new SkinnedMesh( geometry, material, {
+			useBoneIndexWeightsTexture: this.options.useBoneIndexWeightsTexture
+		} );
 
 		const skeleton = new Skeleton( initBones( mesh ) );
 		mesh.bind( skeleton );

diff --git a/examples/models/gltf/HeadWithMax16Joints.glb b/examples/models/gltf/HeadWithMax16Joints.glb
diff --git a/examples/screenshots/webgl_animation_skinning_performance.jpg b/examples/screenshots/webgl_animation_skinning_performance.jpg
diff --git a/examples/screenshots/webgl_animation_skinning_weight-texture.jpg b/examples/screenshots/webgl_animation_skinning_weight-texture.jpg