prim.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_PRIM_H
#define PXR_USD_USD_PRIM_H


#include "pxr/pxr.h"
#include "pxr/usd/usd/api.h"
#include "pxr/usd/usd/common.h"
#include "pxr/usd/usd/object.h"
#include "pxr/usd/usd/primFlags.h"
#include "pxr/usd/usd/schemaRegistry.h"

#include "pxr/usd/sdf/schema.h"
#include "pxr/base/trace/trace.h"

#include "pxr/base/tf/declarePtrs.h"
#include "pxr/base/tf/refBase.h"
#include "pxr/base/tf/token.h"
#include "pxr/base/tf/weakBase.h"

#include "pxr/usd/sdf/path.h"

#include <iterator>
#include <string>
#include <type_traits>
#include <vector>

PXR_NAMESPACE_OPEN_SCOPE

class UsdPrim;
class UsdPrimDefinition;
class UsdPrimRange;
class Usd_PrimData;

class UsdAttribute;
class UsdEditTarget;
class UsdRelationship;
class UsdPayloads;
class UsdReferences;
class UsdResolveTarget;
class UsdSchemaBase;
class UsdAPISchemaBase;
class UsdInherits;
class UsdSpecializes;
class UsdVariantSets;
class UsdVariantSet;

class SdfPayload;

class UsdPrimSiblingIterator;
class UsdPrimSiblingRange;

class UsdPrimSubtreeIterator;
class UsdPrimSubtreeRange;

class UsdPrim : public UsdObject
{
public:
    typedef UsdPrimSiblingIterator SiblingIterator;
    typedef UsdPrimSiblingRange SiblingRange;

    typedef UsdPrimSubtreeIterator SubtreeIterator;
    typedef UsdPrimSubtreeRange SubtreeRange;

    UsdPrim() : UsdObject(_Null<UsdPrim>()) {}

    const UsdPrimTypeInfo &GetPrimTypeInfo() const {
        return _Prim()->GetPrimTypeInfo();
    }

    const UsdPrimDefinition &GetPrimDefinition() const {
        return _Prim()->GetPrimDefinition();
    }

    SdfSpecifier GetSpecifier() const { return _Prim()->GetSpecifier(); };

    USD_API
    SdfPrimSpecHandleVector GetPrimStack() const;

    USD_API
    std::vector<std::pair<SdfPrimSpecHandle, SdfLayerOffset>> 
    GetPrimStackWithLayerOffsets() const;

    bool SetSpecifier(SdfSpecifier specifier) const {
        return SetMetadata(SdfFieldKeys->Specifier, specifier);
    }

    const TfToken &GetTypeName() const { return _Prim()->GetTypeName(); };

    bool SetTypeName(const TfToken & typeName) const {
        return SetMetadata(SdfFieldKeys->TypeName, typeName);
    }

    bool ClearTypeName() const {
        return ClearMetadata(SdfFieldKeys->TypeName);
    }

    bool HasAuthoredTypeName() const {
        return HasAuthoredMetadata(SdfFieldKeys->TypeName);
    }

    bool IsActive() const { return _Prim()->IsActive(); }

    bool SetActive(bool active) const {
        return SetMetadata(SdfFieldKeys->Active, active);
    }

    bool ClearActive() const {
        return ClearMetadata(SdfFieldKeys->Active);
    }

    bool HasAuthoredActive() const {
        return HasAuthoredMetadata(SdfFieldKeys->Active);
    }

    bool IsLoaded() const { return _Prim()->IsLoaded(); }

    bool IsModel() const { return _Prim()->IsModel(); }

    bool IsGroup() const { return _Prim()->IsGroup(); }

    bool IsComponent() const { return _Prim()->IsComponent(); }

    USD_API
    bool IsSubComponent() const { return _Prim()->IsSubComponent(); }

    bool IsAbstract() const { return _Prim()->IsAbstract(); }

    bool IsDefined() const { return _Prim()->IsDefined(); }

    bool HasClassSpecifier() const {
        return _Prim()->HasClassSpecifier();
    }
    
    bool HasDefiningSpecifier() const { 
        return _Prim()->HasDefiningSpecifier(); 
    }

    USD_API
    const TfTokenVector &GetAppliedSchemas() const;

    using PropertyPredicateFunc = 
        std::function<bool (const TfToken &propertyName)>;

    USD_API
    TfTokenVector GetPropertyNames(
        const PropertyPredicateFunc &predicate={}) const;

    USD_API
    TfTokenVector GetAuthoredPropertyNames(
        const PropertyPredicateFunc &predicate={}) const;

    USD_API
    std::vector<UsdProperty> GetProperties(
        const PropertyPredicateFunc &predicate={}) const;

    USD_API
    std::vector<UsdProperty> GetAuthoredProperties(
        const PropertyPredicateFunc &predicate={}) const;

    USD_API
    std::vector<UsdProperty>
    GetPropertiesInNamespace(const std::vector<std::string> &namespaces) const;

    USD_API
    std::vector<UsdProperty>
    GetPropertiesInNamespace(const std::string &namespaces) const;

    USD_API
    std::vector<UsdProperty>
    GetAuthoredPropertiesInNamespace(
        const std::vector<std::string> &namespaces) const;

    USD_API
    std::vector<UsdProperty>
    GetAuthoredPropertiesInNamespace(const std::string &namespaces) const;

    USD_API
    TfTokenVector GetPropertyOrder() const;

    void SetPropertyOrder(const TfTokenVector &order) const {
        SetMetadata(SdfFieldKeys->PropertyOrder, order);
    }

    USD_API
    static void
    ApplyPropertyOrder(const TfTokenVector &order, TfTokenVector *names);

    void ClearPropertyOrder() const {
        ClearMetadata(SdfFieldKeys->PropertyOrder);
    }

    USD_API
    bool RemoveProperty(const TfToken &propName);

    USD_API
    UsdProperty GetProperty(const TfToken &propName) const;

    USD_API
    bool HasProperty(const TfToken &propName) const;

    USD_API
    bool GetKind(TfToken *kind) const;
    
