primDefinition.h

//
// Copyright 2020 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_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& GetAppliedAPISchemas() const { 
        return _appliedAPISchemas; 
    }

    SdfSpecType GetSpecType(const TfToken &propName) const
    {
        if (const _LayerAndPath *layerAndPath = 
                _GetPropertyLayerAndPath(propName)) {
            return layerAndPath->GetSpecType();
        }
        return SdfSpecTypeUnknown;
    }

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

    TfTokenVector ListMetadataFields() const 
    {
        return _ListMetadataFields(TfToken());
    }

    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;

    TfTokenVector ListPropertyMetadataFields(const TfToken &propName) const 
    {
        return propName.IsEmpty() ? 
            TfTokenVector() : _ListMetadataFields(propName);
    }

    template <class T>
    bool GetPropertyMetadata(
        const TfToken &propName, const TfToken &key, T* value) const
    {
        if (propName.IsEmpty() || UsdSchemaRegistry::IsDisallowedField(key)) {
            return false;
        }
        return _HasField(propName, key, value);
    }

    template <class T>
    bool GetPropertyMetadataByDictKey(
        const TfToken &propName, const TfToken &key, 
        const TfToken &keyPath, T* value) const
    {
        if (propName.IsEmpty() || UsdSchemaRegistry::IsDisallowedField(key)) {
            return false;
        }
        return _HasFieldDictKey(propName, key, keyPath, value);
    }

    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 (with the exception of 
        // ListMetadataFields).
        SdfSpecType GetSpecType() const {
            return layer->GetSpecType(path);
        }

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

        USD_API
        TfTokenVector ListMetadataFields() const;
    };

    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;

    USD_API
    void _IntializeForTypedSchema(
        const SdfLayerHandle &schematicsLayer,
        const SdfPath &schematicsPrimPath, 
        const VtTokenArray &propertiesToIgnore);

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

    USD_API
    TfTokenVector _ListMetadataFields(const TfToken &propName) const;

    // Helpers for constructing the prim definition.
    USD_API
    void _ComposePropertiesFromPrimDef(
        const UsdPrimDefinition &weakerPrimDef, 
        bool useWeakerPropertyForTypeConflict = false);

    USD_API
    void _ComposePropertiesFromPrimDefInstance(
        const UsdPrimDefinition &weakerPrimDef, 
        const std::string &instanceName);

    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,
        bool allowDupes = false);

    USD_API
    static bool _PropertyTypesMatch(
        const _LayerAndPath &strongerProp,
        const _LayerAndPath &weakerProp);

    // 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.
    TfTokenVector _properties;
};

PXR_NAMESPACE_CLOSE_SCOPE

#endif //PXR_USD_USD_PRIM_DEFINITION_H