GU_MotionClipUtil.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_MotionClipUtil.h (GU Library, C++)
 *
 * COMMENTS:    Utility methods for working with motion clips
 */

#ifndef __GU_MOTIONCLIPUTIL_H_INCLUDED__
#define __GU_MOTIONCLIPUTIL_H_INCLUDED__

#include "GU_API.h"

#include <CH/CH_Manager.h>

#include <GA/GA_Types.h>

#include <UT/UT_Assert.h>
#include <UT/UT_Options.h>
#include <UT/UT_Vector2.h>

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

class GEO_Detail;
class GU_Detail;

enum class GU_MotionClipEndBehavior
{
    Clamp = 0,
    Loop = 1,
    Mirror = 2
};

/// Returns true if target_rate needs interpolation into source_rate
inline bool
GUsampleRatesNeedInterpolation(fpreal target_rate, fpreal source_rate)
{
    // No interpolation needed if rates match
    // NOTE: Use high tolerance here because we're comparing FPS values
    if (SYSisEqual(target_rate, source_rate, 1e-2))
        return false;

    // Needs interpolation when target_rate is faster because source has less
    // samples.
    if (target_rate > source_rate)
        return true;

    // When source_rate is faster, then only needs to interpolate if it doesn't
    // divide evenly.
    return !SYSequalZero(SYSfmod(source_rate, target_rate));
}

/// Mapper class for conversion between clip and scene time (in seconds)
class GU_API GU_MotionClipTimeMap
{
public:

    /// Reset to the default scene's global range, unclamped.
    void            reset()                 { *this = GU_MotionClipTimeMap{}; }

    /// Start time in clip seconds
    /// @{
    fpreal          start() const
                        { return myStart; }
    void            setStart(fpreal v, bool clamp = true)
                        { myStart = v; myClampStart = clamp; }
    /// This variant will first clamp v to existing parameters
    void            setClampedStart(fpreal v, bool clamp = true)
                        { myStart = clampClipSeconds(v); myClampStart = clamp; }
    /// @}

    /// End time to clamp to in clip seconds
    /// @{
    fpreal          end() const
                        { return myEnd; }
    void            setEnd(fpreal v, bool clamp = true)
                        { myEnd = v; myClampEnd = clamp; }
    /// This variant will first clamp v to existing parameters
    void            setClampedEnd(fpreal v, bool clamp = true)
                        { myEnd = clampClipSeconds(v); myClampEnd = clamp; }
    /// @}

    /// Trim the current range to the given (assumes we have valid range)
    void            trimRange(fpreal start, fpreal end);

    /// Returns true when we have both start/end and start > end
    bool            hasInvalidRange() const     { return (myStart > myEnd); }

    /// Playback start time in scene seconds
    /// @{
    fpreal          playbackStart() const       { return myPlaybackStart; }
    void            setPlaybackStart(fpreal v)  { myPlaybackStart = v; }
    /// @}

    /// Speed at which to playback in the scene
    /// @{
    fpreal          speed() const               { return mySpeed; }
    void            setSpeed(fpreal v)          { mySpeed = v; }
    /// @}

    /// Convert from clip time to scene time
    fpreal          toSceneSeconds(fpreal clip_seconds) const;

    /// Convert from scene time to clip time
    fpreal          toClipSeconds(fpreal scene_seconds) const;

    /// Clamp clip time depending to available clip range
    fpreal          clampClipSeconds(fpreal clip_seconds) const;

private:
    /// clip time origin in seconds
    fpreal          myStart = CHgetManager()->getGlobalStart();

    /// max clip time in seconds
    fpreal          myEnd = CHgetManager()->getGlobalEnd();

    /// scene time origin in seconds
    fpreal          myPlaybackStart = CHgetManager()->getGlobalStart();

    /// scene playback speed
    fpreal          mySpeed = 1.0;

    bool            myClampStart = false;   /// clamp to start time?
    bool            myClampEnd = false;     /// clamp to end time?
};