    USD_API
    bool SetKind(const TfToken &kind) const;

private:
    // Helper functions for the public schema query and API schema
    // authoring functions. The public functions have overloads that take 
    // a type, an identifier, or a family which all are used to find the 
    // SchemaInfo from the schema registry.
    USD_API
    bool _IsA(const UsdSchemaRegistry::SchemaInfo *schemaInfo) const;

    USD_API
    bool _HasAPI(const UsdSchemaRegistry::SchemaInfo *schemaInfo) const;

    USD_API
    bool _HasAPIInstance(
        const UsdSchemaRegistry::SchemaInfo *schemaInfo,
        const TfToken &instanceName) const;

    USD_API
    bool _CanApplySingleApplyAPI(
        const UsdSchemaRegistry::SchemaInfo &schemaInfo,
        std::string *whyNot) const;

    USD_API
    bool _CanApplyMultipleApplyAPI(
        const UsdSchemaRegistry::SchemaInfo &schemaInfo,
        const TfToken& instanceName, 
        std::string *whyNot) const;

    USD_API
    bool _ApplySingleApplyAPI(
        const UsdSchemaRegistry::SchemaInfo &schemaInfo) const;

    USD_API
    bool _ApplyMultipleApplyAPI(
        const UsdSchemaRegistry::SchemaInfo &schemaInfo,
        const TfToken &instanceName) const;

    USD_API
    bool _RemoveSingleApplyAPI(
        const UsdSchemaRegistry::SchemaInfo &schemaInfo) const;

    USD_API
    bool _RemoveMultipleApplyAPI(
        const UsdSchemaRegistry::SchemaInfo &schemaInfo,
        const TfToken &instanceName) const;

public:

    template <typename SchemaType>
    bool IsA() const {
        static_assert(std::is_base_of<UsdSchemaBase, SchemaType>::value,
                      "Provided type must derive UsdSchemaBase.");
        return _IsA(UsdSchemaRegistry::FindSchemaInfo<SchemaType>());
    };

    USD_API
    bool IsA(const TfType& schemaType) const;

    USD_API
    bool IsA(const TfToken& schemaIdentifier) const;

    USD_API
    bool IsA(const TfToken& schemaFamily,
             UsdSchemaVersion schemaVersion) const;



    USD_API
    bool IsInFamily(const TfToken &schemaFamily) const;

    USD_API
    bool IsInFamily(
        const TfToken &schemaFamily,
        UsdSchemaVersion schemaVersion,
        UsdSchemaRegistry::VersionPolicy versionPolicy) const;

    template <typename SchemaType>
    bool IsInFamily(
        UsdSchemaRegistry::VersionPolicy versionPolicy) const {
        static_assert(std::is_base_of<UsdSchemaBase, SchemaType>::value,
                      "Provided type must derive UsdSchemaBase.");
        const UsdSchemaRegistry::SchemaInfo *schemaInfo = 
            UsdSchemaRegistry::FindSchemaInfo<SchemaType>();
        if (!schemaInfo) {
            TF_CODING_ERROR("Class '%s' is not correctly registered with the "
                "UsdSchemaRegistry as a schema type. The schema may need to be "
                "regenerated.", 
                TfType::Find<SchemaType>().GetTypeName().c_str());
            return false;
        }
        return IsInFamily(schemaInfo->family, schemaInfo->version, 
            versionPolicy);
    };

    USD_API
    bool IsInFamily(
        const TfType &schemaType,
        UsdSchemaRegistry::VersionPolicy versionPolicy) const;

    USD_API
    bool IsInFamily(
        const TfToken &schemaIdentifier,
        UsdSchemaRegistry::VersionPolicy versionPolicy) const;

    USD_API
    bool GetVersionIfIsInFamily(
        const TfToken &schemaFamily,
        UsdSchemaVersion *schemaVersion) const;



    template <typename SchemaType>
    bool
    HasAPI() const {
        static_assert(std::is_base_of<UsdAPISchemaBase, SchemaType>::value,
                      "Provided type must derive UsdAPISchemaBase.");
        static_assert(!std::is_same<UsdAPISchemaBase, SchemaType>::value,
                      "Provided type must not be UsdAPISchemaBase.");
        static_assert(
            SchemaType::schemaKind == UsdSchemaKind::SingleApplyAPI ||
            SchemaType::schemaKind == UsdSchemaKind::MultipleApplyAPI,
            "Provided schema type must be an applied API schema.");

        return _HasAPI(UsdSchemaRegistry::FindSchemaInfo<SchemaType>());
    }

    template <typename SchemaType>
    bool
    HasAPI(const TfToken &instanceName) const {
        static_assert(std::is_base_of<UsdAPISchemaBase, SchemaType>::value,
                      "Provided type must derive UsdAPISchemaBase.");
        static_assert(!std::is_same<UsdAPISchemaBase, SchemaType>::value,
                      "Provided type must not be UsdAPISchemaBase.");
        static_assert(SchemaType::schemaKind == UsdSchemaKind::MultipleApplyAPI,
            "Provided schema type must be a multi apply API schema.");

        return _HasAPIInstance(
            UsdSchemaRegistry::FindSchemaInfo<SchemaType>(), instanceName);
    }

    USD_API
    bool HasAPI(const TfType& schemaType) const;

    USD_API
    bool HasAPI(const TfType& schemaType,
                const TfToken& instanceName) const;

    USD_API
    bool HasAPI(const TfToken& schemaIdentifier) const;

    USD_API
    bool HasAPI(const TfToken& schemaIdentifier,
                const TfToken& instanceName) const;

    USD_API
    bool HasAPI(const TfToken& schemaFamily,
                UsdSchemaVersion schemaVersion) const;

    USD_API
    bool HasAPI(const TfToken& schemaFamily,
                UsdSchemaVersion schemaVersion,
                const TfToken& instanceName) const;



    USD_API
    bool HasAPIInFamily(
        const TfToken &schemaFamily) const;

    USD_API
    bool HasAPIInFamily(
        const TfToken &schemaFamily,
        const TfToken &instanceName) const;

    USD_API
    bool HasAPIInFamily(
        const TfToken &schemaFamily,
        UsdSchemaVersion schemaVersion,
        UsdSchemaRegistry::VersionPolicy versionPolicy) const;

    USD_API
    bool HasAPIInFamily(
        const TfToken &schemaFamily,
        UsdSchemaVersion schemaVersion,
        UsdSchemaRegistry::VersionPolicy versionPolicy,
        const TfToken &instanceName) const;

