object.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_USD_USD_OBJECT_H
#define PXR_USD_USD_OBJECT_H
 
 
#include "pxr/pxr.h"
#include "pxr/usd/usd/api.h"
#include "pxr/usd/usd/common.h"
#include "pxr/usd/usd/primData.h"
#include "pxr/usd/usd/stage.h"
 
#include "pxr/usd/sdf/abstractData.h"
#include "pxr/usd/sdf/path.h"
 
#include "pxr/base/tf/hash.h"
 
#include <type_traits>
 
PXR_NAMESPACE_OPEN_SCOPE
 
 
TF_DECLARE_WEAK_PTRS(UsdStage);
 
enum UsdObjType
{
    // Value order matters in this enum.
    UsdTypeObject,
    UsdTypePrim,
    UsdTypeProperty,
    UsdTypeAttribute,
    UsdTypeRelationship,
 
    Usd_NumObjTypes
};
 
 
namespace _Detail {
 
// A metafunction that takes a UsdObject class like UsdObject, UsdPrim,
// UsdProperty, etc, and gives its corresponding UsdObjType, e.g. UsdTypeObject,
// UsdTypePrim, UsdTypeProperty, etc.  Usage: GetObjType<UsdPrim>::Value.
template <UsdObjType Type>
struct Const { static const UsdObjType Value = Type; };
template <class T> struct GetObjType {
    static_assert(std::is_base_of<UsdObject, T>::value,
                  "Type T must be a subclass of UsdObject.");
};
template <> struct GetObjType<UsdObject> : Const<UsdTypeObject> {};
template <> struct GetObjType<UsdPrim> : Const<UsdTypePrim> {};
template <> struct GetObjType<UsdProperty> : Const<UsdTypeProperty> {};
template <> struct GetObjType<UsdAttribute> : Const<UsdTypeAttribute> {};
template <> struct GetObjType<UsdRelationship> : Const<UsdTypeRelationship> {};
 
} // _Detail
 
inline bool
UsdIsSubtype(UsdObjType baseType, UsdObjType subType) {
    return (baseType == UsdTypeObject) || (baseType == subType) ||
        (baseType == UsdTypeProperty && subType > UsdTypeProperty);
}
 
inline bool
UsdIsConvertible(UsdObjType from, UsdObjType to) {
    return UsdIsSubtype(to, from);
}
 
inline bool
UsdIsConcrete(UsdObjType type) {
    return type == UsdTypePrim   ||
        type == UsdTypeAttribute ||
        type == UsdTypeRelationship;
}
 
class UsdObject {
public:
    UsdObject() : _type(UsdTypeObject) {}
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
    bool IsValid() const {
        if (!UsdIsConcrete(_type) || !_prim)
            return false;
        if (_type == UsdTypePrim)
            return true;
        SdfSpecType specType = _GetDefiningSpecType();
        return (_type == UsdTypeAttribute &&
                specType == SdfSpecTypeAttribute) ||
            (_type == UsdTypeRelationship &&
             specType == SdfSpecTypeRelationship);
    }
 
    explicit operator bool() const {
        return IsValid();
    }
 
public:
 
    friend bool operator==(const UsdObject &lhs, const UsdObject &rhs) {
        return lhs._type == rhs._type &&
            lhs._prim == rhs._prim &&
            lhs._proxyPrimPath == rhs._proxyPrimPath &&
            lhs._propName == rhs._propName;
    }
 
    friend bool operator!=(const UsdObject &lhs, const UsdObject &rhs) {
        return !(lhs == rhs);
    }
 
    friend bool operator<(const UsdObject &lhs, const UsdObject &rhs) {
        return lhs.GetPath() < rhs.GetPath();
    }
 
    // hash_value overload for std/boost hash.
    friend size_t hash_value(const UsdObject &obj) {
        return TfHash()(obj);
    }
 
    // TfHash support
    template <class HashState>
    friend void TfHashAppend(HashState &h, const UsdObject &obj) {
        h.Append(obj._type, obj._prim, obj._proxyPrimPath, obj._propName);
    }
 
    USD_API
    UsdStageWeakPtr GetStage() const;
 
    SdfPath GetPath() const {
        // Allow getting expired object paths.
        if (!_proxyPrimPath.IsEmpty()) { 
            return _type == UsdTypePrim ?
                _proxyPrimPath : _proxyPrimPath.AppendProperty(_propName);
        }
        else if (Usd_PrimDataConstPtr p = get_pointer(_prim)) {
            return _type == UsdTypePrim ?
                p->GetPath() : p->GetPath().AppendProperty(_propName);
        }
        return SdfPath();
    }
 
