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

#ifndef __GU_Agent__
#define __GU_Agent__

#include "GU_API.h"
#include "GU_AgentClip.h"
#include "GU_AgentDefinition.h"
#include "GU_PackedImpl.h"

#include <GA/GA_PrimitiveTypeId.h>

#include <UT/UT_Array.h>
#include <UT/UT_BitArray.h>
#include <UT/UT_Map.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_SmallArray.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_TBBSpinLock.h>
#include <UT/UT_VectorTypes.h>
#include <SYS/SYS_Types.h>


#define GU_AGENT_LAYER_DEFAULT      "default"
#define GU_AGENT_LAYER_COLLISION    "collision"


class UT_Options;


/// A packed agent
///
/// The agent is composed of multiple named layers.  Each layer consists of
/// zero or more shapes.
///
/// All agents must have a default layer.  This is the layer used when a
/// specific layer isn't found.  Example layers might be: "default", "low-res",
/// "medium-res", "high-quality", "collision".
///
/// The packed agent conforms to the GU_PackedImpl API, but also provides
/// access to the layers/shapes.
class GU_API GU_Agent : public GU_PackedImpl
{
public:
    typedef UT_StringHolder                     StringType;
    typedef fpreal32                            FloatType;
    typedef UT_Array<FloatType>                 FloatArray;
    typedef UT_SharedPtr<FloatArray>            FloatArrayPtr;
    typedef UT_SharedPtr<const FloatArray>      FloatArrayConstPtr;
    typedef UT_Matrix4T<FloatType>              Matrix4Type;
    typedef UT_Array<Matrix4Type>               Matrix4Array;
    typedef UT_SharedPtr<Matrix4Array>          Matrix4ArrayPtr;
    typedef UT_SharedPtr<const Matrix4Array>    Matrix4ArrayConstPtr;

    enum BlendMode
    {
        BLEND_INTERPOLATE,
        BLEND_ADDITIVE,
        NUM_BLEND_MODES
    };

    struct ClipLayer
    {
        ClipLayer(BlendMode blend_mode, fpreal64 weight = 0.0,
                  int64 parent = -1)
            : myBlendMode(blend_mode), myWeight(weight), myParent(parent)
        {
        }

        BlendMode myBlendMode;
        fpreal64 myWeight;
        int64 myParent;
    };

    /// State of the primitive
    struct GU_API State
    {
        int64 getMemoryUsage(bool inclusive) const;
        void clear();

        GU_AgentClipPtrArray myClips;
        UT_Fpreal64Array myClipTimes;
        UT_Fpreal64Array myClipWeights;
        GU_AgentTransformGroupArray myClipXformGroups;
        UT_Int64Array myClipLayerIds;

        UT_Array<ClipLayer> myClipLayers;
    };

    GU_Agent();
    GU_Agent(const GU_Agent &src);
    ~GU_Agent() override;

    /// Register the packed primitive type
    static void                  install(GA_PrimitiveFactory *pfact);

    /// Get the type ID for the GU_Agent primitive type.
    static GA_PrimitiveTypeId typeId()
    {
        return theTypeId;
    }

    /// Convenience method to create a packed agent primitive
    static GU_PrimPacked        *agent(GU_Detail &dest,
                                       GA_Offset ptoff = GA_INVALID_OFFSET);


    static bool                  hasAgentPackedPrimitives(
                                        const GU_Detail &gdp);

    /// @{
    /// API defined on GU_PackedImpl
    GU_PackedFactory    *getFactory() const override;
    GU_Agent            *copy() const override;
    bool                 isValid() const override;
    void                 clearData() override;

    bool                supportsJSONLoad() const override
                            { return true; }
    bool                load(GU_PrimPacked *prim,
                             const UT_Options &options,
                             const GA_LoadMap &map) override
                            { return loadFrom(prim, options, map); }
    bool                loadFromJSON(
                                GU_PrimPacked *prim,
                                const UT_JSONValueMap &options,
                                const GA_LoadMap &map) override
                            { return loadFrom(prim, options, map); }

