From 949f971e2d6ae264cbbd02d700642a1291397fb7 Mon Sep 17 00:00:00 2001 From: Greg Tatum Date: Tue, 9 Jun 2015 22:38:48 -0500 Subject: [PATCH] Skinning docs --- docs/api/core/Geometry.html | 21 ++- docs/api/objects/Bone.html | 25 ++- docs/api/objects/Skeleton.html | 128 ++++++++++++++ docs/api/objects/SkinnedMesh.html | 49 +++++- docs/list.js | 1 + docs/scenes/bones-browser.html | 271 ++++++++++++++++++++++++++++++ 6 files changed, 477 insertions(+), 18 deletions(-) create mode 100644 docs/api/objects/Skeleton.html create mode 100644 docs/scenes/bones-browser.html diff --git a/docs/api/core/Geometry.html b/docs/api/core/Geometry.html index 1e3ebf6412..7c32c73a88 100644 --- a/docs/api/core/Geometry.html +++ b/docs/api/core/Geometry.html @@ -102,12 +102,29 @@

[property:Array skinWeights]

- Array of skinning weights, matching number and order of vertices. + Array of [page:Vector4 Vector4s] representing the skinning weights as used in a [page:SkinnedMesh], + The weights match the number and order of vertices in the geometry. The weighted values + are typically between the values of 0 and 1 and affect the amount that the individuals bones affect + a given vertex.

[property:Array skinIndices]

- Array of skinning indices, matching number and order of vertices. + Array of [page:Vector4 Vector4s] representing the indices of individual bones in the [page:Skeleton.bones] array, + The indices match the number and order of vertices in the geometry. + + geometry.skinIndices[15] = new THREE.Vector4( 0, 5, 9, 0 ); + geometry.skinWeights[15] = new THREE.Vector4( 0.2, 0.5, 0.3, 0 ); + + // corresponds with the following vertex + geometry.vertices[15] + + // these bones will be used like so: + skeleton.bones[0]; // weight of 0.2 + skeleton.bones[5]; // weight of 0.5 + skeleton.bones[9]; // weight of 0.3 + skeleton.bones[0]; // weight of 0 +

[property:Object boundingBox]

diff --git a/docs/api/objects/Bone.html b/docs/api/objects/Bone.html index c65ab4c42b..5a0c5ed5ae 100644 --- a/docs/api/objects/Bone.html +++ b/docs/api/objects/Bone.html @@ -11,25 +11,34 @@

[name]

-
A bone which is part of a [page:SkinnedMesh].
- +
+ A bone which is part of a [page:Skeleton]. The skeleton in turn is used by the [page:SkinnedMesh]. + Bones are almost identical to a blank [page:Object3D]. +
+ +

Example

+ + + var root = new THREE.Bone(); + var child = new THREE.Bone(); + + root.add( child ); + child.position.y = 5; +

Constructor

-

[name]([page:SkinnedMesh belongsToSkin])

-
- belongsToSkin -- An instance of [page:SkinnedMesh]. -
+

[name]([page:SkinnedMesh skin])

- This creates a new instance of a bone from the skin. + skin — (optional) The [page:SkinnedMesh] to which the bone belongs.

Properties

[property:SkinnedMesh skin]

- The skin that contains this bone. + An optional reference to the [page:SkinnedMesh].
diff --git a/docs/api/objects/Skeleton.html b/docs/api/objects/Skeleton.html new file mode 100644 index 0000000000..9a9569cee7 --- /dev/null +++ b/docs/api/objects/Skeleton.html @@ -0,0 +1,128 @@ + + + + + + + + + + +

[name]

+ +
+ Use an array of [page:Bone bones] to create a skeleton that can be used by a [page:SkinnedMesh]. + WebGL only. +
+ +

Example

+ + + // Create a simple "arm" + + var bones = []; + + var shoulder = new THREE.Bone(); + var elbow = new THREE.Bone(); + var hand = new THREE.Bone(); + + shoulder.add( elbow ); + elbow.add( hand ); + + bones.push( shoulder ); + bones.push( elbow ); + bones.push( hand ); + + shoulder.position.y = -5; + elbow.position.y = 0; + hand.position.y = 5; + + var armSkeleton = THREE.Skeleton( bones ); + + // See THREE.SkinnedMesh for an example of usage with a mesh + + +

Constructor

+ + +

[name]( [page:Array bones], [page:Array boneInverses], [page:Boolean useVertexTexture] )

+
+ bones — The array of [page:bone bones]
+ boneInverses — (optional) An array of [page:Matrix4 Matrix4s]
+ useVertexTexture — (optional) Whether or not to use a vertex texture in the shader. +
+
+ The constructor automatically sets up all of the properties below. +
+ + +

Properties

+ +

[property:Array bones]

