object.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache 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