    void                 update(GU_PrimPacked *prim,
                                const UT_Options &options) override
                            { updateFrom(prim, options); }
    bool                 saveSharedData(
                                UT_JSONWriter &w,
                                GA_SaveMap &map,
                                GA_GeometryIndex *geo_index) const override;
    bool                 loadSharedData(int load_data_type,
                                const GA_SharedLoadData *item) override;
    bool                 save(UT_Options &options,
                                const GA_SaveMap &map) const override;
    bool                 getBounds(UT_BoundingBox &box) const override;
    bool                 getRenderingBounds(UT_BoundingBox &box) const override;
    void                 getVelocityRange(
                                UT_Vector3 &vmin,
                                UT_Vector3 &vmax) const override;
    void                 getWidthRange(
                                fpreal &wmin,
                                fpreal &wmax) const override;

    UT_Optional<exint>   getNumPackedPrims(const GU_PrimPacked *prim) const;

    bool                 unpack(GU_Detail &destgdp,
                                const UT_Matrix4D *transform) const override;
    bool                 unpackWithStyler(
                                GU_Detail &destgdp,
                                STY_StylerGroup &prim_styler_group,
                                const STY_Styler &parent_styler,
                                const GU_PrimPacked *prim) const override;
    GU_ConstDetailHandle getPackedDetail(
                                GU_PackedContext *context = 0) const override;

    /// Report memory usage (includes all shared memory)
    int64                getMemoryUsage(bool inclusive) const override;

    /// Count memory usage using a UT_MemoryCounter in order to count
    /// shared memory correctly.
    void                 countMemory(
                                UT_MemoryCounter &counter,
                                bool inclusive) const override;
    /// @}

    /// Return the agent's definition (which contains e.g. available clips and
    /// layers).
    SYS_FORCE_INLINE const GU_AgentDefinition &definition() const
    {
        loadDefinitionIfNeeded();
        return *myDefinition;
    }

    void setDefinition(GU_PrimPacked *prim,
                       const GU_AgentDefinitionConstPtr &definition);

    /// Rig Accessor
    /// @{
    const GU_AgentRigConstPtr &getRig() const { return definition().rig(); }
    /// @}

    /// Return the list of the agent's current layers.
    const UT_Array<GU_AgentLayerConstPtr> &getCurrentLayers() const;
    /// Sets the agent's display layers.
    void setCurrentLayers(GU_PrimPacked *prim,
                          const UT_Array<GU_AgentLayerConstPtr> &layers);

    /// Return the current layer. This may be a NULL pointer.
    SYS_DEPRECATED_HDK_REPLACE(19.0, getCurrentLayers)
    const GU_AgentLayer *getCurrentLayer() const;
    /// Sets the agent's display layer.
    SYS_DEPRECATED_HDK_REPLACE(19.0, setCurrentLayers)
    void setCurrentLayer(GU_PrimPacked *prim,
                         const GU_AgentLayerConstPtr &layer);

    /// Return the list of the agent's collision layers.
    const UT_Array<GU_AgentLayerConstPtr> &getCollisionLayers() const;
    /// Sets the agent's collision layers.
    void setCollisionLayers(GU_PrimPacked *prim,
                            const UT_Array<GU_AgentLayerConstPtr> &layers);

    /// Return the current collision layer. This may be a NULL pointer.
    SYS_DEPRECATED_HDK_REPLACE(19.0, getCollisionLayers)
    const GU_AgentLayer *getCollisionLayer() const;
    /// Sets the agent's collision layer.
    SYS_DEPRECATED_HDK_REPLACE(19.0, setCollisionLayers)
    void setCollisionLayer(GU_PrimPacked *prim,
                           const GU_AgentLayerConstPtr &layer);

    /// @{
    /// Display layer accesssors for intrinsics.
    exint intrinsicNumCurrentLayers(const GU_PrimPacked *prim) const;
    void intrinsicCurrentLayerNames(const GU_PrimPacked *prim, UT_StringArray &names) const;
    void intrinsicSetCurrentLayerNames(GU_PrimPacked *prim, const UT_StringArray &names);
    /// @}

