HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
motionAPI.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_MOTIONAPI_H
8 #define USDGEOM_GENERATED_MOTIONAPI_H
9 
10 /// \file usdGeom/motionAPI.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/usdGeom/api.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 // MOTIONAPI //
34 // -------------------------------------------------------------------------- //
35 
36 /// \class UsdGeomMotionAPI
37 ///
38 /// UsdGeomMotionAPI encodes data that can live on any prim that
39 /// may affect computations involving:
40 /// - computed motion for motion blur
41 /// - sampling for motion blur
42 ///
43 /// The \ref GetMotionBlurScaleAttr() "motion:blurScale" attribute allows
44 /// artists to scale the __amount__ of motion blur to be rendered for parts
45 /// of the scene without changing the recorded animation. See
46 /// \ref UsdGeomMotionAPI_blurScale for use and implementation details.
47 ///
48 ///
49 ///
51 {
52 public:
53  /// Compile time constant representing what kind of schema this class is.
54  ///
55  /// \sa UsdSchemaKind
57 
58  /// Construct a UsdGeomMotionAPI on UsdPrim \p prim .
59  /// Equivalent to UsdGeomMotionAPI::Get(prim.GetStage(), prim.GetPath())
60  /// for a \em valid \p prim, but will not immediately throw an error for
61  /// an invalid \p prim
62  explicit UsdGeomMotionAPI(const UsdPrim& prim=UsdPrim())
63  : UsdAPISchemaBase(prim)
64  {
65  }
66 
67  /// Construct a UsdGeomMotionAPI on the prim held by \p schemaObj .
68  /// Should be preferred over UsdGeomMotionAPI(schemaObj.GetPrim()),
69  /// as it preserves SchemaBase state.
70  explicit UsdGeomMotionAPI(const UsdSchemaBase& schemaObj)
71  : UsdAPISchemaBase(schemaObj)
72  {
73  }
74 
75  /// Destructor.
77  virtual ~UsdGeomMotionAPI();
78 
79  /// Return a vector of names of all pre-declared attributes for this schema
80  /// class and all its ancestor classes. Does not include attributes that
81  /// may be authored by custom/extended methods of the schemas involved.
83  static const TfTokenVector &
84  GetSchemaAttributeNames(bool includeInherited=true);
85 
86  /// Return a UsdGeomMotionAPI holding the prim adhering to this
87  /// schema at \p path on \p stage. If no prim exists at \p path on
88  /// \p stage, or if the prim at that path does not adhere to this schema,
89  /// return an invalid schema object. This is shorthand for the following:
90  ///
91  /// \code
92  /// UsdGeomMotionAPI(stage->GetPrimAtPath(path));
93  /// \endcode
94  ///
96  static UsdGeomMotionAPI
97  Get(const UsdStagePtr &stage, const SdfPath &path);
98 
99 
100  /// Returns true if this <b>single-apply</b> API schema can be applied to
101  /// the given \p prim. If this schema can not be a applied to the prim,
102  /// this returns false and, if provided, populates \p whyNot with the
103  /// reason it can not be applied.
104  ///
105  /// Note that if CanApply returns false, that does not necessarily imply
106  /// that calling Apply will fail. Callers are expected to call CanApply
107  /// before calling Apply if they want to ensure that it is valid to
108  /// apply a schema.
109  ///
110  /// \sa UsdPrim::GetAppliedSchemas()
111  /// \sa UsdPrim::HasAPI()
112  /// \sa UsdPrim::CanApplyAPI()
113  /// \sa UsdPrim::ApplyAPI()
114  /// \sa UsdPrim::RemoveAPI()
115  ///
117  static bool
118  CanApply(const UsdPrim &prim, std::string *whyNot=nullptr);
119 
120  /// Applies this <b>single-apply</b> API schema to the given \p prim.
121  /// This information is stored by adding "MotionAPI" to the
122  /// token-valued, listOp metadata \em apiSchemas on the prim.
123  ///
124  /// \return A valid UsdGeomMotionAPI object is returned upon success.
125  /// An invalid (or empty) UsdGeomMotionAPI object is returned upon
126  /// failure. See \ref UsdPrim::ApplyAPI() for conditions
127  /// resulting in failure.
128  ///
129  /// \sa UsdPrim::GetAppliedSchemas()
130  /// \sa UsdPrim::HasAPI()
131  /// \sa UsdPrim::CanApplyAPI()
132  /// \sa UsdPrim::ApplyAPI()
133  /// \sa UsdPrim::RemoveAPI()
134  ///
136  static UsdGeomMotionAPI
137  Apply(const UsdPrim &prim);
138 
139 protected:
140  /// Returns the kind of schema this class belongs to.
141  ///
142  /// \sa UsdSchemaKind
144  UsdSchemaKind _GetSchemaKind() const override;
145 
146 private:
147  // needs to invoke _GetStaticTfType.
148  friend class UsdSchemaRegistry;
150  static const TfType &_GetStaticTfType();
151 
152  static bool _IsTypedSchema();
153 
154  // override SchemaBase virtuals.
156  const TfType &_GetTfType() const override;
157 
158 public:
159  // --------------------------------------------------------------------- //
160  // MOTIONBLURSCALE
161  // --------------------------------------------------------------------- //
162  /// BlurScale is an __inherited__ float attribute that stipulates
163  /// the rendered motion blur (as typically specified via UsdGeomCamera's
164  /// _shutter:open_ and _shutter:close_ properties) should be scaled for
165  /// __all objects__ at and beneath the prim in namespace on which the
166  /// _motion:blurScale_ value is specified.
167  ///
168  /// Without changing any other data in the scene, _blurScale_ allows artists to
169  /// "dial in" the amount of blur on a per-object basis. A _blurScale_
170  /// value of zero removes all blur, a value of 0.5 reduces blur by half,
171  /// and a value of 2.0 doubles the blur. The legal range for _blurScale_
172  /// is [0, inf), although very high values may result in extremely expensive
173  /// renders, and may exceed the capabilities of some renderers.
174  ///
175  /// Although renderers are free to implement this feature however they see
176  /// fit, see \ref UsdGeomMotionAPI_blurScale for our guidance on implementing
177  /// the feature universally and efficiently.
178  ///
179  /// \sa ComputeMotionBlurScale()
180  ///
181  ///
182  /// | ||
183  /// | -- | -- |
184  /// | Declaration | `float motion:blurScale = 1` |
185  /// | C++ Type | float |
186  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
189 
190  /// See GetMotionBlurScaleAttr(), and also
191  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
192  /// If specified, author \p defaultValue as the attribute's default,
193  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
194  /// the default for \p writeSparsely is \c false.
196  UsdAttribute CreateMotionBlurScaleAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
197 
198 public:
199  // --------------------------------------------------------------------- //
200  // VELOCITYSCALE
201  // --------------------------------------------------------------------- //
202  /// \deprecated
203  ///
204  /// VelocityScale is an **inherited** float attribute that
205  /// velocity-based schemas (e.g. PointBased, PointInstancer) can consume
206  /// to compute interpolated positions and orientations by applying
207  /// velocity and angularVelocity, which is required for interpolating
208  /// between samples when topology is varying over time. Although these
209  /// quantities are generally physically computed by a simulator, sometimes
210  /// we require more or less motion-blur to achieve the desired look.
211  /// VelocityScale allows artists to dial-in, as a post-sim correction,
212  /// a scale factor to be applied to the velocity prior to computing
213  /// interpolated positions from it.
214  ///
215  /// | ||
216  /// | -- | -- |
217  /// | Declaration | `float motion:velocityScale = 1` |
218  /// | C++ Type | float |
219  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
222 
223  /// See GetVelocityScaleAttr(), and also
224  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
225  /// If specified, author \p defaultValue as the attribute's default,
226  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
227  /// the default for \p writeSparsely is \c false.
229  UsdAttribute CreateVelocityScaleAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
230 
231 public:
232  // --------------------------------------------------------------------- //
233  // NONLINEARSAMPLECOUNT
234  // --------------------------------------------------------------------- //
235  /// Determines the number of position or transformation samples
236  /// created when motion is described by attributes contributing non-linear
237  /// terms.
238  ///
239  /// To give an example, imagine an application (such as a
240  /// renderer) consuming 'points' and the USD document also
241  /// contains 'accelerations' for the same prim. Unless the
242  /// application can consume these 'accelerations' itself, an
243  /// intermediate layer has to compute samples within the sampling
244  /// interval for the point positions based on the value of
245  /// 'points', 'velocities' and 'accelerations'. The number of these
246  /// samples is given by 'nonlinearSampleCount'. The samples are
247  /// equally spaced within the sampling interval.
248  ///
249  /// Another example involves the PointInstancer where
250  /// 'nonlinearSampleCount' is relevant when 'angularVelocities'
251  /// or 'accelerations' are authored.
252  ///
253  /// 'nonlinearSampleCount' is an **inherited** attribute, also
254  /// see ComputeNonlinearSampleCount()
255  ///
256  /// | ||
257  /// | -- | -- |
258  /// | Declaration | `int motion:nonlinearSampleCount = 3` |
259  /// | C++ Type | int |
260  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Int |
263 
264  /// See GetNonlinearSampleCountAttr(), and also
265  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
266  /// If specified, author \p defaultValue as the attribute's default,
267  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
268  /// the default for \p writeSparsely is \c false.
270  UsdAttribute CreateNonlinearSampleCountAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
271 
272 public:
273  // ===================================================================== //
274  // Feel free to add custom code below this line, it will be preserved by
275  // the code generator.
276  //
277  // Just remember to:
278  // - Close the class declaration with };
279  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
280  // - Close the include guard with #endif
281  // ===================================================================== //
282  // --(BEGIN CUSTOM CODE)--
283 
284  /// \deprecated
285  ///
286  /// Compute the inherited value of *velocityScale* at \p time, i.e. the
287  /// authored value on the prim closest to this prim in namespace, resolved
288  /// upwards through its ancestors in namespace.
289  ///
290  /// \return the inherited value, or 1.0 if neither the prim nor any
291  /// of its ancestors possesses an authored value.
292  ///
293  /// \note this is a reference implementation that is not particularly
294  /// efficient if evaluating over many prims, because it does not share
295  /// inherited results.
298 
299  /// Compute the inherited value of *nonlinearSampleCount* at \p time,
300  /// i.e. the authored value on the prim closest to this prim in namespace,
301  /// resolved upwards through its ancestors in namespace.
302  ///
303  /// \return the inherited value, or 3 if neither the prim nor any
304  /// of its ancestors possesses an authored value.
305  ///
306  /// \note this is a reference implementation that is not particularly
307  /// efficient if evaluating over many prims, because it does not share
308  /// inherited results.
312 
313  /// Compute the inherited value of *motion:blurScale* at \p time, i.e. the
314  /// authored value on the prim closest to this prim in namespace, resolved
315  /// upwards through its ancestors in namespace.
316  ///
317  /// \return the inherited value, or 1.0 if neither the prim nor any
318  /// of its ancestors possesses an authored value.
319  ///
320  /// \note this is a reference implementation that is not particularly
321  /// efficient if evaluating over many prims, because it does not share
322  /// inherited results.
326 
327 };
328 
330 
331 #endif
static const UsdSchemaKind schemaKind
Definition: motionAPI.h:56
static constexpr UsdTimeCode Default()
Definition: timeCode.h:113
USDGEOM_API UsdAttribute CreateMotionBlurScaleAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
GT_API const UT_StringHolder time
Single Apply API schema.
USDGEOM_API UsdAttribute GetMotionBlurScaleAttr() const
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USDGEOM_API UsdAttribute CreateVelocityScaleAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API int ComputeNonlinearSampleCount(UsdTimeCode time=UsdTimeCode::Default()) const
USDGEOM_API UsdAttribute GetVelocityScaleAttr() const
UsdGeomMotionAPI(const UsdSchemaBase &schemaObj)
Definition: motionAPI.h:70
USDGEOM_API float ComputeMotionBlurScale(UsdTimeCode time=UsdTimeCode::Default()) const
USDGEOM_API UsdAttribute GetNonlinearSampleCountAttr() const
UsdGeomMotionAPI(const UsdPrim &prim=UsdPrim())
Definition: motionAPI.h:62
Definition: prim.h:116
USDGEOM_API UsdSchemaKind _GetSchemaKind() const override
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
Definition: path.h:273
USDGEOM_API UsdAttribute CreateNonlinearSampleCountAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API float ComputeVelocityScale(UsdTimeCode time=UsdTimeCode::Default()) const
UsdSchemaKind
Definition: common.h:112
static USDGEOM_API UsdGeomMotionAPI Apply(const UsdPrim &prim)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
Definition: type.h:47
virtual USDGEOM_API ~UsdGeomMotionAPI()
Destructor.
#define USDGEOM_API
Definition: api.h:23
static USDGEOM_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
static USDGEOM_API UsdGeomMotionAPI Get(const UsdStagePtr &stage, const SdfPath &path)
Definition: value.h:146
static USDGEOM_API bool CanApply(const UsdPrim &prim, std::string *whyNot=nullptr)