primDefinition.h

//
// Copyright 2020 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_USD_USD_PRIM_DEFINITION_H
#define PXR_USD_USD_PRIM_DEFINITION_H
 
#include "pxr/pxr.h"
#include "pxr/usd/usd/api.h"
#include "pxr/usd/usd/schemaRegistry.h"
 
#include "pxr/usd/sdf/layer.h"
#include "pxr/usd/sdf/attributeSpec.h"
#include "pxr/usd/sdf/propertySpec.h"
#include "pxr/usd/sdf/relationshipSpec.h"
#include "pxr/base/tf/hash.h"
 
#include <unordered_map>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class UsdPrim;
 
class UsdPrimDefinition
{
public:
    ~UsdPrimDefinition() = default;
 
    const TfTokenVector &GetPropertyNames() const { return _properties; }
 
 
    const TfTokenVector &GetLocallyDefinedPropertyNames() const { 
        return _locallyDefinedPropertyNames;
    }
 
    const TfTokenVector& GetAppliedAPISchemas() const { 
        return _appliedAPISchemas; 
    }
 
private:
    // Forward declaration required by Property.
    struct _LayerAndPath;
 
public:
    class Property {
    public:
        Property() = default;
 
        USD_API
        const TfToken &GetName() const;
 
        explicit operator bool() const 
        {
            return _layerAndPath;
        }
 
        USD_API
        bool IsAttribute() const;
 
        USD_API
        bool IsRelationship() const;
 
 
        USD_API
        SdfSpecType GetSpecType() const;
 
        USD_API
        TfTokenVector ListMetadataFields() const;
 
        template <class T>
        bool GetMetadata(const TfToken &key, T* value) const;
 
        template <class T>
        bool GetMetadataByDictKey(
            const TfToken &key, const TfToken &keyPath, T* value) const;
 
        USD_API
        SdfVariability GetVariability() const;
 
        USD_API
        std::string GetDocumentation() const;
 
 
    protected:
        // Only the prim definition can create real property accessors.
        friend class UsdPrimDefinition;
        Property(const TfToken &name, const _LayerAndPath *layerAndPath):
            _name(name), _layerAndPath(layerAndPath) {}
        Property(const _LayerAndPath *layerAndPath):
            _layerAndPath(layerAndPath) {}
 
        TfToken _name;
        const _LayerAndPath *_layerAndPath = nullptr;
    };
 
    class Attribute : public Property {
    public:
        Attribute() = default;
 
        USD_API
        Attribute(const Property &property);
 
        USD_API
        Attribute(Property &&property);
 
        explicit operator bool() const {
            return IsAttribute();
        }
 
 
        USD_API
        SdfValueTypeName GetTypeName() const;
 
        USD_API
        TfToken GetTypeNameToken() const;
 
        template <class T>
        bool GetFallbackValue(T *value) const;
 
    };
 
    class Relationship : public Property {
    public:
        Relationship() = default;
 
        USD_API
        Relationship(const Property &property);
 
        USD_API
        Relationship(Property &&property);
 
        explicit operator bool() const{
            return IsRelationship();
        }
    };
 
    USD_API
    Property GetPropertyDefinition(const TfToken& propName) const;
 
    USD_API
    Attribute GetAttributeDefinition(const TfToken& attrName) const;
 
    USD_API
    Relationship GetRelationshipDefinition(const TfToken& relName) const;
 
    USD_API
    SdfSpecType GetSpecType(const TfToken &propName) const;
 
    USD_API
    SdfPropertySpecHandle GetSchemaPropertySpec(
        const TfToken& propName) const;
 
    USD_API
    SdfAttributeSpecHandle GetSchemaAttributeSpec(
        const TfToken& attrName) const;
 
    USD_API
    SdfRelationshipSpecHandle GetSchemaRelationshipSpec(
        const TfToken& relName) const;
 
    template <class T>
    bool GetAttributeFallbackValue(const TfToken &attrName, T *value) const
    {
        return _HasField(attrName, SdfFieldKeys->Default, value);
    }
 
    USD_API
    TfTokenVector ListMetadataFields() const;
 
    template <class T>
    bool GetMetadata(const TfToken &key, T* value) const 
    {
        if (UsdSchemaRegistry::IsDisallowedField(key)) {
            return false;
        }
        return _HasField(TfToken(), key, value);
    }
 