    /// @{
    /// Collision layer accessors for intrinsics.
    exint intrinsicNumCollisionLayers(const GU_PrimPacked *prim) const;
    void intrinsicCollisionLayerNames(const GU_PrimPacked *prim, UT_StringArray &names) const;
    void intrinsicSetCollisionLayerNames(GU_PrimPacked *prim, const UT_StringArray &names);
    /// @}

    /// @{
    /// Deprecated single-layer accessors for intrinsics.
    StringType  intrinsicCurrentLayerName(const GU_PrimPacked *prim) const;
    void        intrinsicSetCurrentLayerByName(GU_PrimPacked *prim, const StringType &name);
    StringType  intrinsicCollisionLayerName(const GU_PrimPacked *prim) const;
    void        intrinsicSetCollisionLayerByName(GU_PrimPacked *prim, const StringType &name);
    /// @}

    /// Array of clips used for transform evaluation
    /// @{
    const GU_AgentClipPtrArray& clips() const;
    void                setClips(GU_PrimPacked *prim, const GU_AgentClipPtrArray& clips);
    void                setClipsByNames(GU_PrimPacked *prim, const UT_StringArray& clip_names);
    /// @}

    /// Return the number of clips used for transform evaluation
    exint               numClips() const
                            { return clips().entries(); }
    exint               intrinsicNumClips(const GU_PrimPacked *prim) const
    { return numClips(); }

    /// Names of the clips used for transform evaluation
    const char*         clipName(exint i) const;
    const char*         intrinsicClipName(const GU_PrimPacked *prim, exint i) const
    { return clipName(i); }

    /// Set a clip by name
    void                setClipByName(GU_PrimPacked *prim, exint i, const char *clip_name);

    /// Array of times in seconds to evaluate the clips.
    /// Indices in [0,numClips()-1] inclusively.
    /// @{
    fpreal              clipTime(exint i) const
                            { return myState.myClipTimes(i); }
    fpreal              intrinsicClipTime(const GU_PrimPacked *prim, exint i) const
    { return clipTime(i); }
    void                setClipTime(GU_PrimPacked *prim, exint i, fpreal seconds);
    /// @}

    /// Array of weights to evaluate the corresponding clips. Assumes they are
    /// normalized.
    /// @{
    fpreal              clipWeight(exint i) const
                            { return myState.myClipWeights(i); }
    fpreal              intrinsicClipWeight(const GU_PrimPacked *prim, exint i) const
    { return clipWeight(i); }
    void                setClipWeight(GU_PrimPacked *prim, exint i, fpreal weight);
    /// @}

    /// The subset of transforms in the rig that each clip should be applied
    /// to.
    /// @{
    const char*         clipTransformGroupName(exint i) const;
    const char*         intrinsicClipTransformGroupName(const GU_PrimPacked *prim, exint i) const
    { return clipTransformGroupName(i); }
    void                setClipTransformGroupByName(GU_PrimPacked *prim, exint i, const char *name);
    void                setClipTransformGroup(GU_PrimPacked *prim, exint i, const GU_AgentTransformGroupConstPtr &grp);
    /// @}

    /// The layer that each clip belongs to.
    /// @{
    exint               clipLayerId(exint i) const
                            { return myState.myClipLayerIds(i); }
    exint               intrinsicClipLayerId(const GU_PrimPacked *prim, exint i) const
    { return clipLayerId(i); }
    void                setClipLayerId(GU_PrimPacked *prim, exint i, exint layer_id);
    /// @}

    /// List of clip layers and their blend modes.
    /// @{
    void                setClipLayers(GU_PrimPacked *prim, const UT_Array<ClipLayer> &clip_layers);
    exint               numClipLayers() const
                            { return myState.myClipLayers.entries(); }
    /// @}

