GU_AgentClip.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_AgentClip.h (GU Library, C++)
 *
 * COMMENTS:
 */

#ifndef __GU_AgentClip__
#define __GU_AgentClip__

#include "GU_API.h"

#include "GU_AgentRig.h"
#include "GU_AgentXform.h"

#include <UT/UT_Array.h>
#include <UT/UT_Assert.h>
#include <UT/UT_IntrusivePtr.h>
#include <UT/UT_Lock.h>
#include <UT/UT_Matrix3.h>
#include <UT/UT_Matrix4.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringMap.h>
#include <UT/UT_ValArray.h>
#include <UT/UT_VectorTypes.h>
#include <SYS/SYS_Inline.h>
#include <SYS/SYS_Math.h>
#include <SYS/SYS_Types.h>

class CL_Clip;
class GU_AgentTransformGroup;
class UT_BitArray;
class UT_StringArray;

class GU_AgentClip;
typedef UT_IntrusivePtr<GU_AgentClip>   GU_AgentClipPtr;
typedef UT_IntrusivePtr<const GU_AgentClip> GU_AgentClipConstPtr;
typedef UT_Array<GU_AgentClipConstPtr>  GU_AgentClipPtrArray;

/// An agent motion clip
///
/// It is represented as array of samples, where each sample has
/// transformsPerSample() number of transforms. These transforms can be "local"
/// (corresponding to the transform hierarchy of rig()), or "world" where they
/// are multiplied all the way up to a root node in the rig.
class GU_API GU_AgentClip : public UT_IntrusiveRefCounter<GU_AgentClip>
{
public:

    typedef fpreal32                                FloatType;
    typedef UT_Array<FloatType>                     FloatArray;
    typedef UT_SharedPtr<FloatArray>                FloatArrayPtr;
    typedef GU_AgentXformT<FloatType>               Xform;
    typedef UT_Array<Xform>                         XformArray;
    typedef UT_Matrix4T<FloatType>                  Matrix4;
    typedef UT_Array<Matrix4>                       Matrix4Array;
    typedef UT_SharedPtr<Matrix4Array>              Matrix4ArrayPtr;
    typedef UT_SharedPtr<const Matrix4Array>        Matrix4ArrayConstPtr;

    /// Create an empty clip
    static GU_AgentClipPtr      addClip(
                                    const UT_StringHolder &name,
                                    const GU_AgentRigConstPtr &rig);

    /// Create a clip by loading a clip file from disk.
    static GU_AgentClipPtr      addClipFromFile(
                                    const UT_StringHolder &name,
                                    const UT_StringHolder &filename,
                                    const GU_AgentRigConstPtr& rig,
                                    bool delay_load,
                                    UT_StringArray& errors);

    /// Create a clone of a clip, referencing the specified rig.
    /// 'copy_external_ref' should be disabled if the new clip will be
    /// further modified.
    static GU_AgentClipPtr      addClipCopy(const GU_AgentClip &src,
                                    const GU_AgentRigConstPtr &rig,
                                    bool copy_external_ref);

    /// Compute the world transforms 'matrices' from the local 'xforms'
    /// corresponding to the transforms in 'rig'.
    static void                 computeWorldTransforms(
                                    const GU_AgentRig& rig,
                                    const XformArray& xforms,
                                    Matrix4Array& matrices);

    /// Compute the local transforms 'matrices' from the local 'xforms'
    /// corresponding to the transforms in 'rig'.
    static void                 computeLocalTransforms(
                                    const GU_AgentRig& rig,
                                    const XformArray& xforms,
                                    Matrix4Array& matrices);

    /// Given the local transforms 'xforms' corresponding to 'rig', convert
    /// them to world transforms in-place.
    /// The optional 'in_world_space' array can be used to specify if some
    /// transforms in 'xforms' are already in world space.
    static void                 computeWorldTransforms(
                                    const GU_AgentRig& rig,
                                    const UT_BitArray *in_world_space,
                                    Matrix4Array& xforms);