    template <class T>
    bool GetMetadataByDictKey(const TfToken &key, 
                              const TfToken &keyPath, T* value) const 
    {
        if (UsdSchemaRegistry::IsDisallowedField(key)) {
            return false;
        }
        return _HasFieldDictKey(TfToken(), key, keyPath, value);
    }
 
    USD_API
    std::string GetDocumentation() const;
 
    USD_API
    TfTokenVector ListPropertyMetadataFields(const TfToken &propName) const;
 
    template <class T>
    bool GetPropertyMetadata(
        const TfToken &propName, const TfToken &key, T* value) const
    {
        if (Property prop = GetPropertyDefinition(propName)) {
            return prop.GetMetadata(key, value);
        }
        return false;
    }
 
    template <class T>
    bool GetPropertyMetadataByDictKey(
        const TfToken &propName, const TfToken &key, 
        const TfToken &keyPath, T* value) const
    {
        if (Property prop = GetPropertyDefinition(propName)) {
            return prop.GetMetadataByDictKey(key, keyPath, value);
        }
        return false;
    }
 
    USD_API
    std::string GetPropertyDocumentation(const TfToken &propName) const;
 
    USD_API
    bool FlattenTo(const SdfLayerHandle &layer, 
                   const SdfPath &path,
                   SdfSpecifier newSpecSpecifier = SdfSpecifierOver) const;
 
    USD_API
    UsdPrim FlattenTo(const UsdPrim &parent, 
                      const TfToken &name,
                      SdfSpecifier newSpecSpecifier = SdfSpecifierOver) const;
 
    USD_API
    UsdPrim FlattenTo(const UsdPrim &prim, 
                      SdfSpecifier newSpecSpecifier = SdfSpecifierOver) const;
 
private:
    // Only the UsdSchemaRegistry can construct prim definitions.
    friend class UsdSchemaRegistry;
 
    // Friended private accessor for use by UsdStage when composing metadata 
    // values for value resolution. The public GetMetadata functions perform
    // the extra step of filtering out disallowed or private metadata fields
    // from the SdfSpecs before retrieving metadata. Value resolution does not
    // want to pay that extra cost so uses this function instead.
    template <class T>
    friend bool Usd_GetFallbackValue(const UsdPrimDefinition &primDef,
                                     const TfToken &propName,
                                     const TfToken &fieldName,
                                     const TfToken &keyPath,
                                     T *value)
    {
        // Try to read fallback value.
        return keyPath.IsEmpty() ?
            primDef._HasField(propName, fieldName, value) :
            primDef._HasFieldDictKey(propName, fieldName, keyPath, value);
    }
 
    // Prim definitions store property access via a pointer to the schematics
    // layer and a path to the property spec on that layer.
    struct _LayerAndPath {
        // Note that we use a raw pointer to the layer (for efficiency) as only
        // the schema registry can create a UsdPrimDefinition and is responsible
        // for making sure any schematics layers are alive throughout the
        // life-time of any UsdPrimDefinition it creates.
        const SdfLayer *layer = nullptr;
        SdfPath path;
 
        // Accessors for the common data we extract from the schematics, inline
        // for efficiency during value resolution
        template <class T>
        bool HasField(const TfToken& fieldName, T* value) const {
            return layer->HasField(path, fieldName, value);
        }
 
        template <class T>
        bool HasFieldDictKey(
            const TfToken& fieldName, const TfToken& keyPath, T* value) const {
            return layer->HasFieldDictKey(path, fieldName, keyPath, value);
        }
 
        VtValue GetField(const TfToken& fieldName) const {
            return layer->GetField(path, fieldName);
        }
 
        explicit operator bool() const noexcept {
            return layer;
        }
    };
 
    template <class T>
    bool _HasField(const TfToken& propName,
                   const TfToken& fieldName,
                   T* value) const
    {
        if (const _LayerAndPath *layerAndPath = 
                _GetPropertyLayerAndPath(propName)) {
            return layerAndPath->HasField(fieldName, value);
        }
        return false;
    }
 
    template <class T>
    bool _HasFieldDictKey(const TfToken& propName,
                          const TfToken& fieldName,
                          const TfToken& keyPath,
                          T* value) const
    {
        if (const _LayerAndPath *layerAndPath = 
                _GetPropertyLayerAndPath(propName)) {
            return layerAndPath->HasFieldDictKey(fieldName, keyPath, value);
        }
        return false;
    }
 
    UsdPrimDefinition() = default;
    UsdPrimDefinition(const UsdPrimDefinition &) = default;
 
