HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
apiSchemaBase.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 USD_GENERATED_APISCHEMABASE_H
25 #define USD_GENERATED_APISCHEMABASE_H
26 
27 /// \file usd/apiSchemaBase.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usd/api.h"
31 #include "pxr/usd/usd/schemaBase.h"
32 #include "pxr/usd/usd/prim.h"
33 #include "pxr/usd/usd/stage.h"
34 
35 #include "pxr/base/vt/value.h"
36 
37 #include "pxr/base/gf/vec3d.h"
38 #include "pxr/base/gf/vec3f.h"
39 #include "pxr/base/gf/matrix4d.h"
40 
41 #include "pxr/base/tf/token.h"
42 #include "pxr/base/tf/type.h"
43 
45 
46 class SdfAssetPath;
47 
48 // -------------------------------------------------------------------------- //
49 // APISCHEMABASE //
50 // -------------------------------------------------------------------------- //
51 
52 /// \class UsdAPISchemaBase
53 ///
54 /// The base class for all \em API schemas.
55 ///
56 /// An API schema provides an interface to a prim's qualities, but does not
57 /// specify a typeName for the underlying prim. The prim's qualities include
58 /// its inheritance structure, attributes, relationships etc. Since it cannot
59 /// provide a typeName, an API schema is considered to be non-concrete.
60 ///
61 /// To auto-generate an API schema using usdGenSchema, simply leave the
62 /// typeName empty and make it inherit from "/APISchemaBase" or from another
63 /// API schema. See UsdModelAPI, UsdClipsAPI and UsdCollectionAPI for examples.
64 ///
65 /// API schemas are classified into applied and non-applied API schemas.
66 /// The author of an API schema has to decide on the type of API schema
67 /// at the time of its creation by setting customData['apiSchemaType'] in the
68 /// schema definition (i.e. in the associated primSpec inside the schema.usda
69 /// file). UsdAPISchemaBase implements methods that are used to record the
70 /// application of an API schema on a USD prim.
71 ///
72 /// If an API schema only provides an interface to set certain core bits of
73 /// metadata (like UsdModelAPI, which sets model kind and UsdClipsAPI, which
74 /// sets clips-related metadata) OR if the API schema can apply to any type of
75 /// prim or only to a known fixed set of prim types OR if there is no use of
76 /// recording the application of the API schema, in such cases, it would be
77 /// better to make it a non-applied API schema. Examples of non-applied API
78 /// schemas include UsdModelAPI, UsdClipsAPI, UsdShadeConnectableAPI and
79 /// UsdGeomPrimvarsAPI.
80 ///
81 /// If there is a need to discover (or record) whether a prim contains or
82 /// subscribes to a given API schema, it would be advantageous to make the API
83 /// schema be "applied". In general, API schemas that add one or more properties
84 /// to a prim should be tagged as applied API schemas. A public Apply() method
85 /// is generated for applied API schemas by usdGenSchema. An applied API schema
86 /// must be applied to a prim via a call to the generated Apply() method, for
87 /// the schema object to evaluate to true when converted to a bool using the
88 /// explicit bool conversion operator. Examples of applied API schemas include
89 /// UsdCollectionAPI, UsdGeomModelAPI and UsdGeomMotionAPI
90 ///
91 /// \anchor UsdAPISchemaBase_SingleVsMultipleApply
92 /// \name Single vs. Multiple Apply API Schemas
93 ///
94 /// Applied API schemas can further be classified into single-apply and
95 /// multiple-apply API schemas. As the name suggests, a single-apply API schema
96 /// can only be applied once to a prim. A multiple-apply API schema can be
97 /// applied multiple times with different 'instanceName' values. An example of
98 /// a multiple-apply API schema is UsdCollectionAPI, where the API schema is
99 /// applied to a prim once for every collection owned by the prim.
100 ///
101 /// \note An applied API schema can only inherit from another applied API
102 /// schema or directly from APISchemaBase. Similarly, a non-applied API schema
103 /// can only inherit from a non-applied API Schema or directly from
104 /// APISchemaBase. 'usdGenSchema' attempts to issue a warning if it detects
105 /// an incompatibility.
106 ///
107 /// \note A multiple-apply API schema may not inherit from a single-apply API
108 /// schema and vice versa.
109 ///
110 /// \note When the bool-conversion operator is invoked on an applied API
111 /// schema, it evaluates to true only if the application of the API schema has
112 /// been recorded on the prim via a call to the auto-generated Apply() method.
113 ///
114 ///
115 ///
117 {
118 public:
119  /// Compile time constant representing what kind of schema this class is.
120  ///
121  /// \sa UsdSchemaKind
123 
124  /// Construct a UsdAPISchemaBase on UsdPrim \p prim .
125  /// Equivalent to UsdAPISchemaBase::Get(prim.GetStage(), prim.GetPath())
126  /// for a \em valid \p prim, but will not immediately throw an error for
127  /// an invalid \p prim
128  explicit UsdAPISchemaBase(const UsdPrim& prim=UsdPrim())
129  : UsdSchemaBase(prim)
130  {
131  }
132 
133  /// Construct a UsdAPISchemaBase on the prim held by \p schemaObj .
134  /// Should be preferred over UsdAPISchemaBase(schemaObj.GetPrim()),
135  /// as it preserves SchemaBase state.
136  explicit UsdAPISchemaBase(const UsdSchemaBase& schemaObj)
137  : UsdSchemaBase(schemaObj)
138  {
139  }
140 
141  /// Destructor.
142  USD_API
143  virtual ~UsdAPISchemaBase() = 0;
144 
145  /// Return a vector of names of all pre-declared attributes for this schema
146  /// class and all its ancestor classes. Does not include attributes that
147  /// may be authored by custom/extended methods of the schemas involved.
148  USD_API
149  static const TfTokenVector &
150  GetSchemaAttributeNames(bool includeInherited=true);
151 
152 
153 protected:
154  /// Returns the kind of schema this class belongs to.
155  ///
156  /// \sa UsdSchemaKind
157  USD_API
158  UsdSchemaKind _GetSchemaKind() const override;
159 
160 private:
161  // needs to invoke _GetStaticTfType.
162  friend class UsdSchemaRegistry;
163  USD_API
164  static const TfType &_GetStaticTfType();
165 
166  static bool _IsTypedSchema();
167 
168  // override SchemaBase virtuals.
169  USD_API
170  const TfType &_GetTfType() const override;
171 
172 public:
173  // ===================================================================== //
174  // Feel free to add custom code below this line, it will be preserved by
175  // the code generator.
176  //
177  // Just remember to:
178  // - Close the class declaration with };
179  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
180  // - Close the include guard with #endif
181  // ===================================================================== //
182  // --(BEGIN CUSTOM CODE)--
183 
184 protected:
185  /// Construct a multiple-apply UsdAPISchemaBase on UsdPrim \p prim with
186  /// the specified \p instanceName.
187  explicit UsdAPISchemaBase(const UsdPrim& prim,
188  const TfToken &instanceName)
189  : UsdSchemaBase(prim)
190  , _instanceName(instanceName)
191  {
192  }
193 
194  /// Construct a multiple-apply UsdAPISchemaBase on the prim held by
195  /// \p schemaObj with the given \p instanceName.
196  explicit UsdAPISchemaBase(const UsdSchemaBase& schemaObj,
197  const TfToken &instanceName)
198  : UsdSchemaBase(schemaObj)
199  , _instanceName(instanceName)
200  {
201  }
202 
203  /// Returns the instance name of the API schema object belonging to a
204  /// multiple-apply API schema.
205  ///
206  /// The returned instance name will be empty for non-applied and
207  /// single-apply API schemas.
208  const TfToken &_GetInstanceName() const {
209  return _instanceName;
210  }
211 
212 protected:
213  /// Helper method to apply a <b>single-apply</b> API schema with the given
214  /// schema name \p apiSchemaName' and C++ type 'APISchemaType'. The schema
215  /// is applied on the given \p prim in the current edit target.
216  ///
217  /// This information is stored by adding \p apiSchemaName value to the
218  /// token-valued, listOp metadata \em apiSchemas on the prim.
219  ///
220  /// A valid schema object of type \em APISchemaType is returned upon
221  /// success.
222  ///
223  /// A coding error is issued and an invalid schema object is returned if
224  /// <li>if \p prim is invalid or is an instance proxy prim or is contained
225  /// within an instance prototype OR</li>
226  /// <li>\p apiSchemaName cannot be added to the apiSchemas listOp
227  /// metadata.</li></ul>
228  ///
229  /// A run-time error is issued and an invalid schema object is returned
230  /// if the given prim is valid, but cannot be reached or overridden in the
231  /// current edit target.
232  ///
233  template <typename APISchemaType>
234  static APISchemaType _ApplyAPISchema(
235  const UsdPrim &prim,
236  const TfToken &apiSchemaName)
237  {
238  if (prim.ApplyAPI<APISchemaType>()) {
239  return APISchemaType(prim);
240  }
241  return APISchemaType();
242  }
243 
244  /// Helper method to apply a </b>multiple-apply</b> API schema with the
245  /// given schema name \p apiSchemaName', C++ type 'APISchemaType' and
246  /// instance name \p instanceName. The schema is applied on the given
247  /// \p prim in the current edit target.
248  ///
249  /// This information is stored in the token-valued, listOp metadata
250  /// \em apiSchemas on the prim. For example, if \p apiSchemaName is
251  /// 'CollectionAPI' and \p instanceName is 'plasticStuff', the name
252  /// 'CollectionAPI:plasticStuff' is added to 'apiSchemas' listOp metadata.
253  ///
254  /// A valid schema object of type \em APISchemaType is returned upon
255  /// success.
256  ///
257  /// A coding error is issued and an invalid schema object is returned if
258  /// <li>the \p prim is invalid or is an instance proxy prim or is contained
259  /// within an instance prototype OR</li>
260  /// <li>\p instanceName is empty OR</li>
261  /// <li><i>apiSchemaName:instanceName</i> cannot be added to the apiSchemas
262  /// listOp metadata.</li></ul>
263  ///
264  /// A run-time error is issued and an invalid schema object is returned
265  /// if the given prim is valid, but cannot be reached or overridden in the
266  /// current edit target.
267  ///
268  template <typename APISchemaType>
269  static APISchemaType _MultipleApplyAPISchema(
270  const UsdPrim &prim,
271  const TfToken &apiSchemaName,
272  const TfToken &instanceName)
273  {
274  if (prim.ApplyAPI<APISchemaType>(instanceName)) {
275  return APISchemaType(prim, instanceName);
276  }
277  return APISchemaType();
278  }
279 
280  /// Check whether this APISchema object is valid for the currently held
281  /// prim.
282  ///
283  /// If this is an applied API schema, this returns true if the held prim
284  /// is valid and already has the API schema applied to it, along with the
285  /// instanceName (in the case of multiple-apply). The instanceName should
286  /// not be empty in the case of a multiple-apply API schema.
287  ///
288  /// This check is performed when clients invoke the explicit bool conversion
289  /// operator, implemented in UsdSchemaBase.
290  ///
291  /// \sa UsdPrim::HasAPI()
292  USD_API
293  bool _IsCompatible() const override;
294 
295 private:
296  // The instance name associated with this schema object, if it is a
297  // multiple-apply API schema. For example, in the case of UsdCollectionAPI,
298  // this will hold the name of the collection.
299  TfToken _instanceName;
300 };
301 
303 
304 #endif
USD_API UsdSchemaKind _GetSchemaKind() const override
#define USD_API
Definition: api.h:40
static APISchemaType _MultipleApplyAPISchema(const UsdPrim &prim, const TfToken &apiSchemaName, const TfToken &instanceName)
UsdSchemaKind
Definition: common.h:127
const TfToken & _GetInstanceName() const
Definition: token.h:87
UsdAPISchemaBase(const UsdPrim &prim=UsdPrim())
UsdAPISchemaBase(const UsdSchemaBase &schemaObj, const TfToken &instanceName)
UsdAPISchemaBase(const UsdSchemaBase &schemaObj)
Definition: prim.h:132
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
UsdAPISchemaBase(const UsdPrim &prim, const TfToken &instanceName)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
bool ApplyAPI() const
Definition: prim.h:700
virtual USD_API ~UsdAPISchemaBase()=0
Destructor.
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
static USD_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Definition: type.h:64
static const UsdSchemaKind schemaKind
static APISchemaType _ApplyAPISchema(const UsdPrim &prim, const TfToken &apiSchemaName)
USD_API bool _IsCompatible() const override