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

#ifndef __GU_AgentDefinition__
#define __GU_AgentDefinition__

#include "GU_API.h"
#include "GU_AgentClip.h"
#include "GU_AgentCustomDataItem.h"
#include "GU_AgentLayer.h"
#include "GU_AgentMetadata.h"
#include "GU_AgentRig.h"
#include "GU_AgentShapeLib.h"
#include "GU_AgentTransformGroup.h"

#include <UT/UT_Array.h>
#include <UT/UT_Function.h>
#include <UT/UT_IntrusivePtr.h>
#include <UT/UT_StringMap.h>


class GU_AgentDefinition;
typedef UT_IntrusivePtr<GU_AgentDefinition> GU_AgentDefinitionPtr;
typedef UT_IntrusivePtr<const GU_AgentDefinition> GU_AgentDefinitionConstPtr;

/// An agent definition contains a rig, a shape library, a set of available
/// clips, a set of available layers, and a set of transform groups.
class GU_API GU_AgentDefinition
    : public UT_IntrusiveRefCounter<GU_AgentDefinition>
{
public:
    GU_AgentDefinition();

    GU_AgentDefinition(const GU_AgentRigConstPtr &rig,
                       const GU_AgentShapeLibConstPtr &shapelib);

    /// Create a copy of the given agent definition, but referencing a new
    /// version of the shape library and/or rig.
    GU_AgentDefinition(const GU_AgentDefinition &src_defn,
                       const GU_AgentShapeLibConstPtr &new_shapelib,
                       const GU_AgentRigConstPtr &new_rig = nullptr);

    int64 getMemoryUsage(bool inclusive) const;

    /// Loads the agent definition from JSON. Used when loading agent
    /// primitives from a geometry file.
    bool load(UT_JSONParser &p);

    /// Saves the agent definition to JSON. Used when saving agent primitives
    /// to a geometry file.
    bool save(UT_JSONWriter &w) const;

    const GU_AgentRigConstPtr &rig() const { return myRig; }
    const GU_AgentShapeLibConstPtr &shapeLibrary() const { return myShapeLib; }

    /// Add a layer to the agent definition. Replaces any pre-existing layer of
    /// the same name.
    void addLayer(const GU_AgentLayerConstPtr &layer);

    /// Remove a layer from the agent definition by name.
    void removeLayer(const UT_StringRef &name);

    /// Return the list of layers.
    const UT_Array<GU_AgentLayerConstPtr> &layers() const { return myLayers; }

    /// Get a pointer to a specfic layer. This may be a NULL pointer.
    const GU_AgentLayer *layer(const UT_StringRef &name) const;

    /// Get the index of a layer, or -1 if it does not exist.
    exint layerIndex(const UT_StringRef &name) const
        { return myLayersIndex.get(name, -1); }

    /// Get a reference to the ith layer.
    const GU_AgentLayer &layer(exint i) const { return *myLayers(i); }

    /// Return the layer count.
    exint numLayers() const { return myLayers.size(); }

    /// Sorts the layers by name, if any layers have been added or removed since
    /// the last sort.
    void sortLayersIfNeeded();

    /// Add a clip to the agent definition. Replaces any pre-existing clip of
    /// the same name.
    void addClip(const GU_AgentClipConstPtr &clip);

    /// Remove a clip from the agent definition by name.
    void removeClip(const UT_StringRef &name);

    /// Return the list of clips.
    const UT_Array<GU_AgentClipConstPtr> &clips() const { return myClips; }

    /// Get a pointer to a specfic clip. This may be a NULL pointer.
    const GU_AgentClip *clip(const UT_StringRef &name) const;

    /// Get the index of a clip, or -1 if it does not exist.
    exint clipIndex(const UT_StringRef &name) const
        { return myClipsIndex.get(name, -1); }

    /// Get a reference to the ith clip.
    const GU_AgentClip &clip(exint i) const { return *myClips(i); }

    /// Return the clip count.
    exint numClips() const { return myClips.size(); }

    /// Sorts the clips by name, if any clips have been added or removed since
    /// the last sort.
    void sortClipsIfNeeded();

    /// Get a rest clip, which contains a single sample at the rig's rest
    /// pose. This can be used as a fallback for scenarios where a valid clip is
    /// required.
    /// Note this clip is not included in the clip catalog and is not saved with
    /// the agent definition.
    const GU_AgentClip &restClip() const { return *myRestClip; }

    /// Add a transform group to the agent definition. Replaces any
    /// pre-existing group of the same name.
    void addTransformGroup(const GU_AgentTransformGroupConstPtr &group);

    /// Remove a transform group from the agent definition by name.
    void removeTransformGroup(const UT_StringRef &name);

    /// Return the list of groups.
    const UT_Array<GU_AgentTransformGroupConstPtr> &transformGroups() const
        { return myTransformGroups; }

    /// Get a pointer to a specfic group. This may be a NULL pointer.
    const GU_AgentTransformGroup *transformGroup(const UT_StringRef &name) const;

    /// Get the index of a transform group, or -1 if it does not exist.
    exint transformGroupIndex(const UT_StringRef &name) const
        { return myTransformGroupsIndex.get(name, -1); }

    /// Get the default transform group, which contains all transforms in the
    /// rig.
    const GU_AgentTransformGroup &defaultTransformGroup() const
        { return *myDefaultTransformGroup; }

    /// Get a reference to the ith group.
    const GU_AgentTransformGroup &transformGroup(exint i) const
        { return *myTransformGroups(i); }

    /// Return the transform group count.
    exint numTransformGroups() const { return myTransformGroups.size(); }

    /// Sorts the transform groups by name, if any groups have been added or
    /// removed since the last sort.
    void sortTransformGroupsIfNeeded();

    /// Return the metadata dictionary. This may be a nullptr.
    const GU_AgentMetadataConstPtr &metadata() const { return myMetadata; }

    /// Replace the metadata dictionary.
    void setMetadata(const GU_AgentMetadataConstPtr &data)
        { myMetadata = data; }

    /// Add a custom data item to the agent definition. Replaces any
    /// pre-existing item of the same name.
    void addCustomDataItem(const GU_AgentCustomDataItemConstPtr &data);

    /// Remove a custom data item from the agent definition by name.
    void removeCustomDataItem(const UT_StringRef &name);

    /// Return the list of custom data items.
    const UT_Array<GU_AgentCustomDataItemConstPtr> &customDataItems() const
        { return myCustomDataItems; }

    /// Get a pointer to a specfic data item by name. This may be a NULL
    /// pointer.
    const GU_AgentCustomDataItem *customDataItem(const UT_StringRef &name) const;

    /// Get a reference to the ith custom data item.
    const GU_AgentCustomDataItem &customDataItem(exint i) const
        { return *myCustomDataItems[i]; }

    /// Return the number of custom data items.
    exint numCustomDataItems() const { return myCustomDataItems.size(); }

    /// Sorts the custom data items by name, if any items have been added or
    /// removed since the last sort.
    void sortCustomDataItemsIfNeeded();

    /// Constructs a new instance of a GU_AgentCustomDataItem. The provided
    /// agent definition can be used if the data item requires references to
    /// the rig, shape library, etc.
    using CustomDataItemConstructor =
        UT_Function<GU_AgentCustomDataItemPtr (const GU_AgentDefinition &)>;

    /// Register a new custom data item type.
    static void registerCustomDataItemType(
        const UT_StringHolder &dataitemtype,
        CustomDataItemConstructor constructor);

    /// Called by GU_Agent during startup to register custom data item types.
    static void installCustomDataItemTypes();

    /// Sorts the clips, layers, transform groups, and custom data items by
    /// name, if any items have been added or removed since the last sort.
    /// This is equivalent to individually calling sortClipsIfNeeded() and
    /// similar methods.
    void sortItemsIfNeeded();

    /// Runs agent functions on a specific dso.
    static bool runDSO(const char* lib_path);

private:
    /// Constructs the default transform group that contains all of the joints.
    void addDefaultTransformGroup();

    /// Constructs the fallback clip which contains a single sample (rest pose).
    void buildRestClip();

private:
    GU_AgentRigConstPtr         myRig;
    GU_AgentShapeLibConstPtr    myShapeLib;

    UT_Array<GU_AgentLayerConstPtr> myLayers;
    UT_StringMap<exint>         myLayersIndex;

    UT_Array<GU_AgentClipConstPtr>  myClips;
    UT_StringMap<exint>         myClipsIndex;
    GU_AgentClipConstPtr        myRestClip;

    UT_Array<GU_AgentTransformGroupConstPtr> myTransformGroups;
    UT_StringMap<exint>         myTransformGroupsIndex;
    GU_AgentTransformGroupConstPtr myDefaultTransformGroup;

    GU_AgentMetadataConstPtr    myMetadata;

    UT_Array<GU_AgentCustomDataItemConstPtr> myCustomDataItems;
    UT_StringMap<exint> myCustomDataItemsIndex;

    bool                        myAreLayersSorted;
    bool                        myAreClipsSorted;
    bool                        myAreTransformGroupsSorted;
    bool                        myAreCustomDataItemsSorted;
};

inline const GU_AgentLayer *
GU_AgentDefinition::layer(const UT_StringRef &name) const
{
    const exint idx = layerIndex(name);
    return (idx >= 0) ? myLayers[idx].get() : nullptr;
}

inline const GU_AgentClip *
GU_AgentDefinition::clip(const UT_StringRef &name) const
{
    const exint idx = clipIndex(name);
    return (idx >= 0) ? myClips[idx].get() : nullptr;
}

inline const GU_AgentTransformGroup *
GU_AgentDefinition::transformGroup(const UT_StringRef &name) const
{
    const exint idx = transformGroupIndex(name);
    return (idx >= 0) ? myTransformGroups[idx].get() : nullptr;
}

inline const GU_AgentCustomDataItem *
GU_AgentDefinition::customDataItem(const UT_StringRef &name) const
{
    const exint idx = myCustomDataItemsIndex.get(name, -1);
    return (idx >= 0) ? myCustomDataItems[idx].get() : nullptr;
}

extern "C" {
    /// Entry point for registering custom data item types.
    SYS_VISIBILITY_EXPORT extern void GUregisterAgentCustomDataItemType();
};

#endif