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

A mathematical description of a curved function from time to value. More...

#include <spline.h>

Public Member Functions

Construction and value semantics

This is a lightweight class that wraps a shared pointer.

It is intended to be used as a value type, and copied freely. Move semantics are not implemented; there would be no benefit.

TS_API TsSpline ()
 Default constructor creates a spline without a value type.
 
TS_API TsSpline (TfType valueType)
 Creates a spline with a specified value type.
 
TS_API TsSpline (const TsSpline &other)
 
TS_API TsSplineoperator= (const TsSpline &other)
 
TS_API bool operator== (const TsSpline &other) const
 
TS_API bool operator!= (const TsSpline &other) const
 
Curve types
TS_API void SetCurveType (TsCurveType curveType)
 
TS_API TsCurveType GetCurveType () const
 
Extrapolation
TS_API void SetPreExtrapolation (const TsExtrapolation &extrap)
 
TS_API TsExtrapolation GetPreExtrapolation () const
 
TS_API void SetPostExtrapolation (const TsExtrapolation &extrap)
 
TS_API TsExtrapolation GetPostExtrapolation () const
 
Inner loops

Loop params are only valid when all of the following are true:

  • protoEnd > protoStart.
  • At least one of numPreLoops or numPostLoops is nonzero and positive.
  • There is a knot at protoStart.

Any loop params may be set, and will be stored. Whenever the above conditions are not met, the stored params will be ignored.

To determine if loop params are currently valid, call HasInnerLoops.

To disable inner loops, call SetInnerLoopParams(TsLoopParams()).

TS_API void SetInnerLoopParams (const TsLoopParams &params)
 
TS_API TsLoopParams GetInnerLoopParams () const
 
Knots
TS_API void SetKnots (const TsKnotMap &knots)
 
TS_API bool CanSetKnot (const TsKnot &knot, std::string *reasonOut=nullptr) const
 
TS_API bool SetKnot (const TsKnot &knot, GfInterval *affectedIntervalOut=nullptr)
 Incompletely implemented; affectedIntervalOut is not yet populated.
 
TS_API TsKnotMap GetKnots () const
 Returns the spline's knots.
 
TS_API bool GetKnot (TsTime time, TsKnot *knotOut) const
 Retrieves a copy of the knot at the specified time, if one exists.
 
Removing knots
TS_API void ClearKnots ()
 
TS_API void RemoveKnot (TsTime time, GfInterval *affectedIntervalOut=nullptr)
 Incompletely implemented; affectedIntervalOut is not yet populated.
 
TS_API bool ClearRedundantKnots (VtValue defaultValue=VtValue(), const GfInterval &interval=GfInterval::GetFullInterval())
 Not yet implemented.
 
Loop baking
TS_API bool BakeLoops (const GfInterval &interval)
 Not yet implemented.
 
TS_API const TsKnotMapGetKnotsWithInnerLoopsBaked () const
 Not yet implemented.
 
TS_API const TsKnotMapGetKnotsWithLoopsBaked (const GfInterval &interval) const
 Not yet implemented.
 
Splitting
TS_API bool Split (TsTime time, GfInterval *affectedIntervalOut=nullptr)
 Not yet implemented.
 
Evaluation

In all of these templated methods, the T parameter may be the value type of the spline (double/float/GfHalf), or VtValue.

template<typename T >
bool Eval (TsTime time, T *valueOut) const
 
template<typename T >
bool EvalPreValue (TsTime time, T *valueOut) const
 
template<typename T >
bool EvalDerivative (TsTime time, T *valueOut) const
 
template<typename T >
bool EvalPreDerivative (TsTime time, T *valueOut) const
 
template<typename T >
bool EvalHeld (TsTime time, T *valueOut) const
 
template<typename T >
bool EvalPreValueHeld (TsTime time, T *valueOut) const
 
TS_API bool DoSidesDiffer (TsTime time) const
 
Whole-spline queries
TS_API bool IsEmpty () const
 
TS_API bool HasValueBlocks () const
 
TS_API bool IsVarying () const
 Not yet implemented.
 
TS_API bool HasLoops () const
 Convenience for HasInnerLoops() || HasExtrapolatingLoops().
 
TS_API bool HasInnerLoops () const
 
TS_API bool HasExtrapolatingLoops () const
 
TS_API bool IsLinear () const
 Not yet implemented.
 
TS_API bool IsC0Continuous () const
 Not yet implemented.
 
TS_API bool IsG1Continuous () const
 Not yet implemented.
 
