prim.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_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/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 <boost/iterator/iterator_adaptor.hpp>
#include <boost/range/iterator_range.hpp>

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

PXR_NAMESPACE_OPEN_SCOPE

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

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

class SdfPayload;

class UsdPrimSiblingIterator;
typedef boost::iterator_range<UsdPrimSiblingIterator> UsdPrimSiblingRange;

class UsdPrimSubtreeIterator;
typedef boost::iterator_range<UsdPrimSubtreeIterator> 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;

    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 IsAbstract() const { return _Prim()->IsAbstract(); }

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

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

    USD_API
    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);
    }

    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;

private:
    // The non-templated implementation of UsdPrim::IsA using the
    // TfType system. \p validateSchemaType is provided for python clients
    // because they can't use compile time assertions on the input type.
    USD_API
    bool _IsA(const TfType& schemaType, bool validateSchemaType) const;

    // Separate implementations for UsdPrim::HasAPI for single and multiple
    // apply API schema TfTypes.
    USD_API
    bool _HasSingleApplyAPI(const TfType& schemaType) const;

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

    // Private implementation for all ApplyAPI, CanApplyAPI, and RemoveAPI 
    // methods for both single apply and multiple apply APIs. The multiple 
    // apply API methods validate that the instance name is non-empty, but 
    // otherwise all of these methods do no other input validation as the 
    // public methods are expected to have already done either compile time or 
    // runtime validation already.
    USD_API
    bool _CanApplyAPI(const TfType& schemaType, 
                      std::string *whyNot) const;

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

    USD_API
    bool _ApplyAPI(const TfType& schemaType) const;

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

    USD_API
    bool _RemoveAPI(const TfType& schemaType) const;

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

public:
    template <typename T>
    bool IsA() const {
        static_assert(std::is_base_of<UsdSchemaBase, T>::value,
                      "Provided type must derive UsdSchemaBase.");
        return _IsA(TfType::Find<T>(), /*validateSchemaType=*/false);
    };
    
    USD_API
    bool IsA(const TfType& schemaType) const;


    template <typename T>
    typename std::enable_if<T::schemaKind != UsdSchemaKind::MultipleApplyAPI, 
        bool>::type
    HasAPI() const {
        static_assert(std::is_base_of<UsdAPISchemaBase, T>::value,
                      "Provided type must derive UsdAPISchemaBase.");
        static_assert(!std::is_same<UsdAPISchemaBase, T>::value,
                      "Provided type must not be UsdAPISchemaBase.");
        // Note that this function template is enabled for any schema kind, 
        // other than MultipleApplyAPI, but is only valid for SingleApplyAPI. 
        // This static assert provides better error information for calling 
        // HasAPI with an invalid template type than if we limited HasAPI 
        // substitution matching to just the two valid schema kinds.
        static_assert(T::schemaKind == UsdSchemaKind::SingleApplyAPI,
            "Provided schema type must be a single apply API schema.");

        return _HasSingleApplyAPI(TfType::Find<T>());
    }

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

        return _HasMultiApplyAPI(TfType::Find<T>(), instanceName);
    }
        
    USD_API
    bool HasAPI(const TfType& schemaType,
                const TfToken& instanceName=TfToken()) 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.");

        static const TfType schemaType = TfType::Find<SchemaType>();
        return _CanApplyAPI(schemaType, whyNot);
    }

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

    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.");

        static const TfType schemaType = TfType::Find<SchemaType>();
        return _CanApplyAPI(schemaType, instanceName, whyNot);
    }

    USD_API
    bool CanApplyAPI(const TfType& schemaType,
                     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.");

        static const TfType schemaType = TfType::Find<SchemaType>();
        return _ApplyAPI(schemaType);
    }

    USD_API
    bool ApplyAPI(const TfType& schemaType) const;

    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.");

        static const TfType schemaType = TfType::Find<SchemaType>();
        return _ApplyAPI(schemaType, instanceName);
    }

    USD_API
    bool ApplyAPI(const TfType& schemaType, 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.");

        static const TfType schemaType = TfType::Find<SchemaType>();
        return _RemoveAPI(schemaType);
    }

    USD_API
    bool RemoveAPI(const TfType& schemaType) const;

    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.");

        static const TfType schemaType = TfType::Find<SchemaType>();
        return _RemoveAPI(schemaType, instanceName);
    }

    USD_API
    bool RemoveAPI(const TfType& schemaType,
                   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(
        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(
        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;


private:
    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 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(); }
};

#ifdef doxygen

class UsdPrimSiblingIterator {
public:
    typedef UsdPrim value_type;
    typedef value_type reference;
    typedef unspecified-integral-type difference_type;
    reference operator*() const;
    unspecified-type operator->() const;
    UsdPrimSiblingIterator &operator++();
    UsdPrimSiblingIterator operator++(int);
private:
    friend bool operator==(const UsdPrimSiblingIterator &lhs,
                           const UsdPrimSiblingIterator &rhs);
    friend bool operator!=(const UsdPrimSiblingIterator &lhs,
                           const UsdPrimSiblingIterator &rhs);
};

class UsdPrimSiblingRange {
public:
    typedef UsdPrimSiblingIterator iterator;
    typedef UsdPrimSiblingIterator const_iterator;
    typedef unspecified-integral-type difference_type;
    typedef iterator::value_type value_type;
    typedef iterator::reference reference;

    UsdPrimSiblingRange(UsdPrimSiblingIterator begin,
                        UsdPrimSiblingIterator end);

    template <class ForwardRange>
    UsdPrimSiblingRange(const ForwardRange &r);

    template <class ForwardRange>
    UsdPrimSiblingRange &operator=(const ForwardRange &r);

    iterator begin() const;

    iterator end() const;

    operator unspecified_bool_type() const;

    bool equal(const iterator_range&) const;

    reference front() const;

    iterator_range& advance_begin(difference_type n);

    iterator_range& advance_end(difference_type n);

    ;    
    bool empty() const;

private:
    friend bool operator==(const UsdPrimSiblingRange &lhs,
                           const UsdPrimSiblingRange &rhs);
    friend bool operator!=(const UsdPrimSiblingRange &lhs,
                           const UsdPrimSiblingRange &rhs);
};

#else

// Sibling iterator class.  Converts ref to weak and filters according to a
// supplied predicate.
class UsdPrimSiblingIterator : public boost::iterator_adaptor<
    UsdPrimSiblingIterator,                       // crtp base.
    const Usd_PrimData *,                         // base iterator.
    UsdPrim,                                      // value type.
    boost::forward_traversal_tag,                 // traversal
    UsdPrim>                                      // reference type.
{
public:
    // Default ctor.
    UsdPrimSiblingIterator() {}

private:
    friend class UsdPrim;

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

    // Core implementation invoked by iterator_adaptor.
    friend class boost::iterator_core_access;
    bool equal(const UsdPrimSiblingIterator &other) const {
        return base() == other.base() && 
            _proxyPrimPath == other._proxyPrimPath &&
            _predicate == other._predicate;
    }

    void increment() {
        base_type &base = base_reference();
        if (Usd_MoveToNextSiblingOrParent(base, _proxyPrimPath, _predicate)) {
            base = nullptr;
            _proxyPrimPath = SdfPath();
        }
    }

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

    SdfPath _proxyPrimPath;
    Usd_PrimFlagsPredicate _predicate;
};

// Typedef iterator range.
typedef boost::iterator_range<UsdPrimSiblingIterator> UsdPrimSiblingRange;

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

#endif // doxygen


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));
}

