AnimTestbed/3rdparty/ozz-animation/include/ozz/animation/runtime/blending_job.h

140 lines
6.8 KiB
C++

//----------------------------------------------------------------------------//
// //
// ozz-animation is hosted at http://github.com/guillaumeblanc/ozz-animation //
// and distributed under the MIT License (MIT). //
// //
// Copyright (c) Guillaume Blanc //
// //
// Permission is hereby granted, free of charge, to any person obtaining a //
// copy of this software and associated documentation files (the "Software"), //
// to deal in the Software without restriction, including without limitation //
// the rights to use, copy, modify, merge, publish, distribute, sublicense, //
// and/or sell copies of the Software, and to permit persons to whom the //
// Software is furnished to do so, subject to the following conditions: //
// //
// The above copyright notice and this permission notice shall be included in //
// all copies or substantial portions of the Software. //
// //
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR //
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, //
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL //
// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER //
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING //
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER //
// DEALINGS IN THE SOFTWARE. //
// //
//----------------------------------------------------------------------------//
#ifndef OZZ_OZZ_ANIMATION_RUNTIME_BLENDING_JOB_H_
#define OZZ_OZZ_ANIMATION_RUNTIME_BLENDING_JOB_H_
#include "ozz/animation/runtime/export.h"
#include "ozz/base/maths/simd_math.h"
#include "ozz/base/span.h"
namespace ozz {
// Forward declaration of math structures.
namespace math {
struct SoaTransform;
}
namespace animation {
// ozz::animation::BlendingJob is in charge of blending (mixing) multiple poses
// (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 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
// blend operations in a single pass.
// The job does not owned any buffers (input/output) and will thus not delete
// them during job's destruction.
struct OZZ_ANIMATION_DLL BlendingJob {
// Default constructor, initializes default values.
BlendingJob();
// Validates job parameters.
// Returns true for a valid job, false otherwise:
// -if layer range is not valid (can be empty though).
// -if additive layer range is not valid (can be empty though).
// -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 rest pose buffer.
// -if the threshold value is less than or equal to 0.f.
bool Validate() const;
// Runs job's blending task.
// The job is validated before any operation is performed, see Validate() for
// more details.
// Returns false if *this job is not valid.
bool Run() const;
// Defines a layer of blending input data (local space transforms) and
// parameters (weights).
struct OZZ_ANIMATION_DLL Layer {
// Default constructor, initializes default values.
Layer();
// Blending weight of this layer. Negative values are considered as 0.
// Normalization is performed during the blending stage so weight can be in
// any range, even though range [0:1] is optimal.
float weight;
// 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 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 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
// be [0,1]. Negative weight values are considered as 0, but positive ones
// aren't clamped because they could exceed 1.f if all layers contains valid
// joint weights.
span<const math::SimdFloat4> joint_weights;
};
// 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;
// Job input layers, can be empty or nullptr.
// The range of layers that must be blended.
span<const Layer> layers;
// Job input additive layers, can be empty or nullptr.
// The range of layers that must be added to the output.
span<const Layer> additive_layers;
// 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> 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 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
} // namespace ozz
#endif // OZZ_OZZ_ANIMATION_RUNTIME_BLENDING_JOB_H_