TS_API bool IsC1Continuous () const
 Not yet implemented.
 
TS_API bool GetValueRange (const GfInterval &timeSpan, std::pair< VtValue, VtValue > *rangeOut) const
 Not yet implemented.
 
template<typename T >
bool GetValueRange (const GfInterval &timeSpan, std::pair< T, T > *rangeOut) const
 Not yet implemented.
 
Within-spline queries
TS_API bool HasValueBlockAtTime (TsTime time) const
 
TS_API bool IsSegmentFlat (TsTime startTime) const
 Not yet implemented.
 
TS_API bool IsSegmentMonotonic (TsTime startTime) const
 Not yet implemented.
 
TS_API bool IsKnotRedundant (TsTime time, VtValue defaultValue=VtValue()) const
 Not yet implemented.
 

Friends

class TsRegressionPreventer
 
struct Ts_BinaryDataAccess
 
struct Ts_SplineOffsetAccess
 
template<typename HashState >
void TfHashAppend (HashState &h, const TsSpline &spline)
 
Ts_SplineData * Ts_GetSplineData (TsSpline &spline)
 
const Ts_SplineData * Ts_GetSplineData (const TsSpline &spline)
 

Value types

TS_API TfType GetValueType () const
 
template<typename T >
bool IsHolding () const
 
TS_API void SetTimeValued (bool timeValued)
 
TS_API bool IsTimeValued () const
 
static TS_API bool IsSupportedValueType (TfType valueType)
 

Anti-regression

See Regressive Splines in USD for a general introduction to regression and anti-regression.

See also
TsAntiRegressionAuthoringSelector
TsRegressionPreventer
TS_API bool HasRegressiveTangents () const
 Returns whether this spline has any tangents long enough to cause regression; or, if the current authoring mode is Contain, whether this spline has any tangents that exceed their segment interval.
 
TS_API bool AdjustRegressiveTangents ()
 Shorten any regressive tangents; or, if the current authoring mode is Contain, any tangents that exceed their segment interval.
 
static TS_API TsAntiRegressionMode GetAntiRegressionAuthoringMode ()
 Returns the current effective anti-regression authoring mode.
 

Detailed Description

A mathematical description of a curved function from time to value.

This class is STILL IN DEVELOPMENT.

Splines are are supported only for floating-point scalar value types. This class is non-templated, but can hold data for varying value types (double, float, and half). All knots in a spline must have the same value type.

Splines are defined by knots. The curve passes through each knot, and in between, the shape of the curve is controlled by tangents specified at the knots.

Splines typically have Bezier or Hermite curve segments with controllable tangents; linear and held (flat) interpolation are also supported. Outside of the time span of knots, the extrapolation of the curve can be specified.

The main service provided by splines is evaluation: determining the curve's value at a given time.

Splines are copy-on-write. Copying a spline object is cheap; the copy will point to the same data on the heap. Copying, and then modifying one of the copies, will incur the cost of duplicating the data, including all the knots.

Definition at line 58 of file spline.h.

Constructor & Destructor Documentation

◆ TsSpline() [1/2]

TS_API TsSpline ( )

Default constructor creates a spline without a value type.

The value type becomes established when the first knot is added.

◆ TsSpline() [2/2]

TS_API TsSpline ( TfType  valueType)

Creates a spline with a specified value type.

Member Function Documentation

◆ AdjustRegressiveTangents()

TS_API bool AdjustRegressiveTangents ( )

Shorten any regressive tangents; or, if the current authoring mode is Contain, any tangents that exceed their segment interval.

Return whether anything was changed.

◆ BakeLoops()

TS_API bool BakeLoops ( const GfInterval interval)

Not yet implemented.

◆ ClearRedundantKnots()

TS_API bool ClearRedundantKnots ( VtValue  defaultValue = VtValue(),
const GfInterval interval = GfInterval::GetFullInterval() 
)

Not yet implemented.

◆ Eval()

bool Eval ( TsTime  time,
T *  valueOut 
) const

Definition at line 505 of file spline.h.

◆ EvalDerivative()

bool EvalDerivative ( TsTime  time,
T *  valueOut 
) const

Definition at line 517 of file spline.h.

◆ EvalHeld()

bool EvalHeld ( TsTime  time,
T *  valueOut 
) const

Definition at line 529 of file spline.h.

◆ EvalPreDerivative()

bool EvalPreDerivative ( TsTime  time,
T *  valueOut 
) const

Definition at line 523 of file spline.h.

◆ EvalPreValue()