    template <typename SchemaType>
    bool HasAPIInFamily(
        UsdSchemaRegistry::VersionPolicy versionPolicy) const {
        static_assert(std::is_base_of<UsdSchemaBase, SchemaType>::value,
                      "Provided type must derive UsdSchemaBase.");
        const UsdSchemaRegistry::SchemaInfo *schemaInfo = 
            UsdSchemaRegistry::FindSchemaInfo<SchemaType>();
        if (!schemaInfo) {
            TF_CODING_ERROR("Class '%s' is not correctly registered with the "
                "UsdSchemaRegistry as a schema type. The schema may need to be "
                "regenerated.", 
                TfType::Find<SchemaType>().GetTypeName().c_str());
            return false;
        }
        return  HasAPIInFamily(schemaInfo->family, schemaInfo->version, 
            versionPolicy);
    };

    template <typename SchemaType>
    bool HasAPIInFamily(
        UsdSchemaRegistry::VersionPolicy versionPolicy,
        const TfToken &instanceName) const {
        static_assert(std::is_base_of<UsdSchemaBase, SchemaType>::value,
                      "Provided type must derive UsdSchemaBase.");
        const UsdSchemaRegistry::SchemaInfo *schemaInfo = 
            UsdSchemaRegistry::FindSchemaInfo<SchemaType>();
        if (!schemaInfo) {
            TF_CODING_ERROR("Class '%s' is not correctly registered with the "
                "UsdSchemaRegistry as a schema type. The schema may need to be "
                "regenerated.", 
                TfType::Find<SchemaType>().GetTypeName().c_str());
            return false;
        }
        return  HasAPIInFamily(schemaInfo->family, schemaInfo->version, 
            versionPolicy, instanceName);
    };

    USD_API
    bool HasAPIInFamily(
        const TfType &schemaType,
        UsdSchemaRegistry::VersionPolicy versionPolicy) const;

    USD_API
    bool HasAPIInFamily(
        const TfType &schemaType,
        UsdSchemaRegistry::VersionPolicy versionPolicy,
        const TfToken &instanceName) const;

    USD_API
    bool HasAPIInFamily(
        const TfToken &schemaIdentifier,
        UsdSchemaRegistry::VersionPolicy versionPolicy) const;

    USD_API
    bool HasAPIInFamily(
        const TfToken &schemaIdentifier,
        UsdSchemaRegistry::VersionPolicy versionPolicy,
        const TfToken &instanceName) const;

    USD_API
    bool
    GetVersionIfHasAPIInFamily(
        const TfToken &schemaFamily,
        UsdSchemaVersion *schemaVersion) const;

    USD_API
    bool
    GetVersionIfHasAPIInFamily(
        const TfToken &schemaFamily,
        const TfToken &instanceName,
        UsdSchemaVersion *schemaVersion) const;



    template <typename SchemaType>
    bool CanApplyAPI(std::string *whyNot = nullptr) const {
        static_assert(std::is_base_of<UsdAPISchemaBase, SchemaType>::value,
            "Provided type must derive UsdAPISchemaBase.");
        static_assert(!std::is_same<UsdAPISchemaBase, SchemaType>::value,
            "Provided type must not be UsdAPISchemaBase.");
        static_assert(SchemaType::schemaKind == UsdSchemaKind::SingleApplyAPI,
            "Provided schema type must be a single apply API schema.");

        const UsdSchemaRegistry::SchemaInfo *schemaInfo =
            UsdSchemaRegistry::FindSchemaInfo<SchemaType>();
        if (!schemaInfo) {
            TF_CODING_ERROR("Class '%s' is not correctly registered with the "
                "UsdSchemaRegistry as a schema type. The schema may need to be "
                "regenerated.", 
                TfType::Find<SchemaType>().GetTypeName().c_str());
            return false;
        }
        return _CanApplySingleApplyAPI(*schemaInfo, whyNot);
    }

    template <typename SchemaType>
    bool CanApplyAPI(const TfToken &instanceName, 
                     std::string *whyNot = nullptr) const {
        static_assert(std::is_base_of<UsdAPISchemaBase, SchemaType>::value,
            "Provided type must derive UsdAPISchemaBase.");
        static_assert(!std::is_same<UsdAPISchemaBase, SchemaType>::value,
            "Provided type must not be UsdAPISchemaBase.");
        static_assert(SchemaType::schemaKind == UsdSchemaKind::MultipleApplyAPI,
            "Provided schema type must be a multiple apply API schema.");

        const UsdSchemaRegistry::SchemaInfo *schemaInfo =
            UsdSchemaRegistry::FindSchemaInfo<SchemaType>();
        if (!schemaInfo) {
            TF_CODING_ERROR("Class '%s' is not correctly registered with the "
                "UsdSchemaRegistry as a schema type. The schema may need to be "
                "regenerated.", 
                TfType::Find<SchemaType>().GetTypeName().c_str());
            return false;
        }
        return _CanApplyMultipleApplyAPI(*schemaInfo, instanceName, whyNot);
    }

    USD_API
    bool CanApplyAPI(const TfType& schemaType,
                     std::string *whyNot = nullptr) const;

    USD_API
    bool CanApplyAPI(const TfType& schemaType,
                     const TfToken& instanceName,
                     std::string *whyNot = nullptr) const;

    USD_API
    bool CanApplyAPI(const TfToken& schemaIdentifier,
                     std::string *whyNot = nullptr) const;

    USD_API
    bool CanApplyAPI(const TfToken& schemaIdentifier,
                     const TfToken& instanceName,
                     std::string *whyNot = nullptr) const;

    USD_API
    bool CanApplyAPI(const TfToken& schemaFamily,
                     UsdSchemaVersion schemaVersion,
                     std::string *whyNot = nullptr) const;

    USD_API
    bool CanApplyAPI(const TfToken& schemaFamily,
                     UsdSchemaVersion schemaVersion,
                     const TfToken& instanceName,
                     std::string *whyNot = nullptr) const;