+
+ The array of [page:bone bones] +
+ + +

[property:Boolean useVertexTexture]

+
+ Whether or not to use a vertex texture in the shader, set in the constructor. Not all devices + support floating point pixel textures. If this option is set then the bone matrices will be packed into + a texture and sent to the shader. This method allows a much larger set of bones to be used. Otherwise + the vertex shader will use uniforms, which do not allow for as many bones to be used. The exact + numbers vary between devices. +
+ + +

[property:Array boneInverses]

+
+ An array of [page:Matrix4 Matrix4s] that represent the inverse of the matrixWorld of the individual bones. +
+ + +

[property:Integer boneTextureWidth]

+
+ The width of the vertex data texture. +
+ + +

[property:Integer boneTextureHeight]

+
+ The height of the vertex data texture. +
+ + +

[property:Float32Array boneMatrices]

+
+ The array buffer holding the bone data when using a vertex texture. +
+ + +

[property:DataTexture boneTexture]

+
+ The [page:DataTexture] holding the bone data when using a vertex texture. +
+ + +

Methods

+ +

[method:null calculateInverses]()

+
Generates the boneInverses.
+ + +

[method:null pose]()

+
Returns the skeleton to the base pose.
+ + +

[method:null update]()

+
+ Updates the [page:Float32Array boneMatrices] and [page:DataTexture boneTexture] after changing the bones. + This is called automatically by the [page:WebGLRenderer] if the skeleton is used with a [page:SkinnedMesh]. +
+ + +

Source

+ + [link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js] + + diff --git a/docs/api/objects/SkinnedMesh.html b/docs/api/objects/SkinnedMesh.html index f470fa0497..68894983d7 100644 --- a/docs/api/objects/SkinnedMesh.html +++ b/docs/api/objects/SkinnedMesh.html @@ -11,20 +11,53 @@

[name]

-
An 3d object that has bones data. These Bones can then be used to animate the vertices of the object.
- +
A mesh that has a [page:Skeleton] with [page:Bone bones] that can then be used to animate the vertices of the geometry.
+ +

Example

+ + + + + var geometry = new THREE.CylinderGeometry( 5, 5, 5, 5, 15, 5, 30 ); + + //Create the skin indices and skin weights + for( var i=0; i < geometry.vertices.length; i++ ) { + + // Imaginary functions to calculate the indices and weights + var skinIndex = calculateSkinIndex( geometry.vertices, i ); + var skinWeight = calculateSkinWeight( geometry.vertices, i ); + + // Ease between each bone + geometry.skinIndices.push( new THREE.Vector4( skinIndex, skinIndex+1, 0, 0 ) ); + geometry.skinWeights.push( new THREE.Vector4( 1-skinWeight, skinWeight, 0, 0 ) ); + + } + + var mesh = THREE.SkinnedMesh( geometry, material ); + + // See example from THREE.Skeleton for the armSkeleton + mesh.bind( armSkeleton ); + + // Add the root bone, then recalculate the skeleton inverses + mesh.add( armSkeleton.bones[0] ); + mesh.updateMatrixWorld( true ); // ensure the bones matrices are already recomputed + skeleton.calculateInverses(); + + // Move the bones and manipulate the model + armSkeleton.bones[0].rotation.x = -0.1; + armSkeleton.bones[1].rotation.x = 0.2; + + +

Constructor

[name]([page:Geometry geometry], [page:Material material], [page:boolean useVertexTexture])

- geometry — An instance of [page:Geometry].
- material — An instance of [page:Material] (optional).
- useVertexTexture -- Defines wether a vertex texture can be used (optional). -
-
- This Creates a new instance of skinnedMesh. + geometry —- An instance of [page:Geometry]. [page:Geometry.skinIndices] and [page:Geometry.skinWeights] should be set.
+ material —- An instance of [page:Material] (optional).
+ useVertexTexture -- Defines whether a vertex texture can be used (optional).
diff --git a/docs/list.js b/docs/list.js index 6ef9a42bb8..a72dc05214 100644 --- a/docs/list.js +++ b/docs/list.js @@ -116,6 +116,7 @@ var list = { [ "MorphAnimMesh", "api/objects/MorphAnimMesh" ], [ "PointCloud", "api/objects/PointCloud" ], [ "SkinnedMesh", "api/objects/SkinnedMesh" ], + [ "Skeleton", "api/objects/Skeleton" ], [ "Sprite", "api/objects/Sprite" ] ], diff --git a/docs/scenes/bones-browser.html b/docs/scenes/bones-browser.html new file mode 100644 index 0000000000..f73340d4d9 --- /dev/null +++ b/docs/scenes/bones-browser.html @@ -0,0 +1,271 @@ + + + + + Three.js Bones Browser + + + + + Open in New Window + + + + + + + + \ No newline at end of file -- GitLab