All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
xformOp.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 PXR_USD_USD_GEOM_XFORM_OP_H
8#define PXR_USD_USD_GEOM_XFORM_OP_H
9
11
12#include "pxr/pxr.h"
13#include "pxr/usd/usdGeom/api.h"
14#include "pxr/usd/usd/attribute.h"
15#include "pxr/usd/usd/attributeQuery.h"
17
18#include <string>
19#include <variant>
20#include <vector>
21#include <typeinfo>
22
24
25PXR_NAMESPACE_OPEN_SCOPE
26
27
29#define USDGEOM_XFORM_OP_TYPES \
30 (translate) \
31 (scale) \
32 (rotateX) \
33 (rotateY) \
34 (rotateZ) \
35 (rotateXYZ) \
36 (rotateXZY) \
37 (rotateYXZ) \
38 (rotateYZX) \
39 (rotateZXY) \
40 (rotateZYX) \
41 (orient) \
42 (transform) \
43 ((resetXformStack, "!resetXformStack!"))
44
68TF_DECLARE_PUBLIC_TOKENS(UsdGeomXformOpTypes, USDGEOM_API, USDGEOM_XFORM_OP_TYPES);
69
94{
95public:
96
98 enum Type {
119 };
120
126 };
127
128 // Default constructor returns an invalid XformOp. Exists for
129 // container classes
131 {
132 /* NOTHING */
133 }
134
151 USDGEOM_API
152 explicit UsdGeomXformOp(const UsdAttribute &attr, bool isInverseOp=false);
153
154 // -------------------------------------------------------
156 // -------------------------------------------------------
157
162 USDGEOM_API
163 static bool IsXformOp(const UsdAttribute &attr);
164
169 USDGEOM_API
170 static bool IsXformOp(const TfToken &attrName);
171
174 USDGEOM_API
175 static TfToken const &GetOpTypeToken(Type const opType);
176
178 USDGEOM_API
179 static Type GetOpTypeEnum(TfToken const &opTypeToken);
180
182 USDGEOM_API
184
187 USDGEOM_API
188 static const SdfValueTypeName &GetValueTypeName(const Type opType,
189 const Precision precision);
190
194 USDGEOM_API
195 static TfToken GetOpName(const Type opType,
196 const TfToken &opSuffix=TfToken(),
197 bool inverse=false);
198
199 // -------------------------------------------------------
201 // -------------------------------------------------------
202
204 Type GetOpType() const {
205 return _opType;
206 }
207
209 USDGEOM_API
211
213 bool IsInverseOp() const {
214 return _isInverseOp;
215 }
216
224 USDGEOM_API
226
228 USDGEOM_API
229 bool HasSuffix(TfToken const &suffix) const;
230
231 // ---------------------------------------------------------------
233 // ---------------------------------------------------------------
234
248 template <typename T>
249 bool GetAs(T* value, UsdTimeCode time) const {
250 VtValue v;
251 if (!Get(&v, time)) {
252 return false;
253 }
254 v.Cast<T>();
255 if (v.IsEmpty()){
256 TfType thisType = GetTypeName().GetType();
257 TF_CODING_ERROR("Unable to convert xformOp %s's value from %s to "
258 "requested type %s.", GetAttr().GetPath().GetText(),
259 thisType.GetTypeName().c_str(),
260 TfType::GetCanonicalTypeName(typeid(*value)).c_str());
261 return false;
262 }
263 *value = v.UncheckedGet<T>();
264 return true;
265 }
266
276 USDGEOM_API
277 static GfMatrix4d GetOpTransform(Type const opType,
278 VtValue const &opVal,
279 bool isInverseOp=false);
280
281
291 USDGEOM_API
293
299 bool MightBeTimeVarying() const {
300 return std::visit(_GetMightBeTimeVarying(), _attr);
301 }
302
303 // ---------------------------------------------------------------
305 // ---------------------------------------------------------------
306
310 operator UsdAttribute const& () const { return GetAttr(); }
311
313 UsdAttribute const &GetAttr() const {
314 return std::visit(_GetAttr(), _attr);
315 }
316
319 bool IsDefined() const { return IsXformOp(GetAttr()); }
320
321public:
327 explicit operator bool() const {
328 return IsDefined();
329 }
330
333 friend bool operator==(const UsdGeomXformOp &lhs,
334 const UsdGeomXformOp &rhs) {
335 return lhs.GetAttr() == rhs.GetAttr();
336 }
337
340 friend bool operator!=(const UsdGeomXformOp &lhs,
341 const UsdGeomXformOp &rhs) {
342 return !(lhs == rhs);
343 }
344
346 TfToken const &GetName() const { return GetAttr().GetName(); }
347
349 TfToken GetBaseName() const { return GetAttr().GetBaseName(); }
350
352 TfToken GetNamespace() const { return GetAttr().GetNamespace(); }
353
355 std::vector<std::string> SplitName() const { return GetAttr().SplitName(); };
356
359
364 template <typename T>
365 bool Get(T* value, UsdTimeCode time = UsdTimeCode::Default()) const {
366 return std::visit(_Get<T>(value, time), _attr);
367 }
368
375 template <typename T>
376 bool Set(T const & value, UsdTimeCode time = UsdTimeCode::Default()) const {
377 // Issue a coding error and return without setting value,
378 // if this is an inverse op.
379 if (_isInverseOp) {
380 TF_CODING_ERROR("Cannot set a value on the inverse xformOp '%s'. "
381 "Please set value on the paired non-inverse xformOp instead.",
382 GetOpName().GetText());
383 return false;
384 }
385
386 return GetAttr().Set(value, time);
387 }
388
391 bool GetTimeSamples(std::vector<double> *times) const {
392 return std::visit(_GetTimeSamples(times), _attr);
393 }
394
398 std::vector<double> *times) const {
399 return std::visit(
400 _GetTimeSamplesInInterval(interval, times), _attr);
401 }
402
404 size_t GetNumTimeSamples() const {
405 return std::visit(_GetNumTimeSamples(), _attr);
406 }
407
408private:
409 struct _ValidAttributeTagType {};
410
411public:
412 // Allow clients that guarantee \p attr is valid avoid having
413 // UsdGeomXformOp's ctor check again.
414 USDGEOM_API
415 UsdGeomXformOp(const UsdAttribute &attr, bool isInverseOp,
416 _ValidAttributeTagType);
417 USDGEOM_API
418 UsdGeomXformOp(UsdAttributeQuery &&query, bool isInverseOp,
419 _ValidAttributeTagType);
420private:
421 friend class UsdGeomXformable;
422
423 // Shared initialization function.
424 void _Init();
425
426 // Return the op-type for the string value \p str.
427 static Type _GetOpTypeEnumFromCString(char const *str, size_t len);
428
429 // Returns the attribute belonging to \p prim that corresponds to the
430 // given \p opName. It also populates the output parameter \p isInverseOp
431 // appropriately.
432 //
433 // The attribute that's returned will be invalid if the
434 // corresponding xformOp attribute doesn't exist on the prim.
435 //
436 static UsdAttribute _GetXformOpAttr(UsdPrim const& prim,
437 const TfToken &opName, bool *isInverseOp);
438
439 // Private method for creating and using an attribute query interally for
440 // this xformOp.
441 void _CreateAttributeQuery() const {
442 _attr = UsdAttributeQuery(GetAttr());
443 }
444
445 // Factory for UsdGeomXformable's use, so that we can encapsulate the
446 // logic of what discriminates XformOp in this class, while
447 // preserving the pattern that attributes can only be created
448 // via their container objects.
449 //
450 // \p opType must be one of UsdGeomXformOp::Type
451 //
452 // \p precision must be one of UsdGeomXformOp::Precision.
453 //
454 // \return an invalid UsdGeomXformOp if we failed to create a valid
455 // attribute, a valid UsdGeomXformOp otherwise. It is not an
456 // error to create over an existing, compatible attribute.
457 //
458 // It is a failed verification for \p prim to be invalid/expired
459 //
460 // \sa UsdPrim::CreateAttribute()
461 UsdGeomXformOp(UsdPrim const& prim, Type const opType,
462 Precision const precision, TfToken const &opSuffix=TfToken(),
463 bool inverse=false);
464
465 // UsdAttributeQuery already contains a copy of the associated UsdAttribute.
466 // To minimize the memory usage, we only store one or the other.
467 //
468 // The lifetime of a UsdAttributeQuery needs to be managed very carefully as
469 // it gets invalidated whenever the associated attribute is authored.
470 // Hence, access to the creation of an attribute query is restricted inside
471 // a private member function named _CreateAttributeQuery().
472 //
473 mutable std::variant<UsdAttribute, UsdAttributeQuery> _attr;
474
475 Type _opType;
476 bool _isInverseOp;
477
478 // Visitor for getting xformOp value.
479 template <class T>
480 struct _Get
481 {
482 _Get(T *value_,
483 UsdTimeCode time_ = UsdTimeCode::Default()) : value (value_), time(time_)
484 {}
485
486 bool operator()(const UsdAttribute &attr) const
487 {
488 return attr.Get(value, time);
489 }
490
491 bool operator()(const UsdAttributeQuery &attrQuery) const
492 {
493 return attrQuery.Get(value, time);
494 }
495
496 T *value;
497 UsdTimeCode time;
498 };
499
500 // Visitor for getting a const-reference to the UsdAttribute.
501 struct _GetAttr {
502
503 _GetAttr() {}
504
505 const UsdAttribute &operator()(const UsdAttribute &attr) const
506 {
507 return attr;
508 }
509
510 const UsdAttribute &operator()(const UsdAttributeQuery &attrQuery) const
511 {
512 return attrQuery.GetAttribute();
513 }
514 };
515
516 // Visitor for getting all the time samples.
517 struct _GetTimeSamples {
518
519 _GetTimeSamples(std::vector<double> *times_) : times(times_) {}
520
521 bool operator()(const UsdAttribute &attr) const
522 {
523 return attr.GetTimeSamples(times);
524 }
525
526 bool operator()(const UsdAttributeQuery &attrQuery) const
527 {
528 return attrQuery.GetTimeSamples(times);
529 }
530
531 std::vector<double> *times;
532 };
533
534 // Visitor for getting all the time samples within a given interval.
535 struct _GetTimeSamplesInInterval {
536
537 _GetTimeSamplesInInterval(const GfInterval &interval_,
538 std::vector<double> *times_)
539 : interval(interval_), times(times_)
540 {}
541
542 bool operator()(const UsdAttribute &attr) const
543 {
544 return attr.GetTimeSamplesInInterval(interval, times);
545 }
546
547 bool operator()(const UsdAttributeQuery &attrQuery) const
548 {
549 return attrQuery.GetTimeSamplesInInterval(interval, times);
550 }
551
552 const GfInterval &interval;
553 std::vector<double> *times;
554 };
555
556 // Visitor for getting the number of time samples.
557 struct _GetNumTimeSamples {
558
559 _GetNumTimeSamples() {}
560
561 size_t operator()(const UsdAttribute &attr) const
562 {
563 return attr.GetNumTimeSamples();
564 }
565
566 size_t operator()(const UsdAttributeQuery &attrQuery) const
567 {
568 return attrQuery.GetNumTimeSamples();
569 }
570 };
571
572 // Visitor for determining whether the op might vary over time.
573 struct _GetMightBeTimeVarying {
574
575 _GetMightBeTimeVarying() {}
576
577 bool operator()(const UsdAttribute &attr) const
578 {
579 return attr.ValueMightBeTimeVarying();
580 }
581
582 bool operator()(const UsdAttributeQuery &attrQuery) const
583 {
584 return attrQuery.ValueMightBeTimeVarying();
585 }
586 };
587
588};
589
590
591
592PXR_NAMESPACE_CLOSE_SCOPE
593
594#endif // USD_XFORMOP_H
A basic mathematical interval class.
Definition: interval.h:33
Stores a 4x4 matrix of double elements.
Definition: matrix4d.h:71
Represents a value type name, i.e.
Definition: valueTypeName.h:71
SDF_API const TfType & GetType() const
Returns the TfType of the type.
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
TfType represents a dynamic runtime type.
Definition: type.h:48
TF_API const std::string & GetTypeName() const
Return the machine-independent name for this type.
static TF_API std::string GetCanonicalTypeName(const std::type_info &)
Return the canonical typeName used for a given std::type_info.
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:160
USD_API bool GetTimeSamples(std::vector< double > *times) const
Populates a vector with authored sample times.
USD_API bool GetTimeSamplesInInterval(const GfInterval &interval, std::vector< double > *times) const
Populates a vector with authored sample times in interval.
bool Set(const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
Set the value of this attribute in the current UsdEditTarget to value at UsdTimeCode time,...
Definition: attribute.h:461
USD_API SdfValueTypeName GetTypeName() const
Return the "scene description" value type name for this attribute.
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Perform value resolution to fetch the value of this attribute at the requested UsdTimeCode time,...
Definition: attribute.h:420
USD_API size_t GetNumTimeSamples() const
Returns the number of time samples that have been authored.
USD_API bool ValueMightBeTimeVarying() const
Return true if it is possible, but not certain, that this attribute's value changes over time,...
Object for efficiently making repeated queries for attribute values.
USD_API bool GetTimeSamples(std::vector< double > *times) const
Populates a vector with authored sample times.
USD_API bool GetTimeSamplesInInterval(const GfInterval &interval, std::vector< double > *times) const
Populates a vector with authored sample times in interval.
USD_API const UsdAttribute & GetAttribute() const
Return the attribute associated with this query.
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Perform value resolution to fetch the value of the attribute associated with this query at the reques...
USD_API size_t GetNumTimeSamples() const
Returns the number of time samples that have been authored.
USD_API bool ValueMightBeTimeVarying() const
Return true if it is possible, but not certain, that this attribute's value changes over time,...
Schema wrapper for UsdAttribute for authoring and computing transformation operations,...
Definition: xformOp.h:94
friend bool operator==(const UsdGeomXformOp &lhs, const UsdGeomXformOp &rhs)
Equality comparison.
Definition: xformOp.h:333
TfToken GetBaseName() const
Definition: xformOp.h:349
Type
Enumerates the set of all transformation operation types.
Definition: xformOp.h:98
@ TypeRotateY
Rotation about the Y-axis, in degrees.
Definition: xformOp.h:103
@ TypeRotateXYZ
Set of 3 canonical Euler rotations in XYZ order.
Definition: xformOp.h:105
@ TypeScale
XYZ scale.
Definition: xformOp.h:101
@ TypeOrient
Arbitrary axis/angle rotation, expressed as a quaternion.
Definition: xformOp.h:117
@ TypeTranslate
XYZ translation.
Definition: xformOp.h:100
@ TypeRotateZ
Rotation about the Z-axis, in degrees.
Definition: xformOp.h:104
@ TypeRotateX
Rotation about the X-axis, in degrees.
Definition: xformOp.h:102
@ TypeTransform
A 4x4 matrix transformation.
Definition: xformOp.h:118
@ TypeRotateZYX
Set of 3 canonical Euler rotations in ZYX order.
Definition: xformOp.h:115
@ TypeInvalid
Represents an invalid xformOp.
Definition: xformOp.h:99
@ TypeRotateYZX
Set of 3 canonical Euler rotations in YZX order.
Definition: xformOp.h:111
@ TypeRotateZXY
Set of 3 canonical Euler rotations in ZXY order.
Definition: xformOp.h:113
@ TypeRotateXZY
Set of 3 canonical Euler rotations in XZY order.
Definition: xformOp.h:107
@ TypeRotateYXZ
Set of 3 canonical Euler rotations in YXZ order.
Definition: xformOp.h:109
USDGEOM_API UsdGeomXformOp(const UsdAttribute &attr, bool isInverseOp=false)
Speculative constructor that will produce a valid UsdGeomXformOp when attr already represents an attr...
USDGEOM_API bool HasSuffix(TfToken const &suffix) const
Does this op have the given suffix in its name.
friend bool operator!=(const UsdGeomXformOp &lhs, const UsdGeomXformOp &rhs)
Inequality comparison.
Definition: xformOp.h:340
static USDGEOM_API TfToken GetOpName(const Type opType, const TfToken &opSuffix=TfToken(), bool inverse=false)
Returns the xformOp's name as it appears in xformOpOrder, given the opType, the (optional) suffix and...
USDGEOM_API Precision GetPrecision() const
Returns the precision level of the xform op.
static USDGEOM_API GfMatrix4d GetOpTransform(Type const opType, VtValue const &opVal, bool isInverseOp=false)
Return the 4x4 matrix that applies the transformation encoded by op opType and data value opVal.
bool IsInverseOp() const
Returns whether the xformOp represents an inverse operation.
Definition: xformOp.h:213
USDGEOM_API GfMatrix4d GetOpTransform(UsdTimeCode time) const
Return the 4x4 matrix that applies the transformation encoded in this op at time.
TfToken GetNamespace() const
Definition: xformOp.h:352
bool GetTimeSamples(std::vector< double > *times) const
Populates the list of time samples at which the associated attribute is authored.
Definition: xformOp.h:391
static USDGEOM_API bool IsXformOp(const UsdAttribute &attr)
Test whether a given UsdAttribute represents valid XformOp, which implies that creating a UsdGeomXfor...
bool IsDefined() const
Return true if the wrapped UsdAttribute::IsDefined(), and in addition the attribute is identified as ...
Definition: xformOp.h:319
std::vector< std::string > SplitName() const
Definition: xformOp.h:355
Type GetOpType() const
Return the operation type of this op, one of UsdGeomXformOp::Type.
Definition: xformOp.h:204
static USDGEOM_API TfToken const & GetOpTypeToken(Type const opType)
Returns the TfToken used to encode the given opType.
static USDGEOM_API Type GetOpTypeEnum(TfToken const &opTypeToken)
Returns the Type enum associated with the given opTypeToken.
bool MightBeTimeVarying() const
Determine whether there is any possibility that this op's value may vary over time.
Definition: xformOp.h:299
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
Get the attribute value of the XformOp at time.
Definition: xformOp.h:365
SdfValueTypeName GetTypeName() const
Definition: xformOp.h:358
TfToken const & GetName() const
Definition: xformOp.h:346
UsdAttribute const & GetAttr() const
Explicit UsdAttribute extractor.
Definition: xformOp.h:313
USDGEOM_API TfToken GetOpName() const
Returns the opName as it appears in the xformOpOrder attribute.
Precision
Precision with which the value of the tranformation operation is encoded.
Definition: xformOp.h:122
@ PrecisionFloat
Floating-point precision.
Definition: xformOp.h:124
@ PrecisionDouble
Double precision.
Definition: xformOp.h:123
@ PrecisionHalf
Half-float precision.
Definition: xformOp.h:125
size_t GetNumTimeSamples() const
Returns the number of time samples authored for this xformOp.
Definition: xformOp.h:404
bool GetTimeSamplesInInterval(const GfInterval &interval, std::vector< double > *times) const
Populates the list of time samples within the given interval, at which the associated attribute is au...
Definition: xformOp.h:397
bool GetAs(T *value, UsdTimeCode time) const
We allow ops to be encoded with varying degrees of precision, depending on the clients needs and cons...
Definition: xformOp.h:249
static USDGEOM_API bool IsXformOp(const TfToken &attrName)
Test whether a given attrbute name represents a valid XformOp, which implies that creating a UsdGeomX...
static USDGEOM_API const SdfValueTypeName & GetValueTypeName(const Type opType, const Precision precision)
Returns the value typeName token that corresponds to the given combination of opType and precision.
static USDGEOM_API Precision GetPrecisionFromValueTypeName(const SdfValueTypeName &typeName)
Returns the precision corresponding to the given value typeName.
bool Set(T const &value, UsdTimeCode time=UsdTimeCode::Default()) const
Set the attribute value of the XformOp at time.
Definition: xformOp.h:376
Base class for all transformable prims, which allows arbitrary sequences of component affine transfor...
Definition: xformable.h:236
const TfToken & GetName() const
Return the full name of this object, i.e.
Definition: object.h:221
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:117
USD_API TfToken GetBaseName() const
Return this property's name with all namespace prefixes removed, i.e.
USD_API TfToken GetNamespace() const
Return this property's complete namespace prefix.
USD_API std::vector< std::string > SplitName() const
Return this property's name elements including namespaces and its base name as the final element.
Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdT...
Definition: timeCode.h:67
static constexpr UsdTimeCode Default()
Produce a UsdTimeCode representing the sentinel value for 'default'.
Definition: timeCode.h:95
Provides a container which may hold any type, and provides introspection and iteration over array typ...
Definition: value.h:147
bool IsEmpty() const
Returns true iff this value is empty.
Definition: value.h:1285
static VtValue Cast(VtValue const &val)
Return a VtValue holding val cast to hold T.
Definition: value.h:1189
T const & UncheckedGet() const &
Returns a const reference to the held object if the held object is of type T.
Definition: value.h:1104
#define TF_CODING_ERROR(fmt, args)
Issue an internal programming error, but continue execution.
Definition: diagnostic.h:68
This file defines some macros that are useful for declaring and using static TfTokens.
#define TF_DECLARE_PUBLIC_TOKENS(...)
Macro to define public tokens.
Definition: staticTokens.h:81