HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
layerOffset.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_SDF_LAYER_OFFSET_H
8 #define PXR_USD_SDF_LAYER_OFFSET_H
9 
10 /// \file sdf/layerOffset.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/sdf/api.h"
14 
15 #include <iosfwd>
16 #include <vector>
17 
19 
20 class SdfTimeCode;
21 
22 /// \class SdfLayerOffset
23 ///
24 /// Represents a time offset and scale between layers.
25 ///
26 /// The SdfLayerOffset class is an affine transform, providing both a scale and
27 /// a translate. It supports vector algebra semantics for composing
28 /// SdfLayerOffsets together via multiplication. The SdfLayerOffset class is
29 /// unitless: it does not refer to seconds or frames.
30 ///
31 /// For example, suppose layer A uses layer B, with an offset of X:
32 /// when bringing animation from B into A, you first apply the scale of X, and
33 /// then the offset. Suppose you have a scale of 2 and an offset of 24:
34 /// first multiply B's frame numbers by 2, and then add 24. The animation from
35 /// B as seen in A will take twice as long and start 24 frames later.
36 ///
37 /// Offsets are typically used in either sublayers or prim references. For more
38 /// information, see the SetSubLayerOffset() method of the SdfLayer class (the
39 /// subLayerOffsets property in Python), as well as the SetReference() and
40 /// GetReferenceLayerOffset() methods (the latter is the referenceLayerOffset
41 /// property in Python) of the SdfPrimSpec class.
42 ///
44 {
45 public:
46  /// \name Constructors
47  /// @{
48 
49  /// Constructs a new SdfLayerOffset instance.
50  SDF_API
51  explicit SdfLayerOffset(double offset = 0.0, double scale = 1.0);
52 
53  /// @}
54 
55  /// \name Accessors
56  /// @{
57 
58  /// Returns the time offset.
59  double GetOffset() const { return _offset; }
60 
61  /// Returns the time scale factor.
62  double GetScale() const { return _scale; }
63 
64  /// Sets the time offset.
65  void SetOffset(double newOffset) { _offset = newOffset; }
66 
67  /// Sets the time scale factor.
68  void SetScale(double newScale) { _scale = newScale; }
69 
70  /// Returns \c true if this is an identity transformation, with
71  /// an offset of 0.0 and a scale of 1.0.
72  SDF_API
73  bool IsIdentity() const;
74 
75  /// Returns \c true if this offset is valid, i.e. both the offset and
76  /// scale are finite (not infinite or NaN). Note that a valid layer
77  /// offset's inverse may be invalid.
78  SDF_API
79  bool IsValid() const;
80 
81  /// Gets the inverse offset, which performs the opposite transformation.
82  SDF_API
83  SdfLayerOffset GetInverse() const;
84 
85  /// \name Hashing
86  /// @{
87 
88  /// Returns hash for this offset.
89  SDF_API
90  size_t GetHash() const;
91 
92  /// Hash functor for hash maps and sets.
93  struct Hash {
94  size_t operator()(const SdfLayerOffset &offset) const {
95  return offset.GetHash();
96  }
97  };
98 
99  friend inline size_t hash_value(const SdfLayerOffset &offset) {
100  return offset.GetHash();
101  }
102 
103  /// @}
104 
105  /// \name Operators
106  /// @{
107 
108  /// Returns whether the offsets are equal.
109  SDF_API
110  bool operator==(const SdfLayerOffset &rhs) const;
111 
112  /// \sa SdfLayerOffset::operator==
113  bool operator!=(const SdfLayerOffset &rhs) const {
114  return !(*this == rhs);
115  }
116 
117  /// Returns whether this offset is less than another. The meaning
118  /// of less than is somewhat arbitrary.
119  SDF_API
120  bool operator<(const SdfLayerOffset &rhs) const;
121 
122  /// \sa SdfLayerOffset::operator<
123  bool operator>(const SdfLayerOffset& rhs) const {
124  return rhs < *this;
125  }
126 
127  /// \sa SdfLayerOffset::operator<
128  bool operator>=(const SdfLayerOffset& rhs) const {
129  return !(*this < rhs);
130  }
131 
132  /// \sa SdfLayerOffset::operator<
133  bool operator<=(const SdfLayerOffset& rhs) const {
134  return !(*this > rhs);
135  }
136 
137  /// Composes this with the offset \e rhs, such that the resulting
138  /// offset is equivalent to first applying \e rhs and then \e *this.
139  SDF_API
140  SdfLayerOffset operator*(const SdfLayerOffset &rhs) const;
141 
142  /// Applies the offset to the given value.
143  SDF_API
144  double operator*(double rhs) const;
145 
146  /// Applies the offset to the given value.
147  SDF_API
148  SdfTimeCode operator*(const SdfTimeCode &rhs) const;
149 
150  /// @}
151 
152 private:
153  double _offset;
154  double _scale;
155 };
156 
157 typedef std::vector<SdfLayerOffset> SdfLayerOffsetVector;
158 
159 ///
160 /// Writes the string representation of \a SdfLayerOffset to \a out.
161 SDF_API
162 std::ostream & operator<<( std::ostream &out,
163  const SdfLayerOffset &layerOffset );
164 
166 
167 #endif // PXR_USD_SDF_LAYER_OFFSET_H
SDF_API SdfLayerOffset GetInverse() const
Gets the inverse offset, which performs the opposite transformation.
SDF_API bool IsIdentity() const
SDF_API bool operator<(const SdfLayerOffset &rhs) const
bool operator>=(const SdfLayerOffset &rhs) const
Definition: layerOffset.h:128
SDF_API size_t GetHash() const
Returns hash for this offset.
std::vector< SdfLayerOffset > SdfLayerOffsetVector
Definition: layerOffset.h:157
GA_API const UT_StringHolder scale
bool operator!=(const SdfLayerOffset &rhs) const
Definition: layerOffset.h:113
void SetScale(double newScale)
Sets the time scale factor.
Definition: layerOffset.h:68
GLintptr offset
Definition: glcorearb.h:665
SDF_API SdfLayerOffset operator*(const SdfLayerOffset &rhs) const
bool operator>(const SdfLayerOffset &rhs) const
Definition: layerOffset.h:123
double GetScale() const
Returns the time scale factor.
Definition: layerOffset.h:62
size_t operator()(const SdfLayerOffset &offset) const
Definition: layerOffset.h:94
Hash functor for hash maps and sets.
Definition: layerOffset.h:93
SDF_API bool operator==(const SdfLayerOffset &rhs) const
Returns whether the offsets are equal.
SDF_API std::ostream & operator<<(std::ostream &out, const SdfLayerOffset &layerOffset)
Writes the string representation of SdfLayerOffset to out.
friend size_t hash_value(const SdfLayerOffset &offset)
Returns hash for this offset.
Definition: layerOffset.h:99
bool operator<=(const SdfLayerOffset &rhs) const
Definition: layerOffset.h:133
SDF_API bool IsValid() const
#define SDF_API
Definition: api.h:23
double GetOffset() const
Returns the time offset.
Definition: layerOffset.h:59
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
SDF_API SdfLayerOffset(double offset=0.0, double scale=1.0)
Constructs a new SdfLayerOffset instance.
void SetOffset(double newOffset)
Sets the time offset.
Definition: layerOffset.h:65