    /// Get the world transforms for this agent. Disabling interpolation can
    /// improve performance if the clip time falls between two samples.
    bool                computeWorldTransforms(Matrix4ArrayConstPtr &xforms,
                                               bool interpolate_samples = true) const
                            { return computeTransforms(xforms,
                                                       /* world_space */ true,
                                                       interpolate_samples); }
    /// Get the local transforms for this agent.
    bool                computeLocalTransforms(Matrix4ArrayConstPtr &xforms,
                                               bool interpolate_samples = true) const
                            { return computeTransforms(xforms,
                                                       /* world_space */ false,
                                                       interpolate_samples); }
    /// Get a specific world transform for the agent.
    bool                computeWorldTransform(Matrix4Type &xform, exint i,
                                              bool interpolate_samples = true) const
                            { return computeWorldTransformInternal(xform, i, interpolate_samples); }
    /// Get a specific local transform for the agent.
    bool                computeLocalTransform(Matrix4Type &xform, exint i,
                                              bool interpolate_samples = true) const
                            { return computeLocalTransformInternal(xform, i, interpolate_samples); }

    /// Override the world transforms for this agent.
    void                setWorldTransforms(const Matrix4Array &xforms)
                            { setTransforms(xforms, /* world_space */ true); }
    /// Override the local transforms for this agent.
    void                setLocalTransforms(const Matrix4Array &xforms)
                            { setTransforms(xforms, /* world_space */ false); }
    /// Override a specific world transform for this agent.
    void                setWorldTransform(const Matrix4Type &xform, exint i);
    /// Override a specific local transform for this agent.
    void                setLocalTransform(const Matrix4Type &xform, exint i);
    /// Returns whether the agent's transforms have been overridden from the
    /// blended clips.
    bool                hasCustomTransforms() const { return myHasCustomXforms; }
    bool                intrinsicHasCustomTransforms(const GU_PrimPacked *) const
                            { return hasCustomTransforms(); }
    /// Number of transforms in the rig.
    exint               transformCount() const
                            { return getRig() ? getRig()->transformCount() : 0; }
    exint               intrinsicTransformCount(const GU_PrimPacked *prim) const
    { return transformCount(); }
    /// Return the name of the given transform.
    const char*         transformName(exint i) const;
    const char*         intrinsicTransformName(const GU_PrimPacked *prim, exint i) const
    { return transformName(i); }

    /// Functions for the 'agentworldtransforms' and 'agentlocaltransforms'
    /// intrinsics to manipulate the transforms as an array of floats.
    exint               transformsArraySize() const;
    exint               intrinsicTransformsArraySize(const GU_PrimPacked *prim) const
    { return transformsArraySize(); }
    void                worldTransformsArray(const GU_PrimPacked *prim, FloatType *data, exint n) const
                            { transformsArray(data, n, /* world_space */ true); }
    void                setWorldTransformsFromArray(GU_PrimPacked *prim, const FloatType *data,
                                                    exint n)
                            { setTransformsFromArray(data, n,
                                                     /* world_space */ true); }
    void                localTransformsArray(const GU_PrimPacked *prim, FloatType *data, exint n) const
                            { transformsArray(data, n,
                                                    /* world_space */ false); }
    void                setLocalTransformsFromArray(GU_PrimPacked *prim, const FloatType *data,
                                                    exint n)
                            { setTransformsFromArray(data, n,
                                                     /* world_space */ false); }

    /// Number of transforms in the rig.
    exint               channelCount() const
                            { return getRig() ? getRig()->channelCount() : 0; }

    /// Computes the agent's channel values from its clips.
    bool                computeChannelValues(FloatArrayConstPtr &values,
                                             bool interpolate_samples = true) const;

    /// Override a specific channel value for this agent.
    void                setChannelValue(FloatType value, exint i);

    /// Returns whether the agent's channel values have been overridden from
    /// the blended clips.
    bool                hasCustomChannelValues() const
                            { return myHasCustomChannelValues; }

    /// Functions for the 'agentchannelnames', 'agentchannelvalues', and
    /// 'agenthascustomchannelvalues' intrinsics.
    /// @{
    exint               intrinsicChannelCount(const GU_PrimPacked *) const
                            { return channelCount(); }
    const StringType&   intrinsicChannelName(const GU_PrimPacked *, exint i) const;
    void                intrinsicChannelValuesArray(const GU_PrimPacked *,
                            FloatType *data, exint n) const;
    void                intrinsicSetChannelValuesFromArray(GU_PrimPacked *,
                            const FloatType *data, exint n);
    bool                intrinsicHasCustomChannelValues(const GU_PrimPacked *) const
                            { return hasCustomChannelValues(); }
    /// @}