class GU_API GU_MotionClipInfo
{
public:
                        GU_MotionClipInfo() = default;

    /// Reset to default constructed state
    void                reset()                 { *this = GU_MotionClipInfo{}; }

    /// Initialize from given ClipTimeMap, filling in missing information
    /// from CHgetManager() as required.
    void                initFromTimeMap(
                            const GU_MotionClipTimeMap& time_map,
                            fpreal source_rate);

    /// Load values from geometry
    bool                load(const GEO_Detail& geo);

    /// Save values to geometry
    bool                save(GEO_Detail& geo);

    /// Get name of clipinfo detail attribute
    static UT_StringHolder attribName();

    /// Source clip range in seconds
    /// @{
    const UT_Vector2R&  sourceRange() const     { return mySourceRange; }
    void                setSourceRange(fpreal start, fpreal end)
                            { mySourceRange = UT_Vector2R{start, end}; }
    /// @}

    /// Source clip rate in frames per second
    /// @{
    fpreal              sourceRate() const      { return mySourceRate; }
    void                setSourceRate(fpreal rate)
                            { mySourceRate = rate; }
    /// @}

    /// Scene clip range in seconds
    /// @{
    UT_Vector2R&        range()                 { return myRange; }
    const UT_Vector2R&  range() const           { return myRange; }
    void                setRange(fpreal start, fpreal end)
                            { myRange = UT_Vector2R{start, end}; }
    /// @}

    /// Scene rate in frames per second
    /// @{
    fpreal              rate() const            { return myRate; }
    void                setRate(fpreal rate)    { myRate = rate; }
    /// @}

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

    /// SOP path used to create the clip.
    /// @{
    const UT_StringHolder &sopPath() const         { return mySopPath; }
    void                setSopPath(const UT_StringHolder &path);
    /// @}

    /// The end behavior should the clip be evaluate after the last frame 
    /// @{
    UT_StringHolder     rightEndBehavior() const             
                        { return myRightEndBehavior; }
    GU_MotionClipEndBehavior rightEndBehaviorEnum() const;

    void                setRightEndBehavior(const UT_StringHolder &behavior);
    void                setRightEndBehavior(const GU_MotionClipEndBehavior &behavior);
    /// @}
    /// @}

    /// The end behavior should the clip be evaluated before the first frame 
    /// @{
    UT_StringHolder     leftEndBehavior() const             
                        { return myLeftEndBehavior; }
    GU_MotionClipEndBehavior leftEndBehaviorEnum() const;

    void                setLeftEndBehavior(const UT_StringHolder &behavior);
    void                setLeftEndBehavior(const GU_MotionClipEndBehavior &behavior);
    /// @}
    /// @}
    /// @}

    bool operator==(const GU_MotionClipInfo& other) const
    {
        return mySourceRange == other.mySourceRange
               && mySourceRate == other.mySourceRate
               && myRange == other.myRange
               && myRate == other.myRate
               && myName == other.myName
               && mySopPathUsed == other.mySopPathUsed
               && mySopPath == other.mySopPath
               && myRightEndBehaviorUsed == other.myRightEndBehaviorUsed
               && myRightEndBehavior == other.myRightEndBehavior
               && myLeftEndBehaviorUsed == other.myLeftEndBehaviorUsed
               && myLeftEndBehavior == other.myLeftEndBehavior;
    }

    bool operator!=(const GU_MotionClipInfo& other) const
    {
        return (!operator==(other));
    }

private: 
    GU_MotionClipEndBehavior getEndBehaviorFromString(const UT_StringHolder &behavior) const;
    UT_StringHolder          getStringFromEndBehavior(
                                const GU_MotionClipEndBehavior &behavior) const;
    
    UT_Vector2R         mySourceRange{0,0};     // source range in secs
    fpreal              mySourceRate{0.0};      // source sampling rate
    UT_Vector2R         myRange{0,0};           // anim range in seconds
    fpreal              myRate{0.0};            // anim sampling rate
    UT_StringHolder     myName;                 // anim clip name
    UT_StringHolder     mySopPath;              // anim clip path
    bool                mySopPathUsed{false};

