#110 Renames skeleton bind pose to rest pose, to avoid confusion with skinning bind pose

Author: guillaumeblanc

CHANGES.md

@@ -4,6 +4,7 @@ Next release
 * Library
   - [animation] #103 Allows move constructor and assignment for ozz::animation::Skeleton, ozz::animation::Animation and ozz::animation::Track.
   - [animation] Renames SamplingCache to SamplingJob::Context.
+  - [animation] #110 Renames skeleton bind pose to rest pose, to avoid confusion with skinning bind pose.
 
 * Build pipeline
   - #59 Adds support for shared libraries on Windows (dll), Linux and MacOS platforms.

howtos/custom_skeleton_importer.cc

@@ -25,13 +25,12 @@
 //                                                                            //
 //----------------------------------------------------------------------------//
 
+#include <cstdlib>
+
 #include "ozz/animation/offline/raw_skeleton.h"
 #include "ozz/animation/offline/skeleton_builder.h"
-
 #include "ozz/animation/runtime/skeleton.h"
 
-#include <cstdlib>
-
 // Code for ozz-animation HowTo: "How to write a custon skeleton importer?"
 
 int main(int argc, char const* argv[]) {
@@ -52,7 +51,7 @@ int main(int argc, char const* argv[]) {
   // Setup root joints name.
   root.name = "root";
 
-  // Setup root joints bind-pose/rest transformation, in joint local-space.
+  // Setup root joints rest pose transformation, in joint local-space.
   // This is the default skeleton posture (most of the time a T-pose). It's
   // used as a fallback when there's no animation for a joint.
   root.transform.translation = ozz::math::Float3(0.f, 1.f, 0.f);

include/ozz/animation/offline/raw_skeleton.h

@@ -42,12 +42,12 @@ namespace offline {
 // This skeleton type is not intended to be used in run time. It is used to
 // define the offline skeleton object that can be converted to the runtime
 // skeleton using the SkeletonBuilder. This skeleton structure exposes joints'
-// hierarchy. A joint is defined with a name, a transformation (its bind pose),
-// and its children. Children are exposed as a public std::vector of joints.
-// This same type is used for skeleton roots, also exposed from the public API.
-// The public API exposed through std:vector's of joints can be used freely with
-// the only restriction that the total number of joints does not exceed
-// Skeleton::kMaxJoints.
+// hierarchy. A joint is defined with a name, a transformation (its rest_pose
+// pose), and its children. Children are exposed as a public std::vector of
+// joints. This same type is used for skeleton roots, also exposed from the
+// public API. The public API exposed through std:vector's of joints can be used
+// freely with the only restriction that the total number of joints does not
+// exceed Skeleton::kMaxJoints.
 struct OZZ_ANIMOFFLINE_DLL RawSkeleton {
   // Construct an empty skeleton.
   RawSkeleton();
@@ -66,7 +66,7 @@ struct OZZ_ANIMOFFLINE_DLL RawSkeleton {
     // The name of the joint.
     ozz::string name;
 
-    // Joint bind pose transformation in local space.
+    // Joint rest pose transformation in local space.
     math::Transform transform;
   };
 

include/ozz/animation/runtime/blending_job.h

@@ -45,8 +45,8 @@ namespace animation {
 // (the result of a sampled animation) according to their respective weight,
 // into one output pose.
 // The number of transforms/joints blended by the job is defined by the number
-// of transforms of the bind pose (note that this is a SoA format). This means
-// that all buffers must be at least as big as the bind pose buffer.
+// of transforms of the rest pose (note that this is a SoA format). This means
+// that all buffers must be at least as big as the rest pose buffer.
 // Partial animation blending is supported through optional joint weights that
 // can be specified with layers joint_weights buffer. Unspecified joint weights
 // are considered as a unit weight of 1.f, allowing to mix full and partial
@@ -64,7 +64,7 @@ struct OZZ_ANIMATION_DLL BlendingJob {
   // -if any layer is not valid.
   // -if output range is not valid.
   // -if any buffer (including layers' content : transform, joint weights...) is
-  // smaller than the bind pose buffer.
+  // smaller than the rest pose buffer.
   // -if the threshold value is less than or equal to 0.f.
   bool Validate() const;
 
@@ -87,17 +87,17 @@ struct OZZ_ANIMATION_DLL BlendingJob {
 
     // The range [begin,end[ of input layer posture. This buffer expect to store
     // local space transforms, that are usually outputted from a sampling job.
-    // This range must be at least as big as the bind pose buffer, even though
-    // only the number of transforms defined by the bind pose buffer will be
+    // This range must be at least as big as the rest pose buffer, even though
+    // only the number of transforms defined by the rest pose buffer will be
     // processed.
     span<const math::SoaTransform> transform;
 
     // Optional range [begin,end[ of blending weight for each joint in this
     // layer.
     // If both pointers are nullptr (default case) then per joint weight
     // blending is disabled. A valid range is defined as being at least as big
-    // as the bind pose buffer, even though only the number of transforms
-    // defined by the bind pose buffer will be processed. When a layer doesn't
+    // as the rest pose buffer, even though only the number of transforms
+    // defined by the rest pose buffer will be processed. When a layer doesn't
     // specifies per joint weights, then it is implicitly considered as
     // being 1.f. This default value is a reference value for the normalization
     // process, which implies that the range of values for joint weights should
@@ -107,7 +107,7 @@ struct OZZ_ANIMATION_DLL BlendingJob {
     span<const math::SimdFloat4> joint_weights;
   };
 
-  // The job blends the bind pose to the output when the accumulated weight of
+  // The job blends the rest pose to the output when the accumulated weight of
   // all layers is less than this threshold value.
   // Must be greater than 0.f.
   float threshold;
@@ -120,18 +120,18 @@ struct OZZ_ANIMATION_DLL BlendingJob {
   // The range of layers that must be added to the output.
   span<const Layer> additive_layers;
 
-  // The skeleton bind pose. The size of this buffer defines the number of
+  // The skeleton rest pose. The size of this buffer defines the number of
   // transforms to blend. This is the reference because this buffer is defined
   // by the skeleton that all the animations belongs to.
   // It is used when the accumulated weight for a bone on all layers is
   // less than the threshold value, in order to fall back on valid transforms.
-  span<const ozz::math::SoaTransform> bind_pose;
+  span<const ozz::math::SoaTransform> rest_pose;
 
   // Job output.
   // The range of output transforms to be filled with blended layer
   // transforms during job execution.
-  // Must be at least as big as the bind pose buffer, but only the number of
-  // transforms defined by the bind pose buffer size will be processed.
+  // Must be at least as big as the rest pose buffer, but only the number of
+  // transforms defined by the rest pose buffer size will be processed.
   span<ozz::math::SoaTransform> output;
 };
 }  // namespace animation

include/ozz/animation/runtime/skeleton.h

@@ -49,9 +49,9 @@ class SkeletonBuilder;
 }
 
 // This runtime skeleton data structure provides a const-only access to joint
-// hierarchy, joint names and bind-pose. This structure is filled by the
+// hierarchy, joint names and rest-pose. This structure is filled by the
 // SkeletonBuilder and can be serialize/deserialized.
-// Joint names, bind-poses and hierarchy information are all stored in separate
+// Joint names, rest-poses and hierarchy information are all stored in separate
 // arrays of data (as opposed to joint structures for the RawSkeleton), in order
 // to closely match with the way runtime algorithms use them. Joint hierarchy is
 // packed as an array of parent jont indices (16 bits), stored in depth-first
@@ -100,9 +100,9 @@ class OZZ_ANIMATION_DLL Skeleton {
   // skeleton. This value is useful to allocate SoA runtime data structures.
   int num_soa_joints() const { return (num_joints() + 3) / 4; }
 
-  // Returns joint's bind poses. Bind poses are stored in soa format.
-  span<const math::SoaTransform> joint_bind_poses() const {
-    return joint_bind_poses_;
+  // Returns joint's rest poses. Rest poses are stored in soa format.
+  span<const math::SoaTransform> joint_rest_poses() const {
+    return joint_rest_poses_;
   }
 
   // Returns joint's parent indices range.
@@ -130,8 +130,8 @@ class OZZ_ANIMATION_DLL Skeleton {
   // Buffers below store joint informations in joing depth first order. Their
   // size is equal to the number of joints of the skeleton.
 
-  // Bind pose of every joint in local space.
-  span<math::SoaTransform> joint_bind_poses_;
+  // Rest pose of every joint in local space.
+  span<math::SoaTransform> joint_rest_poses_;
 
   // Array of joint parent indexes.
   span<int16_t> joint_parents_;

include/ozz/animation/runtime/skeleton_utils.h

@@ -37,8 +37,8 @@
 namespace ozz {
 namespace animation {
 
-// Get bind-pose of a skeleton joint.
-OZZ_ANIMATION_DLL ozz::math::Transform GetJointLocalBindPose(
+// Get rest-pose of a skeleton joint.
+OZZ_ANIMATION_DLL ozz::math::Transform GetJointLocalRestPose(
     const Skeleton& _skeleton, int _joint);
 
 // Test if a joint is a leaf. _joint number must be in range [0, num joints].

samples/additive/sample_additive.cc

@@ -115,7 +115,7 @@ class AdditiveBlendSampleApplication : public ozz::sample::Application {
     ozz::animation::BlendingJob blend_job;
     blend_job.layers = layers;
     blend_job.additive_layers = additive_layers;
-    blend_job.bind_pose = skeleton_.joint_bind_poses();
+    blend_job.rest_pose = skeleton_.joint_rest_poses();
     blend_job.output = make_span(blended_locals_);
 
     // Blends.

samples/blend/README.md

@@ -23,6 +23,6 @@ There are two ways to use the sample:
 
 1. Load animations and skeleton. See "playback" sample for more details.
 2. Compute each animation time (in order to sync their duration) and samples each of them to get local-space transformations.
-3. Compute each animation (layer) blend weight and fills ozz::animation::BlendingJob object. BlendingJob object takes as input an array of BlendingJob::Layer representing each layer to blend: weight and local-space transformations (as outputed from the sampling stage). It also takes as input the skeleton bind-pose, which represents the default transformation of each joint. It is used by the blending algorithm as a fall-back when the accumulated layer weight is too small (under a threshold value which is also an input) to be used. The output of the blending job is a set of local-space transformations.
+3. Compute each animation (layer) blend weight and fills ozz::animation::BlendingJob object. BlendingJob object takes as input an array of BlendingJob::Layer representing each layer to blend: weight and local-space transformations (as outputed from the sampling stage). It also takes as input the skeleton rest-pose, which represents the default transformation of each joint. It is used by the blending algorithm as a fall-back when the accumulated layer weight is too small (under a threshold value which is also an input) to be used. The output of the blending job is a set of local-space transformations.
 4. Convert local-space transformations to model-space matrices using ozz::animation::LocalToModelJob. It takes as input the skeleton (to know about joint's hierarchy) and local-space transforms. Output is model-space matrices array.
 5. Model-space matrices array can then be used for rendering (to skin a mesh) or updating the scene graph.

samples/blend/sample_blend.cc

@@ -119,7 +119,7 @@ class BlendSampleApplication : public ozz::sample::Application {
     ozz::animation::BlendingJob blend_job;
     blend_job.threshold = threshold_;
     blend_job.layers = layers;
-    blend_job.bind_pose = skeleton_.joint_bind_poses();
+    blend_job.rest_pose = skeleton_.joint_rest_poses();
     blend_job.output = make_span(blended_locals_);
 
     // Blends.
@@ -322,7 +322,7 @@ class BlendSampleApplication : public ozz::sample::Application {
     ozz::vector<ozz::math::SoaTransform> locals;
   } samplers_[kNumLayers];  // kNumLayers animations to blend.
 
-  // Blending job bind pose threshold.
+  // Blending job rest pose threshold.
   float threshold_;
 
   // Buffer of local transforms which stores the blending result.

samples/foot_ik/sample_foot_ik.cc

@@ -746,7 +746,7 @@ class FootIKSampleApplication : public ozz::sample::Application {
   ozz::vector<ozz::math::Float4x4> models_;
 
   // Buffer of skinning matrices, result of the joint multiplication of the
-  // inverse bind pose with the model space matrix.
+  // inverse rest pose with the model space matrix.
   ozz::vector<ozz::math::Float4x4> skinning_matrices_;
 
   // The mesh used by the sample.

samples/framework/internal/renderer_impl.cc

@@ -239,7 +239,7 @@ bool RendererImpl::DrawGrid(int _cell_count, float _cell_size) {
   return true;
 }
 
-// Computes the model space bind pose and renders it.
+// Computes the model space rest pose and renders it.
 bool RendererImpl::DrawSkeleton(const ozz::animation::Skeleton& _skeleton,
                                 const ozz::math::Float4x4& _transform,
                                 bool _draw_joints) {
@@ -253,9 +253,9 @@ bool RendererImpl::DrawSkeleton(const ozz::animation::Skeleton& _skeleton,
   // Reallocate matrix array if necessary.
   prealloc_models_.resize(num_joints);
 
-  // Compute model space bind pose.
+  // Compute model space rest pose.
   ozz::animation::LocalToModelJob job;
-  job.input = _skeleton.joint_bind_poses();
+  job.input = _skeleton.joint_rest_poses();
   job.output = make_span(prealloc_models_);
   job.skeleton = &_skeleton;
   if (!job.Run()) {

samples/framework/renderer.h

@@ -79,7 +79,7 @@ class Renderer {
   // has a size of _cell_size.
   virtual bool DrawGrid(int _cell_count, float _cell_size) = 0;
 
-  // Renders a skeleton in its bind pose posture.
+  // Renders a skeleton in its rest pose posture.
   virtual bool DrawSkeleton(const animation::Skeleton& _skeleton,
                             const ozz::math::Float4x4& _transform,
                             bool _draw_joints = true) = 0;
@@ -121,7 +121,7 @@ class Renderer {
     bool tangents;   // Show tangents.
     bool binormals;  // Show binormals, computed from the normal and tangent.
     bool colors;     // Show vertex colors.
-    bool wireframe;     // Show vertex colors.
+    bool wireframe;  // Show vertex colors.
     bool skip_skinning;  // Show texture (default checkered texture).
 
     Options()

samples/framework/utils.cc

@@ -30,28 +30,22 @@
 #include <cassert>
 #include <limits>
 
-#include "ozz/base/maths/box.h"
-#include "ozz/base/maths/simd_math.h"
-#include "ozz/base/maths/simd_quaternion.h"
-#include "ozz/base/maths/soa_transform.h"
-
-#include "ozz/base/memory/allocator.h"
-
+#include "framework/imgui.h"
+#include "framework/mesh.h"
+#include "ozz/animation/offline/raw_skeleton.h"
 #include "ozz/animation/runtime/animation.h"
 #include "ozz/animation/runtime/local_to_model_job.h"
 #include "ozz/animation/runtime/skeleton.h"
 #include "ozz/animation/runtime/track.h"
-
-#include "ozz/animation/offline/raw_skeleton.h"
-
-#include "ozz/geometry/runtime/skinning_job.h"
-
 #include "ozz/base/io/archive.h"
 #include "ozz/base/io/stream.h"
 #include "ozz/base/log.h"
-
-#include "framework/imgui.h"
-#include "framework/mesh.h"
+#include "ozz/base/maths/box.h"
+#include "ozz/base/maths/simd_math.h"
+#include "ozz/base/maths/simd_quaternion.h"
+#include "ozz/base/maths/soa_transform.h"
+#include "ozz/base/memory/allocator.h"
+#include "ozz/geometry/runtime/skinning_job.h"
 
 namespace ozz {
 namespace sample {
@@ -224,9 +218,9 @@ void ComputeSkeletonBounds(const animation::Skeleton& _skeleton,
   // Allocate matrix array, out of memory is handled by the LocalToModelJob.
   ozz::vector<ozz::math::Float4x4> models(num_joints);
 
-  // Compute model space bind pose.
+  // Compute model space rest pose.
   ozz::animation::LocalToModelJob job;
-  job.input = _skeleton.joint_bind_poses();
+  job.input = _skeleton.joint_rest_poses();
   job.output = make_span(models);
   job.skeleton = &_skeleton;
   if (job.Run()) {

samples/look_at/sample_look_at.cc

@@ -478,7 +478,7 @@ class LookAtSampleApplication : public ozz::sample::Application {
   ozz::vector<ozz::math::Float4x4> models_;
 
   // Buffer of skinning matrices, result of the joint multiplication of the
-  // inverse bind pose with the model-space matrix.
+  // inverse rest pose with the model-space matrix.
   ozz::vector<ozz::math::Float4x4> skinning_matrices_;
 
   // The mesh used by the sample.

samples/optimize/sample_optimize.cc

@@ -123,31 +123,31 @@ class OptimizeSampleApplication : public ozz::sample::Application {
     }
 
     // Computes difference between the optimized and non-optimized animations
-    // in local space, and rebinds it to the bind pose.
+    // in local space, and rebinds it to the rest pose.
     {
-      const ozz::span<const ozz::math::SoaTransform>& bind_poses =
-          skeleton_.joint_bind_poses();
-      const ozz::math::SoaTransform* bind_pose = bind_poses.begin();
+      const ozz::span<const ozz::math::SoaTransform>& rest_poses =
+          skeleton_.joint_rest_poses();
+      const ozz::math::SoaTransform* rest_pose = rest_poses.begin();
       const ozz::math::SoaTransform* locals_raw = locals_raw_.data();
       const ozz::math::SoaTransform* locals_rt = locals_rt_.data();
       ozz::math::SoaTransform* locals_diff = locals_diff_.data();
-      for (; bind_pose < bind_poses.end();
-           ++locals_raw, ++locals_rt, ++locals_diff, ++bind_pose) {
+      for (; rest_pose < rest_poses.end();
+           ++locals_raw, ++locals_rt, ++locals_diff, ++rest_pose) {
         assert(locals_raw < array_end(locals_raw_) &&
                locals_rt < array_end(locals_rt_) &&
                locals_diff < array_end(locals_diff_) &&
-               bind_pose < bind_poses.end());
+               rest_pose < rest_poses.end());
 
         // Computes difference.
         const ozz::math::SoaTransform diff = {
             locals_rt->translation - locals_raw->translation,
             locals_rt->rotation * Conjugate(locals_raw->rotation),
             locals_rt->scale / locals_raw->scale};
 
-        // Rebinds to the bind pose in the diff buffer.
-        locals_diff->translation = bind_pose->translation + diff.translation;
-        locals_diff->rotation = bind_pose->rotation * diff.rotation;
-        locals_diff->scale = bind_pose->scale * diff.scale;
+        // Rebinds to the rest pose in the diff buffer.
+        locals_diff->translation = rest_pose->translation + diff.translation;
+        locals_diff->rotation = rest_pose->rotation * diff.rotation;
+        locals_diff->scale = rest_pose->scale * diff.scale;
       }
     }
 

samples/partial_blend/README.md

@@ -24,6 +24,6 @@ The GUI also proposes to select the "root" joint of the upper body hierarchy, wh
 4. Uses ozz::animation::IterateJointsDF helper function to iterate all children of the upper body root joint, and set up per-joint weight masks as follows (note that weight coefficients are stored as SoA floats):
    - Upper body weight mask: Affects upper body weight coefficient to all the joints that are part of the upper body, all others are set to zero.
    - Lower body weight mask: Affects lower body weight coefficient to all the joints that are part of the lower body (ie: all the ones that are not part of the upper body), all others are set to one.
-5. Sets ozz::animation::BlendingJob object with the two layers for the lower and upper body. Per-joint weight masks are provided as an input to each layer. All other arguments (bind-pose, input local-space transforms, weights, output) are the same as those used by the full skeleton hierarchy blending. See "blend" sample for more details.
+5. Sets ozz::animation::BlendingJob object with the two layers for the lower and upper body. Per-joint weight masks are provided as an input to each layer. All other arguments (rest-pose, input local-space transforms, weights, output) are the same as those used by the full skeleton hierarchy blending. See "blend" sample for more details.
 6. Converts local-space transformations, outputted from the blending stage, to model-space matrices using ozz::animation::LocalToModelJob. It also takes as input the skeleton (to know about joint's hierarchy). Output is model-space matrices array.
 7. Model-space matrices array can then be used for rendering (to skin a mesh) or updating the scene graph.