    /// Functions for the 'agentrigparents' intrinsic.
    exint               intrinsicParentIndex(const GU_PrimPacked *prim, exint i) const;
    /// Functions for the 'agentlayers' intrinsic.
    exint               intrinsicNumLayers(const GU_PrimPacked *prim) const;
    const char*         intrinsicLayerName(const GU_PrimPacked *prim, exint i) const;

    /// Used by the 'agentcliptimes', 'agentclipnames', and 'agentclipweights'
    /// intrinsics to grow or shrink the number of clips.
    void                intrinsicSetNumClips(GU_PrimPacked *prim, GA_Size n);

    /// Functions for the 'agentclipcatalog' intrinsic.
    exint               intrinsicCatalogNumClips(const GU_PrimPacked *prim) const;
    const char*         intrinsicCatalogClipName(const GU_PrimPacked *prim, exint i) const;
    const char*         intrinsicClipCatalogFilenames(const GU_PrimPacked *prim, exint i) const;

    /// Functions for the 'agentshapelibrary' intrinsic.
    exint               intrinsicNumShapes(const GU_PrimPacked *prim) const;
    void                intrinsicShapeNames(const GU_PrimPacked *prim, UT_StringArray &values) const;

    /// Functions for the 'agenttransformgroups' intrinsic.
    /// @{
    exint               intrinsicNumTransformGroups(const GU_PrimPacked *prim) const;
    const char*         intrinsicTransformGroupName(const GU_PrimPacked *prim, exint i) const;
    /// @}

    /// Functions for the clip layer intrinsics.
    /// @{
    const char*         intrinsicClipLayerMode(const GU_PrimPacked *prim, exint i) const;
    exint               intrinsicClipLayerParent(const GU_PrimPacked *prim, exint i) const;
    fpreal              intrinsicClipLayerWeight(const GU_PrimPacked *prim, exint i) const;
    exint               intrinsicNumClipLayers(const GU_PrimPacked *prim) const
    { return numClipLayers(); }
    /// @}

    /// The 'agentmetadata' intrinsic. See GU_AgentDefinition::metadata().
    UT_OptionsHolder    intrinsicMetadata(const GU_PrimPacked *prim) const;

private:
    GU_Agent&           operator=(const GU_Agent& copy); // DISALLOWED

private:
    void                dirtyBlendedTransforms(GU_PrimPacked *prim);
    void                loadDefinition() const;
    SYS_FORCE_INLINE void loadDefinitionIfNeeded() const
    {
        if (!myDefinition)
            loadDefinition();
    }

    template <typename T>
    bool                loadFrom(GU_PrimPacked *prim, const T &options, const GA_LoadMap &map);
    template <typename T>
    void                updateFrom(GU_PrimPacked *prim, const T &options);

    /// Get the agent's current transforms, in local or world space.
    /// Disabling interpolation can improve performance if the clip time falls
    /// between two samples.
    bool                computeTransforms(Matrix4ArrayConstPtr &matrices,
                                          bool world_space,
                                          bool interpolate_samples = true,
                                          bool acquire_xform_lock = true) const;

    /// Internal version of computeWorldTransform(), which allows controlling
    /// whether myXformLock needs to be acquired.
    bool                computeWorldTransformInternal(Matrix4Type &xform,
                                                      exint i,
                                                      bool interpolate_samples,
                                                      bool acquire_xform_lock = true) const;

    /// Internal version of computeLocalTransform(), which allows controlling
    /// whether myXformLock needs to be acquired.
    bool                computeLocalTransformInternal(Matrix4Type &xform,
                                                      exint i,
                                                      bool interpolate_samples,
                                                      bool acquire_xform_lock = true) const;

    /// Override the current transforms of the agent.
    void                setTransforms(const Matrix4Array &xforms,
                                      bool world_space);
    void                transformsArray(FloatType *buf, exint n,
                                        bool world_space) const;
    void                setTransformsFromArray(const FloatType *data, exint n,
                                               bool world_space);

