HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
timeCode.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 PXR_USD_USD_TIME_CODE_H
25 #define PXR_USD_USD_TIME_CODE_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usd/api.h"
29 #include "pxr/usd/sdf/timeCode.h"
30 #include "pxr/base/arch/hints.h"
32 #include "pxr/base/tf/hash.h"
33 
34 #include <limits>
35 #include <iosfwd>
36 #include <cmath>
37 
38 
40 
41 
42 #define USD_TIME_CODE_TOKENS \
43  (DEFAULT) \
44  (EARLIEST)
45 
47 
48 
49 /// \class UsdTimeCode
50 ///
51 /// Represent a time value, which may be either numeric, holding a double
52 /// value, or a sentinel value UsdTimeCode::Default().
53 ///
54 /// A UsdTimeCode does \em not represent an
55 /// <a href="https://en.wikipedia.org/wiki/SMPTE_timecode">SMPTE timecode</a>,
56 /// although we may, in future, support conversion functions between the two.
57 /// Instead, UsdTimeCode is an abstraction that acknowledges that in the
58 /// principal domains of use for USD, there are many different ways of encoding
59 /// time, and USD must be able to capture and translate between all of them for
60 /// interchange, retaining as much intent of the authoring application as
61 /// possible.
62 ///
63 /// A UsdTimeCode is therefore a unitless, generic time measurement that serves
64 /// as the ordinate for time-sampled data in USD files. A client of USD relies
65 /// on the UsdStage (which in turn consults metadata authored in its root layer)
66 /// to define the mapping of TimeCodes to units like seconds and frames.
67 ///
68 /// \sa UsdStage::GetStartTimeCode()
69 /// \sa UsdStage::GetEndTimeCode()
70 /// \sa UsdStage::GetTimeCodesPerSecond()
71 /// \sa UsdStage::GetFramesPerSecond()
72 ///
73 /// As described in \ref Usd_ValueResolution , USD optionally provides an
74 /// unvarying, 'default' value for every attribute. UsdTimeCode embodies a time
75 /// value that can either be a floating-point sample time, or the default.
76 ///
77 /// All UsdAttribute and derived API that requires a time parameter defaults
78 /// to UsdTimeCode::Default() if the parameter is left unspecified, and
79 /// auto-constructs from a floating-point argument.
80 ///
81 /// UsdTimeCode::EarliestTime() is provided to aid clients who wish
82 /// to retrieve the first authored timesample for any attribute.
83 ///
84 class UsdTimeCode {
85 public:
86  /// Construct with optional time value. Impilicitly convert from double.
87  constexpr UsdTimeCode(double t = 0.0) noexcept : _value(t) {}
88 
89  /// Construct and implicitly cast from SdfTimeCode.
90  constexpr UsdTimeCode(const SdfTimeCode &timeCode) noexcept
91  : _value(timeCode.GetValue()) {}
92 
93  /// Produce a UsdTimeCode representing the lowest/earliest possible
94  /// timeCode. Thus, for any given timeSample \em s, its time ordinate
95  /// \em t will obey: t >= UsdTimeCode::EarliestTime()
96  ///
97  /// This is useful for clients that wish to retrieve the first authored
98  /// timeSample for an attribute, as they can use UsdTimeCode::EarliestTime()
99  /// as the \em time argument to UsdAttribute::Get() and
100  /// UsdAttribute::GetBracketingTimeSamples()
101  static constexpr UsdTimeCode EarliestTime() {
102  return UsdTimeCode(std::numeric_limits<double>::lowest());
103  }
104 
105  /// Produce a UsdTimeCode representing the sentinel value for 'default'.
106  ///
107  /// \note In inequality comparisons, Default() is considered less than any
108  /// numeric TimeCode, including EarliestTime(), indicative of the fact that
109  /// in UsdAttribute value resolution, the sample at Default() (if any) is
110  /// always weaker than any numeric timeSample in the same layer. For
111  /// more information, see \ref Usd_ValueResolution
112  static constexpr UsdTimeCode Default() {
113  return UsdTimeCode(std::numeric_limits<double>::quiet_NaN());
114  }
115 
116  /// Produce a safe step value such that for any numeric UsdTimeCode t in
117  /// [-maxValue, maxValue], t +/- (step / maxCompression) != t with a safety
118  /// factor of 2. This is shorthand for
119  /// std::numeric_limits<double>::epsilon() * maxValue * maxCompression *
120  /// 2.0. Such a step value is recommended for simulating jump
121  /// discontinuities in time samples. For example, author value x at time t,
122  /// and value y at time t + SafeStep(). This ensures that as the sample
123  /// times are shifted and scaled, t and t + SafeStep() remain distinct so
124  /// long as they adhere to the \p maxValue and \p maxCompression limits.
125  static constexpr double
126  SafeStep(double maxValue=1e6, double maxCompression=10.0) {
127  return std::numeric_limits<double>::epsilon() *
128  maxValue * maxCompression * 2.0;
129  }
130 
131  /// Return true if this time represents the lowest/earliest possible
132  /// timeCode, false otherwise.
133  bool IsEarliestTime() const {
134  return IsNumeric() && (_value == std::numeric_limits<double>::lowest());
135  }
136 
137  /// Return true if this time represents the 'default' sentinel value, false
138  /// otherwise. This is equivalent to !IsNumeric().
139  bool IsDefault() const {
140  return std::isnan(_value);
141  }
142 
143  /// Return true if this time represents a numeric value, false otherwise.
144  /// This is equivalent to !IsDefault().
145  bool IsNumeric() const {
146  return !IsDefault();
147  }
148 
149  /// Return the numeric value for this time. If this time \a IsDefault(),
150  /// return a quiet NaN value.
151  double GetValue() const {
152  if (ARCH_UNLIKELY(IsDefault()))
153  _IssueGetValueOnDefaultError();
154  return _value;
155  }
156 
157  /// Equality comparison.
158  friend bool operator==(const UsdTimeCode &lhs, const UsdTimeCode& rhs) {
159  return lhs.IsDefault() == rhs.IsDefault() &&
160  (lhs.IsDefault() || (lhs.GetValue() == rhs.GetValue()));
161  }
162 
163  /// Inequality comparison.
164  friend bool operator!=(const UsdTimeCode &lhs, const UsdTimeCode& rhs) {
165  return !(lhs == rhs);
166  }
167 
168  /// Less-than. Default() times are less than all numeric times,
169  /// \em including EarliestTime()
170  friend bool operator<(const UsdTimeCode &lhs, const UsdTimeCode &rhs) {
171  return (lhs.IsDefault() && rhs.IsNumeric()) ||
172  (lhs.IsNumeric() && rhs.IsNumeric() &&
173  lhs.GetValue() < rhs.GetValue());
174  }
175 
176  /// Greater-equal. Default() times are less than all numeric times,
177  /// \em including EarliestTime().
178  friend bool operator>=(const UsdTimeCode &lhs, const UsdTimeCode &rhs) {
179  return !(lhs < rhs);
180  }
181 
182  /// Less-equal. Default() times are less than all numeric times,
183  /// \em including EarliestTime().
184  friend bool operator<=(const UsdTimeCode &lhs, const UsdTimeCode &rhs) {
185  return lhs.IsDefault() ||
186  (rhs.IsNumeric() && lhs.GetValue() <= rhs.GetValue());
187  }
188 
189  /// Greater-than. Default() times are less than all numeric times,
190  /// \em including EarliestTime().
191  friend bool operator>(const UsdTimeCode &lhs, const UsdTimeCode &rhs) {
192  return !(lhs <= rhs);
193  }
194 
195  /// Hash function.
196  friend size_t hash_value(const UsdTimeCode &time) {
197  return TfHash()(time._value);
198  }
199 
200 private:
201  USD_API
202  void _IssueGetValueOnDefaultError() const;
203 
204  double _value;
205 };
206 
207 // Stream I/O operators.
208 USD_API
209 std::ostream& operator<<(std::ostream& os, const UsdTimeCode& time);
210 
211 USD_API
212 std::istream& operator>>(std::istream& is, UsdTimeCode& time);
213 
214 
216 
217 #endif // PXR_USD_USD_TIME_CODE_H
#define USD_TIME_CODE_TOKENS
Definition: timeCode.h:42
friend bool operator==(const UsdTimeCode &lhs, const UsdTimeCode &rhs)
Equality comparison.
Definition: timeCode.h:158
static constexpr UsdTimeCode Default()
Definition: timeCode.h:112
#define USD_API
Definition: api.h:40
double GetValue() const
Definition: timeCode.h:151
static constexpr UsdTimeCode EarliestTime()
Definition: timeCode.h:101
GT_API const UT_StringHolder time
friend bool operator>=(const UsdTimeCode &lhs, const UsdTimeCode &rhs)
Definition: timeCode.h:178
friend bool operator<=(const UsdTimeCode &lhs, const UsdTimeCode &rhs)
Definition: timeCode.h:184
bool IsEarliestTime() const
Definition: timeCode.h:133
USD_API std::istream & operator>>(std::istream &is, UsdTimeCode &time)
constexpr UsdTimeCode(double t=0.0) noexcept
Construct with optional time value. Impilicitly convert from double.
Definition: timeCode.h:87
Definition: hash.h:477
TF_DECLARE_PUBLIC_TOKENS(UsdTimeCodeTokens, USD_API, USD_TIME_CODE_TOKENS)
#define ARCH_UNLIKELY(x)
Definition: hints.h:47
bool IsDefault() const
Definition: timeCode.h:139
constexpr UsdTimeCode(const SdfTimeCode &timeCode) noexcept
Construct and implicitly cast from SdfTimeCode.
Definition: timeCode.h:90
friend size_t hash_value(const UsdTimeCode &time)
Hash function.
Definition: timeCode.h:196
GLdouble t
Definition: glad.h:2397
bool IsNumeric() const
Definition: timeCode.h:145
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
friend bool operator!=(const UsdTimeCode &lhs, const UsdTimeCode &rhs)
Inequality comparison.
Definition: timeCode.h:164
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
SDF_API std::ostream & operator<<(std::ostream &out, const SdfTimeCode &ap)
Stream insertion operator for the string representation of this time code.
friend bool operator<(const UsdTimeCode &lhs, const UsdTimeCode &rhs)
Definition: timeCode.h:170
friend bool operator>(const UsdTimeCode &lhs, const UsdTimeCode &rhs)
Definition: timeCode.h:191
static constexpr double SafeStep(double maxValue=1e6, double maxCompression=10.0)
Definition: timeCode.h:126