GU_MotionClip.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        GU_MotionClip.h ( GU Library, C++)
 *
 * COMMENTS:    Classes to hold & manipulate motion clips.
 *
 * GU_MotionClipRO & GU_MotionClipRW - Containers for motion clips
 * GU_MotionClipBuilder - Batch modifier for motion clips
 *
 */

#ifndef __GU_MOTIONCLIP_H_INCLUDED__
#define __GU_MOTIONCLIP_H_INCLUDED__

#include "GU_API.h"

#include "GU_AgentClip.h"
#include "GU_MotionClipUtil.h"
#include "GU_Hierarchy.h"

#include <GA/GA_Types.h>
#include <GA/GA_AttributeFilter.h>

#include <GOP/GOP_Manager.h>

#include <UT/UT_Array.h>
#include <UT/UT_Lock.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringMap.h>
#include <UT/UT_TransformUtil.h>

#include <SYS/SYS_Inline.h>
#include <SYS/SYS_Types.h>

#include <utility>

/// Read-only animation clip represented in geometry as packed primitives.
///
/// The first packed geometry primitive contains the skeleton "topology"
/// evaluated at the given rest frame and the remaining packed geometry
/// primitives each represent a cached pose (ie. a KineFX skeleton), each
/// containing a list of points with joint names and transforms.
/// For each pose, the @c time primitive attribute represents where it should
/// be in seconds.
///
/// Note that the joints in the pose packed primitives must exist in the
/// topology packed primitive, but the converse is not necessarily true. The
/// pose packed primitive may be missing particular joints from the topology
/// packed primitive, in which case, interpolation will be done using adjacent
/// pose packed primitives which do have data for the particular joint.
///
class GU_API GU_MotionClipRO
{
public:


    // This is used to define the evaluation parameters for a call to the
    // ::evaluate() function.
    struct EvaluationParms
    {
        EvaluationParms()
        {
            myRestAttribsToUnpack  = nullptr;
            myAnimAttribsToUnpack  = nullptr;

            myUseLeftEndBehavior   = false;
            myLeftEndBehavior      = GU_MotionClipEndBehavior::Clamp;

            myUseRightEndBehavior  = false;
            myRightEndBehavior     = GU_MotionClipEndBehavior::Clamp;

            myResetMissingAttribs  = false;
            myConstantEvaluation   = false;
            myOutputTime           = false;

            myRecomputeWorld = true;
            myHierarchyCache = nullptr;

            myCenterOfMassName     = "COM";
            myCenterOfMassPtoff    = GA_INVALID_OFFSET;
            myConfigAttribName     = "";
        }

        // A filter which defines which point and detail attributes should be
        // obtained from the topology.
        const GA_AttributeFilter *myRestAttribsToUnpack;

        // A filter which defines which point and detail attributes should be
        // obtained from the animated poses of the MotionClip.
        const GA_AttributeFilter *myAnimAttribsToUnpack;

        // Pairs of attributes which define the left and right end behaviors
        // and whether to use the values from this class.
        // If myUseLelfEndBehvaior is false, the left end behvaior of the
        // MotionClip's clipinfo will be used instead.
        bool                      myUseLeftEndBehavior;
        GU_MotionClipEndBehavior  myLeftEndBehavior;
        bool                      myUseRightEndBehavior;
        GU_MotionClipEndBehavior  myRightEndBehavior;

        // If true, the point and detail attributes which exist on the input
        // destination geometry, match the animated attribute filter, and
        // do not exist on all of the animated poses used as the start of the
        // blend will be reset or removed before evaluation. This ensures that
        // the result of evaluating the MotionClip will remain the same for all
        // filtered attributes, regardless of what the value of the attribtue
        // was on the destination geometry prior to evalution.
        bool                      myResetMissingAttribs;

        // If true, instead of linearly interpolating the poses, the
        // interpolation mode will be constant.
        bool                      myConstantEvaluation;

        // If true, the time of the evaluation will be added as a point
        // attribute to the evaluated pose.
        bool                      myOutputTime;