    template <typename SchemaType>
    bool ApplyAPI() const {
        static_assert(std::is_base_of<UsdAPISchemaBase, SchemaType>::value,
            "Provided type must derive UsdAPISchemaBase.");
        static_assert(!std::is_same<UsdAPISchemaBase, SchemaType>::value,
            "Provided type must not be UsdAPISchemaBase.");
        static_assert(SchemaType::schemaKind == UsdSchemaKind::SingleApplyAPI,
            "Provided schema type must be a single apply API schema.");

        const UsdSchemaRegistry::SchemaInfo *schemaInfo =
            UsdSchemaRegistry::FindSchemaInfo<SchemaType>();
        if (!schemaInfo) {
            TF_CODING_ERROR("Class '%s' is not correctly registered with the "
                "UsdSchemaRegistry as a schema type. The schema may need to be "
                "regenerated.", 
                TfType::Find<SchemaType>().GetTypeName().c_str());
            return false;
        }
        return _ApplySingleApplyAPI(*schemaInfo);
    }

    template <typename SchemaType>
    bool ApplyAPI(const TfToken &instanceName) const {
        static_assert(std::is_base_of<UsdAPISchemaBase, SchemaType>::value,
            "Provided type must derive UsdAPISchemaBase.");
        static_assert(!std::is_same<UsdAPISchemaBase, SchemaType>::value,
            "Provided type must not be UsdAPISchemaBase.");
        static_assert(SchemaType::schemaKind == UsdSchemaKind::MultipleApplyAPI,
            "Provided schema type must be a multiple apply API schema.");

        const UsdSchemaRegistry::SchemaInfo *schemaInfo =
            UsdSchemaRegistry::FindSchemaInfo<SchemaType>();
        if (!schemaInfo) {
            TF_CODING_ERROR("Class '%s' is not correctly registered with the "
                "UsdSchemaRegistry as a schema type. The schema may need to be "
                "regenerated.", 
                TfType::Find<SchemaType>().GetTypeName().c_str());
            return false;
        }
        return _ApplyMultipleApplyAPI(*schemaInfo, instanceName);
    }

    USD_API
    bool ApplyAPI(const TfType& schemaType) const;

    USD_API
    bool ApplyAPI(const TfType& schemaType,
                  const TfToken& instanceName) const;

    USD_API
    bool ApplyAPI(const TfToken& schemaIdentifier) const;

    USD_API
    bool ApplyAPI(const TfToken& schemaIdentifier,
                  const TfToken& instanceName) const;

    USD_API
    bool ApplyAPI(const TfToken& schemaFamily,
                  UsdSchemaVersion schemaVersion) const;

    USD_API
    bool ApplyAPI(const TfToken& schemaFamily,
                  UsdSchemaVersion schemaVersion,
                  const TfToken& instanceName) const;



    template <typename SchemaType>
    bool RemoveAPI() const {
        static_assert(std::is_base_of<UsdAPISchemaBase, SchemaType>::value,
            "Provided type must derive UsdAPISchemaBase.");
        static_assert(!std::is_same<UsdAPISchemaBase, SchemaType>::value,
            "Provided type must not be UsdAPISchemaBase.");
        static_assert(SchemaType::schemaKind == UsdSchemaKind::SingleApplyAPI,
            "Provided schema type must be a single apply API schema.");

        const UsdSchemaRegistry::SchemaInfo *schemaInfo =
            UsdSchemaRegistry::FindSchemaInfo<SchemaType>();
        if (!schemaInfo) {
            TF_CODING_ERROR("Class '%s' is not correctly registered with the "
                "UsdSchemaRegistry as a schema type. The schema may need to be "
                "regenerated.", 
                TfType::Find<SchemaType>().GetTypeName().c_str());
            return false;
        }
        return _RemoveSingleApplyAPI(*schemaInfo);
    }

    template <typename SchemaType>
    bool RemoveAPI(const TfToken &instanceName) const {
        static_assert(std::is_base_of<UsdAPISchemaBase, SchemaType>::value,
            "Provided type must derive UsdAPISchemaBase.");
        static_assert(!std::is_same<UsdAPISchemaBase, SchemaType>::value,
            "Provided type must not be UsdAPISchemaBase.");
        static_assert(SchemaType::schemaKind == UsdSchemaKind::MultipleApplyAPI,
            "Provided schema type must be a multiple apply API schema.");

        const UsdSchemaRegistry::SchemaInfo *schemaInfo =
            UsdSchemaRegistry::FindSchemaInfo<SchemaType>();
        if (!schemaInfo) {
            TF_CODING_ERROR("Class '%s' is not correctly registered with the "
                "UsdSchemaRegistry as a schema type. The schema may need to be "
                "regenerated.", 
                TfType::Find<SchemaType>().GetTypeName().c_str());
            return false;
        }
        return _RemoveMultipleApplyAPI(*schemaInfo, instanceName);
    }

    USD_API
    bool RemoveAPI(const TfType& schemaType) const;

    USD_API
    bool RemoveAPI(const TfType& schemaType,
                  const TfToken& instanceName) const;

    USD_API
    bool RemoveAPI(const TfToken& schemaIdentifier) const;

    USD_API
    bool RemoveAPI(const TfToken& schemaIdentifier,
                  const TfToken& instanceName) const;

    USD_API
    bool RemoveAPI(const TfToken& schemaFamily,
                  UsdSchemaVersion schemaVersion) const;

    USD_API
    bool RemoveAPI(const TfToken& schemaFamily,
                  UsdSchemaVersion schemaVersion,
                  const TfToken& instanceName) const;


    USD_API
    bool AddAppliedSchema(const TfToken &appliedSchemaName) const;

    USD_API
    bool RemoveAppliedSchema(const TfToken &appliedSchemaName) const;

    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //

    USD_API
    UsdPrim GetChild(const TfToken &name) const;

    inline SiblingRange GetChildren() const;

    inline SiblingRange GetAllChildren() const;

    inline SiblingRange
    GetFilteredChildren(const Usd_PrimFlagsPredicate &predicate) const;

    USD_API
    TfTokenVector GetChildrenNames() const;

    USD_API
    TfTokenVector GetAllChildrenNames() const;

    USD_API
    TfTokenVector GetFilteredChildrenNames(
        const Usd_PrimFlagsPredicate &predicate) const;

    inline SubtreeRange GetDescendants() const;

    inline SubtreeRange GetAllDescendants() const;

