All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
UsdTimeCode Class Reference

Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdTimeCode::Default(). More...

#include <timeCode.h>

Public Member Functions

constexpr UsdTimeCode (double t=0.0) noexcept
 Construct with optional time value. Impilicitly convert from double.
 
constexpr UsdTimeCode (const SdfTimeCode &timeCode) noexcept
 Construct and implicitly cast from SdfTimeCode.
 
bool IsEarliestTime () const
 Return true if this time represents the lowest/earliest possible timeCode, false otherwise.
 
bool IsDefault () const
 Return true if this time represents the 'default' sentinel value, false otherwise.
 
bool IsNumeric () const
 Return true if this time represents a numeric value, false otherwise.
 
double GetValue () const
 Return the numeric value for this time.
 

Static Public Member Functions

static constexpr UsdTimeCode EarliestTime ()
 Produce a UsdTimeCode representing the lowest/earliest possible timeCode.
 
static constexpr UsdTimeCode Default ()
 Produce a UsdTimeCode representing the sentinel value for 'default'.
 
static constexpr double SafeStep (double maxValue=1e6, double maxCompression=10.0)
 Produce a safe step value such that for any numeric UsdTimeCode t in [-maxValue, maxValue], t +/- (step / maxCompression) != t with a safety factor of 2.
 

Friends

bool operator== (const UsdTimeCode &lhs, const UsdTimeCode &rhs)
 Equality comparison.
 
bool operator!= (const UsdTimeCode &lhs, const UsdTimeCode &rhs)
 Inequality comparison.
 
bool operator< (const UsdTimeCode &lhs, const UsdTimeCode &rhs)
 Less-than.
 
bool operator>= (const UsdTimeCode &lhs, const UsdTimeCode &rhs)
 Greater-equal.
 
bool operator<= (const UsdTimeCode &lhs, const UsdTimeCode &rhs)
 Less-equal.
 
bool operator> (const UsdTimeCode &lhs, const UsdTimeCode &rhs)
 Greater-than.
 
size_t hash_value (const UsdTimeCode &time)
 Hash function.
 

Detailed Description

Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdTimeCode::Default().

A UsdTimeCode does not represent an SMPTE timecode, although we may, in future, support conversion functions between the two. Instead, UsdTimeCode is an abstraction that acknowledges that in the principal domains of use for USD, there are many different ways of encoding time, and USD must be able to capture and translate between all of them for interchange, retaining as much intent of the authoring application as possible.

A UsdTimeCode is therefore a unitless, generic time measurement that serves as the ordinate for time-sampled data in USD files. A client of USD relies on the UsdStage (which in turn consults metadata authored in its root layer) to define the mapping of TimeCodes to units like seconds and frames.

See also
UsdStage::GetStartTimeCode()
UsdStage::GetEndTimeCode()
UsdStage::GetTimeCodesPerSecond()
UsdStage::GetFramesPerSecond()

As described in TimeSamples, Defaults, and Value Resolution , USD optionally provides an unvarying, 'default' value for every attribute. UsdTimeCode embodies a time value that can either be a floating-point sample time, or the default.

All UsdAttribute and derived API that requires a time parameter defaults to UsdTimeCode::Default() if the parameter is left unspecified, and auto-constructs from a floating-point argument.

UsdTimeCode::EarliestTime() is provided to aid clients who wish to retrieve the first authored timesample for any attribute.

Definition at line 67 of file timeCode.h.

Constructor & Destructor Documentation

◆ UsdTimeCode() [1/2]

constexpr UsdTimeCode ( double  t = 0.0)
inlineconstexprnoexcept

Construct with optional time value. Impilicitly convert from double.

Definition at line 70 of file timeCode.h.

◆ UsdTimeCode() [2/2]

constexpr UsdTimeCode ( const SdfTimeCode timeCode)
inlineconstexprnoexcept

Construct and implicitly cast from SdfTimeCode.

Definition at line 73 of file timeCode.h.

Member Function Documentation

◆ Default()

static constexpr UsdTimeCode Default ( )
inlinestaticconstexpr