    const SdfPath &GetPrimPath() const {
        // Allow getting expired object paths.
        if (!_proxyPrimPath.IsEmpty()) {
            return _proxyPrimPath;
        }
        else if (Usd_PrimDataConstPtr p = get_pointer(_prim)) {
            return p->GetPath();
        }
        return SdfPath::EmptyPath();
    }
 
    inline UsdPrim GetPrim() const;
 
    const TfToken &GetName() const {
        return _type == UsdTypePrim ? GetPrimPath().GetNameToken() : _propName;
    }
 
    template <class T>
    T As() const {
        // compile-time type assertion provided by invoking Is<T>().
        return Is<T>() ? T(_type, _prim, _proxyPrimPath, _propName) : T();
    }
 
    template <class T>
    bool Is() const {
        static_assert(std::is_base_of<UsdObject, T>::value,
                      "Provided type T must derive from or be UsdObject");
        return UsdIsConvertible(_type, _Detail::GetObjType<T>::Value);
    }
 
    USD_API
    std::string GetDescription() const;
    
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
    template<typename T>
    bool GetMetadata(const TfToken& key, T* value) const;
    USD_API
    bool GetMetadata(const TfToken& key, VtValue* value) const;
 
    template<typename T>
    bool SetMetadata(const TfToken& key, const T& value) const;
    USD_API
    bool SetMetadata(const TfToken& key, const VtValue& value) const;
 
    USD_API
    bool ClearMetadata(const TfToken& key) const;
 
    USD_API
    bool HasMetadata(const TfToken& key) const;
 
    USD_API
    bool HasAuthoredMetadata(const TfToken& key) const;
 
    template <class T>
    bool GetMetadataByDictKey(
        const TfToken& key, const TfToken &keyPath, T *value) const;
    USD_API
    bool GetMetadataByDictKey(
        const TfToken& key, const TfToken &keyPath, VtValue *value) const;
 
    template<typename T>
    bool SetMetadataByDictKey(
        const TfToken& key, const TfToken &keyPath, const T& value) const;
    USD_API
    bool SetMetadataByDictKey(
        const TfToken& key, const TfToken &keyPath, const VtValue& value) const;
 
    USD_API
    bool ClearMetadataByDictKey(
        const TfToken& key, const TfToken& keyPath) const;
 
    USD_API
    bool HasMetadataDictKey(
        const TfToken& key, const TfToken &keyPath) const;
 
    USD_API
    bool HasAuthoredMetadataDictKey(
        const TfToken& key, const TfToken &keyPath) const;
 
    USD_API
    UsdMetadataValueMap GetAllMetadata() const;
 
    USD_API
    UsdMetadataValueMap GetAllAuthoredMetadata() const;
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
    USD_API
    bool IsHidden() const;
 
    USD_API
    bool SetHidden(bool hidden) const;
 
    USD_API
    bool ClearHidden() const;
 
    USD_API
    bool HasAuthoredHidden() const;
 
    USD_API
    VtDictionary GetCustomData() const;
 
    USD_API
    VtValue GetCustomDataByKey(const TfToken &keyPath) const;
 
    USD_API
    void SetCustomData(const VtDictionary &customData) const;
 
    USD_API
    void SetCustomDataByKey(const TfToken &keyPath, const VtValue &value) const;
 
    USD_API
    void ClearCustomData() const;
 
    USD_API
    void ClearCustomDataByKey(const TfToken &keyPath) const;
 
    USD_API
    bool HasCustomData() const;
 
    USD_API
    bool HasCustomDataKey(const TfToken &keyPath) const;
 
    USD_API
    bool HasAuthoredCustomData() const;
 
    USD_API
    bool HasAuthoredCustomDataKey(const TfToken &keyPath) const;
 
    USD_API
    VtDictionary GetAssetInfo() const;
 
    USD_API
    VtValue GetAssetInfoByKey(const TfToken &keyPath) const;
 
    USD_API
    void SetAssetInfo(const VtDictionary &customData) const;
 
    USD_API
    void SetAssetInfoByKey(const TfToken &keyPath, const VtValue &value) const;
 
    USD_API
    void ClearAssetInfo() const;
 
    USD_API
    void ClearAssetInfoByKey(const TfToken &keyPath) const;
 
    USD_API
    bool HasAssetInfo() const;
 
    USD_API
    bool HasAssetInfoKey(const TfToken &keyPath) const;
 
    USD_API
    bool HasAuthoredAssetInfo() const;
 
    USD_API
    bool HasAuthoredAssetInfoKey(const TfToken &keyPath) const;
 
    USD_API
    std::string GetDocumentation() const;
 
    USD_API
    bool SetDocumentation(const std::string& doc) const;
 