    inline SubtreeRange
    GetFilteredDescendants(const Usd_PrimFlagsPredicate &predicate) const;

    USD_API
    TfTokenVector GetChildrenReorder() const;

    void SetChildrenReorder(const TfTokenVector &order) const {
        SetMetadata(SdfFieldKeys->PrimOrder, order);
    }

    void ClearChildrenReorder() const {
        ClearMetadata(SdfFieldKeys->PrimOrder);
    }

public:
    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //

    UsdPrim GetParent() const {
        Usd_PrimDataConstPtr prim = get_pointer(_Prim());
        SdfPath proxyPrimPath = _ProxyPrimPath();
        Usd_MoveToParent(prim, proxyPrimPath);
        return UsdPrim(prim, proxyPrimPath);
    }

    USD_API
    UsdPrim GetNextSibling() const;

    USD_API
    UsdPrim GetFilteredNextSibling(
        const Usd_PrimFlagsPredicate &predicate) const;
        
    USD_API
    bool IsPseudoRoot() const;

    USD_API UsdPrim GetPrimAtPath(const SdfPath& path) const;

    USD_API UsdObject GetObjectAtPath(const SdfPath& path) const;

    USD_API UsdProperty GetPropertyAtPath(const SdfPath& path) const;
    
    USD_API UsdAttribute GetAttributeAtPath(const SdfPath& path) const;

    USD_API UsdRelationship GetRelationshipAtPath(const SdfPath& path) const;

    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //

    USD_API
    UsdVariantSets GetVariantSets() const;

    USD_API
    UsdVariantSet GetVariantSet(const std::string& variantSetName) const;

    USD_API
    bool HasVariantSets() const;

    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //

    USD_API
    UsdAttribute
    CreateAttribute(const TfToken& name,
                    const SdfValueTypeName &typeName,
                    bool custom,
                    SdfVariability variability = SdfVariabilityVarying) const;
    USD_API
    UsdAttribute
    CreateAttribute(const TfToken& name,
                    const SdfValueTypeName &typeName,
                    SdfVariability variability = SdfVariabilityVarying) const;

    USD_API
    UsdAttribute CreateAttribute(
        const std::vector<std::string> &nameElts,
        const SdfValueTypeName &typeName,
        bool custom,
        SdfVariability variability = SdfVariabilityVarying) const;
    USD_API
    UsdAttribute CreateAttribute(
        const std::vector<std::string> &nameElts,
        const SdfValueTypeName &typeName,
        SdfVariability variability = SdfVariabilityVarying) const;

    USD_API
    std::vector<UsdAttribute> GetAttributes() const;

    USD_API
    std::vector<UsdAttribute> GetAuthoredAttributes() const;

    USD_API
    UsdAttribute GetAttribute(const TfToken& attrName) const;

    USD_API
    bool HasAttribute(const TfToken& attrName) const;

    USD_API
    SdfPathVector
    FindAllAttributeConnectionPaths(
        Usd_PrimFlagsPredicate const &traversalPredicate,
        std::function<bool (UsdAttribute const &)> const &pred = nullptr,
        bool recurseOnSources = false) const;

    USD_API
    SdfPathVector
    FindAllAttributeConnectionPaths(
        std::function<bool (UsdAttribute const &)> const &pred = nullptr,
        bool recurseOnSources = false) const;

    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //

    USD_API
    UsdRelationship CreateRelationship(const TfToken& relName,
                                       bool custom=true) const;

    USD_API
    UsdRelationship CreateRelationship(const std::vector<std::string> &nameElts,
                                       bool custom=true)
        const;

    USD_API
    std::vector<UsdRelationship> GetRelationships() const;

    USD_API
    std::vector<UsdRelationship> GetAuthoredRelationships() const;

    USD_API
    UsdRelationship GetRelationship(const TfToken& relName) const;

    USD_API
    bool HasRelationship(const TfToken& relName) const;

    USD_API
    SdfPathVector
    FindAllRelationshipTargetPaths(
        Usd_PrimFlagsPredicate const &traversalPredicate,
        std::function<bool (UsdRelationship const &)> const &pred = nullptr,
        bool recurseOnTargets = false) const;

    USD_API
    SdfPathVector
    FindAllRelationshipTargetPaths(
        std::function<bool (UsdRelationship const &)> const &pred = nullptr,
        bool recurseOnTargets = false) const;

    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //

    USD_API
    bool ClearPayload() const;

    USD_API
    bool HasPayload() const;

    USD_API
    bool SetPayload(const SdfPayload& payload) const;

    USD_API
    bool SetPayload(
        const std::string& assetPath, const SdfPath& primPath) const;
    
    USD_API
    bool SetPayload(const SdfLayerHandle& layer, const SdfPath& primPath) const;


    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //

    USD_API
    UsdPayloads GetPayloads() const;

    USD_API
    bool HasAuthoredPayloads() const;

    USD_API
    void Load(UsdLoadPolicy policy = UsdLoadWithDescendants) const;

    USD_API
    void Unload() const;

    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //

    USD_API
    UsdReferences GetReferences() const;

    USD_API
    bool HasAuthoredReferences() const;

    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
    
    USD_API
    UsdInherits GetInherits() const;

    USD_API
    bool HasAuthoredInherits() const;

    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //
    
    USD_API
    UsdSpecializes GetSpecializes() const;

    USD_API
    bool HasAuthoredSpecializes() const;

    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //

    bool IsInstanceable() const { 
        bool instanceable = false;
        return GetMetadata(SdfFieldKeys->Instanceable, &instanceable) &&
            instanceable;
    }

    bool SetInstanceable(bool instanceable) const {
        return SetMetadata(SdfFieldKeys->Instanceable, instanceable);
    }

    bool ClearInstanceable() const {
        return ClearMetadata(SdfFieldKeys->Instanceable);
    }

    bool HasAuthoredInstanceable() const {
        return HasAuthoredMetadata(SdfFieldKeys->Instanceable);
    }

    bool IsInstance() const { return _Prim()->IsInstance(); }

    bool IsInstanceProxy() const { 
        return Usd_IsInstanceProxy(_Prim(), _ProxyPrimPath());
    }

    USD_API
    static bool IsPrototypePath(const SdfPath& path);

