HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
primDefinition.h
Go to the documentation of this file.
1 //
2 // Copyright 2020 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_USD_PRIM_DEFINITION_H
25 #define PXR_USD_USD_PRIM_DEFINITION_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usd/api.h"
30 
31 #include "pxr/usd/sdf/layer.h"
35 #include "pxr/base/tf/hash.h"
36 #include "pxr/base/tf/hashmap.h"
37 
39 
40 /// Class representing the builtin definition of a prim given the schemas
41 /// registered in the schema registry. It provides access to the the builtin
42 /// properties and metadata of a prim whose type is defined by this definition.
43 ///
44 /// Instances of this class can only be created by the UsdSchemaRegistry.
46 {
47 public:
48  ~UsdPrimDefinition() = default;
49 
50  /// Return the list of names of builtin properties for this prim definition.
51  const TfTokenVector &GetPropertyNames() const { return _properties; }
52 
53  /// Return the list of names of the API schemas that have been applied to
54  /// this prim definition in order.
56  return _appliedAPISchemas;
57  }
58 
59  /// Return the SdfSpecType for \p propName if it is a builtin property of
60  /// the prim type represented by this prim definition. Otherwise return
61  /// SdfSpecTypeUnknown.
62  SdfSpecType GetSpecType(const TfToken &propName) const
63  {
64  if (const SdfPath *path = TfMapLookupPtr(_propPathMap, propName)) {
65  return _GetSchematics()->GetSpecType(*path);
66  }
67  return SdfSpecTypeUnknown;
68  }
69 
70  /// \deprecated Please use the API on UsdPrimDefinition itself to inquire
71  /// about metadata and properties.
72  ///
73  /// Returns the prim spec in the registered schematics that represents this
74  /// prim definition's prim type. This will be null for invalid prim types
75  /// or definitions composed for a prim with applied API schemas.
76  SdfPrimSpecHandle GetSchemaPrimSpec() const { return _primSpec; }
77 
78  /// Return the property spec that defines the fallback for the property
79  /// named \a propName on prims of this prim definition's type. Return null
80  /// if there is no such property spec.
81  SdfPropertySpecHandle GetSchemaPropertySpec(const TfToken& propName) const
82  {
83  if (const SdfPath *path = TfMapLookupPtr(_propPathMap, propName)) {
84  return _GetSchematics()->GetPropertyAtPath(*path);
85  }
86  return TfNullPtr;
87  }
88 
89  /// This is a convenience method. It is shorthand for
90  /// TfDynamic_cast<SdfAttributeSpecHandle>(
91  /// GetSchemaPropertySpec(primType, attrName));
92  SdfAttributeSpecHandle GetSchemaAttributeSpec(const TfToken& attrName) const
93  {
94  if (const SdfPath *path = TfMapLookupPtr(_propPathMap, attrName)) {
95  return _GetSchematics()->GetAttributeAtPath(*path);
96  }
97  return TfNullPtr;
98  }
99 
100  /// This is a convenience method. It is shorthand for
101  /// TfDynamic_cast<SdfRelationshipSpecHandle>(
102  /// GetSchemaPropertySpec(primType, relName));
103  SdfRelationshipSpecHandle GetSchemaRelationshipSpec(const TfToken& relName) const
104  {
105  if (const SdfPath *path = TfMapLookupPtr(_propPathMap, relName)) {
106  return _GetSchematics()->GetRelationshipAtPath(*path);
107  }
108  return TfNullPtr;
109  }
110 
111  /// Retrieves the fallback value for the attribute named \p attrName and
112  /// stores it in \p value if possible.
113  ///
114  /// Returns true if the attribute exists in this prim definition and it has
115  /// a fallback value defined. Returns false otherwise.
116  template <class T>
117  bool GetAttributeFallbackValue(const TfToken &attrName, T *value) const
118  {
119  return _HasField(attrName, SdfFieldKeys->Default, value);
120  }
121 
122  /// Returns the list of names of metadata fields that are defined by this
123  /// prim definition for the prim itself.
125  {
126  return _ListMetadataFields(TfToken());
127  }
128 
129  /// Retrieves the fallback value for the metadata field named \p key, that
130  /// is defined by this prim definition for the prim itself and stores it in
131  /// \p value if possible.
132  ///
133  /// Returns true if a fallback value is defined for the given metadata
134  /// \p key. Returns false otherwise.
135  template <class T>
136  bool GetMetadata(const TfToken &key, T* value) const
137  {
139  return false;
140  }
141  return _HasField(TfToken(), key, value);
142  }
143 
144  /// Retrieves the value at \p keyPath from the fallback dictionary value
145  /// for the dictionary metadata field named \p key, that is defined by this
146  /// prim definition for the prim itself, and stores it in \p value if
147  /// possible.
148  ///
149  /// Returns true if a fallback dictionary value is defined for the given
150  /// metadata \p key and it contains a value at \p keyPath. Returns false
151  /// otherwise.
152  template <class T>
153  bool GetMetadataByDictKey(const TfToken &key,
154  const TfToken &keyPath, T* value) const
155  {
157  return false;
158  }
159  return _HasFieldDictKey(TfToken(), key, keyPath, value);
160  }
161 
162  /// Returns the documentation metadata defined by the prim definition for
163  /// the prim itself.
164  USD_API
166 
167  /// Returns the list of names of metadata fields that are defined by this
168  /// prim definition for property \p propName if a property named \p propName
169  /// exists.
171  {
172  return propName.IsEmpty() ?
173  TfTokenVector() : _ListMetadataFields(propName);
174  }
175 
176  /// Retrieves the fallback value for the metadata field named \p key, that
177  /// is defined by this prim definition for the property named \p propName,
178  /// and stores it in \p value if possible.
179  ///
180  /// Returns true if a fallback value is defined for the given metadata
181  /// \p key for the named property. Returns false otherwise.
182  template <class T>
184  const TfToken &propName, const TfToken &key, T* value) const
185  {
186  if (propName.IsEmpty() || UsdSchemaRegistry::IsDisallowedField(key)) {
187  return false;
188  }
189  return _HasField(propName, key, value);
190  }
191 
192  /// Retrieves the value at \p keyPath from the fallback dictionary value
193  /// for the dictionary metadata field named \p key, that is defined by this
194  /// prim definition for the property named \p propName, and stores it in
195  /// \p value if possible.
196  ///
197  /// Returns true if a fallback dictionary value is defined for the given
198  /// metadata \p key for the named property and it contains a value at
199  /// \p keyPath. Returns false otherwise.
200  template <class T>
202  const TfToken &propName, const TfToken &key,
203  const TfToken &keyPath, T* value) const
204  {
205  if (propName.IsEmpty() || UsdSchemaRegistry::IsDisallowedField(key)) {
206  return false;
207  }
208  return _HasFieldDictKey(propName, key, keyPath, value);
209  }
210 
211  /// Returns the documentation metadata defined by the prim definition for
212  /// the property named \p propName if it exists.
213  USD_API
214  std::string GetPropertyDocumentation(const TfToken &propName) const;
215 
216 private:
217  // Only the UsdSchemaRegistry can construct prim definitions.
218  friend class UsdSchemaRegistry;
219 
220  // Friended private accessor for use by UsdStage when composing metadata
221  // values for value resolution. The public GetMetadata functions perform
222  // the extra step of filtering out disallowed or private metadata fields
223  // from the SdfSpecs before retrieving metadata. Value resolution does not
224  // want to pay that extra cost so uses this function instead.
225  template <class T>
226  friend bool Usd_GetFallbackValue(const UsdPrimDefinition &primDef,
227  const TfToken &propName,
228  const TfToken &fieldName,
229  const TfToken &keyPath,
230  T *value)
231  {
232  // Try to read fallback value.
233  return keyPath.IsEmpty() ?
234  primDef._HasField(propName, fieldName, value) :
235  primDef._HasFieldDictKey(propName, fieldName, keyPath, value);
236  }
237 
238  /// It is preferable to use the _HasField and _HasFieldDictKey methods to
239  /// access property field values, as opposed to getting a spec handle from
240  /// the GetSchemaXXXSpec functions, as these methods are faster.
241  template <class T>
242  bool _HasField(const TfToken& propName,
243  const TfToken& fieldName,
244  T* value) const
245  {
246  if (const SdfPath *path = TfMapLookupPtr(_propPathMap, propName)) {
247  return _GetSchematics()->HasField(*path, fieldName, value);
248  }
249  return false;
250  }
251 
252  template <class T>
253  bool _HasFieldDictKey(const TfToken& propName,
254  const TfToken& fieldName,
255  const TfToken& keyPath,
256  T* value) const
257  {
258  if (const SdfPath *path = TfMapLookupPtr(_propPathMap, propName)) {
259  return _GetSchematics()->HasFieldDictKey(
260  *path, fieldName, keyPath, value);
261  }
262  return false;
263  }
264 
265  UsdPrimDefinition() = default;
266 
267  UsdPrimDefinition(const SdfPrimSpecHandle &primSpec, bool isAPISchema);
268 
269  // Access to the schema registry's schematics.
270  const SdfLayerRefPtr &_GetSchematics() const {
271  return UsdSchemaRegistry::GetInstance()._schematics;
272  }
273 
274  USD_API
275  TfTokenVector _ListMetadataFields(const TfToken &propName) const;
276 
277  // Helpers for constructing the prim definition.
278  USD_API
279  void _SetPrimSpec(const SdfPrimSpecHandle &primSpec,
280  bool providesPrimMetadata);
281 
282  USD_API
283  void _ApplyPropertiesFromPrimDef(const UsdPrimDefinition &primDef,
284  const std::string &propPrefix = "");
285 
286  void _AddProperty(const TfToken &name, const SdfPath &schemaPath)
287  {
288  // Adds the property name with schema path to the prim def. This makes
289  // sure we overwrite the original property path with the new path if it
290  // already exists, but makes sure we don't end up with duplicate names
291  // in the property names list.
292  auto it = _propPathMap.insert(std::make_pair(name, schemaPath));
293  if (it.second) {
294  _properties.push_back(name);
295  } else {
296  it.first->second = schemaPath;
297  }
298  }
299 
300  SdfPrimSpecHandle _primSpec;
301 
302  // Map for caching the paths to each property spec in the schematics by
303  // property name.
304  using _PrimTypePropNameToPathMap =
306  _PrimTypePropNameToPathMap _propPathMap;
307  TfTokenVector _appliedAPISchemas;
308 
309  // Cached list of property names.
310  TfTokenVector _properties;
311 };
312 
314 
315 #endif //PXR_USD_USD_PRIM_DEFINITION_H
SdfSpecType GetSpecType(const TfToken &propName) const
friend class UsdPrimDefinition
GLuint const GLchar * name
Definition: glew.h:1814
#define USD_API
Definition: api.h:40
SDF_API SdfAttributeSpecHandle GetAttributeAtPath(const SdfPath &path)
SDF_API SdfRelationshipSpecHandle GetRelationshipAtPath(const SdfPath &path)
TF_API const TfNullPtrType TfNullPtr
~UsdPrimDefinition()=default
SdfPrimSpecHandle GetSchemaPrimSpec() const
TfTokenVector ListMetadataFields() const
const TfTokenVector & GetAppliedAPISchemas() const
friend bool Usd_GetFallbackValue(const UsdPrimDefinition &primDef, const TfToken &propName, const TfToken &fieldName, const TfToken &keyPath, T *value)
std::pair< iterator, bool > insert(const value_type &v)
Definition: hashmap.h:329
bool GetPropertyMetadataByDictKey(const TfToken &propName, const TfToken &key, const TfToken &keyPath, T *value) const
SDF_API SdfSpecType GetSpecType(const SdfPath &path) const
bool GetPropertyMetadata(const TfToken &propName, const TfToken &key, T *value) const
Definition: token.h:87
SDF_API bool HasField(const SdfPath &path, const TfToken &fieldName, VtValue *value=NULL) const
USD_API std::string GetPropertyDocumentation(const TfToken &propName) const
Container::mapped_type * TfMapLookupPtr(Container &map, Key const &key)
Definition: stl.h:143
USD_API std::string GetDocumentation() const
bool GetAttributeFallbackValue(const TfToken &attrName, T *value) const
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:446
SdfRelationshipSpecHandle GetSchemaRelationshipSpec(const TfToken &relName) const
Definition: path.h:288
SDF_API bool HasFieldDictKey(const SdfPath &path, const TfToken &fieldName, const TfToken &keyPath, VtValue *value=NULL) const
SdfPropertySpecHandle GetSchemaPropertySpec(const TfToken &propName) const
bool GetMetadataByDictKey(const TfToken &key, const TfToken &keyPath, T *value) const
GLsizei const GLchar *const * path
Definition: glew.h:6461
GLsizei const GLchar *const * string
Definition: glew.h:1844
static USD_API bool IsDisallowedField(const TfToken &fieldName)
const TfTokenVector & GetPropertyNames() const
Return the list of names of builtin properties for this prim definition.
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
SdfSpecType
Definition: types.h:91
static USD_API UsdSchemaRegistry & GetInstance()
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
bool GetMetadata(const TfToken &key, T *value) const
SDF_API SdfPropertySpecHandle GetPropertyAtPath(const SdfPath &path)
SdfAttributeSpecHandle GetSchemaAttributeSpec(const TfToken &attrName) const
GLsizei const GLfloat * value
Definition: glew.h:1849
bool IsEmpty() const
Returns true iff this token contains the empty string "".
Definition: token.h:302
TfTokenVector ListPropertyMetadataFields(const TfToken &propName) const