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() (or
85 /// private _Apply()) method is generated for applied API schemas by
86 /// usdGenSchema. An applied API schema must be applied to a prim via a call to
87 /// the generated Apply() method, for the schema object to evaluate to true when
88 /// converted to a bool using the explicit bool conversion operator. Examples of
89 /// applied API schemas include UsdCollectionAPI, UsdGeomModelAPI and
90 /// UsdGeomMotionAPI
91 ///
92 /// \anchor UsdAPISchemaBase_SingleVsMultipleApply
93 /// \name Single vs. Multiple Apply API Schemas
94 ///
95 /// Applied API schemas can further be classified into single-apply and
96 /// multiple-apply API schemas. As the name suggests, a single-apply API schema
97 /// can only be applied once to a prim. A multiple-apply API schema can be
98 /// applied multiple times with different 'instanceName' values. An example of
99 /// a multiple-apply API schema is UsdCollectionAPI, where the API schema is
100 /// applied to a prim once for every collection owned by the prim.
101 ///
102 /// \note An applied API schema can only inherit from another applied API
103 /// schema or directly from APISchemaBase. Similarly, a non-applied API schema
104 /// can only inherit from a non-applied API Schema or directly from
105 /// APISchemaBase. 'usdGenSchema' attempts to issue a warning if it detects
106 /// an incompability.
107 ///
108 /// \note A multiple-apply API schema may not inherit from a single-apply API
109 /// schema and vice versa.
110 ///
111 /// \note When the bool-conversion operator is invoked on an applied API
112 /// schema, it evaluates to true only if the application of the API schema has
113 /// been recorded on the prim via a call to the auto-generated Apply() method.
114 ///
115 ///
116 ///
118 {
119 public:
120  /// Compile time constant representing what kind of schema this class is.
121  ///
122  /// \sa UsdSchemaType
124 
125  /// Construct a UsdAPISchemaBase on UsdPrim \p prim .
126  /// Equivalent to UsdAPISchemaBase::Get(prim.GetStage(), prim.GetPath())
127  /// for a \em valid \p prim, but will not immediately throw an error for
128  /// an invalid \p prim
129  explicit UsdAPISchemaBase(const UsdPrim& prim=UsdPrim())
130  : UsdSchemaBase(prim)
131  {
132  }
133 
134  /// Construct a UsdAPISchemaBase on the prim held by \p schemaObj .
135  /// Should be preferred over UsdAPISchemaBase(schemaObj.GetPrim()),
136  /// as it preserves SchemaBase state.
137  explicit UsdAPISchemaBase(const UsdSchemaBase& schemaObj)
138  : UsdSchemaBase(schemaObj)
139  {
140  }
141 
142  /// Destructor.
143  USD_API
144  virtual ~UsdAPISchemaBase() = 0;
145 
146  /// Return a vector of names of all pre-declared attributes for this schema
147  /// class and all its ancestor classes. Does not include attributes that
148  /// may be authored by custom/extended methods of the schemas involved.
149  USD_API
150  static const TfTokenVector &
151  GetSchemaAttributeNames(bool includeInherited=true);
152 
153 
154 protected:
155  /// Returns the type of schema this class belongs to.
156  ///
157  /// \sa UsdSchemaType
158  USD_API
159  UsdSchemaType _GetSchemaType() const override;
160 
161 private:
162  // needs to invoke _GetStaticTfType.
163  friend class UsdSchemaRegistry;
164  USD_API
165  static const TfType &_GetStaticTfType();
166 
167  static bool _IsTypedSchema();
168 
169  // override SchemaBase virtuals.
170  USD_API
171  const TfType &_GetTfType() const override;
172 
173 public:
174  // ===================================================================== //
175  // Feel free to add custom code below this line, it will be preserved by
176  // the code generator.
177  //
178  // Just remember to:
179  // - Close the class declaration with };
180  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
181  // - Close the include guard with #endif
182  // ===================================================================== //
183  // --(BEGIN CUSTOM CODE)--
184 
185 protected:
186  /// Construct a multiple-apply UsdAPISchemaBase on UsdPrim \p prim with
187  /// the specified \p instanceName.
188  explicit UsdAPISchemaBase(const UsdPrim& prim,
189  const TfToken &instanceName)
190  : UsdSchemaBase(prim)
191  , _instanceName(instanceName)
192  {
193  }
194 
195  /// Construct a multiple-apply UsdAPISchemaBase on the prim held by
196  /// \p schemaObj with the given \p instanceName.
197  explicit UsdAPISchemaBase(const UsdSchemaBase& schemaObj,
198  const TfToken &instanceName)
199  : UsdSchemaBase(schemaObj)
200  , _instanceName(instanceName)
201  {
202  }
203 
204  /// Returns the instance name of the API schema object belonging to a
205  /// multiple-apply API schema.
206  ///
207  /// The returned instance name will be empty for non-applied and
208  /// single-apply API schemas.
209  const TfToken &_GetInstanceName() const {
210  return _instanceName;
211  }
212 
213 protected:
214  /// Helper method to apply a <b>single-apply</b> API schema with the given
215  /// schema name \p apiSchemaName' and C++ type 'APISchemaType'. The schema
216  /// is applied on the given \p prim in the current edit target.
217  ///
218  /// This information is stored by adding \p apiSchemaName value to the
219  /// token-valued, listOp metadata \em apiSchemas on the prim.
220  ///
221  /// A valid schema object of type \em APISchemaType is returned upon
222  /// success.
223  ///
224  /// A coding error is issued and an invalid schema object is returned if
225  /// <li>if \p prim is invalid or is an instance proxy prim or is contained
226  /// within an instance master OR</li>
227  /// <li>\p apiSchemaName cannot be added to the apiSchemas listOp
228  /// metadata.</li></ul>
229  ///
230  /// A run-time error is issued and an invalid schema object is returned
231  /// if the given prim is valid, but cannot be reached or overridden in the
232  /// current edit target.
233  ///
234  template <typename APISchemaType>
235  static APISchemaType _ApplyAPISchema(
236  const UsdPrim &prim,
237  const TfToken &apiSchemaName)
238  {
239  return APISchemaType(_ApplyAPISchemaImpl(prim, apiSchemaName));
240  }
241 
242  /// Helper method to apply a </b>multiple-apply</b> API schema with the
243  /// given schema name \p apiSchemaName', C++ type 'APISchemaType' and
244  /// instance name \p instanceName. The schema is applied on the given
245  /// \p prim in the current edit target.
246  ///
247  /// This information is stored in the token-valued, listOp metadata
248  /// \em apiSchemas on the prim. For example, if \p apiSchemaName is
249  /// 'CollectionAPI' and \p instanceName is 'plasticStuff', the name
250  /// 'CollectionAPI:plasticStuff' is added to 'apiSchemas' listOp metadata.
251  ///
252  /// A valid schema object of type \em APISchemaType is returned upon
253  /// success.
254  ///
255  /// A coding error is issued and an invalid schema object is returned if
256  /// <li>the \p prim is invalid or is an instance proxy prim or is contained
257  /// within an instance master OR</li>
258  /// <li>\p instanceName is empty OR</li>
259  /// <li><i>apiSchemaName:instanceName</i> cannot be added to the apiSchemas
260  /// listOp metadata.</li></ul>
261  ///
262  /// A run-time error is issued and an invalid schema object is returned
263  /// if the given prim is valid, but cannot be reached or overridden in the
264  /// current edit target.
265  ///
266  template <typename APISchemaType>
267  static APISchemaType _MultipleApplyAPISchema(
268  const UsdPrim &prim,
269  const TfToken &apiSchemaName,
270  const TfToken &instanceName)
271  {
272  if (instanceName.IsEmpty()) {
273  TF_CODING_ERROR("Instance name is empty!");
274  return APISchemaType();
275  }
276 
277  TfToken apiName(SdfPath::JoinIdentifier(apiSchemaName, instanceName));
278  return APISchemaType(_ApplyAPISchemaImpl(prim, apiName), instanceName);
279  }
280 
281  /// Check whether this APISchema object is valid for the currently held
282  /// prim.
283  ///
284  /// If this is an applied API schema, this returns true if the held prim
285  /// is valid and already has the API schema applied to it, along with the
286  /// instanceName (in the case of multiple-apply). The instanceName should
287  /// not be empty in the case of a multiple-apply API schema.
288  ///
289  /// This check is performed when clients invoke the explicit bool conversion
290  /// operator, implemented in UsdSchemaBase.
291  ///
292  /// \sa UsdPrim::HasAPI()
293  USD_API
294  bool _IsCompatible() const override;
295 
296 private:
297  // Helper method for adding 'apiName' to the apiSchemas metadata on the
298  // prim at 'path' on the given 'stage'.
299  USD_API
300  static UsdPrim _ApplyAPISchemaImpl(
301  const UsdPrim &prim,
302  const TfToken &apiName);
303 
304  // The instance name associated with this schema object, if it is a
305  // multiple-apply API schema. For example, in the case of UsdCollectionAPI,
306  // this will hold the name of the collection.
307  TfToken _instanceName;
308 };
309 
311 
312 #endif
#define USD_API
Definition: api.h:40
static APISchemaType _MultipleApplyAPISchema(const UsdPrim &prim, const TfToken &apiSchemaName, const TfToken &instanceName)
#define TF_CODING_ERROR
const TfToken & _GetInstanceName() const
Definition: token.h:89
UsdAPISchemaBase(const UsdPrim &prim=UsdPrim())
UsdAPISchemaBase(const UsdSchemaBase &schemaObj, const TfToken &instanceName)
UsdAPISchemaBase(const UsdSchemaBase &schemaObj)
USD_API UsdSchemaType _GetSchemaType() const override
static const UsdSchemaType schemaType
UsdSchemaType
Definition: common.h:149
Definition: prim.h:131
static SDF_API std::string JoinIdentifier(const std::vector< std::string > &names)
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:438
UsdAPISchemaBase(const UsdPrim &prim, const TfToken &instanceName)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1245
virtual USD_API ~UsdAPISchemaBase()=0
Destructor.
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:83
static USD_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Definition: type.h:70
static APISchemaType _ApplyAPISchema(const UsdPrim &prim, const TfToken &apiSchemaName)
bool IsEmpty() const
Returns true iff this token contains the empty string "".
Definition: token.h:311
USD_API bool _IsCompatible() const override