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