primDefinition.h
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"
29 #include "pxr/usd/usd/schemaRegistry.h"
30 
31 #include "pxr/usd/sdf/layer.h"
35 #include "pxr/base/tf/hash.h"
36 
37 #include <unordered_map>
38 
39 PXR_NAMESPACE_OPEN_SCOPE
40 
41 class UsdPrim;
42 
49 {
50 public:
51  ~UsdPrimDefinition() = default;
52 
54  const TfTokenVector &GetPropertyNames() const { return _properties; }
55 
59  return _appliedAPISchemas;
60  }
61 
65  SdfSpecType GetSpecType(const TfToken &propName) const
66  {
67  if (const SdfPath *path = TfMapLookupPtr(_propPathMap, propName)) {
68  return _GetSchematics()->GetSpecType(*path);
69  }
70  return SdfSpecTypeUnknown;
71  }
72 
76  SdfPropertySpecHandle GetSchemaPropertySpec(const TfToken& propName) const
77  {
78  if (const SdfPath *path = TfMapLookupPtr(_propPathMap, propName)) {
79  return _GetSchematics()->GetPropertyAtPath(*path);
80  }
81  return TfNullPtr;
82  }
83 
87  SdfAttributeSpecHandle GetSchemaAttributeSpec(const TfToken& attrName) const
88  {
89  if (const SdfPath *path = TfMapLookupPtr(_propPathMap, attrName)) {
90  return _GetSchematics()->GetAttributeAtPath(*path);
91  }
92  return TfNullPtr;
93  }
94 
98  SdfRelationshipSpecHandle GetSchemaRelationshipSpec(const TfToken& relName) const
99  {
100  if (const SdfPath *path = TfMapLookupPtr(_propPathMap, relName)) {
101  return _GetSchematics()->GetRelationshipAtPath(*path);
102  }
103  return TfNullPtr;
104  }
105 
111  template <class T>
112  bool GetAttributeFallbackValue(const TfToken &attrName, T *value) const
113  {
114  return _HasField(attrName, SdfFieldKeys->Default, value);
115  }
116 
120  {
121  return _ListMetadataFields(TfToken());
122  }
123 
130  template <class T>
131  bool GetMetadata(const TfToken &key, T* value) const
132  {
134  return false;
135  }
136  return _HasField(TfToken(), key, value);
137  }
138 
147  template <class T>
148  bool GetMetadataByDictKey(const TfToken &key,
149  const TfToken &keyPath, T* value) const
150  {
152  return false;
153  }
154  return _HasFieldDictKey(TfToken(), key, keyPath, value);
155  }
156 
159  USD_API
160  std::string GetDocumentation() const;
161 
166  {
167  return propName.IsEmpty() ?
168  TfTokenVector() : _ListMetadataFields(propName);
169  }
170 
177  template <class T>
179  const TfToken &propName, const TfToken &key, T* value) const
180  {
181  if (propName.IsEmpty() || UsdSchemaRegistry::IsDisallowedField(key)) {
182  return false;
183  }
184  return _HasField(propName, key, value);
185  }
186 
195  template <class T>
197  const TfToken &propName, const TfToken &key,
198  const TfToken &keyPath, T* value) const
199  {
200  if (propName.IsEmpty() || UsdSchemaRegistry::IsDisallowedField(key)) {
201  return false;
202  }
203  return _HasFieldDictKey(propName, key, keyPath, value);
204  }
205 
208  USD_API
209  std::string GetPropertyDocumentation(const TfToken &propName) const;
210 
234  USD_API
235  bool FlattenTo(const SdfLayerHandle &layer,
236  const SdfPath &path,
237  SdfSpecifier newSpecSpecifier = SdfSpecifierOver) const;
238 
243  USD_API
244  UsdPrim FlattenTo(const UsdPrim &parent,
245  const TfToken &name,
246  SdfSpecifier newSpecSpecifier = SdfSpecifierOver) const;
247 
251  USD_API
252  UsdPrim FlattenTo(const UsdPrim &prim,
253  SdfSpecifier newSpecSpecifier = SdfSpecifierOver) const;
254 
255 
256 private:
257  // Only the UsdSchemaRegistry can construct prim definitions.
258  friend class UsdSchemaRegistry;
259 
260  // Friended private accessor for use by UsdStage when composing metadata
261  // values for value resolution. The public GetMetadata functions perform
262  // the extra step of filtering out disallowed or private metadata fields
263  // from the SdfSpecs before retrieving metadata. Value resolution does not
264  // want to pay that extra cost so uses this function instead.
265  template <class T>
266  friend bool Usd_GetFallbackValue(const UsdPrimDefinition &primDef,
267  const TfToken &propName,
268  const TfToken &fieldName,
269  const TfToken &keyPath,
270  T *value)
271  {
272  // Try to read fallback value.
273  return keyPath.IsEmpty() ?
274  primDef._HasField(propName, fieldName, value) :
275  primDef._HasFieldDictKey(propName, fieldName, keyPath, value);
276  }
277 
281  template <class T>
282  bool _HasField(const TfToken& propName,
283  const TfToken& fieldName,
284  T* value) const
285  {
286  if (const SdfPath *path = TfMapLookupPtr(_propPathMap, propName)) {
287  return _GetSchematics()->HasField(*path, fieldName, value);
288  }
289  return false;
290  }
291 
292  template <class T>
293  bool _HasFieldDictKey(const TfToken& propName,
294  const TfToken& fieldName,
295  const TfToken& keyPath,
296  T* value) const
297  {
298  if (const SdfPath *path = TfMapLookupPtr(_propPathMap, propName)) {
299  return _GetSchematics()->HasFieldDictKey(
300  *path, fieldName, keyPath, value);
301  }
302  return false;
303  }
304 
305  UsdPrimDefinition() = default;
306 
307  // Constructor that initializes the prim definition with prim path of
308  // the primary prim spec of this definition's schema type in the schematics.
309  // This does not populate any of the properties of the prim definition.
310  UsdPrimDefinition(const SdfPath &schematicsPrimPath, bool isAPISchema);
311 
312  // Access to the schema registry's schematics.
313  const SdfLayerRefPtr &_GetSchematics() const {
314  return UsdSchemaRegistry::GetInstance()._schematics;
315  }
316 
317  USD_API
318  TfTokenVector _ListMetadataFields(const TfToken &propName) const;
319 
320  // Helpers for constructing the prim definition.
321  USD_API
322  void _ComposePropertiesFromPrimSpec(
323  const SdfPrimSpecHandle &weakerPrimSpec,
324  const std::string &propPrefix = "");
325 
326  USD_API
327  void _ComposePropertiesFromPrimDef(
328  const UsdPrimDefinition &weakerPrimDef,
329  const std::string &propPrefix = "");
330 
331  // Path to the prim in the schematics for this prim definition.
332  SdfPath _schematicsPrimPath;
333 
334  // Map for caching the paths to each property spec in the schematics by
335  // property name.
336  using _PrimTypePropNameToPathMap =
337  std::unordered_map<TfToken, SdfPath, TfToken::HashFunctor>;
338  _PrimTypePropNameToPathMap _propPathMap;
339  TfTokenVector _appliedAPISchemas;
340 
341  // Cached list of property names.
342  TfTokenVector _properties;
343 };
344 
345 PXR_NAMESPACE_CLOSE_SCOPE
346 
347 #endif //PXR_USD_USD_PRIM_DEFINITION_H
bool IsEmpty() const
Returns true iff this token contains the empty string "".
Definition: token.h:302
const TfTokenVector & GetPropertyNames() const
Return the list of names of builtin properties for this prim definition.
SdfSpecType GetSpecType(const TfToken &propName) const
Return the SdfSpecType for propName if it is a builtin property of the prim type represented by this ...
TfTokenVector ListPropertyMetadataFields(const TfToken &propName) const
Returns the list of names of metadata fields that are defined by this prim definition for property pr...
SdfPropertySpecHandle GetSchemaPropertySpec(const TfToken &propName) const
Return the property spec that defines the fallback for the property named propName on prims of this p...
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...
SdfRelationshipSpecHandle GetSchemaRelationshipSpec(const TfToken &relName) const
This is a convenience method.
USD_API std::string GetPropertyDocumentation(const TfToken &propName) const
Returns the documentation metadata defined by the prim definition for the property named propName if ...
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:87
const TfTokenVector & GetAppliedAPISchemas() const
Return the list of names of the API schemas that have been applied to this prim definition in order.
USD_API std::string GetDocumentation() const
Returns the documentation metadata defined by the prim definition for the prim itself.
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.
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...
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:132
SdfSpecifier
An enum that identifies the possible specifiers for an SdfPrimSpec.
Definition: types.h:123
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:288
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...
static USD_API bool IsDisallowedField(const TfToken &fieldName)
Returns true if the field fieldName cannot have fallback values specified in schemas.
SdfSpecType
An enum that specifies the type of an object.
Definition: types.h:91
SdfAttributeSpecHandle GetSchemaAttributeSpec(const TfToken &attrName) const
This is a convenience method.
Class representing the builtin definition of a prim given the schemas registered in the schema regist...
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:143
TfTokenVector ListMetadataFields() const
Returns the list of names of metadata fields that are defined by this prim definition for the prim it...
Singleton registry that provides access to schema type information and the prim definitions for regis...
bool GetAttributeFallbackValue(const TfToken &attrName, T *value) const
Retrieves the fallback value for the attribute named attrName and stores it in value if possible.