        bool                      myRecomputeWorld;
        GU_HierarchyCache        *myHierarchyCache;

        // The name of the center of mass point and the point offset of the
        // point in the result geometry.
        // If the point offset is a valid offset for the result geometry,
        // the point will be given transform and position attributes that
        // correspond with the center of mass of the result point group. The
        // center of mass point should not be in the result point group.
        GA_Offset                 myCenterOfMassPtoff;
        UT_StringHolder           myCenterOfMassName;
        UT_StringHolder           myConfigAttribName;
    };

    /// clipinfo will override the gdp's clipinfo detail attribute
    GU_MotionClipRO(
            const GU_Detail *gdp,
            UT_WorkBuffer &err_msg,
            bool can_evaluate = true,
            GU_MotionClipInfo *clipinfo = nullptr,
            bool compute_default_clipinfo = false,
            bool do_sort_samples = true,
            bool enable_locking = true);

    virtual ~GU_MotionClipRO() = default;

    virtual bool updateGdp(const GU_Detail *gdp);

    /// Appends the unpacked toplogy geometry to dest
    ///
    void getTopology(fpreal &time, GU_Detail *dest,
                     const GA_AttributeFilter* skip = nullptr);

    bool hasTopology() const { return myHasTopology; }

    /// This will compute the frame at the given time, and
    /// then copy the P+transform attributes of the ith
    /// point in topologyPts into the ith point in resultPts.
    ///
    /// It will also include whatever extra attribs you request
    /// as long as there is no current active GU_MotionClipBuilder
    ///
    /// @pre resultPts and topologyPts must correspond
    ///      to the same points in their respective 
    ///      geometries, in the same order.
    void evaluate(fpreal time, GU_Detail *result,
                  const GA_PointGroup *result_pts=nullptr,
                  const GA_PointGroup *topology_pts=nullptr,
                  const GA_AttributeFilter* extra_attribs_to_unpack=nullptr,
                  GU_MotionClipEndBehavior left_end_behavior=GU_MotionClipEndBehavior::Clamp,
                  GU_MotionClipEndBehavior right_end_behavior=GU_MotionClipEndBehavior::Clamp)
    {
        AutoLock lock(getLock());
        myEvaluator.evaluate(time, result, result_pts,
                             getFrameDetail(-1), topology_pts, myHierarchyCache,
                             extra_attribs_to_unpack /*rest_attribs_to_unpack*/,
                             extra_attribs_to_unpack /*anim_attribs_to_unpack*/,
                             left_end_behavior, right_end_behavior,
                             false /*reset_missing_attribs*/,
                             false /*constant_evaluation*/,
                             false /*output_time*/,
                             true /*recompute_world*/,
                             nullptr /*is_anim_point_attrib*/,
                             GA_INVALID_OFFSET /*com_ptoff*/,
                             "" /*com_name*/,
                             "" /*config_attrib*/);
    }


