HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
primvarsAPI.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 USDGEOM_GENERATED_PRIMVARSAPI_H
25 #define USDGEOM_GENERATED_PRIMVARSAPI_H
26 
27 /// \file usdGeom/primvarsAPI.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usdGeom/api.h"
32 #include "pxr/usd/usd/prim.h"
33 #include "pxr/usd/usd/stage.h"
34 
35 #include "pxr/usd/usdGeom/primvar.h"
36 
37 #include "pxr/base/vt/value.h"
38 
39 #include "pxr/base/gf/vec3d.h"
40 #include "pxr/base/gf/vec3f.h"
41 #include "pxr/base/gf/matrix4d.h"
42 
43 #include "pxr/base/tf/token.h"
44 #include "pxr/base/tf/type.h"
45 
47 
48 class SdfAssetPath;
49 
50 // -------------------------------------------------------------------------- //
51 // PRIMVARSAPI //
52 // -------------------------------------------------------------------------- //
53 
54 /// \class UsdGeomPrimvarsAPI
55 ///
56 /// UsdGeomPrimvarsAPI encodes geometric "primitive variables",
57 /// as UsdGeomPrimvar, which interpolate across a primitive's topology,
58 /// can override shader inputs, and inherit down namespace.
59 ///
60 /// \section usdGeom_PrimvarFetchingAPI Which Method to Use to Retrieve Primvars
61 ///
62 /// While creating primvars is unambiguous (CreatePrimvar()), there are quite
63 /// a few methods available for retrieving primvars, making it potentially
64 /// confusing knowing which one to use. Here are some guidelines:
65 ///
66 /// \li If you are populating a GUI with the primvars already available for
67 /// authoring values on a prim, use GetPrimvars().
68 /// \li If you want all of the "useful" (e.g. to a renderer) primvars
69 /// available at a prim, including those inherited from ancestor prims, use
70 /// FindPrimvarsWithInheritance(). Note that doing so individually for many
71 /// prims will be inefficient.
72 /// \li To find a particular primvar defined directly on a prim, which may
73 /// or may not provide a value, use GetPrimvar().
74 /// \li To find a particular primvar defined on a prim or inherited from
75 /// ancestors, which may or may not provide a value, use
76 /// FindPrimvarWithInheritance().
77 /// \li To *efficiently* query for primvars using the overloads of
78 /// FindPrimvarWithInheritance() and FindPrimvarsWithInheritance(), one
79 /// must first cache the results of FindIncrementallyInheritablePrimvars() for
80 /// each non-leaf prim on the stage.
81 ///
83 {
84 public:
85  /// Compile time constant representing what kind of schema this class is.
86  ///
87  /// \sa UsdSchemaType
89 
90  /// Construct a UsdGeomPrimvarsAPI on UsdPrim \p prim .
91  /// Equivalent to UsdGeomPrimvarsAPI::Get(prim.GetStage(), prim.GetPath())
92  /// for a \em valid \p prim, but will not immediately throw an error for
93  /// an invalid \p prim
94  explicit UsdGeomPrimvarsAPI(const UsdPrim& prim=UsdPrim())
95  : UsdAPISchemaBase(prim)
96  {
97  }
98 
99  /// Construct a UsdGeomPrimvarsAPI on the prim held by \p schemaObj .
100  /// Should be preferred over UsdGeomPrimvarsAPI(schemaObj.GetPrim()),
101  /// as it preserves SchemaBase state.
102  explicit UsdGeomPrimvarsAPI(const UsdSchemaBase& schemaObj)
103  : UsdAPISchemaBase(schemaObj)
104  {
105  }
106 
107  /// Destructor.
109  virtual ~UsdGeomPrimvarsAPI();
110 
111  /// Return a vector of names of all pre-declared attributes for this schema
112  /// class and all its ancestor classes. Does not include attributes that
113  /// may be authored by custom/extended methods of the schemas involved.
115  static const TfTokenVector &
116  GetSchemaAttributeNames(bool includeInherited=true);
117 
118  /// Return a UsdGeomPrimvarsAPI holding the prim adhering to this
119  /// schema at \p path on \p stage. If no prim exists at \p path on
120  /// \p stage, or if the prim at that path does not adhere to this schema,
121  /// return an invalid schema object. This is shorthand for the following:
122  ///
123  /// \code
124  /// UsdGeomPrimvarsAPI(stage->GetPrimAtPath(path));
125  /// \endcode
126  ///
128  static UsdGeomPrimvarsAPI
129  Get(const UsdStagePtr &stage, const SdfPath &path);
130 
131 
132 protected:
133  /// Returns the type of schema this class belongs to.
134  ///
135  /// \sa UsdSchemaType
137  UsdSchemaType _GetSchemaType() const override;
138 
139 private:
140  // needs to invoke _GetStaticTfType.
141  friend class UsdSchemaRegistry;
143  static const TfType &_GetStaticTfType();
144 
145  static bool _IsTypedSchema();
146 
147  // override SchemaBase virtuals.
149  const TfType &_GetTfType() const override;
150 
151 public:
152  // ===================================================================== //
153  // Feel free to add custom code below this line, it will be preserved by
154  // the code generator.
155  //
156  // Just remember to:
157  // - Close the class declaration with };
158  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
159  // - Close the include guard with #endif
160  // ===================================================================== //
161  // --(BEGIN CUSTOM CODE)--
162 
163  /// Author scene description to create an attribute on this prim that
164  /// will be recognized as Primvar (i.e. will present as a valid
165  /// UsdGeomPrimvar).
166  ///
167  /// The name of the created attribute may or may not be the specified
168  /// \p attrName, due to the possible need to apply property namespacing
169  /// for primvars. See \ref Usd_Creating_and_Accessing_Primvars
170  /// for more information. Creation may fail and return an invalid
171  /// Primvar if \p attrName contains a reserved keyword, such as the
172  /// "indices" suffix we use for indexed primvars.
173  ///
174  /// The behavior with respect to the provided \p typeName
175  /// is the same as for UsdAttributes::Create(), and
176  /// \p interpolation and \p elementSize are as described in
177  /// UsdGeomPrimvar::GetInterpolation() and UsdGeomPrimvar::GetElementSize().
178  ///
179  /// If \p interpolation and/or \p elementSize are left unspecified, we
180  /// will author no opinions for them, which means any (strongest) opinion
181  /// already authored in any contributing layer for these fields will
182  /// become the Primvar's values, or the fallbacks if no opinions
183  /// have been authored.
184  ///
185  /// \return an invalid UsdGeomPrimvar if we failed to create a valid
186  /// attribute, a valid UsdGeomPrimvar otherwise. It is not an
187  /// error to create over an existing, compatible attribute.
188  ///
189  /// \sa UsdPrim::CreateAttribute(), UsdGeomPrimvar::IsPrimvar()
191  UsdGeomPrimvar CreatePrimvar(const TfToken& attrName,
192  const SdfValueTypeName &typeName,
193  const TfToken& interpolation = TfToken(),
194  int elementSize = -1) const;
195 
196  /// Return the Primvar object named by \p name, which will
197  /// be valid if a Primvar attribute definition already exists.
198  ///
199  /// Name lookup will account for Primvar namespacing, which means
200  /// that this method will succeed in some cases where
201  /// \code
202  /// UsdGeomPrimvar(prim->GetAttribute(name))
203  /// \endcode
204  /// will not, unless \p name is properly namespace prefixed.
205  ///
206  /// \note Just because a Primvar is valid and defined, and *even if* its
207  /// underlying UsdAttribute (GetAttr()) answers HasValue() affirmatively,
208  /// one must still check the return value of Get(), due to the potential
209  /// of time-varying value blocks (see \ref Usd_AttributeBlocking).
210  ///
211  /// \sa HasPrimvar(), \ref usdGeom_PrimvarFetchingAPI
213  UsdGeomPrimvar GetPrimvar(const TfToken &name) const;
214 
215  /// Return valid UsdGeomPrimvar objects for all defined Primvars on
216  /// this prim, similarly to UsdPrim::GetAttributes().
217  ///
218  /// The returned primvars may not possess any values, and therefore not
219  /// be useful to some clients. For the primvars useful for inheritance
220  /// computations, see GetPrimvarsWithAuthoredValues(), and for primvars
221  /// useful for direct consumption, see GetPrimvarsWithValues().
222  ///
223  /// \sa \ref usdGeom_PrimvarFetchingAPI
225  std::vector<UsdGeomPrimvar> GetPrimvars() const;
226 
227  /// Like GetPrimvars(), but include only primvars that have some
228  /// authored scene description (though not necessarily a value).
229  ///
230  /// \sa \ref usdGeom_PrimvarFetchingAPI
232  std::vector<UsdGeomPrimvar> GetAuthoredPrimvars() const;
233 
234  /// Like GetPrimvars(), but include only primvars that have some
235  /// value, whether it comes from authored scene description or a schema
236  /// fallback.
237  ///
238  /// For most purposes, this method is more useful than GetPrimvars().
239  ///
240  /// \sa \ref usdGeom_PrimvarFetchingAPI
242  std::vector<UsdGeomPrimvar> GetPrimvarsWithValues() const;
243 
244  /// Like GetPrimvars(), but include only primvars that have an **authored**
245  /// value.
246  ///
247  /// This is the query used when computing inheritable primvars, and is
248  /// generally more useful than GetAuthoredPrimvars().
249  ///
250  /// \sa \ref usdGeom_PrimvarFetchingAPI
252  std::vector<UsdGeomPrimvar> GetPrimvarsWithAuthoredValues() const;
253 
254  /// Compute the primvars that can be inherited from this prim by its
255  /// child prims, including the primvars that **this** prim inherits from
256  /// ancestor prims. Inherited primvars will be bound to attributes on
257  /// the corresponding ancestor prims.
258  ///
259  /// Only primvars with **authored**, **non-blocked**,
260  /// **constant interpolation** values are inheritable;
261  /// fallback values are not inherited. The order of the returned
262  /// primvars is undefined.
263  ///
264  /// It is not generally useful to call this method on UsdGeomGprim leaf
265  /// prims, and furthermore likely to be expensive since *most* primvars
266  /// are defined on Gprims.
267  ///
268  /// \sa \ref usdGeom_PrimvarFetchingAPI
270  std::vector<UsdGeomPrimvar> FindInheritablePrimvars() const;
271 
272  /// Compute the primvars that can be inherited from this prim by its
273  /// child prims, starting from the set of primvars inherited from
274  /// this prim's ancestors. If this method returns an empty vector, then
275  /// this prim's children should inherit the same set of primvars available
276  /// to this prim, i.e. the input `inheritedFromAncestors` .
277  ///
278  /// As opposed to FindInheritablePrimvars(), which always recurses up
279  /// through all of the prim's ancestors, this method allows more
280  /// efficient computation of inheritable primvars by starting with the
281  /// list of primvars inherited from this prim's ancestors, and returning
282  /// a newly allocated vector only when this prim makes a change to the
283  /// set of inherited primvars. This enables O(n) inherited primvar
284  /// computation for all prims on a Stage, with potential to share
285  /// computed results that are identical (i.e. when this method returns an
286  /// empty vector, its parent's result can (and must!) be reused for all
287  /// of the prim's children.
288  ///
289  /// \sa \ref usdGeom_PrimvarFetchingAPI
291  std::vector<UsdGeomPrimvar> FindIncrementallyInheritablePrimvars(
292  const std::vector<UsdGeomPrimvar> &inheritedFromAncestors) const;
293 
294  /// Like GetPrimvar(), but if the named primvar does not exist or has no
295  /// authored value on this prim, search for the named, value-producing
296  /// primvar on ancestor prims.
297  ///
298  /// The returned primvar will be bound to the attribute on the
299  /// corresponding ancestor prim on which it was found (if any). If neither
300  /// this prim nor any ancestor contains a value-producing primvar, then
301  /// the returned primvar will be the same as that returned by GetPrimvar().
302  ///
303  /// This is probably the method you want to call when needing to consume
304  /// a primvar of a particular name.
305  ///
306  /// \sa \ref usdGeom_PrimvarFetchingAPI
309 
310  /// \overload
311  ///
312  /// This version of FindPrimvarWithInheritance() takes the pre-computed
313  /// set of primvars inherited from this prim's ancestors, as computed
314  /// by FindInheritablePrimvars() or FindIncrementallyInheritablePrimvars()
315  /// on the prim's parent.
316  ///
317  /// \sa \ref usdGeom_PrimvarFetchingAPI
320  const std::vector<UsdGeomPrimvar> &inheritedFromAncestors) const;
321 
322  /// Find all of the value-producing primvars either defined on this prim,
323  /// or inherited from ancestor prims.
324  ///
325  /// \sa \ref usdGeom_PrimvarFetchingAPI
327  std::vector<UsdGeomPrimvar> FindPrimvarsWithInheritance() const;
328 
329  /// \overload
330  ///
331  /// This version of FindPrimvarsWithInheritance() takes the pre-computed
332  /// set of primvars inherited from this prim's ancestors, as computed
333  /// by FindInheritablePrimvars() or FindIncrementallyInheritablePrimvars()
334  /// on the prim's parent.
335  ///
336  /// \sa \ref usdGeom_PrimvarFetchingAPI
338  std::vector<UsdGeomPrimvar> FindPrimvarsWithInheritance(
339  const std::vector<UsdGeomPrimvar> &inheritedFromAncestors) const;
340 
341  /// Is there a defined Primvar \p name on this prim?
342  ///
343  /// Name lookup will account for Primvar namespacing.
344  ///
345  /// Like GetPrimvar(), a return value of `true` for HasPrimvar() does not
346  /// guarantee the primvar will produce a value.
348  bool HasPrimvar(const TfToken &name) const;
349 
350  /// Is there a Primvar named \p name with an authored value on this
351  /// prim or any of its ancestors?
352  ///
353  /// This is probably the method you want to call when wanting to know
354  /// whether or not the prim "has" a primvar of a particular name.
355  ///
356  /// \sa FindPrimvarWithInheritance()
358  bool HasPossiblyInheritedPrimvar(const TfToken &name) const;
359 
360 };
361 
363 
364 #endif
USDGEOM_API std::vector< UsdGeomPrimvar > GetPrimvarsWithAuthoredValues() const
USDGEOM_API UsdGeomPrimvar GetPrimvar(const TfToken &name) const
UsdGeomPrimvarsAPI(const UsdPrim &prim=UsdPrim())
Definition: primvarsAPI.h:94
USDGEOM_API std::vector< UsdGeomPrimvar > FindIncrementallyInheritablePrimvars(const std::vector< UsdGeomPrimvar > &inheritedFromAncestors) const
GLuint const GLchar * name
Definition: glew.h:1814
USDGEOM_API std::vector< UsdGeomPrimvar > GetAuthoredPrimvars() const
USDGEOM_API std::vector< UsdGeomPrimvar > FindPrimvarsWithInheritance() const
USDGEOM_API UsdGeomPrimvar CreatePrimvar(const TfToken &attrName, const SdfValueTypeName &typeName, const TfToken &interpolation=TfToken(), int elementSize=-1) const
USDGEOM_API UsdSchemaType _GetSchemaType() const override
USDGEOM_API std::vector< UsdGeomPrimvar > FindInheritablePrimvars() const
virtual USDGEOM_API ~UsdGeomPrimvarsAPI()
Destructor.
Definition: token.h:89
static USDGEOM_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Non-applied API schema.
UsdSchemaType
Definition: common.h:149
Definition: prim.h:131
USDGEOM_API bool HasPrimvar(const TfToken &name) const
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:438
Definition: path.h:287
GLsizei const GLchar *const * path
Definition: glew.h:6461
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1245
USDGEOM_API std::vector< UsdGeomPrimvar > GetPrimvars() const
UsdGeomPrimvarsAPI(const UsdSchemaBase &schemaObj)
Definition: primvarsAPI.h:102
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:83
USDGEOM_API bool HasPossiblyInheritedPrimvar(const TfToken &name) const
Definition: type.h:70
static const UsdSchemaType schemaType
Definition: primvarsAPI.h:88
#define USDGEOM_API
Definition: api.h:40
USDGEOM_API std::vector< UsdGeomPrimvar > GetPrimvarsWithValues() const
static USDGEOM_API UsdGeomPrimvarsAPI Get(const UsdStagePtr &stage, const SdfPath &path)
USDGEOM_API UsdGeomPrimvar FindPrimvarWithInheritance(const TfToken &name) const