    USD_API
    static bool IsPathInPrototype(const SdfPath& path);

    bool IsPrototype() const { return _Prim()->IsPrototype(); }

    bool IsInPrototype() const { 
        return (IsInstanceProxy() ? 
            IsPathInPrototype(GetPrimPath()) : _Prim()->IsInPrototype());
    }

    USD_API
    UsdPrim GetPrototype() const;

    UsdPrim GetPrimInPrototype() const {
        if (IsInstanceProxy()) {
            return UsdPrim(_Prim(), SdfPath());
        }
        return UsdPrim();
    }

    USD_API
    std::vector<UsdPrim> GetInstances() const;

    // --------------------------------------------------------------------- //
    // --------------------------------------------------------------------- //

    const PcpPrimIndex &GetPrimIndex() const { return _Prim()->GetPrimIndex(); }

    USD_API
    PcpPrimIndex ComputeExpandedPrimIndex() const;

    USD_API
    UsdResolveTarget MakeResolveTargetUpToEditTarget(
        const UsdEditTarget &editTarget) const;

    USD_API
    UsdResolveTarget MakeResolveTargetStrongerThanEditTarget(
        const UsdEditTarget &editTarget) const;


private:
    class _ProtoToInstancePathMap {
        friend class UsdPrim;
    public:
        using _Map = std::vector<std::pair<SdfPath, SdfPath>>;
        SdfPath MapProtoToInstance(SdfPath const &protoPath) const;
    private:
        _Map _map;
    };
    
    friend class UsdObject;
    friend class UsdPrimSiblingIterator;
    friend class UsdPrimSubtreeIterator;
    friend class UsdProperty;
    friend class UsdSchemaBase;
    friend class UsdAPISchemaBase;
    friend class UsdStage;
    friend class UsdPrimRange;
    friend class Usd_PrimData;
    friend class Usd_PrimFlagsPredicate;
    friend struct Usd_StageImplAccess;
    friend struct UsdPrim_RelTargetFinder;
    friend struct UsdPrim_AttrConnectionFinder;

    // Prim constructor.
    UsdPrim(const Usd_PrimDataHandle &primData,
            const SdfPath &proxyPrimPath) 
        : UsdObject(primData, proxyPrimPath) { }

    // General constructor.
    UsdPrim(UsdObjType objType,
            const Usd_PrimDataHandle &prim, 
            const SdfPath &proxyPrimPath,
            const TfToken &propName)
        : UsdObject(objType, prim, proxyPrimPath, propName) {}

    // Helper to make a sibling range.
    inline SiblingRange
    _MakeSiblingRange(const Usd_PrimFlagsPredicate &pred) const;

    // Helper to make a range of descendants.
    inline SubtreeRange
    _MakeDescendantsRange(const Usd_PrimFlagsPredicate &pred) const;

    // Helper to make a vector of properties from names.
    std::vector<UsdProperty>
    _MakeProperties(const TfTokenVector &names) const;

    // Helper for Get{Authored}{PropertyNames,Properties} 
    TfTokenVector _GetPropertyNames(
        bool onlyAuthored,
        bool applyOrder=true,
        const PropertyPredicateFunc &predicate={}) const;

    // Helper for Get(Authored)PropertiesInNamespace.
    std::vector<UsdProperty>
    _GetPropertiesInNamespace(const std::string &namespaces,
                              bool onlyAuthored) const;

    // Helper for Get(Authored)Attributes.
    std::vector<UsdAttribute>
    _GetAttributes(bool onlyAuthored, bool applyOrder=false) const;

    // Helper for Get(Authored)Relationships.
    std::vector<UsdRelationship>
    _GetRelationships(bool onlyAuthored, bool applyOrder=false) const;

    friend const PcpPrimIndex &Usd_PrimGetSourcePrimIndex(const UsdPrim&);
    // Return a const reference to the source PcpPrimIndex for this prim.
    //
    // For all prims in prototypes (which includes the prototype prim itself), 
    // this is the prim index for the instance that was chosen to serve
    // as the prototype for all other instances.  This prim index will not
    // have the same path as the prim's path.
    //
    // This is a private helper but is also wrapped out to Python
    // for testing and debugging purposes.
    const PcpPrimIndex &_GetSourcePrimIndex() const
    { return _Prim()->GetSourcePrimIndex(); }

    // Helper function for MakeResolveTargetUpToEditTarget and 
    // MakeResolveTargetStrongerThanEditTarget.
    UsdResolveTarget 
    _MakeResolveTargetFromEditTarget(
        const UsdEditTarget &editTarget,
        bool makeAsStrongerThan) const;

    _ProtoToInstancePathMap _GetProtoToInstancePathMap() const;
};

class UsdPrimSiblingIterator {
    using _UnderlyingIterator = const Usd_PrimData*;
    class _PtrProxy {
    public:
        UsdPrim* operator->() { return &_prim; }
    private:
        friend class UsdPrimSiblingIterator;
        explicit _PtrProxy(const UsdPrim& prim) : _prim(prim) {}
        UsdPrim _prim;
    };
public:
    using iterator_category = std::forward_iterator_tag;
    using value_type = UsdPrim;
    using reference = UsdPrim;
    using pointer = _PtrProxy;
    using difference_type = std::ptrdiff_t;

    // Default ctor.
    UsdPrimSiblingIterator() = default;

    reference operator*() const { return dereference(); }

    pointer operator->() const { return pointer(dereference()); }

    UsdPrimSiblingIterator &operator++() {
        increment();
        return *this;
    }

    UsdPrimSiblingIterator operator++(int) {
        UsdPrimSiblingIterator result = *this;
        increment();
        return result;
    }

    bool operator==(const UsdPrimSiblingIterator& other) const {
        return equal(other);
    }

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

private:
    friend class UsdPrim;

    // Constructor used by Prim.
    UsdPrimSiblingIterator(const _UnderlyingIterator &i,
                           const SdfPath& proxyPrimPath,
                           const Usd_PrimFlagsPredicate &predicate)
        : _underlyingIterator(i)
        , _proxyPrimPath(proxyPrimPath)
        , _predicate(predicate) {
        // Need to advance iterator to first matching element.
        if (_underlyingIterator &&
            !Usd_EvalPredicate(_predicate, _underlyingIterator,
                               _proxyPrimPath))
            increment();
    }