    USD_API
    bool ClearDocumentation() const;
 
    USD_API
    bool HasAuthoredDocumentation() const;
 
    USD_API
    std::string GetDisplayName() const;
 
    USD_API
    bool SetDisplayName(const std::string& name) const;
 
    USD_API
    bool ClearDisplayName() const;
 
    USD_API
    bool HasAuthoredDisplayName() const;
 
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
 
    // XXX: This method can and probably should move to UsdProperty
    static char GetNamespaceDelimiter() 
        { return SdfPathTokens->namespaceDelimiter.GetText()[0]; }
    
private:
    template <class T>
    bool _GetMetadataImpl(const TfToken& key,
                          T* value,
                          const TfToken &keyPath=TfToken()) const;
 
    bool _GetMetadataImpl(const TfToken& key,
                          VtValue* value,
                          const TfToken &keyPath=TfToken()) const;
 
    template <class T>
    bool _SetMetadataImpl(const TfToken& key,
                          const T& value,
                          const TfToken &keyPath=TfToken()) const;
 
    bool _SetMetadataImpl(const TfToken& key,
                          const VtValue& value,
                          const TfToken &keyPath=TfToken()) const;
 
protected:
    template <class Derived> struct _Null {};
 
    // Private constructor for null dervied types.
    template <class Derived>
    explicit UsdObject(_Null<Derived>)
        : _type(_Detail::GetObjType<Derived>::Value) {}
    
    // Private constructor for UsdPrim.
    UsdObject(const Usd_PrimDataHandle &prim,
              const SdfPath &proxyPrimPath)
        : _type(UsdTypePrim)
        , _prim(prim)
        , _proxyPrimPath(proxyPrimPath)
    {
        TF_VERIFY(!_prim || _prim->GetPath() != _proxyPrimPath);
    }
 
    // Private constructor for UsdAttribute/UsdRelationship.
    UsdObject(UsdObjType objType,
              const Usd_PrimDataHandle &prim,
              const SdfPath &proxyPrimPath,
              const TfToken &propName)
        : _type(objType)
        , _prim(prim)
        , _proxyPrimPath(proxyPrimPath)
        , _propName(propName) 
    {
        TF_VERIFY(!_prim || _prim->GetPath() != _proxyPrimPath);
    }
 
    // Return the stage this object belongs to.
    UsdStage *_GetStage() const { return _prim->GetStage(); }
 
    // Return this object's defining spec type.
    USD_API
    SdfSpecType _GetDefiningSpecType() const;
 
    // Helper for subclasses: return held prim data.
    const Usd_PrimDataHandle &_Prim() const { return _prim; }
 
    // Helper for subclasses: return held property name.
    const TfToken &_PropName() const { return _propName; }
 
    // Helper for subclasses: return held proxy prim path.
    const SdfPath &_ProxyPrimPath() const { return _proxyPrimPath; }
 
private:
    // Helper for the above helper, and also for GetDescription()
    std::string _GetObjectDescription(const std::string &preface) const;
 
    friend class UsdStage;
 
    friend UsdObjType Usd_GetObjType(const UsdObject &obj) {
        return obj._type;
    }
 
    UsdObjType _type;
    Usd_PrimDataHandle _prim;
    SdfPath _proxyPrimPath;
    TfToken _propName;
 
};
 
template<typename T>
inline
bool
UsdObject::GetMetadata(const TfToken& key, T* value) const
{
    return _GetMetadataImpl(key, value);
}
 
template<typename T>
inline
bool 
UsdObject::SetMetadata(const TfToken& key, const T& value) const
{
    return _SetMetadataImpl(key, value);
}
 
template <typename T>
inline
bool
UsdObject::GetMetadataByDictKey(const TfToken& key, 
                                const TfToken &keyPath, 
                                T *value) const
{
    return _GetMetadataImpl(key, value, keyPath);
}
 
template <typename T>
inline
bool
UsdObject::SetMetadataByDictKey(const TfToken& key, 
                                const TfToken &keyPath, 
                                const T& value) const
{
    return _SetMetadataImpl(key, value, keyPath);
}
 
template <class T>
bool 
UsdObject::_GetMetadataImpl(const TfToken& key,
                            T* value,
                            const TfToken &keyPath) const
{
    return _GetStage()->_GetMetadata(
        *this, key, keyPath, /*useFallbacks=*/true, value);
}
 
template <class T>
bool 
UsdObject::_SetMetadataImpl(const TfToken& key,
                            const T& value,
                            const TfToken &keyPath) const
{
    return _GetStage()->_SetMetadata(*this, key, keyPath, value);
}
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif //PXR_USD_USD_OBJECT_H