All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
primDefinition.h
1//
2// Copyright 2020 Pixar
3//
4// Licensed under the terms set forth in the LICENSE.txt file available at
5// https://openusd.org/license.
6//
7#ifndef PXR_USD_USD_PRIM_DEFINITION_H
8#define PXR_USD_USD_PRIM_DEFINITION_H
9
10#include "pxr/pxr.h"
11#include "pxr/usd/usd/api.h"
12#include "pxr/usd/usd/schemaRegistry.h"
13
14#include "pxr/usd/sdf/layer.h"
18#include "pxr/base/tf/hash.h"
19
20#include <unordered_map>
21
22PXR_NAMESPACE_OPEN_SCOPE
23
24class UsdPrim;
25
32{
33public:
34 ~UsdPrimDefinition() = default;
35
37 const TfTokenVector &GetPropertyNames() const { return _properties; }
38
42 return _appliedAPISchemas;
43 }
44
45private:
46 // Forward declaration required by Property.
47 struct _LayerAndPath;
48
49public:
60 class Property {
61 public:
63 Property() = default;
64
68 USD_API
69 const TfToken &GetName() const;
70
73 explicit operator bool() const
74 {
75 return _layerAndPath;
76 }
77
80 USD_API
81 bool IsAttribute() const;
82
85 USD_API
86 bool IsRelationship() const;
87
101
103 USD_API
105
108 USD_API
110
117 template <class T>
118 bool GetMetadata(const TfToken &key, T* value) const;
119
128 template <class T>
130 const TfToken &key, const TfToken &keyPath, T* value) const;
131
133 USD_API
135
138 USD_API
139 std::string GetDocumentation() const;
140
142
143 protected:
144 // Only the prim definition can create real property accessors.
145 friend class UsdPrimDefinition;
146 Property(const TfToken &name, const _LayerAndPath *layerAndPath):
147 _name(name), _layerAndPath(layerAndPath) {}
148 Property(const _LayerAndPath *layerAndPath):
149 _layerAndPath(layerAndPath) {}
150
151 TfToken _name;
152 const _LayerAndPath *_layerAndPath = nullptr;
153 };
154
166 class Attribute : public Property {
167 public:
169 Attribute() = default;
170
172 USD_API
173 Attribute(const Property &property);
174
176 USD_API
177 Attribute(Property &&property);
178
181 explicit operator bool() const {
182 return IsAttribute();
183 }
184
198
201 USD_API
203
206 USD_API
208
214 template <class T>
215 bool GetFallbackValue(T *value) const;
216
218 };
219
232 class Relationship : public Property {
233 public:
235 Relationship() = default;
236
238 USD_API
239 Relationship(const Property &property);
240
242 USD_API
244
247 explicit operator bool() const{
248 return IsRelationship();
249 }
250 };
251
255 USD_API
256 Property GetPropertyDefinition(const TfToken& propName) const;
257
262 USD_API
264
269 USD_API
271
275 USD_API
276 SdfSpecType GetSpecType(const TfToken &propName) const;
277
283 USD_API
284 SdfPropertySpecHandle GetSchemaPropertySpec(
285 const TfToken& propName) const;
286
292 USD_API
293 SdfAttributeSpecHandle GetSchemaAttributeSpec(
294 const TfToken& attrName) const;
295
301 USD_API
302 SdfRelationshipSpecHandle GetSchemaRelationshipSpec(
303 const TfToken& relName) const;
304
310 template <class T>
311 bool GetAttributeFallbackValue(const TfToken &attrName, T *value) const
312 {
313 return _HasField(attrName, SdfFieldKeys->Default, value);
314 }
315
318 USD_API
320
327 template <class T>
328 bool GetMetadata(const TfToken &key, T* value) const
329 {
331 return false;
332 }
333 return _HasField(TfToken(), key, value);
334 }
335
344 template <class T>
346 const TfToken &keyPath, T* value) const
347 {
349 return false;
350 }
351 return _HasFieldDictKey(TfToken(), key, keyPath, value);
352 }
353
356 USD_API
357 std::string GetDocumentation() const;
358
362 USD_API
364
371 template <class T>
373 const TfToken &propName, const TfToken &key, T* value) const
374 {
375 if (Property prop = GetPropertyDefinition(propName)) {
376 return prop.GetMetadata(key, value);
377 }
378 return false;
379 }
380
389 template <class T>
391 const TfToken &propName, const TfToken &key,
392 const TfToken &keyPath, T* value) const
393 {
394 if (Property prop = GetPropertyDefinition(propName)) {
395 return prop.GetMetadataByDictKey(key, keyPath, value);
396 }
397 return false;
398 }
399
402 USD_API
403 std::string GetPropertyDocumentation(const TfToken &propName) const;
404
428 USD_API
429 bool FlattenTo(const SdfLayerHandle &layer,
430 const SdfPath &path,
431 SdfSpecifier newSpecSpecifier = SdfSpecifierOver) const;
432
437 USD_API
438 UsdPrim FlattenTo(const UsdPrim &parent,
439 const TfToken &name,
440 SdfSpecifier newSpecSpecifier = SdfSpecifierOver) const;
441
445 USD_API
447 SdfSpecifier newSpecSpecifier = SdfSpecifierOver) const;
448
449private:
450 // Only the UsdSchemaRegistry can construct prim definitions.
451 friend class UsdSchemaRegistry;
452
453 // Friended private accessor for use by UsdStage when composing metadata
454 // values for value resolution. The public GetMetadata functions perform
455 // the extra step of filtering out disallowed or private metadata fields
456 // from the SdfSpecs before retrieving metadata. Value resolution does not
457 // want to pay that extra cost so uses this function instead.
458 template <class T>
459 friend bool Usd_GetFallbackValue(const UsdPrimDefinition &primDef,
460 const TfToken &propName,
461 const TfToken &fieldName,
462 const TfToken &keyPath,
463 T *value)
464 {
465 // Try to read fallback value.
466 return keyPath.IsEmpty() ?
467 primDef._HasField(propName, fieldName, value) :
468 primDef._HasFieldDictKey(propName, fieldName, keyPath, value);
469 }
470
471 // Prim definitions store property access via a pointer to the schematics
472 // layer and a path to the property spec on that layer.
473 struct _LayerAndPath {
474 // Note that we use a raw pointer to the layer (for efficiency) as only
475 // the schema registry can create a UsdPrimDefinition and is responsible
476 // for making sure any schematics layers are alive throughout the
477 // life-time of any UsdPrimDefinition it creates.
478 const SdfLayer *layer = nullptr;
479 SdfPath path;
480
481 // Accessors for the common data we extract from the schematics, inline
482 // for efficiency during value resolution
483 template <class T>
484 bool HasField(const TfToken& fieldName, T* value) const {
485 return layer->HasField(path, fieldName, value);
486 }
487
488 template <class T>
489 bool HasFieldDictKey(
490 const TfToken& fieldName, const TfToken& keyPath, T* value) const {
491 return layer->HasFieldDictKey(path, fieldName, keyPath, value);
492 }
493 };
494
498 template <class T>
499 bool _HasField(const TfToken& propName,
500 const TfToken& fieldName,
501 T* value) const
502 {
503 if (const _LayerAndPath *layerAndPath =
504 _GetPropertyLayerAndPath(propName)) {
505 return layerAndPath->HasField(fieldName, value);
506 }
507 return false;
508 }
509
510 template <class T>
511 bool _HasFieldDictKey(const TfToken& propName,
512 const TfToken& fieldName,
513 const TfToken& keyPath,
514 T* value) const
515 {
516 if (const _LayerAndPath *layerAndPath =
517 _GetPropertyLayerAndPath(propName)) {
518 return layerAndPath->HasFieldDictKey(fieldName, keyPath, value);
519 }
520 return false;
521 }
522
523 UsdPrimDefinition() = default;
524 UsdPrimDefinition(const UsdPrimDefinition &) = default;
525
526 USD_API
527 void _IntializeForTypedSchema(
528 const SdfLayerHandle &schematicsLayer,
529 const SdfPath &schematicsPrimPath,
530 const VtTokenArray &propertiesToIgnore);
531
532 USD_API
533 void _IntializeForAPISchema(
534 const TfToken &apiSchemaName,
535 const SdfLayerHandle &schematicsLayer,
536 const SdfPath &schematicsPrimPath,
537 const VtTokenArray &propertiesToIgnore);
538
539 // Only used by the two _Initialize methods.
540 bool _MapSchematicsPropertyPaths(
541 const VtTokenArray &propertiesToIgnore);
542
543 // Accessors for looking property spec paths by name.
544 const _LayerAndPath *_GetPropertyLayerAndPath(const TfToken& propName) const
545 {
546 return TfMapLookupPtr(_propLayerAndPathMap, propName);
547 }
548
549 _LayerAndPath *_GetPropertyLayerAndPath(const TfToken& propName)
550 {
551 return TfMapLookupPtr(_propLayerAndPathMap, propName);
552 }
553
554 // Helpers for constructing the prim definition.
555 void _ComposePropertiesFromPrimDef(
556 const UsdPrimDefinition &weakerPrimDef);
557
558 void _ComposePropertiesFromPrimDefInstance(
559 const UsdPrimDefinition &weakerPrimDef,
560 const std::string &instanceName);
561
562 void _AddOrComposeProperty(
563 const TfToken &propName,
564 const _LayerAndPath &layerAndPath);
565
566 SdfPropertySpecHandle _FindOrCreatePropertySpecForComposition(
567 const TfToken &propName,
568 const _LayerAndPath &srcLayerAndPath);
569
570 SdfPropertySpecHandle _CreateComposedPropertyIfNeeded(
571 const TfToken &propName,
572 const _LayerAndPath &strongProp,
573 const _LayerAndPath &weakProp);
574
575 USD_API
576 void _ComposeOverAndReplaceExistingProperty(
577 const TfToken &propName,
578 const SdfLayerRefPtr &overLayer,
579 const SdfPath &overPrimPath);
580
581 using _FamilyAndInstanceToVersionMap =
582 std::unordered_map<std::pair<TfToken, TfToken>, UsdSchemaVersion, TfHash>;
583
584 USD_API
585 bool _ComposeWeakerAPIPrimDefinition(
586 const UsdPrimDefinition &apiPrimDef,
587 const TfToken &instanceName,
588 _FamilyAndInstanceToVersionMap *alreadyAppliedSchemaFamilyVersions);
589
590 static bool _PropertyTypesMatch(
591 const Property &strongProp,
592 const Property &weakProp);
593
594 // Path to the prim in the schematics for this prim definition.
595 _LayerAndPath _primLayerAndPath;
596
597 // Map for caching the paths to each property spec in the schematics by
598 // property name.
599 using _PrimTypePropNameToPathMap =
600 std::unordered_map<TfToken, _LayerAndPath, TfToken::HashFunctor>;
601 _PrimTypePropNameToPathMap _propLayerAndPathMap;
602 TfTokenVector _appliedAPISchemas;
603
604 // Cached list of property names.
605 TfTokenVector _properties;
606
607 // Layer that may be created for this prim definition if it's necessary to
608 // compose any new property specs for this definition from multiple
609 // property specs from other definitions.
610 SdfLayerRefPtr _composedPropertyLayer;
611};
612
613template <class T>
614bool
616{
618 return false;
619 }
620 return _layerAndPath->HasField(key, value);
621}
622
623template <class T>
624bool
626 const TfToken &key, const TfToken &keyPath, T* value) const
627{
629 return false;
630 }
631 return _layerAndPath->HasFieldDictKey(key, keyPath, value);
632}
633
634template <class T>
635bool
637{
638 return _layerAndPath->HasField(SdfFieldKeys->Default, value);
639}
640
641
642PXR_NAMESPACE_CLOSE_SCOPE
643
644#endif //PXR_USD_USD_PRIM_DEFINITION_H
A scene description container that can combine with other such containers to form simple component as...
Definition: layer.h:84
SDF_API bool HasFieldDictKey(const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath, VtValue *value=NULL) const
Return whether a value exists for the given path and fieldName and keyPath.
SDF_API bool HasField(const SdfPath &path, const TfToken &fieldName, VtValue *value=NULL) const
Return whether a value exists for the given path and fieldName.
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:274
Represents a value type name, i.e.
Definition: valueTypeName.h:71
A user-extensible hashing mechanism for use with runtime hash tables.
Definition: hash.h:460
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
bool IsEmpty() const
Returns true iff this token contains the empty string "".
Definition: token.h:288
Accessor to a attribute's definition in the prim definition.
USD_API Attribute(const Property &property)
Copy constructor from a Property to allow implicit conversion.
USD_API Attribute(Property &&property)
Move constructor from a Property to allow implicit conversion.
Attribute()=default
Default constructor returns an invalid attribute.
USD_API SdfValueTypeName GetTypeName() const
Returns the value type name of this attribute in the prim definition.
USD_API TfToken GetTypeNameToken() const
Returns the token value of the type name of this attribute in the prim definition.
bool GetFallbackValue(T *value) const
Retrieves the fallback value of type T for this attribute and stores it in value if possible.
Accessor to a property's definition in the prim definition.
USD_API const TfToken & GetName() const
Returns the name of the requested property.
Property()=default
Default constructor returns an invalid property.
USD_API SdfSpecType GetSpecType() const
Returns the spec type of this property in the prim definition.
USD_API bool IsRelationship() const
Return true if the property is a valid is a valid property in the prim definition and is a relationsh...
USD_API SdfVariability GetVariability() const
Returns the variability of this property in the prim definition.
bool GetMetadataByDictKey(const TfToken &key, const TfToken &keyPath, T *value) const
Retrieves the value at keyPath from the dictionary value for the dictionary metadata field named key,...
USD_API bool IsAttribute() const
Return true if the property is a valid is a valid property in the prim definition and is an attribute...
bool GetMetadata(const TfToken &key, T *value) const
Retrieves the fallback value for the metadata field named key, that is defined for this property in t...
USD_API TfTokenVector ListMetadataFields() const
Returns the list of names of metadata fields that are defined for this property in the prim definitio...
USD_API std::string GetDocumentation() const
Returns the documentation metadata defined by the prim definition for this property.
Accessor to a relationship's definition in the prim definition.
Relationship()=default
Default constructor returns an invalid relationship.
USD_API Relationship(Property &&property)
Move constructor from a Property to allow implicit conversion.
USD_API Relationship(const Property &property)
Copy constructor from a Property to allow implicit conversion.
Class representing the builtin definition of a prim given the schemas registered in the schema regist...
USD_API SdfRelationshipSpecHandle GetSchemaRelationshipSpec(const TfToken &relName) const
USD_API TfTokenVector ListPropertyMetadataFields(const TfToken &propName) const
Returns the list of names of metadata fields that are defined by this prim definition for property pr...
USD_API SdfSpecType GetSpecType(const TfToken &propName) const
Return the SdfSpecType for propName if it is a builtin property of the prim type represented by this ...
USD_API Attribute GetAttributeDefinition(const TfToken &attrName) const
Returns an attribute accessor the property named attrName if it is defined by this this prim definiti...
USD_API SdfPropertySpecHandle GetSchemaPropertySpec(const TfToken &propName) const
const TfTokenVector & GetPropertyNames() const
Return the list of names of builtin properties for this prim definition.
USD_API Relationship GetRelationshipDefinition(const TfToken &relName) const
Returns a relationship accessor the property named relName if it is defined by this this prim definit...
USD_API Property GetPropertyDefinition(const TfToken &propName) const
Returns a property accessor the property named propName if it is defined by this this prim definition...
USD_API UsdPrim FlattenTo(const UsdPrim &prim, SdfSpecifier newSpecSpecifier=SdfSpecifierOver) const
This is an overloaded member function, provided for convenience. It differs from the above function o...
bool GetPropertyMetadata(const TfToken &propName, const TfToken &key, T *value) const
Retrieves the fallback value for the metadata field named key, that is defined by this prim definitio...
USD_API UsdPrim FlattenTo(const UsdPrim &parent, const TfToken &name, SdfSpecifier newSpecSpecifier=SdfSpecifierOver) const
This is an overloaded member function, provided for convenience. It differs from the above function o...
USD_API SdfAttributeSpecHandle GetSchemaAttributeSpec(const TfToken &attrName) const
bool GetAttributeFallbackValue(const TfToken &attrName, T *value) const
Retrieves the fallback value for the attribute named attrName and stores it in value if possible.
const TfTokenVector & GetAppliedAPISchemas() const
Return the list of names of the API schemas that have been applied to this prim definition in order.
bool GetPropertyMetadataByDictKey(const TfToken &propName, const TfToken &key, const TfToken &keyPath, T *value) const
Retrieves the value at keyPath from the fallback dictionary value for the dictionary metadata field n...
USD_API std::string GetPropertyDocumentation(const TfToken &propName) const
Returns the documentation metadata defined by the prim definition for the property named propName if ...
bool GetMetadataByDictKey(const TfToken &key, const TfToken &keyPath, T *value) const
Retrieves the value at keyPath from the fallback dictionary value for the dictionary metadata field n...
bool GetMetadata(const TfToken &key, T *value) const
Retrieves the fallback value for the metadata field named key, that is defined by this prim definitio...
USD_API TfTokenVector ListMetadataFields() const
Returns the list of names of metadata fields that are defined by this prim definition for the prim it...
USD_API bool FlattenTo(const SdfLayerHandle &layer, const SdfPath &path, SdfSpecifier newSpecSpecifier=SdfSpecifierOver) const
Copies the contents of this prim definition to a prim spec on the given layer at the given path.
USD_API std::string GetDocumentation() const
Returns the documentation metadata defined by the prim definition for the prim itself.
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:117
Singleton registry that provides access to schema type information and the prim definitions for regis...
static USD_API bool IsDisallowedField(const TfToken &fieldName)
Returns true if the field fieldName cannot have fallback values specified in schemas.
Container::mapped_type * TfMapLookupPtr(Container &map, Key const &key)
Checks if an item exists in a map or TfHashMap, without copying it.
Definition: stl.h:124
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
SdfSpecType
An enum that specifies the type of an object.
Definition: types.h:68
SdfSpecifier
An enum that identifies the possible specifiers for an SdfPrimSpec.
Definition: types.h:100
SdfVariability
An enum that identifies variability types for attributes.
Definition: types.h:156