    bool equal(const UsdPrimSiblingIterator &other) const {
        return _underlyingIterator == other._underlyingIterator && 
            _proxyPrimPath == other._proxyPrimPath &&
            _predicate == other._predicate;
    }

    void increment() {
        if (Usd_MoveToNextSiblingOrParent(_underlyingIterator, _proxyPrimPath,
                                          _predicate)) {
            _underlyingIterator = nullptr;
            _proxyPrimPath = SdfPath();
        }
    }

    reference dereference() const {
        return UsdPrim(_underlyingIterator, _proxyPrimPath);
    }

    _UnderlyingIterator _underlyingIterator = nullptr;
    SdfPath _proxyPrimPath;
    Usd_PrimFlagsPredicate _predicate;
};

class UsdPrimSiblingRange {
public:
    typedef UsdPrimSiblingIterator iterator;
    typedef UsdPrimSiblingIterator const_iterator;
    typedef std::ptrdiff_t difference_type;
    typedef iterator::value_type value_type;
    typedef iterator::reference reference;

    UsdPrimSiblingRange() = default;

    UsdPrimSiblingRange(UsdPrimSiblingIterator begin,
                        UsdPrimSiblingIterator end) : _begin(begin),
                                                      _end(end) {}

    iterator begin() const { return _begin; }

    const_iterator cbegin() const { return _begin; }

    iterator end() const { return _end; }

    const_iterator cend() const { return _end; }

    explicit operator bool() const { return !empty(); }

    bool equal(const UsdPrimSiblingRange& other) const {
        return _begin == other._begin && _end == other._end;
    }

    reference front() const {
        TF_DEV_AXIOM(!empty());
        return *begin();
    }

    UsdPrimSiblingRange& advance_begin(difference_type n) {
        std::advance(_begin, n);
        return *this;
    }

    UsdPrimSiblingRange& advance_end(difference_type n) {
        std::advance(_end, n);
        return *this;
    }

    bool empty() const { return begin() == end(); }

private:
    friend bool operator==(const UsdPrimSiblingRange &lhs,
                           const UsdPrimSiblingRange &rhs) {
        return lhs.equal(rhs);
    }

    template <class ForwardRange>
    friend bool operator==(const UsdPrimSiblingRange& lhs,
                           const ForwardRange& rhs) {
        static_assert(
            std::is_same<typename decltype(std::cbegin(rhs))::iterator_category,
                         std::forward_iterator_tag>::value,
            "rhs must be a forward iterator."
        );
        return (std::distance(std::cbegin(lhs), std::cend(lhs)) ==
                std::distance(std::cbegin(rhs), std::cend(rhs))) &&
               std::equal(std::cbegin(lhs), std::cend(lhs), std::cbegin(rhs));
    }

    template <class ForwardRange>
    friend bool operator==(const ForwardRange& lhs,
                           const UsdPrimSiblingRange& rhs) {
        return rhs == lhs;
    }

    friend bool operator!=(const UsdPrimSiblingRange &lhs,
                           const UsdPrimSiblingRange &rhs) {
        return !lhs.equal(rhs);
    }

    template <class ForwardRange>
    friend bool operator!=(const ForwardRange& lhs,
                           const UsdPrimSiblingRange& rhs) {
        return !(lhs == rhs);
    }

    template <class ForwardRange>
    friend bool operator!=(const UsdPrimSiblingRange& lhs,
                           const ForwardRange& rhs) {
        return !(lhs == rhs);
    }

    iterator _begin;
    iterator _end;
};

// Inform TfIterator it should feel free to make copies of the range type.
template <>
struct Tf_ShouldIterateOverCopy<
    UsdPrimSiblingRange> : std::true_type {};
template <>
struct Tf_ShouldIterateOverCopy<
    const UsdPrimSiblingRange> : std::true_type {};

UsdPrimSiblingRange
UsdPrim::GetFilteredChildren(const Usd_PrimFlagsPredicate &pred) const
{
    return _MakeSiblingRange(
        Usd_CreatePredicateForTraversal(_Prim(), _ProxyPrimPath(), pred));
}

UsdPrimSiblingRange
UsdPrim::GetAllChildren() const
{
    return GetFilteredChildren(UsdPrimAllPrimsPredicate);
}

UsdPrimSiblingRange
UsdPrim::GetChildren() const
{
    return GetFilteredChildren(UsdPrimDefaultPredicate);
}

// Helper to make a sibling range.
UsdPrim::SiblingRange
UsdPrim::_MakeSiblingRange(const Usd_PrimFlagsPredicate &pred) const {
    Usd_PrimDataConstPtr firstChild = get_pointer(_Prim());
    SdfPath firstChildPath = _ProxyPrimPath();
    if (!Usd_MoveToChild(firstChild, firstChildPath, pred)) {
        firstChild = nullptr;
        firstChildPath = SdfPath();
    }

    return SiblingRange(
        SiblingIterator(firstChild, firstChildPath, pred),
        SiblingIterator(nullptr, SdfPath(), pred));
}

class UsdPrimSubtreeIterator {
    using _UnderlyingIterator = Usd_PrimDataConstPtr;
    class _PtrProxy {
    public:
        UsdPrim* operator->() { return &_prim; }
    private:
        friend class UsdPrimSubtreeIterator;
        explicit _PtrProxy(const UsdPrim& prim) : _prim(prim) {}
        UsdPrim _prim;
    };
public:
    using iterator_category = std::forward_iterator_tag;
    using value_type = UsdPrim;
    using reference = UsdPrim;
    using pointer = _PtrProxy;
    using difference_type = std::ptrdiff_t;

    // Default ctor.
    UsdPrimSubtreeIterator() = default;

    reference operator*() const { return dereference(); }
    pointer operator->() const { return pointer(dereference()); }

    UsdPrimSubtreeIterator &operator++() {
        increment();
        return *this;
    }

    UsdPrimSubtreeIterator operator++(int) {
        UsdPrimSubtreeIterator result;
        increment();
        return result;
    }

    bool operator==(const UsdPrimSubtreeIterator &other) const {
        return equal(other);
    }

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


private:
    friend class UsdPrim;