    /// This will compute the frame at the given time, and
    /// then copy the P+transform attributes of the ith
    /// point in topologyPts into the ith point in resultPts.
    ///
    /// It will also include whatever extra attribs you request
    /// as long as there is no current active GU_MotionClipBuilder
    ///
    /// The parameters used to define the interpolation must be set
    /// by in an EvaluationParms structure.
    ///
    /// @pre resultPts and topologyPts must correspond
    ///      to the same points in their respective 
    ///      geometries, in the same order.
    ///
    /// @pre is_anim_point_attribs returns whether each the requested point
    /// attribute exists on the animated poses. An entry must already exist
    /// for each attribtue in question.
    void evaluate(fpreal time, GU_Detail *result,
                  const EvaluationParms &evaluation_parms,
                  const GA_PointGroup *result_pts=nullptr,
                  const GA_PointGroup *topology_pts=nullptr,
                  UT_ArrayStringMap<bool> *is_anim_point_attrib = nullptr)
    {
        AutoLock lock(getLock());

        GU_MotionClipEndBehavior left_end_behavior = myClipinfo.leftEndBehaviorEnum();
        if (evaluation_parms.myUseLeftEndBehavior)
            left_end_behavior = evaluation_parms.myLeftEndBehavior;

        GU_MotionClipEndBehavior right_end_behavior = myClipinfo.rightEndBehaviorEnum();
        if (evaluation_parms.myUseRightEndBehavior)
            right_end_behavior = evaluation_parms.myRightEndBehavior;

        GU_HierarchyCache *sopcache = evaluation_parms.myHierarchyCache;
        if (!sopcache)
            sopcache = &myHierarchyCache;

        myEvaluator.evaluate(time, result, result_pts,
                             getFrameDetail(-1), topology_pts, *sopcache,
                             evaluation_parms.myRestAttribsToUnpack,
                             evaluation_parms.myAnimAttribsToUnpack,
                             left_end_behavior, right_end_behavior,
                             evaluation_parms.myResetMissingAttribs,
                             evaluation_parms.myConstantEvaluation,
                             evaluation_parms.myOutputTime,
                             evaluation_parms.myRecomputeWorld,
                             is_anim_point_attrib,
                             evaluation_parms.myCenterOfMassPtoff,
                             evaluation_parms.myCenterOfMassName,
                             evaluation_parms.myConfigAttribName);
    }
    void evaluateNoLock(fpreal time, GU_Detail *result,
                  const EvaluationParms &evaluation_parms,
                  const GA_PointGroup *result_pts=nullptr,
                  const GA_PointGroup *topology_pts=nullptr,
                  UT_ArrayStringMap<bool> *is_anim_point_attrib = nullptr)
    {
        //AutoLock lock(getLock());

        GU_MotionClipEndBehavior left_end_behavior = myClipinfo.leftEndBehaviorEnum();
        if (evaluation_parms.myUseLeftEndBehavior)
            left_end_behavior = evaluation_parms.myLeftEndBehavior;

        GU_MotionClipEndBehavior right_end_behavior = myClipinfo.rightEndBehaviorEnum();
        if (evaluation_parms.myUseRightEndBehavior)
            right_end_behavior = evaluation_parms.myRightEndBehavior;

        GU_HierarchyCache *sopcache = evaluation_parms.myHierarchyCache;
        if (!sopcache)
            sopcache = &myHierarchyCache;

        myEvaluator.evaluate(time, result, result_pts,
                             getFrameDetail(-1), topology_pts, *sopcache,
                             evaluation_parms.myRestAttribsToUnpack,
                             evaluation_parms.myAnimAttribsToUnpack,
                             left_end_behavior, right_end_behavior,
                             evaluation_parms.myResetMissingAttribs,
                             evaluation_parms.myConstantEvaluation,
                             evaluation_parms.myOutputTime,
                             evaluation_parms.myRecomputeWorld,
                             is_anim_point_attrib,
                             evaluation_parms.myCenterOfMassPtoff,
                             evaluation_parms.myCenterOfMassName,
                             evaluation_parms.myConfigAttribName
                             );
    }
    
    // This will re-compute the localtransforms of each frame in the
    // evaluator so that each frame evaluates to the correct position
    // while using the input scale inheritance for all joints
    void setScaleInheritance(UT_ScaleInheritanceMode scale_inheritance)
    {
        AutoLock lock(getLock());
        myEvaluator.setScaleInheritance(getFrameDetail(-1),
                                        scale_inheritance);
    }
    /// This computes the local transforms of each joint at the given
    /// time. The ith element defines represents the ith joint in the
    /// topology detail. getJointIndex can be used to check this
    void computeLocalTransforms(fpreal time,
                                UT_Array<GU_AgentXformD> &result,
                                bool constant_evaluation=false)
    {
        AutoLock lock(getLock());

        UT_Array<GU_AgentXformD> *presult = nullptr;
        UT_Array<UT_Matrix4D> *presult4 = nullptr;
        myEvaluator.computeLocalTransforms(time, result, presult, presult4,
            constant_evaluation);
        if (presult!=nullptr)
            result = *presult;
    }

