HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
modelAPI.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_MODELAPI_H
25 #define USD_GENERATED_MODELAPI_H
26 
27 /// \file usd/modelAPI.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usd/api.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 // MODELAPI //
50 // -------------------------------------------------------------------------- //
51 
52 /// \class UsdModelAPI
53 ///
54 /// UsdModelAPI is an API schema that provides an interface to a prim's
55 /// model qualities, if it does, in fact, represent the root prim of a model.
56 ///
57 /// The first and foremost model quality is its \em kind, i.e. the metadata
58 /// that establishes it as a model (See KindRegistry). UsdModelAPI provides
59 /// various methods for setting and querying the prim's kind, as well as
60 /// queries (also available on UsdPrim) for asking what category of model
61 /// the prim is. See \ref Usd_ModelKind "Kind and Model-ness".
62 ///
63 /// UsdModelAPI also provides access to a prim's \ref Usd_Model_AssetInfo "assetInfo"
64 /// data. While any prim \em can host assetInfo, it is common that published
65 /// (referenced) assets are packaged as models, therefore it is convenient
66 /// to provide access to the one from the other.
67 ///
68 /// \todo establish an _IsCompatible() override that returns IsModel()
69 /// \todo GetModelInstanceName()
70 ///
71 ///
73 {
74 public:
75  /// Compile time constant representing what kind of schema this class is.
76  ///
77  /// \sa UsdSchemaType
79 
80  /// Construct a UsdModelAPI on UsdPrim \p prim .
81  /// Equivalent to UsdModelAPI::Get(prim.GetStage(), prim.GetPath())
82  /// for a \em valid \p prim, but will not immediately throw an error for
83  /// an invalid \p prim
84  explicit UsdModelAPI(const UsdPrim& prim=UsdPrim())
85  : UsdAPISchemaBase(prim)
86  {
87  }
88 
89  /// Construct a UsdModelAPI on the prim held by \p schemaObj .
90  /// Should be preferred over UsdModelAPI(schemaObj.GetPrim()),
91  /// as it preserves SchemaBase state.
92  explicit UsdModelAPI(const UsdSchemaBase& schemaObj)
93  : UsdAPISchemaBase(schemaObj)
94  {
95  }
96 
97  /// Destructor.
98  USD_API
99  virtual ~UsdModelAPI();
100 
101  /// Return a vector of names of all pre-declared attributes for this schema
102  /// class and all its ancestor classes. Does not include attributes that
103  /// may be authored by custom/extended methods of the schemas involved.
104  USD_API
105  static const TfTokenVector &
106  GetSchemaAttributeNames(bool includeInherited=true);
107 
108  /// Return a UsdModelAPI holding the prim adhering to this
109  /// schema at \p path on \p stage. If no prim exists at \p path on
110  /// \p stage, or if the prim at that path does not adhere to this schema,
111  /// return an invalid schema object. This is shorthand for the following:
112  ///
113  /// \code
114  /// UsdModelAPI(stage->GetPrimAtPath(path));
115  /// \endcode
116  ///
117  USD_API
118  static UsdModelAPI
119  Get(const UsdStagePtr &stage, const SdfPath &path);
120 
121 
122 protected:
123  /// Returns the type of schema this class belongs to.
124  ///
125  /// \sa UsdSchemaType
126  USD_API
127  UsdSchemaType _GetSchemaType() const override;
128 
129 private:
130  // needs to invoke _GetStaticTfType.
131  friend class UsdSchemaRegistry;
132  USD_API
133  static const TfType &_GetStaticTfType();
134 
135  static bool _IsTypedSchema();
136 
137  // override SchemaBase virtuals.
138  USD_API
139  const TfType &_GetTfType() const override;
140 
141 public:
142  // ===================================================================== //
143  // Feel free to add custom code below this line, it will be preserved by
144  // the code generator.
145  //
146  // Just remember to:
147  // - Close the class declaration with };
148  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
149  // - Close the include guard with #endif
150  // ===================================================================== //
151  // --(BEGIN CUSTOM CODE)--
152 
153  /// \anchor Usd_ModelKind
154  /// \name Kind and Model-ness
155  /// @{
156 
157  /// \enum KindValidation
158  ///
159  /// Option for validating queries to a prim's kind metadata.
160  /// \sa IsKind()
164  };
165 
166  /// Retrieve the authored \p kind for this prim.
167  ///
168  /// To test whether the returned \p kind matches a particular known
169  /// "clientKind":
170  /// \code
171  /// TfToken kind;
172  ///
173  /// bool isClientKind = UsdModelAPI(prim).GetKind(&kind) and
174  /// KindRegistry::IsA(kind, clientKind);
175  /// \endcode
176  ///
177  /// \return true if there was an authored kind that was successfully read,
178  /// otherwise false.
179  ///
180  /// \sa \ref mainpage_kind "The Kind module" for further details on
181  /// how to use Kind for classification, and how to extend the taxonomy.
182  USD_API
183  bool GetKind(TfToken* kind) const;
184 
185  /// Author a \p kind for this prim, at the current UsdEditTarget.
186  /// \return true if \p kind was successully authored, otherwise false.
187  USD_API
188  bool SetKind(const TfToken& kind);
189 
190  /// Return true if the prim's kind metadata is or inherits from
191  /// \p baseKind as defined by the Kind Registry.
192  ///
193  /// If \p validation is KindValidationModelHierarchy (the default), then
194  /// this also ensures that if baseKind is a model, the prim conforms to
195  /// the rules of model hierarchy, as defined by IsModel. If set to
196  /// KindValidationNone, no additional validation is done.
197  ///
198  /// IsModel and IsGroup are preferrable to IsKind("model") as they are
199  /// optimized for fast traversal.
200  ///
201  /// \note If a prim's model hierarchy is not valid, it is possible that
202  /// that prim.IsModel() and
203  /// prim.IsKind("model", Usd.ModelAPI.KindValidationNone) return different
204  /// answers. (As a corallary, this is also true for for prim.IsGroup())
205  USD_API
206  bool IsKind(const TfToken& baseKind,
208 
209  /// Return true if this prim represents a model, based on its kind
210  /// metadata.
211  USD_API
212  bool IsModel() const;
213 
214  /// Return true if this prim represents a model group, based on its kind
215  /// metadata.
216  USD_API
217  bool IsGroup() const;
218 
219  /// @}
220 
221  /// \anchor Usd_Model_AssetInfo
222  /// \name Model Asset Info API
223  /// @{
224 
225  /// Returns the model's asset identifier as authored in the composed
226  /// assetInfo dictionary.
227  ///
228  /// The asset identifier can be used to resolve the model's root layer via
229  /// the asset resolver plugin.
230  ///
231  USD_API
232  bool GetAssetIdentifier(SdfAssetPath *identifier) const;
233 
234  /// Sets the model's asset identifier to the given asset path, \p identifier.
235  ///
236  /// \sa GetAssetIdentifier()
237  ///
238  USD_API
239  void SetAssetIdentifier(const SdfAssetPath &identifier) const;
240 
241  /// Returns the model's asset name from the composed assetInfo dictionary.
242  ///
243  /// The asset name is the name of the asset, as would be used in a database
244  /// query.
245  ///
246  USD_API
247  bool GetAssetName(std::string *assetName) const;
248 
249  /// Sets the model's asset name to \p assetName.
250  ///
251  /// \sa GetAssetName()
252  ///
253  USD_API
254  void SetAssetName(const std::string &assetName) const;
255 
256  /// Returns the model's resolved asset version.
257  ///
258  /// If you publish assets with an embedded version, then you may receive
259  /// that version string. You may, however, cause your authoring tools to
260  /// record the resolved version <em>at the time at which a reference to the
261  /// asset was added to an aggregate</em>, at the referencing site. In
262  /// such a pipeline, this API will always return that stronger opinion,
263  /// even if the asset is republished with a newer version, and even though
264  /// that newer version may be the one that is resolved when the UsdStage is
265  /// opened.
266  ///
267  USD_API
268  bool GetAssetVersion(std::string *version) const;
269 
270  /// Sets the model's asset version string.
271  ///
272  /// \sa GetAssetVersion()
273  ///
274  USD_API
275  void SetAssetVersion(const std::string &version) const;
276 
277  /// Returns the list of asset dependencies referenced inside the
278  /// payload of the model.
279  ///
280  /// This typically contains identifiers of external assets that are
281  /// referenced inside the model's payload. When the model is created, this
282  /// list is compiled and set at the root of the model. This enables
283  /// efficient dependency analysis without the need to include the model's
284  /// payload.
285  ///
286  USD_API
288  const;
289 
290  /// Sets the list of external asset dependencies referenced inside the
291  /// payload of a model.
292  ///
293  /// \sa GetPayloadAssetDependencies()
294  ///
295  USD_API
296  void SetPayloadAssetDependencies(const VtArray<SdfAssetPath> &assetDeps)
297  const;
298 
299  /// Returns the model's composed assetInfo dictionary.
300  ///
301  /// The asset info dictionary is used to annotate models with various
302  /// data related to asset management. For example, asset name,
303  /// identifier, version etc.
304  ///
305  /// The elements of this dictionary are composed element-wise, and are
306  /// nestable.
307  ///
308  USD_API
309  bool GetAssetInfo(VtDictionary *info) const;
310 
311  /// Sets the model's assetInfo dictionary to \p info in the current edit
312  /// target.
313  ///
314  USD_API
315  void SetAssetInfo(const VtDictionary &info) const;
316 
317  /// @}
318 
319 protected:
320 
321  template<typename T>
322  bool _GetAssetInfoByKey(const TfToken &key, T *val) const {
323  VtValue vtVal = GetPrim().GetAssetInfoByKey(key);
324  if (!vtVal.IsEmpty() && vtVal.IsHolding<T>()) {
325  *val = vtVal.UncheckedGet<T>();
326  return true;
327  }
328  return false;
329  }
330 };
331 
332 /// \anchor UsdModelAPIAssetInfoKeys
333 ///
334 /// <b>UsdModelAPIAssetInfoKeys</b> provides tokens for the various core
335 /// entries into the assetInfo dictionary.
336 ///
337 /// The keys provided here are:
338 /// \li <b> identifier</b>
339 /// \li <b> name</b>
340 /// \li <b> version</b>
341 ///
342 /// \sa UsdModelAPI::GetAssetIdentifier()
343 /// \sa UsdModelAPI::GetAssetName()
344 /// \sa UsdModelAPI::GetAssetVersion()
345 ///
346 #define USDMODEL_ASSET_INFO_KEYS \
347  (identifier) \
348  (name) \
349  (version) \
350  (payloadAssetDependencies)
351 
352 TF_DECLARE_PUBLIC_TOKENS(UsdModelAPIAssetInfoKeys, USD_API, USDMODEL_ASSET_INFO_KEYS);
353 
355 
356 #endif
T const & UncheckedGet() const
Definition: value.h:1101
USD_API bool GetAssetInfo(VtDictionary *info) const
USD_API void SetAssetName(const std::string &assetName) const
#define USD_API
Definition: api.h:40
static USD_API UsdModelAPI Get(const UsdStagePtr &stage, const SdfPath &path)
GLuint const GLfloat * val
Definition: glew.h:2794
#define USDMODEL_ASSET_INFO_KEYS
Definition: modelAPI.h:346
USD_API bool GetKind(TfToken *kind) const
USD_API bool GetAssetVersion(std::string *version) const
USD_API void SetAssetIdentifier(const SdfAssetPath &identifier) const
USD_API bool SetKind(const TfToken &kind)
USD_API UsdSchemaType _GetSchemaType() const override
bool IsEmpty() const
Returns true iff this value is empty.
Definition: value.h:1255
USD_API bool IsGroup() const
USD_API void SetAssetVersion(const std::string &version) const
USD_API void SetAssetInfo(const VtDictionary &info) const
USD_API bool IsKind(const TfToken &baseKind, KindValidation validation=KindValidationModelHierarchy) const
Definition: token.h:87
UsdModelAPI(const UsdPrim &prim=UsdPrim())
Definition: modelAPI.h:84
bool _GetAssetInfoByKey(const TfToken &key, T *val) const
Definition: modelAPI.h:322
USD_API VtValue GetAssetInfoByKey(const TfToken &keyPath) const
Non-applied API schema.
USD_API bool GetAssetIdentifier(SdfAssetPath *identifier) const
UsdSchemaType
Definition: common.h:127
Definition: prim.h:132
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:446
Definition: types.h:166
Definition: path.h:288
USD_API bool IsModel() const
GT_API const UT_StringHolder version
USD_API bool GetAssetName(std::string *assetName) const
GLsizei const GLchar *const * path
Definition: glew.h:6461
GLsizei const GLchar *const * string
Definition: glew.h:1844
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
static const UsdSchemaType schemaType
Definition: modelAPI.h:78
static USD_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
bool IsHolding() const
Definition: value.h:1073
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USD_API void SetPayloadAssetDependencies(const VtArray< SdfAssetPath > &assetDeps) const
Definition: type.h:64
TF_DECLARE_PUBLIC_TOKENS(UsdModelAPIAssetInfoKeys, USD_API, USDMODEL_ASSET_INFO_KEYS)
USD_API bool GetPayloadAssetDependencies(VtArray< SdfAssetPath > *assetDeps) const
virtual USD_API ~UsdModelAPI()
Destructor.
UsdPrim GetPrim() const
Return this schema object's held prim.
Definition: schemaBase.h:119
Definition: value.h:174
UsdModelAPI(const UsdSchemaBase &schemaObj)
Definition: modelAPI.h:92