    /// Resize the clip arrays to n elements.
    void                changeNumClips(GU_PrimPacked *prim, exint n, bool fill_valid_clips = false);

    /// Convert the cached transforms from local to world space (or vice versa).
    void                convertCachedTransforms(bool world_space) const;

    /// Internal method to set a single current / collision layer for the
    /// agent.
    void                setLayer(GU_PrimPacked *prim,
                                 UT_Array<GU_AgentLayerConstPtr> &layers,
                                 const GU_AgentLayerConstPtr &layer);
    /// Internal method to set the current / collision layers for the agent.
    void                setLayers(GU_PrimPacked *prim,
                            UT_Array<GU_AgentLayerConstPtr> &layers,
                            const UT_Array<GU_AgentLayerConstPtr> &new_layers);
    /// Internal method to set the agent's current / collision layers by name,
    /// for use with intrinsics.
    void                setLayerNames(GU_PrimPacked *prim,
                                      UT_Array<GU_AgentLayerConstPtr> &layers,
                                      const UT_StringArray &names);

    struct DelayLoadData
    {
        DelayLoadData(const GA_SharedDataHandlePtr &definition,
                      const GA_SharedDataHandlePtr &transforms,
                      const GA_SharedDataHandlePtr &channel_values)
            : myDefinition(definition),
              myTransforms(transforms),
              myChannelValues(channel_values)
        {
        }

        DelayLoadData(const DelayLoadData &src)
            : myDefinition(src.myDefinition),
              myTransforms(src.myTransforms),
              myChannelValues(src.myChannelValues),
              myClipNames(src.myClipNames),
              myClipXformGroupNames(src.myClipXformGroupNames),
              myCurrentLayerNames(src.myCurrentLayerNames),
              myCollisionLayerNames(src.myCollisionLayerNames)
        {
        }

        /// Return whether the shared data has been loaded.
        bool isLoaded() const
        {
            return !myDefinition && !myTransforms && !myChannelValues;
        }

        int64 getMemoryUsage(bool inclusive) const;

        UT_Lock myLock;
        /// Shared agent definition.
        GA_SharedDataHandlePtr myDefinition;
        /// Shared transforms.
        GA_SharedDataHandlePtr myTransforms;
        /// Cached channel values.
        GA_SharedDataHandlePtr myChannelValues;
        /// Names of the clips that this agent will use after the shared
        /// definition has been loaded.
        UT_StringArray myClipNames;
        /// Names of the transform groups that this agent will use after the
        /// shared definition has been loaded.
        UT_StringArray myClipXformGroupNames;

        /// Names of the layers to be resolved after the shared definition has
        /// been loaded.
        UT_StringArray myCurrentLayerNames;
        UT_StringArray myCollisionLayerNames;
    };

    GU_AgentDefinitionConstPtr myDefinition;

    static constexpr size_t LAYER_CAPACITY = sizeof(GU_AgentLayerConstPtr);
    UT_SmallArray<GU_AgentLayerConstPtr, LAYER_CAPACITY> myCurrentLayers;
    UT_SmallArray<GU_AgentLayerConstPtr, LAYER_CAPACITY> myCollisionLayers;

    State myState;

    mutable FloatArrayPtr myCachedChannelValues;
    mutable Matrix4ArrayPtr myCachedTransforms;
    /// Tracks which entries of myCachedTransforms are in local or world space.
    mutable UT_BitArray     myWorldSpace;

    /// Whether or not myCachedChannelValues matches the clip intrinsics.
    mutable bool myHasCustomChannelValues;
    /// Whether or not myCachedTransforms matches the clip intrinsics.
    mutable bool myHasCustomXforms;

    using XformLock = UT_TBBSpinLock;
    using XformLockScope = UT_TBBSpinLock::Scope;
    /// Lock for myCachedTransforms and myCachedChannelValues.
    mutable XformLock       myXformLock;

    mutable UT_UniquePtr<DelayLoadData> myDelayLoadData;

    static GA_PrimitiveTypeId theTypeId;
};

#endif