    /// Returns the index of the given joint name within the
    /// topology detail
    exint getJointIndex(const UT_StringHolder& joint_name) const
    {
        if (!myNameToJointIdx.contains(joint_name))
            return -1;
        return myNameToJointIdx.at(joint_name);
    }

    /// Returns a point group of the topology detail based
    /// on the given pattern
    const GA_PointGroup* getJointGroup(
        GOP_Manager &gop, const UT_StringHolder& pattern) const;
    void                 getJointsInGroup(
        GOP_Manager &gop, const UT_StringHolder& pattern,
        UT_StringArray &joints_in_group) const;

    /// returns false if there was an error during initialization
    ///
    bool isInitialised() const
    {
        return myIsInitialised;
    }

    exint numJoints() const
    {
        return myNumJoints;
    }
    
    const GU_MotionClipInfo &clipInfo() const { return myClipinfo; }

    /// returns the sample at time, or nullptr if not found
    const GU_Detail *getSample(fpreal time) const;
    const GU_Detail *restFrame() const { return getFrameDetail(-1); }

    void             getSortedFrameOrder(UT_Array<exint> &frame_order);

    const UT_Array<fpreal>& getSampleTimes() {
        return myEvaluator.getSampleTimes();
    }
    
    bool canEvaluate() const {
        return myCanEvaluate;
    }

protected:
    const GU_Detail *ourGdp;

    // Data Ids of the input geometry which were recorded for the purpose
    // of determining if this GU_MotionClipRO class is still valid or if
    // the geometry has changed too much.
    GU_MotionClipDataIds ourDataIds;

    void sortPrimitives(GU_Detail *gdp, bool clear_array);

private:
    friend class GU_MotionClipRW;
    friend class GU_MotionClipBuilder;

    /// Returns the time in seconds of the indexth frame
    fpreal getFrameTime(exint index) const;
    const GU_Detail* getFrameDetail(exint frame,
                                    UT_Matrix4D *intrinsic=nullptr) const;
    GA_Offset getFrameOffset(exint frame) const;

    /// Returns the highest frame index with a time
    /// less than or equal to time or -1 if no such index exists
    exint getFrameAtOrBefore(fpreal time) const;

    /// We use this class to separate the evaluation data
    /// from the other members so that we can safely evaluate
    /// while a MotionClipBuilder is manipulating the rest of
    /// the object. This also makes it clear what data you
    /// can skip updating when myCanEvaluate is false
    /// 
    /// However if we need to unpack extra attributes we
    /// need to find them within the gdp which is impossible
    /// while there is a MotionClip builder operating on it...
    /// Because of this we store a ptr to the clip and set it to
    /// null whenever the Evaluator is out of date - when it is
    /// null evaluate will skip unpacking attribs. The caller should
    /// ensure that this is not allowed
    class Evaluator
    {
    public:
        Evaluator();

        void computeLocalTransforms(fpreal time,
                                    UT_Array<GU_AgentXformD> &result,
                                    UT_Array<GU_AgentXformD> *&presult,
                                    UT_Array<UT_Matrix4D> *&presult4,
                                    bool constant_evaluation);
        void evaluate(fpreal target_time, GU_Detail *result,
                      const GA_PointGroup *result_pts,
                      const GU_Detail *topology,
                      const GA_PointGroup *topology_pts,
                      GU_HierarchyCache &sopcache,
                      const GA_AttributeFilter* rest_attribs_to_unpack,
                      const GA_AttributeFilter* anim_attribs_to_unpack,
                      GU_MotionClipEndBehavior left_end_behavior,
                      GU_MotionClipEndBehavior right_end_behavior,
                      bool reset_missing_attribs,
                      bool constant_evaluation,
                      bool output_time,
                      bool recompute_world,
                      UT_ArrayStringMap<bool> *is_anim_point_attrib,
                      const GA_Offset com_ptoff,
                      const UT_StringHolder com_name,
                      const UT_StringHolder config_attrib);
        void setScaleInheritance(const GU_Detail *topology,
                                 UT_ScaleInheritanceMode scale_inheritance);
        void update(const GU_MotionClipRO &clip);
        void setDirty()
        {
            myClip = nullptr;
        }
        const UT_Array<fpreal>& getSampleTimes() {
            return myFrameTimes;
        }

