HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
pointBased.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef USDGEOM_GENERATED_POINTBASED_H
8 #define USDGEOM_GENERATED_POINTBASED_H
9 
10 /// \file usdGeom/pointBased.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/usdGeom/api.h"
14 #include "pxr/usd/usdGeom/gprim.h"
15 #include "pxr/usd/usd/prim.h"
16 #include "pxr/usd/usd/stage.h"
17 #include "pxr/usd/usdGeom/tokens.h"
18 
19 #include "pxr/base/vt/value.h"
20 
21 #include "pxr/base/gf/vec3d.h"
22 #include "pxr/base/gf/vec3f.h"
23 #include "pxr/base/gf/matrix4d.h"
24 
25 #include "pxr/base/tf/token.h"
26 #include "pxr/base/tf/type.h"
27 
29 
30 class SdfAssetPath;
31 
32 // -------------------------------------------------------------------------- //
33 // POINTBASED //
34 // -------------------------------------------------------------------------- //
35 
36 /// \class UsdGeomPointBased
37 ///
38 /// Base class for all UsdGeomGprims that possess points,
39 /// providing common attributes such as normals and velocities.
40 ///
42 {
43 public:
44  /// Compile time constant representing what kind of schema this class is.
45  ///
46  /// \sa UsdSchemaKind
48 
49  /// Construct a UsdGeomPointBased on UsdPrim \p prim .
50  /// Equivalent to UsdGeomPointBased::Get(prim.GetStage(), prim.GetPath())
51  /// for a \em valid \p prim, but will not immediately throw an error for
52  /// an invalid \p prim
53  explicit UsdGeomPointBased(const UsdPrim& prim=UsdPrim())
54  : UsdGeomGprim(prim)
55  {
56  }
57 
58  /// Construct a UsdGeomPointBased on the prim held by \p schemaObj .
59  /// Should be preferred over UsdGeomPointBased(schemaObj.GetPrim()),
60  /// as it preserves SchemaBase state.
61  explicit UsdGeomPointBased(const UsdSchemaBase& schemaObj)
62  : UsdGeomGprim(schemaObj)
63  {
64  }
65 
66  /// Destructor.
68  virtual ~UsdGeomPointBased();
69 
70  /// Return a vector of names of all pre-declared attributes for this schema
71  /// class and all its ancestor classes. Does not include attributes that
72  /// may be authored by custom/extended methods of the schemas involved.
74  static const TfTokenVector &
75  GetSchemaAttributeNames(bool includeInherited=true);
76 
77  /// Return a UsdGeomPointBased holding the prim adhering to this
78  /// schema at \p path on \p stage. If no prim exists at \p path on
79  /// \p stage, or if the prim at that path does not adhere to this schema,
80  /// return an invalid schema object. This is shorthand for the following:
81  ///
82  /// \code
83  /// UsdGeomPointBased(stage->GetPrimAtPath(path));
84  /// \endcode
85  ///
87  static UsdGeomPointBased
88  Get(const UsdStagePtr &stage, const SdfPath &path);
89 
90 
91 protected:
92  /// Returns the kind of schema this class belongs to.
93  ///
94  /// \sa UsdSchemaKind
96  UsdSchemaKind _GetSchemaKind() const override;
97 
98 private:
99  // needs to invoke _GetStaticTfType.
100  friend class UsdSchemaRegistry;
102  static const TfType &_GetStaticTfType();
103 
104  static bool _IsTypedSchema();
105 
106  // override SchemaBase virtuals.
108  const TfType &_GetTfType() const override;
109 
110 public:
111  // --------------------------------------------------------------------- //
112  // POINTS
113  // --------------------------------------------------------------------- //
114  /// The primary geometry attribute for all PointBased
115  /// primitives, describes points in (local) space.
116  ///
117  /// | ||
118  /// | -- | -- |
119  /// | Declaration | `point3f[] points` |
120  /// | C++ Type | VtArray<GfVec3f> |
121  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Point3fArray |
123  UsdAttribute GetPointsAttr() const;
124 
125  /// See GetPointsAttr(), and also
126  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
127  /// If specified, author \p defaultValue as the attribute's default,
128  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
129  /// the default for \p writeSparsely is \c false.
131  UsdAttribute CreatePointsAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
132 
133 public:
134  // --------------------------------------------------------------------- //
135  // VELOCITIES
136  // --------------------------------------------------------------------- //
137  /// If provided, 'velocities' should be used by renderers to
138  ///
139  /// compute positions between samples for the 'points' attribute, rather
140  /// than interpolating between neighboring 'points' samples. This is the
141  /// only reasonable means of computing motion blur for topologically
142  /// varying PointBased primitives. It follows that the length of each
143  /// 'velocities' sample must match the length of the corresponding
144  /// 'points' sample. Velocity is measured in position units per second,
145  /// as per most simulation software. To convert to position units per
146  /// UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond().
147  ///
148  /// See also \ref UsdGeom_VelocityInterpolation .
149  ///
150  /// | ||
151  /// | -- | -- |
152  /// | Declaration | `vector3f[] velocities` |
153  /// | C++ Type | VtArray<GfVec3f> |
154  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Vector3fArray |
157 
158  /// See GetVelocitiesAttr(), and also
159  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
160  /// If specified, author \p defaultValue as the attribute's default,
161  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
162  /// the default for \p writeSparsely is \c false.
164  UsdAttribute CreateVelocitiesAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
165 
166 public:
167  // --------------------------------------------------------------------- //
168  // ACCELERATIONS
169  // --------------------------------------------------------------------- //
170  /// If provided, 'accelerations' should be used with
171  /// velocities to compute positions between samples for the 'points'
172  /// attribute rather than interpolating between neighboring 'points'
173  /// samples. Acceleration is measured in position units per second-squared.
174  /// To convert to position units per squared UsdTimeCode, divide by the
175  /// square of UsdStage::GetTimeCodesPerSecond().
176  ///
177  /// | ||
178  /// | -- | -- |
179  /// | Declaration | `vector3f[] accelerations` |
180  /// | C++ Type | VtArray<GfVec3f> |
181  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Vector3fArray |
184 
185  /// See GetAccelerationsAttr(), and also
186  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
187  /// If specified, author \p defaultValue as the attribute's default,
188  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
189  /// the default for \p writeSparsely is \c false.
191  UsdAttribute CreateAccelerationsAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
192 
193 public:
194  // --------------------------------------------------------------------- //
195  // NORMALS
196  // --------------------------------------------------------------------- //
197  /// Provide an object-space orientation for individual points,
198  /// which, depending on subclass, may define a surface, curve, or free
199  /// points. Note that 'normals' should not be authored on any Mesh that
200  /// is subdivided, since the subdivision algorithm will define its own
201  /// normals. 'normals' is not a generic primvar, but the number of elements
202  /// in this attribute will be determined by its 'interpolation'. See
203  /// \ref SetNormalsInterpolation() . If 'normals' and 'primvars:normals'
204  /// are both specified, the latter has precedence.
205  ///
206  /// | ||
207  /// | -- | -- |
208  /// | Declaration | `normal3f[] normals` |
209  /// | C++ Type | VtArray<GfVec3f> |
210  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Normal3fArray |
213 
214  /// See GetNormalsAttr(), and also
215  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
216  /// If specified, author \p defaultValue as the attribute's default,
217  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
218  /// the default for \p writeSparsely is \c false.
220  UsdAttribute CreateNormalsAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
221 
222 public:
223  // ===================================================================== //
224  // Feel free to add custom code below this line, it will be preserved by
225  // the code generator.
226  //
227  // Just remember to:
228  // - Close the class declaration with };
229  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
230  // - Close the include guard with #endif
231  // ===================================================================== //
232  // --(BEGIN CUSTOM CODE)--
233 
234  /// Get the \ref Usd_InterpolationVals "interpolation" for the \em normals
235  /// attribute.
236  ///
237  /// Although 'normals' is not classified as a generic UsdGeomPrimvar (and
238  /// will not be included in the results of UsdGeomPrimvarsAPI::GetPrimvars() )
239  /// it does require an interpolation specification. The fallback
240  /// interpolation, if left unspecified, is UsdGeomTokens->vertex ,
241  /// which will generally produce smooth shading on a polygonal mesh.
242  /// To achieve partial or fully faceted shading of a polygonal mesh
243  /// with normals, one should use UsdGeomTokens->faceVarying or
244  /// UsdGeomTokens->uniform interpolation.
247 
248  /// Set the \ref Usd_InterpolationVals "interpolation" for the \em normals
249  /// attribute.
250  ///
251  /// \return true upon success, false if \p interpolation is not a legal
252  /// value as defined by UsdGeomPrimvar::IsValidInterpolation(), or if there
253  /// was a problem setting the value. No attempt is made to validate
254  /// that the normals attr's value contains the right number of elements
255  /// to match its interpolation to its prim's topology.
256  ///
257  /// \sa GetNormalsInterpolation()
259  bool SetNormalsInterpolation(TfToken const &interpolation);
260 
261  /// Compute the extent for the point cloud defined by points.
262  ///
263  /// \return true on success, false if extents was unable to be calculated.
264  ///
265  /// On success, extent will contain the axis-aligned bounding box of the
266  /// point cloud defined by points.
267  ///
268  /// This function is to provide easy authoring of extent for usd authoring
269  /// tools, hence it is static and acts outside a specific prim (as in
270  /// attribute based methods).
272  static bool ComputeExtent(const VtVec3fArray& points, VtVec3fArray* extent);
273 
274  /// \overload
275  /// Computes the extent as if the matrix \p transform was first applied.
277  static bool ComputeExtent(const VtVec3fArray& points,
278  const GfMatrix4d& transform, VtVec3fArray* extent);
279 
280 public:
281  /// Compute points given the positions, velocities and accelerations
282  /// at \p time.
283  ///
284  /// This will return \c false and leave \p points untouched if:
285  /// - \p points is NULL
286  /// - one of \p time and \p baseTime is numeric and the other is
287  /// UsdTimeCode::Default() (they must either both be numeric or both be
288  /// default)
289  /// - there is no authored points attribute
290  ///
291  /// If there is no error, we will return \c true and \p points will contain
292  /// the computed points.
293  ///
294  /// \param points - the out parameter for the new points. Its size
295  /// will depend on the authored data.
296  /// \param time - UsdTimeCode at which we want to evaluate the transforms
297  /// \param baseTime - required for correct interpolation between samples
298  /// when \em velocities or \em accelerations are
299  /// present. If there are samples for \em positions and
300  /// \em velocities at t1 and t2, normal value resolution
301  /// would attempt to interpolate between the two samples,
302  /// and if they could not be interpolated because they
303  /// differ in size (common in cases where velocity is
304  /// authored), will choose the sample at t1. When
305  /// sampling for the purposes of motion-blur, for example,
306  /// it is common, when rendering the frame at t2, to
307  /// sample at [ t2-shutter/2, t2+shutter/2 ] for a
308  /// shutter interval of \em shutter. The first sample
309  /// falls between t1 and t2, but we must sample at t2
310  /// and apply velocity-based interpolation based on those
311  /// samples to get a correct result. In such scenarios,
312  /// one should provide a \p baseTime of t2 when querying
313  /// \em both samples. If your application does not care
314  /// about off-sample interpolation, it can supply the
315  /// same value for \p baseTime that it does for \p time.
316  /// When \p baseTime is less than or equal to \p time,
317  /// we will choose the lower bracketing timeSample.
319  bool
322  const UsdTimeCode time,
323  const UsdTimeCode baseTime) const;
324 
325  /// Compute points as in ComputePointsAtTime, but using multiple sample times. An
326  /// array of vector arrays is returned where each vector array contains the
327  /// points for the corresponding time in \p times .
328  ///
329  /// \param times - A vector containing the UsdTimeCodes at which we want to
330  /// sample.
332  bool
334  std::vector<VtArray<GfVec3f>>* pointsArray,
335  const std::vector<UsdTimeCode>& times,
336  const UsdTimeCode baseTime) const;
337 
338  /// \overload
339  /// Perform the point computation. This does the same computation as
340  /// the non-static ComputePointsAtTime method, but takes all
341  /// data as parameters rather than accessing authored data.
342  ///
343  /// \param points - the out parameter for the computed points. Its size
344  /// will depend on the given data.
345  /// \param stage - the UsdStage
346  /// \param time - time at which we want to evaluate the transforms
347  /// \param positions - array containing all current points.
348  /// \param velocities - array containing all velocities. This array
349  /// must be either the same size as \p positions or
350  /// empty. If it is empty, points are computed as if
351  /// all velocities were zero in all dimensions.
352  /// \param velocitiesSampleTime - time at which the samples from
353  /// \p velocities were taken.
354  /// \param accelerations - array containing all accelerations.
355  /// This array must be either the same size as
356  /// \p positions or empty. If it is empty, points
357  /// are computed as if all accelerations were zero in
358  /// all dimensions.
359  /// \param velocityScale - \deprecated
361  static bool
364  UsdStageWeakPtr& stage,
366  const VtVec3fArray& positions,
367  const VtVec3fArray& velocities,
368  UsdTimeCode velocitiesSampleTime,
369  const VtVec3fArray& accelerations,
370  float velocityScale=1.0);
371 
372 };
373 
375 
376 #endif
GLdouble GLdouble GLint GLint const GLdouble * points
Definition: glad.h:2676
GT_API const UT_StringHolder time
UsdGeomPointBased(const UsdPrim &prim=UsdPrim())
Definition: pointBased.h:53
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USDGEOM_API bool ComputePointsAtTime(VtArray< GfVec3f > *points, const UsdTimeCode time, const UsdTimeCode baseTime) const
USDGEOM_API UsdAttribute CreateNormalsAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute GetAccelerationsAttr() const
UsdStagePtr UsdStageWeakPtr
Definition: common.h:38
USDGEOM_API UsdAttribute GetPointsAttr() const
Definition: token.h:70
Represents a non-concrete typed schema.
static const UsdSchemaKind schemaKind
Definition: pointBased.h:47
Definition: prim.h:116
USDGEOM_API TfToken GetNormalsInterpolation() const
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
Definition: path.h:273
USDGEOM_API UsdSchemaKind _GetSchemaKind() const override
GA_API const UT_StringHolder transform
UsdGeomPointBased(const UsdSchemaBase &schemaObj)
Definition: pointBased.h:61
static USDGEOM_API UsdGeomPointBased Get(const UsdStagePtr &stage, const SdfPath &path)
UsdSchemaKind
Definition: common.h:112
USDGEOM_API UsdAttribute CreateVelocitiesAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute GetNormalsAttr() const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
USDGEOM_API UsdAttribute CreateAccelerationsAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
virtual USDGEOM_API ~UsdGeomPointBased()
Destructor.
USDGEOM_API UsdAttribute CreatePointsAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API bool SetNormalsInterpolation(TfToken const &interpolation)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
Definition: type.h:47
#define USDGEOM_API
Definition: api.h:23
USDGEOM_API bool ComputePointsAtTimes(std::vector< VtArray< GfVec3f >> *pointsArray, const std::vector< UsdTimeCode > &times, const UsdTimeCode baseTime) const
Definition: value.h:146
USDGEOM_API UsdAttribute GetVelocitiesAttr() const
static USDGEOM_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
static USDGEOM_API bool ComputeExtent(const VtVec3fArray &points, VtVec3fArray *extent)