bool EvalPreValue ( TsTime  time,
T *  valueOut 
) const

Definition at line 511 of file spline.h.

◆ EvalPreValueHeld()

bool EvalPreValueHeld ( TsTime  time,
T *  valueOut 
) const

Definition at line 535 of file spline.h.

◆ GetAntiRegressionAuthoringMode()

static TS_API TsAntiRegressionMode GetAntiRegressionAuthoringMode ( )
static

Returns the current effective anti-regression authoring mode.

This may come from the overall default of Keep Ratio; the build-configured default defined by PXR_TS_DEFAULT_ANTI_REGRESSION_AUTHORING_MODE; or a TsAntiRegressionAuthoringSelector.

◆ GetKnot()

TS_API bool GetKnot ( TsTime  time,
TsKnot knotOut 
) const

Retrieves a copy of the knot at the specified time, if one exists.

This must be an original knot, not a knot that is echoed due to looping. Returns true on success, false if there is no such knot.

◆ GetKnots()

TS_API TsKnotMap GetKnots ( ) const

Returns the spline's knots.

These are the original knots; if inner or extrapolating loops are present, this set of knots does not reflect that.

◆ GetKnotsWithInnerLoopsBaked()

TS_API const TsKnotMap & GetKnotsWithInnerLoopsBaked ( ) const

Not yet implemented.

◆ GetKnotsWithLoopsBaked()

TS_API const TsKnotMap & GetKnotsWithLoopsBaked ( const GfInterval interval) const

Not yet implemented.

◆ GetValueRange() [1/2]

bool GetValueRange ( const GfInterval timeSpan,
std::pair< T, T > *  rangeOut 
) const

Not yet implemented.

◆ GetValueRange() [2/2]

TS_API bool GetValueRange ( const GfInterval timeSpan,
std::pair< VtValue, VtValue > *  rangeOut 
) const

Not yet implemented.

◆ HasLoops()

TS_API bool HasLoops ( ) const

Convenience for HasInnerLoops() || HasExtrapolatingLoops().

◆ HasRegressiveTangents()

TS_API bool HasRegressiveTangents ( ) const

Returns whether this spline has any tangents long enough to cause regression; or, if the current authoring mode is Contain, whether this spline has any tangents that exceed their segment interval.

◆ IsC0Continuous()

TS_API bool IsC0Continuous ( ) const

Not yet implemented.

◆ IsC1Continuous()

TS_API bool IsC1Continuous ( ) const

Not yet implemented.

◆ IsG1Continuous()

TS_API bool IsG1Continuous ( ) const

Not yet implemented.

◆ IsHolding()

bool IsHolding

Definition at line 475 of file spline.h.

◆ IsKnotRedundant()

TS_API bool IsKnotRedundant ( TsTime  time,
VtValue  defaultValue = VtValue() 
) const

Not yet implemented.

◆ IsLinear()

TS_API bool IsLinear ( ) const

Not yet implemented.

◆ IsSegmentFlat()

TS_API bool IsSegmentFlat ( TsTime  startTime) const

Not yet implemented.

◆ IsSegmentMonotonic()

TS_API bool IsSegmentMonotonic ( TsTime  startTime) const

Not yet implemented.

◆ IsVarying()

TS_API bool IsVarying ( ) const

Not yet implemented.

◆ RemoveKnot()

TS_API void RemoveKnot ( TsTime  time,
GfInterval affectedIntervalOut = nullptr 
)

Incompletely implemented; affectedIntervalOut is not yet populated.

◆ SetKnot()

TS_API bool SetKnot ( const TsKnot knot,
GfInterval affectedIntervalOut = nullptr 
)

Incompletely implemented; affectedIntervalOut is not yet populated.

◆ Split()

TS_API bool Split ( TsTime  time,
GfInterval affectedIntervalOut = nullptr 
)

Not yet implemented.

Adds a knot at the specified time. The new knot is arranged so that the shape of the curve is as unchanged as possible.

Friends And Related Function Documentation

◆ TfHashAppend

void TfHashAppend ( HashState &  h,
const TsSpline spline 
)
friend

Definition at line 406 of file spline.h.

◆ Ts_BinaryDataAccess

friend struct Ts_BinaryDataAccess
friend

Definition at line 421 of file spline.h.

◆ Ts_SplineOffsetAccess

friend struct Ts_SplineOffsetAccess
friend

Definition at line 422 of file spline.h.

◆ TsRegressionPreventer

friend class TsRegressionPreventer
friend

Definition at line 414 of file spline.h.


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