    private:
        // A helper function for ::evaluate() which evaluates the extra detail
        // attributes.
        void evaluateDetailAttribs(GU_Detail *result,
                                   const GU_Detail *topology,
                                   const GU_Detail *detail_a,
                                   const GU_Detail *detail_b,
                                   const fpreal weight,
                                   const GA_AttributeFilter &rest_filter,
                                   const GA_AttributeFilter &anim_filter,
                                   bool reset_missing_attribs);

        // A helper function for ::evaluaet() which resets the values of or
        // removes attributes which exist on the result geometry, match the
        // animated filter, and do not exist on at least one of the poses used
        // as the start point of the blend.
        // If result_pts is defined, the attribute is reset to its default value
        // on those points.
        // Otherwise, the attribute is destroyed (and may be re-created later in
        // the evaluation process).
        void resetMissingPointAttribs(GU_Detail *result,
                                      const GA_PointGroup *result_pts,
                                      const GU_Detail *topology,
                                      const GA_AttributeFilter &rest_filter,
                                      const GA_AttributeFilter &anim_filter,
                                      bool output_time,
                                      const UT_IntArray &start_poses,
                                      UT_StringArray &whole_attrib_names);

        /// Returns the highest frame index with a time
        /// less than or equal to time or -1 if no such index exists
        exint getFrameAtOrBefore(fpreal time) const;

        /// myFrameTransforms[frame_idx][joint_idx] represents 
        /// joint_idx's decomposed local space transform in frame
        /// frame_idx, even if the joint does not exist in the sample
        UT_Array<UT_Array<GU_AgentXformD>> myFrameTransforms;
        UT_Array<UT_Array<UT_Matrix4D>> myFrameTransforms4;

        /// myInterpFrames[frame_idx][joint_idx] contains a pair
        /// containing the two sample indices used when interpolating
        /// the position of this joint. 
        /// the first index will be strictly less than frame_idx
        /// the second will be greater than or equal to frame_idx
        UT_Array<UT_Array<std::pair<exint, exint>>> myInterpFrames;
        UT_Array<fpreal> myFrameTimes;

        /// maps a joint name to the corresponding point offset
        /// within each sample
        UT_Array<UT_StringMap<GA_Offset>> myFrameJointOffsets;
        fpreal myLastEvalTime;
        exint myLastEvalFrame;
        UT_Vector2R myClipRange;

        /// these are always outputted
        GA_AttributeFilter myIsAttribExtra;
        
        // This is a flag to indicate whether the clearModel method has
        // been called since the last time the evaluator was updated.
        // This is needed so that the MotionClip can be evaluated properly.
        bool                    myIsScaleInheritanceChanged;
        UT_ScaleInheritanceMode myScaleInheritance;

        // We need the clip to fetch additional attributes. However
        // we can not safely use it when the evaluator is dirty.
        // We'll set this to null whenever it is unsafe to use
        const GU_MotionClipRO *myClip;
    };
    
    GU_MotionClipInfo generateClipInfo();

    Evaluator myEvaluator;

    GU_HierarchyCache myHierarchyCache;
    GU_MotionClipInfo myClipinfo;

    class AutoLock : UT_NonCopyable
    {
    public:
         AutoLock(UT_Lock *lock)
             : myLock(lock)
            {
                if(myLock)
                    myLock->lock();
            }
        
        ~AutoLock()
        {
            if (myLock)
                myLock->unlock();
        }
        
    private:
        UT_Lock *myLock;
    };

    UT_Lock myLock;
    UT_Lock *getLock() { return myEnableLocking ? &myLock : nullptr; }
    bool myEnableLocking;
    bool myHasTopology;

