All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
timeCodeRange.h
Go to the documentation of this file.
1//
2// Copyright 2019 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_UTILS_TIME_CODE_RANGE_H
8#define PXR_USD_USD_UTILS_TIME_CODE_RANGE_H
9
11
12#include "pxr/pxr.h"
13#include "pxr/usd/usdUtils/api.h"
14
15#include "pxr/base/gf/math.h"
18#include "pxr/usd/usd/timeCode.h"
19
20#include <iosfwd>
21#include <iterator>
22#include <string>
23
24
25PXR_NAMESPACE_OPEN_SCOPE
26
27
28#define USDUTILS_TIME_CODE_RANGE_TOKENS \
29 ((EmptyTimeCodeRange, "NONE")) \
30 ((RangeSeparator, ":")) \
31 ((StrideSeparator, "x"))
32
34 UsdUtilsTimeCodeRangeTokens,
35 USDUTILS_API,
36 USDUTILS_TIME_CODE_RANGE_TOKENS);
37
38
57{
58public:
59
64 {
65 public:
66 using iterator_category = std::forward_iterator_tag;
67 using value_type = UsdTimeCode;
68 using reference = const UsdTimeCode&;
69 using pointer = const UsdTimeCode*;
70 using difference_type = std::ptrdiff_t;
71
74 return _currTimeCode;
75 }
76
79 return &_currTimeCode;
80 }
81
87 if (_timeCodeRange) {
88 ++_currStep;
89 _currTimeCode =
91 _timeCodeRange->_startTimeCode.GetValue() +
92 _timeCodeRange->_stride * _currStep);
93 }
94 _InvalidateIfExhausted();
95 return *this;
96 }
97
103 const_iterator preAdvanceIter = *this;
104 ++(*this);
105 return preAdvanceIter;
106 }
107
109 bool operator ==(const const_iterator& other) const {
110 return _timeCodeRange == other._timeCodeRange &&
111 _currStep == other._currStep;
112 }
113
115 bool operator !=(const const_iterator& other) const {
116 return !(*this == other);
117 }
118
119 private:
120 friend class UsdUtilsTimeCodeRange;
121
122 const_iterator(const UsdUtilsTimeCodeRange* timeCodeRange) :
123 _timeCodeRange(timeCodeRange),
124 _currStep(0u),
125 _maxSteps(0u),
126 _currTimeCode()
127 {
128 if (_timeCodeRange) {
129 const double startVal = _timeCodeRange->_startTimeCode.GetValue();
130 const double endVal = _timeCodeRange->_endTimeCode.GetValue();
131 const double stride = _timeCodeRange->_stride;
132
133 _maxSteps = static_cast<size_t>(
134 GfFloor((endVal - startVal + stride) / stride));
135 _currTimeCode = _timeCodeRange->_startTimeCode;
136 }
137
138 _InvalidateIfExhausted();
139 }
140
141 void _InvalidateIfExhausted() {
142 bool finished = false;
143 if (!_timeCodeRange) {
144 finished = true;
145 } else if (_currStep >= _maxSteps) {
146 finished = true;
147 }
148
149 if (finished) {
150 _timeCodeRange = nullptr;
151 _currStep = 0u;
152 _maxSteps = 0u;
153 _currTimeCode = UsdTimeCode();
154 }
155 }
156
157 const UsdUtilsTimeCodeRange* _timeCodeRange;
158 size_t _currStep;
159 size_t _maxSteps;
160 UsdTimeCode _currTimeCode;
161 };
162
163 using iterator = const_iterator;
164
194 USDUTILS_API
196 const std::string& frameSpec);
197
203 {
204 _Invalidate();
205 }
206
211 UsdUtilsTimeCodeRange(timeCode, timeCode)
212 {
213 }
214
221 const UsdTimeCode startTimeCode,
222 const UsdTimeCode endTimeCode) :
224 startTimeCode,
225 endTimeCode,
226 (endTimeCode >= startTimeCode) ? 1.0 : -1.0)
227 {
228 }
229
241 const UsdTimeCode startTimeCode,
242 const UsdTimeCode endTimeCode,
243 const double stride) :
244 _startTimeCode(startTimeCode),
245 _endTimeCode(endTimeCode),
246 _stride(stride)
247 {
248 if (_startTimeCode.IsEarliestTime()) {
250 "startTimeCode cannot be UsdTimeCode::EarliestTime()");
251 _Invalidate();
252 return;
253 }
254 if (_startTimeCode.IsDefault()) {
256 "startTimeCode cannot be UsdTimeCode::Default()");
257 _Invalidate();
258 return;
259 }
260 if (_endTimeCode.IsEarliestTime()) {
262 "endTimeCode cannot be UsdTimeCode::EarliestTime()");
263 _Invalidate();
264 return;
265 }
266 if (_endTimeCode.IsDefault()) {
268 "endTimeCode cannot be UsdTimeCode::Default()");
269 _Invalidate();
270 return;
271 }
272
273 if (_stride > 0.0) {
274 if (_endTimeCode < _startTimeCode) {
276 "endTimeCode cannot be less than startTimeCode with "
277 "positive stride");
278 _Invalidate();
279 return;
280 }
281 } else if (_stride < 0.0) {
282 if (_endTimeCode > _startTimeCode) {
284 "endTimeCode cannot be greater than startTimeCode with "
285 "negative stride");
286 _Invalidate();
287 return;
288 }
289 } else {
290 TF_CODING_ERROR("stride cannot be zero");
291 _Invalidate();
292 return;
293 }
294 }
295
298 return _startTimeCode;
299 }
300
303 return _endTimeCode;
304 }
305
307 double GetStride() const {
308 return _stride;
309 }
310
312 iterator begin() const {
313 return iterator(this);
314 }
315
318 return const_iterator(this);
319 }
320
322 iterator end() const {
323 return iterator(nullptr);
324 }
325
328 return const_iterator(nullptr);
329 }
330
332 bool empty() const {
333 return begin() == end();
334 }
335
338 bool IsValid() const {
339 return !empty();
340 }
341
344 explicit operator bool() const {
345 return IsValid();
346 }
347
349 bool operator ==(const UsdUtilsTimeCodeRange& other) const {
350 return _startTimeCode == other._startTimeCode &&
351 _endTimeCode == other._endTimeCode &&
352 _stride == other._stride;
353 }
354
356 bool operator !=(const UsdUtilsTimeCodeRange& other) const {
357 return !(*this == other);
358 }
359
360private:
361
363 void _Invalidate() {
364 _startTimeCode = UsdTimeCode(0.0);
365 _endTimeCode = UsdTimeCode(-1.0);
366 _stride = 1.0;
367 }
368
369 UsdTimeCode _startTimeCode;
370 UsdTimeCode _endTimeCode;
371 double _stride;
372};
373
374// Stream I/O operators.
375
377USDUTILS_API
378std::ostream& operator<<(
379 std::ostream& os,
380 const UsdUtilsTimeCodeRange& timeCodeRange);
381
383USDUTILS_API
384std::istream& operator>>(
385 std::istream& is,
386 UsdUtilsTimeCodeRange& timeCodeRange);
387
388
389PXR_NAMESPACE_CLOSE_SCOPE
390
391
392#endif
Low-level utilities for informing users of various internal and external diagnostic conditions.
Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdT...
Definition: timeCode.h:67
double GetValue() const
Return the numeric value for this time.
Definition: timeCode.h:134
bool IsDefault() const
Return true if this time represents the 'default' sentinel value, false otherwise.
Definition: timeCode.h:122
bool IsEarliestTime() const
Return true if this time represents the lowest/earliest possible timeCode, false otherwise.
Definition: timeCode.h:116
A forward iterator into a UsdUtilsTimeCodeRange.
Definition: timeCodeRange.h:64
bool operator!=(const const_iterator &other) const
Return true if this iterator is not equivalent to other.
pointer operator->()
Returns a pointer to the UsdTimeCode referenced by this iterator.
Definition: timeCodeRange.h:78
reference operator*()
Returns the UsdTimeCode referenced by this iterator.
Definition: timeCodeRange.h:73
const_iterator operator++(int)
Post-increment operator.
bool operator==(const const_iterator &other) const
Return true if this iterator is equivalent to other.
const_iterator & operator++()
Pre-increment operator.
Definition: timeCodeRange.h:86
Represents a range of UsdTimeCode values as start and end time codes and a stride value.
Definition: timeCodeRange.h:57
iterator begin() const
Return an iterator to the start of this range.
UsdUtilsTimeCodeRange(const UsdTimeCode timeCode)
Construct a range containing only the given timeCode.
UsdUtilsTimeCodeRange()
Construct an invalid empty range.
const_iterator cbegin() const
Return a const_iterator to the start of this range.
UsdTimeCode GetStartTimeCode() const
Return the start time code of this range.
bool operator==(const UsdUtilsTimeCodeRange &other) const
Return true if this range is equivalent to other.
UsdUtilsTimeCodeRange(const UsdTimeCode startTimeCode, const UsdTimeCode endTimeCode)
Construct a range containing the time codes from startTimeCode to endTimeCode.
double GetStride() const
Return the stride value of this range.
bool empty() const
Return true if this range contains no time codes, or false otherwise.
iterator end() const
Return the past-the-end iterator for this range.
static USDUTILS_API UsdUtilsTimeCodeRange CreateFromFrameSpec(const std::string &frameSpec)
Create a time code range from frameSpec.
bool operator!=(const UsdUtilsTimeCodeRange &other) const
Return true if this range is not equivalent to other.
const_iterator cend() const
Return the past-the-end const_iterator for this range.
UsdUtilsTimeCodeRange(const UsdTimeCode startTimeCode, const UsdTimeCode endTimeCode, const double stride)
Construct a range containing the time codes from startTimeCode to endTimeCode using the stride value ...
bool IsValid() const
Return true if this range contains one or more time codes, or false otherwise.
UsdTimeCode GetEndTimeCode() const
Return the end time code of this range.
Assorted mathematical utility functions.
double GfFloor(double f)
Return floor(f).
Definition: math.h:208
GF_API std::ostream & operator<<(std::ostream &, const GfBBox3d &)
Output a GfBBox3d using the format [(range) matrix zeroArea].
#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
USDUTILS_API std::istream & operator>>(std::istream &is, UsdUtilsTimeCodeRange &timeCodeRange)
Stream extraction operator.