    // right end behavior
    bool myRightEndBehaviorUsed{false};
    UT_StringHolder    myRightEndBehavior{""};
    
    // left end behavior
    bool myLeftEndBehaviorUsed{false};
    UT_StringHolder    myLeftEndBehavior{""};

    // Keep a copy of the dict when calling gpd.load()
    UT_OptionsHolder    myOptionsHolder; 
};

/// Map between channel names and the attributes that the channel values are
/// stored in.
class GU_API GU_MotionClipChannelMap
{
public:
    /// Returns whether there are any channels in the map.
    bool isEmpty() const { return myOptions.isEmpty(); }

    /// Load the channel map from a detail attribute.
    bool load(const GU_Detail& detail);

    /// Save the channel map as a detail attribute.
    bool save(GU_Detail& detail) const;

    /// Returns a sorted list of the channel names.
    UT_StringArray channelNames() const;

    /// Returns the channel's value, using the attribute specified in the map.
    fpreal getChannelValue(
            const GU_Detail& detail,
            const UT_StringHolder& channel_name) const;

    /// Add a channel where the value is provided by a detail attribute.
    void addDetailAttrib(
            const UT_StringHolder& channel_name,
            const UT_StringHolder& attrib_name);

    /// Add a channel where the value is provided by a point attribute's value
    /// for a specific joint.
    void addPointAttrib(
            const UT_StringHolder& attrib_name,
            const UT_StringHolder& joint_name);

private:
    UT_OptionsHolder myOptions;
};

// Keeps track of and compares the data ids of details that are important for
// the evaluation of motion clips.
class GU_API GU_MotionClipDataIds
{
public:
    GU_MotionClipDataIds(const GU_Detail *gdp);
    ~GU_MotionClipDataIds() {}

    bool update(const GU_Detail *gdp, bool &did_change);

private:
    GA_DataId myPrimitivesId;
    GA_DataId myTopologyId;
    GA_DataId myTimeAttribId;
    GA_DataId myClipInfoAttribId;
};

namespace GU_MotionClipNames
{
    /// Attribute storing the channel name that provides the shape's weight.
    extern GU_API const UT_StringHolder blendshape_channel;
    /// Attribute storing the unique name of the blendshape input.
    extern GU_API const UT_StringHolder blendshape_name;
    /// Attribute storing the name of a blendshape inbetween
    extern GU_API const UT_StringHolder blendshape_inbetween_name;
    /// Attribute storing the weight position of a blendshape inbetween
    extern GU_API const UT_StringHolder blendshape_inbetween_weight;
}

///////////////////////////////////////////////////////////////////////////////
//
// Inline Implementations
//

inline void
GU_MotionClipTimeMap::trimRange(fpreal start, fpreal end)
{
    if (myStart < start)
        myStart = start;
    if (myEnd > end)
        myEnd = end;
}

inline fpreal
GU_MotionClipTimeMap::clampClipSeconds(fpreal clip_seconds) const
{
    UT_ASSERT(!hasInvalidRange());
    if (myClampStart && clip_seconds < myStart)
        clip_seconds = myStart;
    else if (myClampEnd && clip_seconds > myEnd)
        clip_seconds = myEnd;
    return clip_seconds;
}

inline fpreal
GU_MotionClipTimeMap::toSceneSeconds(fpreal clip_seconds) const
{
    fpreal t = clampClipSeconds(clip_seconds);
    return SYSsafediv(t - myStart, mySpeed) + myPlaybackStart;
}

inline fpreal
GU_MotionClipTimeMap::toClipSeconds(fpreal scene_seconds) const
{
    fpreal t = (scene_seconds - myPlaybackStart)*mySpeed;
    return clampClipSeconds(t + myStart);
}

#endif // __GU_MOTIONCLIPUTIL_H_INCLUDED__