HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
schemaRegistry.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 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_SCHEMA_REGISTRY_H
25 #define PXR_USD_USD_SCHEMA_REGISTRY_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usd/api.h"
29 #include "pxr/usd/usd/common.h"
30 
31 #include "pxr/usd/sdf/layer.h"
32 #include "pxr/usd/sdf/primSpec.h"
33 
34 #include "pxr/base/tf/hash.h"
35 #include "pxr/base/tf/singleton.h"
36 #include "pxr/base/tf/hashmap.h"
37 
39 
42 
43 class UsdPrimDefinition;
44 
45 /// \class UsdSchemaRegistry
46 ///
47 /// Singleton registry that provides access to schema type information and
48 /// the prim definitions for registered Usd "IsA" and applied API schema
49 /// types. It also contains the data from the generated schemas that is used
50 /// by prim definitions to provide properties and fallbacks.
51 ///
52 /// The data contained herein comes from the generatedSchema.usda file
53 /// (generated when a schema.usda file is processed by \em usdGenSchema)
54 /// of each schema-defining module. The registry expects each schema type to
55 /// be represented as a single prim spec with its inheritance flattened, i.e.
56 /// the prim spec contains a union of all its local and class inherited property
57 /// specs and metadata fields.
58 ///
59 /// It is used by the Usd core, via UsdPrimDefinition, to determine how to
60 /// create scene description for unauthored "built-in" properties of schema
61 /// classes, to enumerate all properties for a given schema class, and finally
62 /// to provide fallback values for unauthored built-in properties.
63 ///
64 class UsdSchemaRegistry : public TfWeakBase, hboost::noncopyable {
65 public:
66  USD_API
69  }
70 
71  /// Return the type name in the USD schema for prims or API schemas of the
72  /// given registered \p schemaType.
73  USD_API
74  static TfToken GetSchemaTypeName(const TfType &schemaType);
75 
76  /// Return the type name in the USD schema for prims or API schemas of the
77  /// given registered \p SchemaType.
78  template <class SchemaType>
79  static
81  return GetSchemaTypeName(SchemaType::_GetStaticTfType());
82  }
83 
84  /// Return the type name in the USD schema for concrete prim types only from
85  /// the given registered \p schemaType.
86  USD_API
87  static TfToken GetConcreteSchemaTypeName(const TfType &schemaType);
88 
89  /// Return the type name in the USD schema for API schema types only from
90  /// the given registered \p schemaType.
91  USD_API
92  static TfToken GetAPISchemaTypeName(const TfType &schemaType);
93 
94  /// Return the TfType of the schema corresponding to the given prim or API
95  /// schema name \p typeName. This the inverse of GetSchemaTypeName.
96  USD_API
97  static TfType GetTypeFromSchemaTypeName(const TfToken &typeName);
98 
99  /// Return the TfType of the schema corresponding to the given concrete prim
100  /// type name \p typeName. This the inverse of GetConcreteSchemaTypeName.
101  USD_API
102  static TfType GetConcreteTypeFromSchemaTypeName(const TfToken &typeName);
103 
104  /// Return the TfType of the schema corresponding to the given API schema
105  /// type name \p typeName. This the inverse of GetAPISchemaTypeNAme.
106  USD_API
107  static TfType GetAPITypeFromSchemaTypeName(const TfToken &typeName);
108 
109  /// Returns true if the field \p fieldName cannot have fallback values
110  /// specified in schemas.
111  ///
112  /// Fields are generally disallowed because their fallback values
113  /// aren't used. For instance, fallback values for composition arcs
114  /// aren't used during composition, so allowing them to be set in
115  /// schemas would be misleading.
116  USD_API
117  static bool IsDisallowedField(const TfToken &fieldName);
118 
119  /// Returns true if the prim type \p primType inherits from \ref UsdTyped.
120  USD_API
121  static bool IsTyped(const TfType& primType);
122 
123  /// Returns the kind of the schema the given \p schemaType represents.
124  ///
125  /// This returns UsdSchemaKind::Invalid if \p schemaType is not a valid
126  /// schema type or if the kind cannot be determined from type's plugin
127  /// information.
128  USD_API
129  static UsdSchemaKind GetSchemaKind(const TfType &schemaType);
130 
131  /// Returns the kind of the schema the given \p typeName represents.
132  ///
133  /// This returns UsdSchemaKind::Invalid if \p typeName is not a valid
134  /// schema type name or if the kind cannot be determined from type's plugin
135  /// information.
136  USD_API
137  static UsdSchemaKind GetSchemaKind(const TfToken &typeName);
138 
139  /// Returns true if the prim type \p primType is instantiable
140  /// in scene description.
141  USD_API
142  static bool IsConcrete(const TfType& primType);
143 
144  /// Returns true if the prim type \p primType is instantiable
145  /// in scene description.
146  USD_API
147  static bool IsConcrete(const TfToken& primType);
148 
149  /// Returns true if \p apiSchemaType is an applied API schema type.
150  USD_API
151  static bool IsAppliedAPISchema(const TfType& apiSchemaType);
152 
153  /// Returns true if \p apiSchemaType is an applied API schema type.
154  USD_API
155  static bool IsAppliedAPISchema(const TfToken& apiSchemaType);
156 
157  /// Returns true if \p apiSchemaType is a multiple-apply API schema type.
158  USD_API
159  static bool IsMultipleApplyAPISchema(const TfType& apiSchemaType);
160 
161  /// Returns true if \p apiSchemaType is a multiple-apply API schema type.
162  USD_API
163  static bool IsMultipleApplyAPISchema(const TfToken& apiSchemaType);
164 
165  /// Finds the TfType of a schema with \p typeName
166  ///
167  /// This is primarily for when you have been provided Schema typeName
168  /// (perhaps from a User Interface or Script) and need to identify
169  /// if a prim's type inherits/is that typeName. If the type name IS known,
170  /// then using the schema class is preferred.
171  ///
172  /// \code{.py}
173  /// # This code attempts to match all prims on a stage to a given
174  /// # user specified type, making the traditional schema based idioms not
175  /// # applicable.
176  /// data = parser.parse_args()
177  /// tfType = UsdSchemaRegistry.GetTypeFromName(data.type)
178  /// matchedPrims = [p for p in stage.Traverse() if p.IsA(tfType)]
179  /// \endcode
180  ///
181  /// \note It's worth noting that
182  /// GetTypeFromName("Sphere") == GetTypeFromName("UsdGeomSphere"), as
183  /// this function resolves both the Schema's C++ class name and any
184  /// registered aliases from a libraries plugInfo.json file. However,
185  /// GetTypeFromName("Boundable") != GetTypeFromName("UsdGeomBoundable")
186  /// because type aliases don't get registered for abstract schema types.
187  USD_API
188  static TfType GetTypeFromName(const TfToken& typeName);
189 
190  /// Returns the schema type name and the instance name parsed from the
191  /// given \p apiSchemaName
192  ///
193  /// \p apiSchemaName is the name of an applied schema as it appears in
194  /// the list of applied schemas on a prim. For single-apply API schemas
195  /// the name will just be the schema type name. For multiple-apply schemas
196  /// the name should include the schema type name and the applied instance
197  /// name separated by a namespace delimiter, for example
198  /// 'CollectionAPI:plasticStuff'.
199  ///
200  /// This function returns the separated schema type name and instance name
201  /// component tokens if possible, otherwise it returns the \p apiSchemaName
202  /// as the type name and an empty instance name.
203  ///
204  /// Note that no validation is done on the returned tokens. Clients are
205  /// advised to use GetTypeFromSchemaTypeName() to validate the typeName
206  /// token.
207  ///
208  /// \sa UsdPrim::AddAppliedSchema(const TfToken&) const
209  /// \sa UsdPrim::GetAppliedSchemas() const
210  USD_API
211  static std::pair<TfToken, TfToken> GetTypeNameAndInstance(
212  const TfToken &apiSchemaName);
213 
214  /// Returns true if the given \p instanceName is an allowed instance name
215  /// for the multiple apply API schema named \p apiSchemaName.
216  ///
217  /// Any instance name that matches the name of a property provided by the
218  /// API schema is disallowed and will return false. If the schema type
219  /// has plugin metadata that specifies allowed instance names, then only
220  /// those specified names are allowed for the schema type.
221  /// If the instance name is empty or the API is not a multiple apply schema,
222  /// this will return false.
223  USD_API
224  static bool IsAllowedAPISchemaInstanceName(
225  const TfToken &apiSchemaName,
226  const TfToken &instanceName);
227 
228  /// Returns a list of prim type names that the given \p apiSchemaName can
229  /// only be applied to.
230  ///
231  /// A non-empty list indicates that the API schema can only be applied to
232  /// prim that are or derive from prim type names in the list. If the list
233  /// is empty, the API schema can be applied to prims of any type.
234  ///
235  /// If a non-empty \p instanceName is provided, this will first look for
236  /// a list of "can only apply to" names specific to that instance of the API
237  /// schema and return that if found. If a list is not found for the specific
238  /// instance, it will fall back to looking for a "can only apply to" list
239  /// for just the schema name itself.
240  USD_API
242  const TfToken &apiSchemaName,
243  const TfToken &instanceName = TfToken());
244 
245  /// Returns a map of the names of all registered auto apply API schemas
246  /// to the list of type names each is registered to be auto applied to.
247  ///
248  /// The list of type names to apply to will directly match what is specified
249  /// in the plugin metadata for each schema type. While auto apply schemas do
250  /// account for the existence and validity of the type names and expand to
251  /// include derived types of the listed types, the type lists returned by
252  /// this function do not.
253  USD_API
254  static const std::map<TfToken, TfTokenVector> &GetAutoApplyAPISchemas();
255 
256  /// Collects all the additional auto apply schemas that can be defined in
257  /// a plugin through "AutoApplyAPISchemas" metadata and adds the mappings
258  /// to \p autoApplyAPISchemas.
259  ///
260  /// These are separate from the auto-apply schemas that are built in to the
261  /// applied API schema types themselves and can be defined in any plugin to
262  /// map any applied API schema to any concrete prim type.
263  ///
264  /// Note that GetAutoApplyAPISchemas will already include API schemas
265  /// collected from this method; this function is provided for clients that
266  /// may want to collect just these plugin API schema mappings.
267  USD_API
269  std::map<TfToken, TfTokenVector> *autoApplyAPISchemas);
270 
271  /// Returns the namespace prefix that is prepended to all properties of
272  /// the given \p multiApplyAPISchemaName.
273  USD_API
275  const TfToken &multiApplyAPISchemaName) const;
276 
277  /// Finds the prim definition for the given \p typeName token if
278  /// \p typeName is a registered concrete typed schema type. Returns null if
279  /// it is not.
281  const TfToken &typeName) const {
282  auto it = _concreteTypedPrimDefinitions.find(typeName);
283  return it != _concreteTypedPrimDefinitions.end() ? it->second : nullptr;
284  }
285 
286  /// Finds the prim definition for the given \p typeName token if
287  /// \p typeName is a registered applied API schema type. Returns null if
288  /// it is not.
290  const TfToken &typeName) const {
291  auto it = _appliedAPIPrimDefinitions.find(typeName);
292  return it != _appliedAPIPrimDefinitions.end() ? it->second : nullptr;
293  }
294 
295  /// Returns the empty prim definition.
297  return _emptyPrimDefinition;
298  }
299 
300  /// Composes and returns a new UsdPrimDefinition from the given \p primType
301  /// and list of \p appliedSchemas. This prim definition will contain a union
302  /// of properties from the registered prim definitions of each of the
303  /// provided types.
304  USD_API
305  std::unique_ptr<UsdPrimDefinition>
307  const TfToken &primType, const TfTokenVector &appliedAPISchemas) const;
308 
309  /// Returns a dictionary mapping concrete schema prim type names to a
310  /// VtTokenArray of fallback prim type names if fallback types are defined
311  /// for the schema type in its registered schema.
312  ///
313  /// The standard use case for this to provide schema defined metadata that
314  /// can be saved with a stage to inform an older version of USD - that
315  /// may not have some schema types - as to which types it can used instead
316  /// when encountering a prim of one these types.
317  ///
318  /// \sa UsdStage::WriteFallbackPrimTypes
319  /// \sa \ref Usd_OM_FallbackPrimTypes
321  return _fallbackPrimTypes;
322  }
323 
324 private:
326 
328 
329  void _FindAndAddPluginSchema();
330 
331  void _ApplyAPISchemasToPrimDefinition(
332  UsdPrimDefinition *primDef, const TfTokenVector &appliedAPISchemas) const;
333 
334  SdfLayerRefPtr _schematics;
335  typedef TfHashMap<TfToken, UsdPrimDefinition *,
337 
338  _TypeNameToPrimDefinitionMap _concreteTypedPrimDefinitions;
339  _TypeNameToPrimDefinitionMap _appliedAPIPrimDefinitions;
340  UsdPrimDefinition *_emptyPrimDefinition;
341 
343  _multipleApplyAPISchemaNamespaces;
344 
345  VtDictionary _fallbackPrimTypes;
346 
347  friend class UsdPrimDefinition;
348 };
349 
351 
352 // Utility function for extracting the metadata about applying API schemas from
353 // the plugin metadata for the schema's type. It is useful for certain clients
354 // to be able to access this plugin data in the same way that the
355 // UsdSchemaRegistry does.
357  const TfType &apiSchemaType,
358  const TfToken &apiSchemaName,
359  std::map<TfToken, TfTokenVector> *autoApplyAPISchemasMap,
360  TfHashMap<TfToken, TfTokenVector, TfHash> *canOnlyApplyAPISchemasMap,
361  TfHashMap<TfToken, TfToken::Set, TfHash> *allowedInstanceNamesMap);
362 
364 
365 #endif //PXR_USD_USD_SCHEMA_REGISTRY_H
static T & GetInstance()
Definition: singleton.h:137
const UsdPrimDefinition * FindAppliedAPIPrimDefinition(const TfToken &typeName) const
#define USD_API
Definition: api.h:40
static USD_API TfType GetConcreteTypeFromSchemaTypeName(const TfToken &typeName)
iterator end()
Definition: hashmap.h:318
const VtDictionary & GetFallbackPrimTypes() const
USD_API TfToken GetPropertyNamespacePrefix(const TfToken &multiApplyAPISchemaName) const
const UsdPrimDefinition * GetEmptyPrimDefinition() const
Returns the empty prim definition.
static USD_API TfType GetTypeFromName(const TfToken &typeName)
Functor to use for hash maps from tokens to other things.
Definition: token.h:166
static USD_API bool IsConcrete(const TfType &primType)
static USD_API UsdSchemaKind GetSchemaKind(const TfType &schemaType)
static USD_API bool IsAllowedAPISchemaInstanceName(const TfToken &apiSchemaName, const TfToken &instanceName)
UsdSchemaKind
Definition: common.h:127
Definition: token.h:87
static TfToken GetSchemaTypeName()
static USD_API bool IsTyped(const TfType &primType)
Returns true if the prim type primType inherits from UsdTyped.
static USD_API void CollectAddtionalAutoApplyAPISchemasFromPlugins(std::map< TfToken, TfTokenVector > *autoApplyAPISchemas)
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
static USD_API const TfTokenVector & GetAPISchemaCanOnlyApplyToTypeNames(const TfToken &apiSchemaName, const TfToken &instanceName=TfToken())
void Usd_GetAPISchemaPluginApplyToInfoForType(const TfType &apiSchemaType, const TfToken &apiSchemaName, std::map< TfToken, TfTokenVector > *autoApplyAPISchemasMap, TfHashMap< TfToken, TfTokenVector, TfHash > *canOnlyApplyAPISchemasMap, TfHashMap< TfToken, TfToken::Set, TfHash > *allowedInstanceNamesMap)
static USD_API TfToken GetConcreteSchemaTypeName(const TfType &schemaType)
static USD_API bool IsDisallowedField(const TfToken &fieldName)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
static USD_API UsdSchemaRegistry & GetInstance()
static USD_API TfToken GetAPISchemaTypeName(const TfType &schemaType)
static USD_API TfType GetAPITypeFromSchemaTypeName(const TfToken &typeName)
static USD_API bool IsMultipleApplyAPISchema(const TfType &apiSchemaType)
Returns true if apiSchemaType is a multiple-apply API schema type.
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
static USD_API std::pair< TfToken, TfToken > GetTypeNameAndInstance(const TfToken &apiSchemaName)
Definition: type.h:64
USD_API std::unique_ptr< UsdPrimDefinition > BuildComposedPrimDefinition(const TfToken &primType, const TfTokenVector &appliedAPISchemas) const
static USD_API bool IsAppliedAPISchema(const TfType &apiSchemaType)
Returns true if apiSchemaType is an applied API schema type.
static USD_API const std::map< TfToken, TfTokenVector > & GetAutoApplyAPISchemas()
USD_API_TEMPLATE_CLASS(TfSingleton< UsdSchemaRegistry >)
static USD_API TfType GetTypeFromSchemaTypeName(const TfToken &typeName)
PXR_NAMESPACE_OPEN_SCOPE SDF_DECLARE_HANDLES(SdfAttributeSpec)
const UsdPrimDefinition * FindConcretePrimDefinition(const TfToken &typeName) const