Produce a UsdTimeCode representing the sentinel value for 'default'.

Note
In inequality comparisons, Default() is considered less than any numeric TimeCode, including EarliestTime(), indicative of the fact that in UsdAttribute value resolution, the sample at Default() (if any) is always weaker than any numeric timeSample in the same layer. For more information, see TimeSamples, Defaults, and Value Resolution

Definition at line 95 of file timeCode.h.

◆ EarliestTime()

static constexpr UsdTimeCode EarliestTime ( )
inlinestaticconstexpr

Produce a UsdTimeCode representing the lowest/earliest possible timeCode.

Thus, for any given timeSample s, its time ordinate t will obey: t >= UsdTimeCode::EarliestTime()

This is useful for clients that wish to retrieve the first authored timeSample for an attribute, as they can use UsdTimeCode::EarliestTime() as the time argument to UsdAttribute::Get() and UsdAttribute::GetBracketingTimeSamples()

Definition at line 84 of file timeCode.h.

◆ GetValue()

double GetValue ( ) const
inline

Return the numeric value for this time.

If this time IsDefault(), return a quiet NaN value.

Definition at line 134 of file timeCode.h.

◆ IsDefault()

bool IsDefault ( ) const
inline

Return true if this time represents the 'default' sentinel value, false otherwise.

This is equivalent to !IsNumeric().

Definition at line 122 of file timeCode.h.

◆ IsEarliestTime()

bool IsEarliestTime ( ) const
inline

Return true if this time represents the lowest/earliest possible timeCode, false otherwise.

Definition at line 116 of file timeCode.h.

◆ IsNumeric()

bool IsNumeric ( ) const
inline

Return true if this time represents a numeric value, false otherwise.

This is equivalent to !IsDefault().

Definition at line 128 of file timeCode.h.

◆ SafeStep()

static constexpr double SafeStep ( double  maxValue = 1e6,
double  maxCompression = 10.0 
)
inlinestaticconstexpr

Produce a safe step value such that for any numeric UsdTimeCode t in [-maxValue, maxValue], t +/- (step / maxCompression) != t with a safety factor of 2.

This is shorthand for std::numeric_limits<double>::epsilon() * maxValue * maxCompression * 2.0. Such a step value is recommended for simulating jump discontinuities in time samples. For example, author value x at time t, and value y at time t + SafeStep(). This ensures that as the sample times are shifted and scaled, t and t + SafeStep() remain distinct so long as they adhere to the maxValue and maxCompression limits.

Definition at line 109 of file timeCode.h.

Friends And Related Function Documentation

◆ hash_value

size_t hash_value ( const UsdTimeCode time)
friend

Hash function.

Definition at line 179 of file timeCode.h.

◆ operator!=

bool operator!= ( const UsdTimeCode lhs,
const UsdTimeCode rhs 
)
friend

Inequality comparison.

Definition at line 147 of file timeCode.h.

◆ operator<

bool operator< ( const UsdTimeCode lhs,
const UsdTimeCode rhs 
)
friend

Less-than.

Default() times are less than all numeric times, including EarliestTime()

Definition at line 153 of file timeCode.h.

◆ operator<=

bool operator<= ( const UsdTimeCode lhs,
const UsdTimeCode rhs 
)
friend

Less-equal.

Default() times are less than all numeric times, including EarliestTime().

Definition at line 167 of file timeCode.h.

◆ operator==

bool operator== ( const UsdTimeCode lhs,
const UsdTimeCode rhs 
)
friend

Equality comparison.

Definition at line 141 of file timeCode.h.

◆ operator>

bool operator> ( const UsdTimeCode lhs,
const UsdTimeCode rhs 
)
friend

Greater-than.

Default() times are less than all numeric times, including EarliestTime().

Definition at line 174 of file timeCode.h.

◆ operator>=

bool operator>= ( const UsdTimeCode lhs,
const UsdTimeCode rhs 
)
friend

Greater-equal.

Default() times are less than all numeric times, including EarliestTime().

Definition at line 161 of file timeCode.h.


The documentation for this class was generated from the following file: