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

#include <spline.h>

Public Member Functions
template<>
TS_API bool	_Eval (const TsTime time, VtValue *const valueOut, const Ts_EvalAspect aspect, const Ts_EvalLocation location) const

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 TsSpline &	operator= (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 TsKnotMap	GetKnots (const GfInterval &timeInterval) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Get the spline's knots that affect the specified time interval.

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	BakeInnerLoops ()
	Bake inner loops in the spline.

TS_API TsKnotMap	GetKnotsWithInnerLoopsBaked () const
	Return all the knots on the spline, including knots generated by inner looping.

TS_API TsKnotMap	GetKnotsWithLoopsBaked (const GfInterval &interval) const
	Return baked knots that will replicate this spline over the given time interval without any looping.

Breakdowns
A Breakdown in animation is a pose between the key poses. Breakdown applied to a `TsSpline` will insert a TsKnot between existing knots with as little disruption as possible to the overall shape of the spline.
TS_API bool	Breakdown (TsTime time, GfInterval *affectedIntervalOut=nullptr)
	Add a knot at the specified time.

TS_API bool	CanBreakdown (TsTime time, std::string *reason=nullptr)
	Test if a knot could be inserted by `Breakdown` at `time`.

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

template<typename Vertex >
bool	Sample (const GfInterval &timeInterval, double timeScale, double valueScale, double tolerance, TsSplineSamples< Vertex > *splineSamples) const
	Evaluates the value of the TsSpline over the given time interval, typically for drawing.

template<typename Vertex >
bool	Sample (const GfInterval &timeInterval, double timeScale, double valueScale, double tolerance, TsSplineSamplesWithSources< Vertex > *splineSamples) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. When passed a `TsSplineSamplesWithSources<Vertex>` class, the returned information contains a `TsSplineSampleSource` value for each polyline.

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.

◆ BakeInnerLoops()

TS_API bool BakeInnerLoops ( )

Bake inner loops in the spline.

Modify the spline by baking out the knots generated by inner looping to explicit knots and resetting the looping parameters to default.

◆ Breakdown()

TS_API bool Breakdown	(	TsTime	time,
		GfInterval *	affectedIntervalOut = `nullptr`
	)

Add a knot at the specified time.

The new knot is defined so that the shape of the curve is changed as little as possible. If necessary, neighboring knots may also be modified.

There are some situations where a new knot cannot be inserted. For example, if there is already a knot at the requested time, or if the requested insertion time is in a region of the spline that is looped from either extrapolation or inner looping. Use CanBreakdown to see if a breakdown would succeed.

Returns: true if a knot was successfully inserted or false if not.

◆ CanBreakdown()

TS_API bool CanBreakdown	(	TsTime	time,
		std::string *	reason = `nullptr`
	)

Test if a knot could be inserted by Breakdown at time.

Returns: true if a knot could be successfully inserted by Breakdown or false if not. If false is returned and reason is not nullptr then a description of the failure will be stored in reason. This is the same error or warning message that would have been emitted by Breakdown if it had failed to insert a knot.

◆ 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 644 of file spline.h.

◆ EvalDerivative()

bool EvalDerivative	(	TsTime	time,
		T *	valueOut
	)		const

Definition at line 656 of file spline.h.

◆ EvalHeld()

bool EvalHeld	(	TsTime	time,
		T *	valueOut
	)		const

Definition at line 668 of file spline.h.

◆ EvalPreDerivative()

bool EvalPreDerivative	(	TsTime	time,
		T *	valueOut
	)		const

Definition at line 662 of file spline.h.

◆ EvalPreValue()

bool EvalPreValue	(	TsTime	time,
		T *	valueOut
	)		const

Definition at line 650 of file spline.h.

◆ EvalPreValueHeld()

bool EvalPreValueHeld	(	TsTime	time,
		T *	valueOut
	)		const

Definition at line 674 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() [1/2]

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.

◆ GetKnots() [2/2]

TS_API TsKnotMap GetKnots ( const GfInterval & timeInterval ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Get the spline's knots that affect the specified time interval.

Return a TsKnotMap containing the knots that affect the time interval. This may include knots outside the time interval if they affect the curve inside the time interval. For example, if there are knots at times 10, 20, and 30. Calling GetKnots with a timeInteval of [15 .. 25] may return all 3 knots since the knots at 10 and 30 may affect the shape of the spline at times that are inside the timeInterval.

◆ GetKnotsWithInnerLoopsBaked()

TS_API TsKnotMap GetKnotsWithInnerLoopsBaked ( ) const

Return all the knots on the spline, including knots generated by inner looping.

These knots can be used to create a new spline that does not use looping but has the same shape as this spline. Note that extrapolated knots are not included in the result. If you want to include extrapolated knots use GetKnotsWithLoopsBaked and provide a time interval over which knots should be expanded.

◆ GetKnotsWithLoopsBaked()

TS_API TsKnotMap GetKnotsWithLoopsBaked ( const GfInterval & interval ) const

Return baked knots that will replicate this spline over the given time interval without any looping.

Return a TsKnotMap containing baked knots that will replicate the shape of the spline over the time interval without using any looping. Both inner and extrapolation loops are included in the returned knots.

If extrapolation loops are in use, the specified interval argument, must specify a finite time interval since extrapolation looping extends to infinity and will generate a theoretically infinite number of knots. Attempts to bake an infinite number of knots will emit a coding error and return an empty TsKnotMap.

Note: Knots baked from extrapolation loops may include knots that are generated from multiple input knots. Knots at loop boundaries get their "pre" values from the end of the loop and their "post" values from the beginning.

◆ 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 603 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.

◆ Sample() [1/2]

bool Sample	(	const GfInterval &	timeInterval,
		double	timeScale,
		double	valueScale,
		double	tolerance,
		TsSplineSamples< Vertex > *	splineSamples
	)		const

inline

Evaluates the value of the TsSpline over the given time interval, typically for drawing.

Sample creates a piecewise linear approximation of the spline curve. When the returned samples are scaled by timeScale and valueScale and linearly interpolated, the reconstructed curve will nowhere have an error greater than tolerance.

The values of timeScale and valueScale are typically chosen to scale the spline's units to pixels and then tolerance represents the allowed deviation in pixel space from a theoretical exact answer.

timeInterval must not be empty and timeScale, valueScale, and tolerance must all be greater than 0.0. If any of these conditions are not met, Sample returns false and *splineSamples is unchanged. Otherwise, true is returned and splineSamples is populated.

Definition at line 399 of file spline.h.

◆ Sample() [2/2]

bool Sample	(	const GfInterval &	timeInterval,
		double	timeScale,
		double	valueScale,
		double	tolerance,
		TsSplineSamplesWithSources< Vertex > *	splineSamples
	)		const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. When passed a TsSplineSamplesWithSources<Vertex> class, the returned information contains a TsSplineSampleSource value for each polyline.

The TsSplineSampleSource indicates the source region (extrapolation, looping, normal interpolation, etc.) of the spline generated that polyline.

Definition at line 418 of file spline.h.

◆ SetKnot()

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

Incompletely implemented; affectedIntervalOut is not yet populated.

Friends And Related Function Documentation

◆ TfHashAppend

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

friend

Definition at line 512 of file spline.h.

◆ Ts_BinaryDataAccess

friend struct Ts_BinaryDataAccess

friend

Definition at line 537 of file spline.h.

◆ Ts_SplineOffsetAccess

friend struct Ts_SplineOffsetAccess

friend

Definition at line 538 of file spline.h.

◆ TsRegressionPreventer

friend class TsRegressionPreventer

friend

Definition at line 520 of file spline.h.

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

pxr/base/ts/spline.h

Public Member Functions

Friends

Value types

Anti-regression

Detailed Description

Constructor & Destructor Documentation

◆ TsSpline() [1/2]

◆ TsSpline() [2/2]

Member Function Documentation

◆ AdjustRegressiveTangents()

◆ BakeInnerLoops()

◆ Breakdown()

◆ CanBreakdown()

◆ ClearRedundantKnots()

◆ Eval()

◆ EvalDerivative()

◆ EvalHeld()

◆ EvalPreDerivative()

◆ EvalPreValue()

◆ EvalPreValueHeld()

◆ GetAntiRegressionAuthoringMode()

◆ GetKnot()

◆ GetKnots() [1/2]

◆ GetKnots() [2/2]

◆ GetKnotsWithInnerLoopsBaked()

◆ GetKnotsWithLoopsBaked()

◆ GetValueRange() [1/2]

◆ GetValueRange() [2/2]

◆ HasLoops()

◆ HasRegressiveTangents()

◆ IsC0Continuous()

◆ IsC1Continuous()

◆ IsG1Continuous()

◆ IsHolding()

◆ IsKnotRedundant()

◆ IsLinear()

◆ IsSegmentFlat()

◆ IsSegmentMonotonic()

◆ IsVarying()

◆ RemoveKnot()

◆ Sample() [1/2]

◆ Sample() [2/2]

◆ SetKnot()

Friends And Related Function Documentation

◆ TfHashAppend

◆ Ts_BinaryDataAccess

◆ Ts_SplineOffsetAccess

◆ TsRegressionPreventer