    // Constructor used by Prim.
    UsdPrimSubtreeIterator(const _UnderlyingIterator &i,
                           const SdfPath &proxyPrimPath,
                           const Usd_PrimFlagsPredicate &predicate)
        : _underlyingIterator(i)
        , _proxyPrimPath(proxyPrimPath)
        , _predicate(predicate) {
        // Need to advance iterator to first matching element.
        if (_underlyingIterator &&
            !Usd_EvalPredicate(_predicate, _underlyingIterator,
                               _proxyPrimPath)) {
            if (Usd_MoveToNextSiblingOrParent(_underlyingIterator,
                                              _proxyPrimPath, _predicate)) {
                _underlyingIterator = nullptr;
                _proxyPrimPath = SdfPath();
            }
        }
    }

    bool equal(const UsdPrimSubtreeIterator &other) const {
        return _underlyingIterator == other._underlyingIterator &&
            _proxyPrimPath == other._proxyPrimPath &&
            _predicate == other._predicate;
    }

    void increment() {
        if (!Usd_MoveToChild(_underlyingIterator, _proxyPrimPath,
                             _predicate)) {
            while (Usd_MoveToNextSiblingOrParent(_underlyingIterator,
                                                 _proxyPrimPath,
                                                 _predicate)) {}
        }
    }

    reference dereference() const {
        return UsdPrim(_underlyingIterator, _proxyPrimPath);
    }

    _UnderlyingIterator _underlyingIterator = nullptr;
    SdfPath _proxyPrimPath;
    Usd_PrimFlagsPredicate _predicate;
};

class UsdPrimSubtreeRange {
public:
    typedef UsdPrimSubtreeIterator iterator;
    typedef UsdPrimSubtreeIterator const_iterator;
    typedef std::ptrdiff_t difference_type;
    typedef iterator::value_type value_type;
    typedef iterator::reference reference;

    UsdPrimSubtreeRange() = default;

    UsdPrimSubtreeRange(UsdPrimSubtreeIterator begin,
                        UsdPrimSubtreeIterator end) : _begin(begin),
                                                      _end(end) {}

    iterator begin() const { return _begin; }

    const_iterator cbegin() const { return _begin; }

    iterator end() const { return _end; }

    const_iterator cend() const { return _end; }

    explicit operator bool() const {
        return !empty();
    }

    bool equal(const UsdPrimSubtreeRange& other) const {
        return _begin == other._begin && _end == other._end;
    }

    reference front() const {
        TF_DEV_AXIOM(!empty());
        return *begin();
    }

    UsdPrimSubtreeRange& advance_begin(difference_type n) {
        std::advance(_begin, n);
        return *this;
    }

    UsdPrimSubtreeRange& advance_end(difference_type n) {
        std::advance(_end, n);
        return *this;
    }

    bool empty() const { return begin() == end(); }

private:
    friend bool operator==(const UsdPrimSubtreeRange &lhs,
                           const UsdPrimSubtreeRange &rhs) {
        return lhs.equal(rhs);
    }

    template <class ForwardRange>
    friend bool operator==(const UsdPrimSubtreeRange& lhs,
                           const ForwardRange& rhs) {
        static_assert(
            std::is_convertible<
                typename decltype(std::cbegin(rhs))::iterator_category,
                std::forward_iterator_tag>::value,
            "rhs must be a forward iterator."
        );
        return (std::distance(std::cbegin(lhs), std::cend(lhs)) ==
                std::distance(std::cbegin(rhs), std::cend(rhs))) &&
               std::equal(std::cbegin(lhs), std::cend(lhs), std::cbegin(rhs));
    }

    template <class ForwardRange>
    friend bool operator==(const ForwardRange& lhs,
                           const UsdPrimSubtreeRange& rhs) {
        return rhs == lhs;
    }

    friend bool operator!=(const UsdPrimSubtreeRange &lhs,
                           const UsdPrimSubtreeRange &rhs) {
        return !lhs.equal(rhs);
    }

    template <class ForwardRange>
    friend bool operator!=(const ForwardRange& lhs,
                           const UsdPrimSubtreeRange& rhs) {
        return !(lhs == rhs);
    }

    template <class ForwardRange>
    friend bool operator!=(const UsdPrimSubtreeRange& lhs,
                           const ForwardRange& rhs) {
        return !(lhs == rhs);
    }

    iterator _begin;
    iterator _end;
};

// Inform TfIterator it should feel free to make copies of the range type.
template <>
struct Tf_ShouldIterateOverCopy<
    UsdPrimSubtreeRange> : std::true_type {};
template <>
struct Tf_ShouldIterateOverCopy<
    const UsdPrimSubtreeRange> : std::true_type {};

UsdPrimSubtreeRange
UsdPrim::GetFilteredDescendants(const Usd_PrimFlagsPredicate &pred) const
{
    return _MakeDescendantsRange(
        Usd_CreatePredicateForTraversal(_Prim(), _ProxyPrimPath(), pred));
}

UsdPrimSubtreeRange
UsdPrim::GetAllDescendants() const
{
    return GetFilteredDescendants(UsdPrimAllPrimsPredicate);
}

UsdPrimSubtreeRange
UsdPrim::GetDescendants() const
{
    return GetFilteredDescendants(UsdPrimDefaultPredicate);
}

// Helper to make a sibling range.
UsdPrim::SubtreeRange
UsdPrim::_MakeDescendantsRange(const Usd_PrimFlagsPredicate &pred) const {
    Usd_PrimDataConstPtr firstChild = get_pointer(_Prim());
    SdfPath firstChildPath = _ProxyPrimPath();
    Usd_PrimDataConstPtr endChild = firstChild;
    SdfPath endChildPath = firstChildPath;
    if (Usd_MoveToChild(firstChild, firstChildPath, pred)) {
        while (Usd_MoveToNextSiblingOrParent(endChild, endChildPath, pred)) {}
    }

    return SubtreeRange(
        SubtreeIterator(firstChild, firstChildPath, pred),
        SubtreeIterator(endChild, endChildPath, pred));
}


// UsdObject methods that require UsdPrim be a complete type.

inline UsdPrim
UsdObject::GetPrim() const
{
    return UsdPrim(_prim, _proxyPrimPath);
}

PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_USD_USD_PRIM_H