HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
xformCommonAPI.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_XFORMCOMMONAPI_H
25 #define USDGEOM_GENERATED_XFORMCOMMONAPI_H
26 
27 /// \file usdGeom/xformCommonAPI.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 #include "pxr/usd/usdGeom/tokens.h"
35 
37 #include "pxr/usd/usdGeom/xformOp.h"
38 
39 #include "pxr/base/vt/value.h"
40 
41 #include "pxr/base/gf/vec3d.h"
42 #include "pxr/base/gf/vec3f.h"
43 #include "pxr/base/gf/matrix4d.h"
44 
45 #include "pxr/base/tf/token.h"
46 #include "pxr/base/tf/type.h"
47 
49 
50 class SdfAssetPath;
51 
52 // -------------------------------------------------------------------------- //
53 // XFORMCOMMONAPI //
54 // -------------------------------------------------------------------------- //
55 
56 /// \class UsdGeomXformCommonAPI
57 ///
58 /// This class provides API for authoring and retrieving a standard set
59 /// of component transformations which include a scale, a rotation, a
60 /// scale-rotate pivot and a translation. The goal of the API is to enhance
61 /// component-wise interchange. It achieves this by limiting the set of allowed
62 /// basic ops and by specifying the order in which they are applied. In addition
63 /// to the basic set of ops, the 'resetXformStack' bit can also be set to
64 /// indicate whether the underlying xformable resets the parent transformation
65 /// (i.e. does not inherit it's parent's transformation).
66 ///
67 /// \sa UsdGeomXformCommonAPI::GetResetXformStack()
68 /// \sa UsdGeomXformCommonAPI::SetResetXformStack()
69 ///
70 /// The operator-bool for the class will inform you whether an existing
71 /// xformable is compatible with this API.
72 ///
73 /// The scale-rotate pivot is represented by a pair of (translate,
74 /// inverse-translate) xformOps around the scale and rotate operations.
75 /// The rotation operation can be any of the six allowed Euler angle sets.
76 /// \sa UsdGeomXformOp::Type.
77 ///
78 /// The xformOpOrder of an xformable that has all of the supported basic ops
79 /// is as follows:
80 /// ["xformOp:translate", "xformOp:translate:pivot", "xformOp:rotateXYZ",
81 /// "xformOp:scale", "!invert!xformOp:translate:pivot"].
82 ///
83 /// It is worth noting that all of the ops are optional. For example, an
84 /// xformable may have only a translate or a rotate. It would still be
85 /// considered as compatible with this API. Individual SetTranslate(),
86 /// SetRotate(), SetScale() and SetPivot() methods are provided by this API
87 /// to allow such sparse authoring.
88 ///
90 {
91 public:
92  /// Compile time constant representing what kind of schema this class is.
93  ///
94  /// \sa UsdSchemaType
96 
97  /// Construct a UsdGeomXformCommonAPI on UsdPrim \p prim .
98  /// Equivalent to UsdGeomXformCommonAPI::Get(prim.GetStage(), prim.GetPath())
99  /// for a \em valid \p prim, but will not immediately throw an error for
100  /// an invalid \p prim
101  explicit UsdGeomXformCommonAPI(const UsdPrim& prim=UsdPrim())
102  : UsdAPISchemaBase(prim)
103  {
104  }
105 
106  /// Construct a UsdGeomXformCommonAPI on the prim held by \p schemaObj .
107  /// Should be preferred over UsdGeomXformCommonAPI(schemaObj.GetPrim()),
108  /// as it preserves SchemaBase state.
109  explicit UsdGeomXformCommonAPI(const UsdSchemaBase& schemaObj)
110  : UsdAPISchemaBase(schemaObj)
111  {
112  }
113 
114  /// Destructor.
116  virtual ~UsdGeomXformCommonAPI();
117 
118  /// Return a vector of names of all pre-declared attributes for this schema
119  /// class and all its ancestor classes. Does not include attributes that
120  /// may be authored by custom/extended methods of the schemas involved.
122  static const TfTokenVector &
123  GetSchemaAttributeNames(bool includeInherited=true);
124 
125  /// Return a UsdGeomXformCommonAPI holding the prim adhering to this
126  /// schema at \p path on \p stage. If no prim exists at \p path on
127  /// \p stage, or if the prim at that path does not adhere to this schema,
128  /// return an invalid schema object. This is shorthand for the following:
129  ///
130  /// \code
131  /// UsdGeomXformCommonAPI(stage->GetPrimAtPath(path));
132  /// \endcode
133  ///
135  static UsdGeomXformCommonAPI
136  Get(const UsdStagePtr &stage, const SdfPath &path);
137 
138 
139 protected:
140  /// Returns the type of schema this class belongs to.
141  ///
142  /// \sa UsdSchemaType
144  UsdSchemaType _GetSchemaType() 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  // Feel free to add custom code below this line, it will be preserved by
161  // the code generator.
162  //
163  // Just remember to:
164  // - Close the class declaration with };
165  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
166  // - Close the include guard with #endif
167  // ===================================================================== //
168  // --(BEGIN CUSTOM CODE)--
169 
170  /// Enumerates the rotation order of the 3-angle Euler rotation.
178  };
179 
180  /// Enumerates the categories of ops that can be handled by XformCommonAPI.
181  /// For use with CreateXformOps().
182  enum OpFlags {
183  OpNone = 0,
185  OpPivot = 2,
186  OpRotate = 4,
187  OpScale = 8,
188  };
189 
190  /// Return type for CreateXformOps().
191  /// Stores the op of each type that is present on the prim.
192  /// The order of members in this struct corresponds to the expected op order
193  /// for XformCommonAPI.
194  struct Ops {
200  };
201 
202  /// Set values for the various component xformOps at a given \p time.
203  ///
204  /// Calling this method will call all of the supported ops to be created,
205  /// even if they only contain default (identity) values.
206  ///
207  /// To author individual operations selectively, use the Set[OpType]()
208  /// API.
209  ///
210  /// \note Once the rotation order has been established for a given xformable
211  /// (either because of an already defined (and compatible) rotate op or
212  /// from calling SetXformVectors() or SetRotate()), it cannot be changed.
213  ///
215  bool SetXformVectors(const GfVec3d &translation,
216  const GfVec3f &rotation,
217  const GfVec3f &scale,
218  const GfVec3f &pivot,
219  RotationOrder rotOrder,
220  const UsdTimeCode time) const;
221 
222  /// Retrieve values of the various component xformOps at a given \p time.
223  /// Identity values are filled in for the component xformOps that don't
224  /// exist or don't have an authored value.
225  ///
226  /// \note This method works even on prims with an incompatible xform schema,
227  /// i.e. when the bool operator returns false.
228  ///
229  /// When the underlying xformable has an incompatible xform schema, it
230  /// performs a full-on matrix decomposition to XYZ rotation order.
231  ///
233  bool GetXformVectors(GfVec3d *translation,
234  GfVec3f *rotation,
235  GfVec3f *scale,
236  GfVec3f *pivot,
237  RotationOrder *rotOrder,
238  const UsdTimeCode time) const;
239 
240  /// Retrieve values of the various component xformOps at a given \p time.
241  /// Identity values are filled in for the component xformOps that don't
242  /// exist or don't have an authored value.
243  ///
244  /// This method allows some additional flexibility for xform schemas that
245  /// do not strictly adhere to the xformCommonAPI. For incompatible schemas,
246  /// this method will attempt to reduce the schema into one from which
247  /// component vectors can be extracted by accumulating xformOp transforms
248  /// of the common types.
249  ///
250  /// \note When the underlying xformable has a compatible xform schema, the
251  /// usual component value extraction method is used instead. When the xform
252  /// schema is incompatible and it cannot be reduced by accumulating
253  /// transforms, it performs a full-on matrix decomposition to XYZ rotation
254  /// order.
255  ///
257  bool GetXformVectorsByAccumulation(GfVec3d* translation,
258  GfVec3f* rotation,
259  GfVec3f* scale,
260  GfVec3f* pivot,
262  const UsdTimeCode time) const;
263 
264  /// Returns whether the xformable resets the transform stack.
265  /// i.e., does not inherit the parent transformation.
267  bool GetResetXformStack() const;
268 
269  /// \anchor UsdGeomXformCommonAPI_Set_Individual_Ops
270  /// \name API for setting individual ops independently.
271  ///
272  /// @{
273 
274  /// Set translation at \p time to \p translation.
276  bool SetTranslate(const GfVec3d &translation,
277  const UsdTimeCode time=UsdTimeCode::Default()) const;
278 
279  /// Set pivot position at \p time to \p pivot.
281  bool SetPivot(const GfVec3f &pivot,
282  const UsdTimeCode time=UsdTimeCode::Default()) const;
283 
284  /// Set rotation at \p time to \p rotation.
286  bool SetRotate(const GfVec3f &rotation,
288  const UsdTimeCode time=UsdTimeCode::Default()) const;
289 
290  /// Set scale at \p time to \p scale.
292  bool SetScale(const GfVec3f &scale,
293  const UsdTimeCode time=UsdTimeCode::Default()) const;
294 
295  /// Set whether the xformable resets the transform stack.
296  /// i.e., does not inherit the parent transformation.
298  bool SetResetXformStack(bool resetXformStack) const;
299 
300  /// Creates the specified XformCommonAPI-compatible xform ops, or returns
301  /// the existing ops if they already exist. If successful, returns an Ops
302  /// object with all the ops on this prim, identified by type. If the
303  /// requested xform ops couldn't be created or the prim is not
304  /// XformCommonAPI-compatible, returns an Ops object with all invalid ops.
305  ///
306  /// The \p rotOrder is only used if OpRotate is specified. Otherwise,
307  /// it is ignored. (If you don't need to create a rotate op, you might find
308  /// it helpful to use the other overload that takes no rotation order.)
311  RotationOrder rotOrder,
312  OpFlags op1=OpNone,
313  OpFlags op2=OpNone,
314  OpFlags op3=OpNone,
315  OpFlags op4=OpNone) const;
316 
317  /// \overload
318  /// This overload does not take a rotation order. If you specify
319  /// OpRotate, then this overload assumes RotationOrderXYZ or the
320  /// previously-authored rotation order. (If you do need to create a rotate
321  /// op, you might find it helpful to use the other overload that explicitly
322  /// takes a rotation order.)
325  OpFlags op1=OpNone,
326  OpFlags op2=OpNone,
327  OpFlags op3=OpNone,
328  OpFlags op4=OpNone) const;
329 
330  /// @}
331 
332  /// \name Computing transforms
333  /// @{
334 
335  /// Return the 4x4 matrix that applies the rotation encoded by rotation
336  /// vector \p rotation using the rotation order \p rotationOrder.
337  ///
338  /// \deprecated Please use the result of ConvertRotationOrderToOpType()
339  /// along with UsdGeomXformOp::GetOpTransform() instead.
342  const GfVec3f &rotation,
343  const UsdGeomXformCommonAPI::RotationOrder rotationOrder);
344 
345  /// @}
346 
347  /// Converts the given \p rotOrder to the corresponding value in the
348  /// UsdGeomXformOp::Type enum. For example, RotationOrderYZX corresponds to
349  /// TypeRotateYZX. Raises a coding error if \p rotOrder is not one of the
350  /// named enumerators of RotationOrder.
353  RotationOrder rotOrder);
354 
355  /// Converts the given \p opType to the corresponding value in the
356  /// UsdGeomXformCommonAPI::RotationOrder enum. For example, TypeRotateYZX
357  /// corresponds to RotationOrderYZX. Raises a coding error if \p opType is
358  /// not convertible to RotationOrder (i.e., if it isn't a three-axis
359  /// rotation) and returns the default RotationOrderXYZ instead.
362  UsdGeomXformOp::Type opType);
363 
364  /// Whether the given \p opType has a corresponding value in the
365  /// UsdGeomXformCommonAPI::RotationOrder enum (i.e., whether it is a
366  /// three-axis rotation).
369  UsdGeomXformOp::Type opType);
370 
371 protected:
372  /// Returns whether the underlying xformable is compatible with the API.
374  bool _IsCompatible() const override;
375 };
376 
377 
379 
380 #endif
static USDGEOM_API RotationOrder ConvertOpTypeToRotationOrder(UsdGeomXformOp::Type opType)
static USDGEOM_API GfMatrix4d GetRotationTransform(const GfVec3f &rotation, const UsdGeomXformCommonAPI::RotationOrder rotationOrder)
UsdGeomXformCommonAPI(const UsdPrim &prim=UsdPrim())
static constexpr UsdTimeCode Default()
Definition: timeCode.h:113
USDGEOM_API bool SetPivot(const GfVec3f &pivot, const UsdTimeCode time=UsdTimeCode::Default()) const
Set pivot position at time to pivot.
GT_API const UT_StringHolder time
UsdGeomXformCommonAPI(const UsdSchemaBase &schemaObj)
USDGEOM_API bool SetResetXformStack(bool resetXformStack) const
GLenum GLenum GLenum GLenum GLenum scale
Definition: glew.h:13880
USDGEOM_API UsdSchemaType _GetSchemaType() const override
Definition: vec3f.h:63
USDGEOM_API bool GetXformVectors(GfVec3d *translation, GfVec3f *rotation, GfVec3f *scale, GfVec3f *pivot, RotationOrder *rotOrder, const UsdTimeCode time) const
static USDGEOM_API bool CanConvertOpTypeToRotationOrder(UsdGeomXformOp::Type opType)
static USDGEOM_API UsdGeomXformOp::Type ConvertRotationOrderToOpType(RotationOrder rotOrder)
USDGEOM_API bool _IsCompatible() const override
Returns whether the underlying xformable is compatible with the API.
Non-applied API schema.
UsdSchemaType
Definition: common.h:127
Definition: prim.h:132
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:446
USDGEOM_API bool SetRotate(const GfVec3f &rotation, UsdGeomXformCommonAPI::RotationOrder rotOrder=RotationOrderXYZ, const UsdTimeCode time=UsdTimeCode::Default()) const
Set rotation at time to rotation.
Definition: path.h:288
USDGEOM_API bool SetTranslate(const GfVec3d &translation, const UsdTimeCode time=UsdTimeCode::Default()) const
Set translation at time to translation.
USDGEOM_API bool SetXformVectors(const GfVec3d &translation, const GfVec3f &rotation, const GfVec3f &scale, const GfVec3f &pivot, RotationOrder rotOrder, const UsdTimeCode time) const
GLsizei const GLchar *const * path
Definition: glew.h:6461
static USDGEOM_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
virtual USDGEOM_API ~UsdGeomXformCommonAPI()
Destructor.
RotationOrder
Enumerates the rotation order of the 3-angle Euler rotation.
Definition: vec3d.h:63
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
static USDGEOM_API UsdGeomXformCommonAPI Get(const UsdStagePtr &stage, const SdfPath &path)
GA_API const UT_StringHolder pivot
Definition: type.h:64
USDGEOM_API Ops CreateXformOps(RotationOrder rotOrder, OpFlags op1=OpNone, OpFlags op2=OpNone, OpFlags op3=OpNone, OpFlags op4=OpNone) const
Type
Enumerates the set of all transformation operation types.
Definition: xformOp.h:116
#define USDGEOM_API
Definition: api.h:40
USDGEOM_API bool GetXformVectorsByAccumulation(GfVec3d *translation, GfVec3f *rotation, GfVec3f *scale, GfVec3f *pivot, UsdGeomXformCommonAPI::RotationOrder *rotOrder, const UsdTimeCode time) const
USDGEOM_API bool GetResetXformStack() const
static const UsdSchemaType schemaType
USDGEOM_API bool SetScale(const GfVec3f &scale, const UsdTimeCode time=UsdTimeCode::Default()) const
Set scale at time to scale.
MatType rotation(const Quat< typename MatType::value_type > &q, typename MatType::value_type eps=static_cast< typename MatType::value_type >(1.0e-8))
Return the rotation matrix specified by the given quaternion.
Definition: Mat.h:177