    /// Given the world transforms 'xforms' corresponding to 'rig', convert
    /// them to local transforms in-place.
    /// The optional 'in_world_space' array can be used to specify if only some
    /// transforms in 'xforms' are currently in world space.
    static void                 computeLocalTransforms(
                                    const GU_AgentRig& rig,
                                    const UT_BitArray *in_world_space,
                                    Matrix4Array& xforms);

    /// Replaces whitespace, special characters, etc with underscores.
    SYS_NO_DISCARD_RESULT static UT_StringHolder forceValidName(
                                    const UT_StringHolder &clipname);

private:
                                GU_AgentClip(const UT_StringHolder &name,
                                             const UT_StringHolder &filename,
                                             const GU_AgentRigConstPtr &rig)
                                    : myName(name)
                                    , myFileName(filename)
                                    , myIsFile(filename.isstring())
                                    , myIsLoaded(!filename.isstring())
                                    , myHasLoadErrors(false)
                                    , myNumXformTracks(0)
                                    , myRig(rig)
                                    , myStart(0)
                                    , mySampleRate(24.0)
                                 {
                                 }

public:

                                ~GU_AgentClip();

    int64                       getMemoryUsage(bool inclusive) const;

    /// Set this clip to have the specified number of samples, filled with
    /// the rest transforms.
    ///
    /// @pre num_samples must be larger than 0.
    void                        init(exint num_samples);

    /// Load from clip.
    void                        load(const CL_Clip &clip);

    /// Copy from another agent clip, and inherit the external reference if
    /// there is one. If the rigs are different, the rig's rest transforms will
    /// be used for the additional joints.
    void                        load(const GU_AgentClip &clip);

    /// Return the number of transform tracks of the clip that was loaded into
    /// this clip.
    // This is currently only used for consistency checks.
    int                         numTransformTracks() const
                                    { ensureLoaded(); return myNumXformTracks; }

    /// Save to clip
    void                        save(CL_Clip &clip,
                                     bool worldspace = false) const;

    /// Name of the clip.
    /// @{
    const UT_StringHolder&      name() const
                                    { return myName; }
    void                        setName(const UT_StringHolder &name)
                                    { myName = name; }
    /// @}

    /// Returns whether the clip references a file on disk.
    bool                        isFile() const
                                    { return myIsFile; }
    /// Returns the name of the file referenced by the clip.
    const UT_StringHolder&      fileName() const
                                    { UT_ASSERT(isFile()); return myFileName; }
    /// Clears the external file reference. The clip's contents will also be
    /// loaded from disk if necessary.
    void                        clearIsFile();

    /// Returns whether the clip's contents have been loaded from disk.
    bool                        isLoaded() const
                                    { UT_ASSERT(isFile()); return myIsLoaded; }
    /// Returns whether there were errors when loading the clip from disk.
    bool                        hasLoadErrors() const
                                    { return myHasLoadErrors; }
    /// Explicitly loads the clip from disk.
    bool                        loadFromFile(
                                    UT_StringArray *errors = nullptr) const;

    const GU_AgentRig&          rig() const
                                    { return *myRig; }

    /// Number of transforms in each sample
    exint                       transformsPerSample() const
                                {
                                    ensureLoaded();
                                    if (myLocalTransforms.entries() < 1)
                                        return 0;
                                    return myLocalTransforms(0).entries();
                                }

    /// Number of samples in this clip
    exint                       sampleCount() const
                                {
                                    ensureLoaded();
                                    return myLocalTransforms.entries();
                                }

    /// Start time of this clip in seconds
    /// @{
    fpreal                      start() const
                                    { ensureLoaded(); return myStart; }
    void                        setStart(fpreal t)
                                    { ensureLoaded(); myStart = t; }
    /// @}

    /// Length of the clip, in seconds.
    fpreal                      length() const
                                {
                                    return sampleCount() / sampleRate();
                                }

    /// Sample rate of this clip
    /// @{
    fpreal                      sampleRate() const
                                    { ensureLoaded(); return mySampleRate; }
    void                        setSampleRate(fpreal sample_rate)
                                {
                                    ensureLoaded();
                                    mySampleRate = sample_rate;
                                }
    /// @}

    /// Directly set the local transforms for this clip (as an alternative to
    /// using GU_AgentClip::load()).
    ///
    /// @param samples An array of local transform samples 
    ///
    /// @pre samples (and each sample within) must be at least length 1
    /// @pre Each entry in samples must be the same length
    /// @post sampleCount() == samples.entries()
    /// @post transformsPerSample() == samples.last().entries()
    void                        setLocalTransforms(
                                    const UT_Array<XformArray> &samples);

    /// Edit the transforms for a specific sample in the clip.
    void                        setLocalTransforms(exint sample_i,
                                                   const XformArray &xforms);

    const XformArray&           localTransforms(exint sample_i) const
                                {
                                    ensureLoaded();
                                    return myLocalTransforms(sample_i);
                                }
    Matrix4ArrayConstPtr        worldTransforms(exint sample_i) const
                                {
                                    ensureLoaded();
                                    return myWorldTransforms(sample_i);
                                }
    const FloatArray&           channelValues(exint sample_i) const
                                {
                                    ensureLoaded();
                                    return *myChannelValueSamples[sample_i];
                                }

    /// Samples a transform in the clip at a specific time.
    void                        sampleTransform(exint i, fpreal seconds,
                                                bool worldspace,
                                                Matrix4 &xform_sample) const;

    /// Add an extra channel into the clip (as an alternative to
    /// GU_AgentClip::load()).
    /// If a channel with the same name already exists, its data is replaced
    /// with the new samples.
    ///
    /// @param name Unique name of the channel.
    /// @param samples Float array with length sampleCount().
    void                        addChannel(const UT_StringHolder &name,
                                           const FloatType *samples);

    /// Finds a channel by name. Returns -1 if the channel does not exist.
    exint                       findChannel(const UT_StringRef &name) const;
    /// Samples a channel in the clip at a specific time.
    /// The channel indices from GU_AgentRig are valid indices for the clip's
    /// channels.
    /// For transforms, use GU_AgentClip::sampleTransform().
    FloatType                   sampleChannel(exint channel_index,
                                              fpreal seconds) const;
    /// Returns the number of non-transform channels in the clip. This value
    /// will be >= GU_AgentRig::channelCount().
    exint                       channelCount() const;
    /// Returns the name of the specified channel.
    const UT_StringHolder      &channelName(exint i) const;
    /// Builds a list of all channel names in the clip (channels defined by
    /// GU_AgentRig, plus any spare channels).
    UT_StringArray              channelNames() const;

    /// Add a scaled version of our local transforms using the given clip time.
    /// If the time in seconds exceeds the length of our clip, then it is
    /// wrapped around.
    void                        addScaledLocalTransforms(
                                    XformArray& dst,
                                    fpreal scale,
                                    fpreal seconds) const;
    /// Variant of addScaledLocalTransforms that only affects a subset of the
    /// joints.
    ///
    /// @param inv_total_weight Inverse of the total blend weight at each joint.
    void                        addScaledLocalTransforms(
                                    XformArray &dst,
                                    const UT_BitArray &joints,
                                    fpreal scale,
                                    const UT_Array<fpreal> &inv_total_weights,
                                    fpreal seconds) const;
    /// Perform an additive blend with the specified percentage.
    void                        concatLocalTransforms(
                                    XformArray &dst,
                                    const GU_AgentTransformGroup &xform_grp,
                                    fpreal percent,
                                    fpreal seconds) const;
    void                        addScaledLocalTransform(
                                    Xform& xform,
                                    exint i,
                                    fpreal scale,
                                    fpreal seconds) const;

    /// Adds a scaled version of the channel values given a clip time. Only the
    /// channels defined on GU_AgentRig are included.
    void                        addScaledChannelValues(
                                    FloatArray &dst,
                                    const UT_BitArray &channels,
                                    fpreal scale,
                                    const UT_Array<fpreal> &inv_total_weights,
                                    fpreal seconds) const;