#ifdef doxygen

class UsdPrimSubtreeIterator {
public:
    typedef UsdPrim value_type;
    typedef value_type reference;
    typedef unspecified-integral-type difference_type;
    reference operator*() const;
    unspecified-type operator->() const;
    UsdPrimSubtreeIterator &operator++();
    UsdPrimSubtreeIterator operator++(int);
private:
    friend bool operator==(const UsdPrimSubtreeIterator &lhs,
                           const UsdPrimSubtreeIterator &rhs);
    friend bool operator!=(const UsdPrimSubtreeIterator &lhs,
                           const UsdPrimSubtreeIterator &rhs);
};

class UsdPrimSubtreeRange {
public:
    typedef UsdPrimSubtreeIterator iterator;
    typedef UsdPrimSubtreeIterator const_iterator;
    typedef unspecified-integral-type difference_type;
    typedef iterator::value_type value_type;
    typedef iterator::reference reference;

    UsdPrimSubtreeRange(UsdPrimSubtreeIterator begin,
                        UsdPrimSubtreeIterator end);

    template <class ForwardRange>
    UsdPrimSubtreeRange(const ForwardRange &r);

    template <class ForwardRange>
    UsdPrimSubtreeRange &operator=(const ForwardRange &r);

    iterator begin() const;

    iterator end() const;

    operator unspecified_bool_type() const;

    bool equal(const iterator_range&) const;

    reference front() const;

    iterator_range& advance_begin(difference_type n);

    iterator_range& advance_end(difference_type n);

    bool empty() const;

private:
    friend bool operator==(const UsdPrimSubtreeRange &lhs,
                           const UsdPrimSubtreeRange &rhs);
    friend bool operator!=(const UsdPrimSubtreeRange &lhs,
                           const UsdPrimSubtreeRange &rhs);
};

#else

// Subtree iterator class.  Converts ref to weak and filters according to a
// supplied predicate.
class UsdPrimSubtreeIterator : public boost::iterator_adaptor<
    UsdPrimSubtreeIterator,                       // crtp base.
    const Usd_PrimData *,                         // base iterator.
    UsdPrim,                                      // value type.
    boost::forward_traversal_tag,                 // traversal
    UsdPrim>                                      // reference type.
{
public:
    // Default ctor.
    UsdPrimSubtreeIterator() {}

private:
    friend class UsdPrim;

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

    // Core implementation invoked by iterator_adaptor.
    friend class boost::iterator_core_access;
    bool equal(const UsdPrimSubtreeIterator &other) const {
        return base() == other.base() && 
            _proxyPrimPath == other._proxyPrimPath &&
            _predicate == other._predicate;
    }

    void increment() {
        base_type &base = base_reference();
        if (!Usd_MoveToChild(base, _proxyPrimPath, _predicate)) {
            while (Usd_MoveToNextSiblingOrParent(base, _proxyPrimPath, 
                                                 _predicate)) {}
        }
    }

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

    SdfPath _proxyPrimPath;
    Usd_PrimFlagsPredicate _predicate;
};

// Typedef iterator range.
typedef boost::iterator_range<UsdPrimSubtreeIterator> UsdPrimSubtreeRange;

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

#endif // doxygen

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