    UT_Array<std::pair<GA_Offset, fpreal>> mySortedFrameOffsets;

    /// myUsedJoints[frame_idx][joint_idx] represents whether
    /// joint_idx is is present in frame frame_idx
    UT_Array<UT_BitArray> myUsedJoints;

    UT_StringMap<exint> myNameToJointIdx;

    exint myNumJoints;
    exint myNumFrames;

    bool myIsInitialised;
    
    /// If we never evaluate we can skip a bunch of
    /// slow useless computations (updating myEvaluator)
    const bool myCanEvaluate;
};

/// MotionClip object which allows for modifications
///
/// You can add/remove frames by passing an instance of this
/// into GU_MotionBuilder
class GU_API GU_MotionClipRW : public GU_MotionClipRO
{
public:
    friend class GU_MotionClipBuilder;

    GU_MotionClipRW(
            GU_Detail *gdp,
            UT_WorkBuffer &err_msg,
            bool can_evaluate = true,
            GU_MotionClipInfo *clipinfo = nullptr,
            bool compute_default_clipinfo = false,
            bool do_sort_samples = true,
            bool enable_locking = true);

    ~GU_MotionClipRW() override = default;

    bool updateGdp(const GU_Detail *gdp) override { return false; }
    bool updateGdpNC(GU_Detail *gdp) { return GU_MotionClipRO::updateGdp(gdp); }

    /// Sets the topology to the sample geometry,
    /// marking the packed primitive with the given time attribute
    ///
    /// If there is already an existing topology sample must
    /// contain only the same joints.
    ///
    /// The topology must be set before attempting to add frames
    ///
    /// returns false on error
    bool setTopology(fpreal time, const GU_Detail *sample,
                     UT_WorkBuffer &error_msg);

    /// This will add a clipinfo detail attribute based on the primitive times
    void addClipInfo(); 

private:
    SYS_FORCE_INLINE GU_Detail *gdp()
    {
        // the const cast should be safe because an instance of
        // GU_MotionClipRW can only be created with a non-const gdp
        return SYSconst_cast(ourGdp);
    }

};

/// Used to make a batch of modifications to a motion clip.
///
/// It will store the changes in the clip object and then flush
/// them to the clip's evaluator when it is destroyed
///
/// Each call to add/removeSample will update the clip's GDP, etc
/// but the evaluator's internal data structures will not
/// be updated until the flush - so we can safely keep evaluating the
/// the clip which we are adding frames, but the new frames will not
/// be reflected in the evaluated animation until this object is destroyed
///
/// Note that the evaluator will not be able to unpack attributes until
/// this is destructed
class GU_API GU_MotionClipBuilder
{
public:
    /// @pre Clip must outlive this instance
    ///
    GU_MotionClipBuilder(GU_MotionClipRW *clip)
        : myClip(clip) {}

    /// This will update clip to store the new samples
    ///
    ~GU_MotionClipBuilder();

    /// Adds a sample/keyframe into the clip at the given time
    ///
    /// If the a sample at the given time exists it will be replaced
    /// returns false on error
    ///
    /// @pre Each point's name attrib must correspond to one
    ///      of the topology's joint names
    /// @pre Sample must either provide a localtransform attribute
    ///      or have the same topology as our class so we can compute it
    bool addSample(fpreal time, const GU_Detail *sample,
                   UT_WorkBuffer &error_msg,
                   GA_AttributeFilter extra_attribs,
                   const GA_PointGroup *pts = nullptr,
                   bool recompute_local = false,
                   bool is_key_pose = false,
                   const UT_StringHolder key_pose_attrib="");

    /// Removes all samples within a given inclusive time range.
    /// Returns false on error
    bool removeSamples(UT_Vector2R range, UT_WorkBuffer &error_msg);

    /// Removes the sample at time
    ///
    /// returns false on error/missing sample
    bool removeSample(fpreal time, UT_WorkBuffer &error_msg);

private:
    GU_MotionClipRW *myClip;
};

#endif