    void _ApplyPropertyOrder();
 
    USD_API
    void _InitializeForTypedSchema(
        const SdfLayerHandle &schematicsLayer,
        const SdfPath &schematicsPrimPath, 
        const VtTokenArray &propertiesToIgnore);
 
    USD_API
    void _InitializeForAPISchema(
        const TfToken &apiSchemaName,
        const SdfLayerHandle &schematicsLayer,
        const SdfPath &schematicsPrimPath, 
        const VtTokenArray &propertiesToIgnore);
 
    // Only used by the two _Initialize methods.
    bool _MapSchematicsPropertyPaths(
        const VtTokenArray &propertiesToIgnore);
 
    // Accessors for looking property spec paths by name.
    const _LayerAndPath *_GetPropertyLayerAndPath(const TfToken& propName) const
    {
        return TfMapLookupPtr(_propLayerAndPathMap, propName);
    }
 
    _LayerAndPath *_GetPropertyLayerAndPath(const TfToken& propName)
    {
        return TfMapLookupPtr(_propLayerAndPathMap, propName);
    }
 
    // Helpers for constructing the prim definition.
    void _ComposePropertiesFromPrimDef(
        const UsdPrimDefinition &weakerPrimDef);
 
    void _ComposePropertiesFromPrimDefInstance(
        const UsdPrimDefinition &weakerPrimDef, 
        const std::string &instanceName);
 
    void _AddOrComposeProperty(
        const TfToken &propName,
        const _LayerAndPath &layerAndPath);
 
    SdfSpecHandle _FindOrCreateSpecForComposition(
        const TfToken &propName,
        const _LayerAndPath &srcLayerAndPath);
 
    SdfSpecHandle _CreateComposedPrimOrPropertyIfNeeded(
        const TfToken &propName,
        const _LayerAndPath &strongProp, 
        const _LayerAndPath &weakProp);
 
    USD_API
    void _ComposeOverAndReplaceExistingProperty(
        const TfToken &propName,
        const SdfLayerRefPtr &overLayer,
        const SdfPath &overPrimPath);
 
    using _FamilyAndInstanceToVersionMap = 
        std::unordered_map<std::pair<TfToken, TfToken>, UsdSchemaVersion, TfHash>;
 
    USD_API
    bool _ComposeWeakerAPIPrimDefinition(
        const UsdPrimDefinition &apiPrimDef,
        const TfToken &instanceName,
        _FamilyAndInstanceToVersionMap *alreadyAppliedSchemaFamilyVersions);
 
    static bool _PropertyTypesMatch(
        const Property &strongProp,
        const Property &weakProp);
 
    // Path to the prim in the schematics for this prim definition.
    _LayerAndPath _primLayerAndPath;
 
    // Map for caching the paths to each property spec in the schematics by 
    // property name.
    using _PrimTypePropNameToPathMap = 
        std::unordered_map<TfToken, _LayerAndPath, TfToken::HashFunctor>;
    _PrimTypePropNameToPathMap _propLayerAndPathMap;
    TfTokenVector _appliedAPISchemas;
 
    // Cached list of property names that are locally sourced from this prim
    // definition's schema.usda. This is a subset of _properties.
    TfTokenVector _locallyDefinedPropertyNames;
 
    // Cached list of property names.
    TfTokenVector _properties;
 
    // Layer that may be created for this prim definition if it's necessary to
    // compose any new property specs for this definition from multiple 
    // property specs from other definitions.
    SdfLayerRefPtr _composedPropertyLayer;
};
 
template <class T>
bool 
UsdPrimDefinition::Property::GetMetadata(const TfToken &key, T* value) const
{
    if (UsdSchemaRegistry::IsDisallowedField(key)) {
        return false;
    }
    return _layerAndPath->HasField(key, value);
}
 
template <class T>
bool 
UsdPrimDefinition::Property::GetMetadataByDictKey(
    const TfToken &key, const TfToken &keyPath, T* value) const
{
    if (UsdSchemaRegistry::IsDisallowedField(key)) {
        return false;
    }
    return _layerAndPath->HasFieldDictKey(key, keyPath, value);
}
 
template <class T>
bool 
UsdPrimDefinition::Attribute::GetFallbackValue(T *value) const
{
    return _layerAndPath->HasField(SdfFieldKeys->Default, value);
}
 
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif //PXR_USD_USD_PRIM_DEFINITION_H