    inline fpreal               sampleFromSeconds(fpreal seconds) const
                                {
                                    ensureLoaded();
                                    return (seconds - myStart) * mySampleRate;
                                }
    inline fpreal               secondsFromSample(fpreal sample) const
                                {
                                    ensureLoaded();
                                    return myStart + (sample / mySampleRate);
                                }
    inline exint                nearestSampleFromSeconds(fpreal seconds) const
                                {
                                    return (exint)
                                        SYSrint(sampleFromSeconds(seconds));
                                }
    inline fpreal               wrappedSampleFromSeconds(fpreal seconds) const
                                {
                                    fpreal len = sampleCount();
                                    fpreal s = SYSfmod(
                                                sampleFromSeconds(seconds),
                                                len);
                                    if (s >= 0)
                                        return s;
                                    else
                                        return s + len;
                                }

private:
    /// Called before any clip data is accessed to ensure that the clip has
    /// been loaded from disk.
    SYS_FORCE_INLINE void       ensureLoaded() const
                                {
                                    if (!myIsLoaded)
                                        loadFromFile();
                                }

    /// Removes the clip from the agent clip file cache.
    void                        removeFromFileCache();

    /// Given a sample time in seconds, find the two samples that we need to
    /// interpolate between.
    void                        getSamples(fpreal scale, fpreal seconds,
                                           exint& sample_a, fpreal& weight_a,
                                           exint& sample_b, fpreal& weight_b) const;

    /// Initialize myChannelValueSamples with the channels defined on
    /// GU_AgentRig.
    void                        initChannels(exint num_samples);

    /// Build myWorldTransforms from myLocalTransforms.
    void                        computeWorldSpaceSamples();

    UT_StringHolder             myName;
    UT_StringHolder             myFileName;
    bool                        myIsFile;
    /// Tracks whether the clip's contents have been loaded from disk.
    bool                        myIsLoaded;
    /// Records whether there were any errors when the clip was delay-loaded.
    bool                        myHasLoadErrors;
    int                         myNumXformTracks; // put here for the same ABI 
    GU_AgentRigConstPtr         myRig;
    fpreal                      myStart;
    fpreal                      mySampleRate;

    /// The local transforms for the rig, at each sample.
    UT_Array<XformArray>        myLocalTransforms;
    /// The world transforms for the rig, at each sample.
    UT_Array<Matrix4ArrayPtr>   myWorldTransforms;

    /// The (non-transform) channel values in the clip, at each sample.
    /// Channels are ordered beginning with the channels defined on
    /// GU_AgentRig.
    UT_Array<FloatArrayPtr>     myChannelValueSamples;
    /// List of spare channels not defined on GU_AgentRig. These are stored at
    /// the end of myChannelValueSamples[i].
    UT_StringArray              mySpareChannelNames;
    /// Index into myChannelValueSamples[i] for each channel in
    /// mySpareChannelNames.
    UT_StringMap<int>           mySpareChannelIndex;

    /// Lock for delayed loading of the clip data.
    mutable UT_Lock             myDelayLoadLock;
};

inline exint
GU_AgentClip::findChannel(const UT_StringRef &name) const
{
    ensureLoaded();

    // First, see if this channel is defined on the rig.
    exint i = myRig->findChannel(name);
    if (i >= 0)
        return i;

    // Otherwise, it would need to be a spare channel.
    auto it = mySpareChannelIndex.find(name);
    return it != mySpareChannelIndex.end() ? it->second : -1;
}

inline const UT_StringHolder &
GU_AgentClip::channelName(exint i) const
{
    ensureLoaded();

    // Grab the channel name from the rig, unless it is a spare channel.
    if (i < myRig->channelCount())
        return myRig->channelName(i);
    else
        return mySpareChannelNames[i - myRig->channelCount()];
}

inline exint
GU_AgentClip::channelCount() const
{
    ensureLoaded();
    return myRig->channelCount() + mySpareChannelNames.entries();
}

inline UT_StringHolder
GU_AgentClip::forceValidName(const UT_StringHolder &clipname)
{
    return clipname.forceValidVariableName(".-");
}

#endif