G3D::Spline< Control > Class Template Reference

Smooth parameteric curve implemented using a piecewise 3rd-order Catmull-Rom spline curve. More...

Inherits G3D::SplineBase.

Public Member Functions
	Spline ()
void	append (float t, const Control &c)
	Appends a control point at a specific time that must be greater than that of the previous point.
void	append (const Control &c)
	Appends control point spaced in time based on the previous control point, or spaced at unit intervals if this is the first control point.
void	clear ()
	Erases all control points and times, but retains the state of cyclic and finalInterval.
void	computeIndex (float s, int &i, float &u) const
	Given a time s, finds i and 0 <= u < 1 such that s = time[i] * u + time[i + 1] * (1 - u).
float	duration () const
	Returns the amount of time covered by this spline in one period.
Control	evaluate (float s) const
	Return the position at time s.
void	getControl (int i, float &t, Control &c) const
	Returns the requested control point and time sample based on array index.
float	getFinalInterval () const
	See specification for Spline::finalInterval; this handles the non-positive case.
int	size () const
	Number of control points.

Static Public Member Functions
static Matrix4	computeBasis ()
	Computes the derivative spline basis from the control point version.

Public Attributes
Array< Control >	control
	Control points.
bool	cyclic
	If cyclic, then the control points will be assumed to wrap around.
float	finalInterval
	For a cyclic spline, this is the time elapsed between the last control point and the first.
Array< float >	time
	Times at which control points occur.

Protected Member Functions
void	computeIndexInBounds (float s, int &i, float &u) const
	Assumes that t0 <= s < tn.
virtual void	correct (Control &A) const
	Normalize or otherwise adjust this interpolated Control.
virtual void	ensureShortestPath (Control *A, int N) const
	Mutates the array of N control points that begins at A.
void	getControls (int i, float *T, Control *A, int N) const
	Returns a series of N control points and times, fixing boundary issues.

Protected Attributes
Control	zero
	The additive identity control point.

Detailed Description

template<typename Control>
class G3D::Spline< Control >

Smooth parameteric curve implemented using a piecewise 3rd-order Catmull-Rom spline curve.

The spline is considered infinite and may either continue linearly from the specified control points or cycle through them. Control points are spaced uniformly in time at unit intervals by default, but irregular spacing may be explicitly specified.

The dimension of the spline can be set by varying the Control template parameter. For a 1D function, use Spline<float>. For a curve in the plane, Spline<Vector2>. Note that any template parameter that supports operator+(Control) and operator*(float) can be used; you can make splines out of G3D::Vector4, G3D::Matrix3, or your own classes.

To provide shortest-path interpolation, subclass G3D::Spline and override ensureShortestPath(). To provide normalization of interpolated points (e.g., projecting Quats onto the unit hypersphere) override correct().

See Real Time Rendering, 2nd edition, ch 12 for a general discussion of splines and their properties.

See Also

G3D::UprightSpline

Constructor & Destructor Documentation

template<typename Control>

G3D::Spline< Control >::Spline ( )

inline

Member Function Documentation

template<typename Control>

void G3D::Spline< Control >::append ( float  t, const Control &  c  )

inline

Appends a control point at a specific time that must be greater than that of the previous point.

Referenced by G3D::Spline< UprightFrame >::append().

template<typename Control>

void G3D::Spline< Control >::append ( const Control &  c )

inline

Appends control point spaced in time based on the previous control point, or spaced at unit intervals if this is the first control point.

template<typename Control>

void G3D::Spline< Control >::clear ( )

inline

Erases all control points and times, but retains the state of cyclic and finalInterval.

static Matrix4 G3D::SplineBase::computeBasis ( )

staticinherited

Computes the derivative spline basis from the control point version.

Referenced by G3D::Spline< UprightFrame >::evaluate().

void G3D::SplineBase::computeIndex ( float  s, int &  i, float &  u  ) const

inherited

Given a time s, finds i and 0 <= u < 1 such that s = time[i] * u + time[i + 1] * (1 - u).

Note that i may be outside the bounds of the time and control arrays; use getControl to handle wraparound and extrapolation issues.

This function takes expected O(1) time for control points with uniform time sampled control points or for uniformly distributed random time samples, but may take O( log time.size() ) time in the worst case.

Called from evaluate().

Referenced by G3D::Spline< UprightFrame >::evaluate().

void G3D::SplineBase::computeIndexInBounds ( float  s, int &  i, float &  u  ) const

protectedinherited

Assumes that t0 <= s < tn.

called by computeIndex.

template<typename Control>

virtual void G3D::Spline< Control >::correct ( Control &  A ) const

inlineprotectedvirtual

Normalize or otherwise adjust this interpolated Control.

Reimplemented in G3D::PhysicsFrameSpline.

Referenced by G3D::Spline< UprightFrame >::evaluate(), and G3D::Spline< UprightFrame >::getControl().

float G3D::SplineBase::duration ( ) const

inherited

Returns the amount of time covered by this spline in one period.

For a cyclic spline, this contains the final interval.

Referenced by G3D::Spline< UprightFrame >::getControl().

template<typename Control>

virtual void G3D::Spline< Control >::ensureShortestPath ( Control *  A, int  N  ) const

inlineprotectedvirtual

Mutates the array of N control points that begins at A.

It is useful to override this method by one that wraps the values if they are angles or quaternions for which "shortest path" interpolation is significant.

Reimplemented in G3D::UprightSpline, and G3D::PhysicsFrameSpline.

Referenced by G3D::Spline< UprightFrame >::getControls().

template<typename Control>

Control G3D::Spline< Control >::evaluate ( float  s ) const

inline

Return the position at time s.

The spline is defined outside of the time samples by extrapolation or cycling.

template<typename Control>

void G3D::Spline< Control >::getControl ( int  i, float &  t, Control &  c  ) const

inline

Returns the requested control point and time sample based on array index.

If the array index is out of bounds, wraps (for a cyclic spline) or linearly extrapolates (for a non-cyclic spline), assuming time intervals follow the first or last sample recorded.

Calls correct() on the control point if it was extrapolated.

Returns 0 if there are no control points.

See Also

Spline::control and Spline::time for the underlying control point array; Spline::computeIndex to find the index given a time.

Referenced by G3D::Spline< UprightFrame >::getControls().

template<typename Control>

void G3D::Spline< Control >::getControls ( int  i, float *  T, Control *  A, int  N  ) const

inlineprotected

Returns a series of N control points and times, fixing boundary issues.

The indices may be assumed to be treated cyclically.

Referenced by G3D::Spline< UprightFrame >::evaluate().

float G3D::SplineBase::getFinalInterval ( ) const

inherited

See specification for Spline::finalInterval; this handles the non-positive case.

Returns 0 if not cyclic.

template<typename Control>

int G3D::Spline< Control >::size ( ) const

inline

Number of control points.

Member Data Documentation

template<typename Control>

Array<Control> G3D::Spline< Control >::control

Control points.

Must have the same number of elements as Spline::time.

Referenced by G3D::Spline< UprightFrame >::append(), G3D::Spline< UprightFrame >::clear(), G3D::Spline< UprightFrame >::evaluate(), G3D::Spline< UprightFrame >::getControl(), G3D::Spline< UprightFrame >::size(), and G3D::UprightSplineManipulator::splineSize().

bool G3D::SplineBase::cyclic

inherited

If cyclic, then the control points will be assumed to wrap around.

If not cyclic, then the tangents at the ends of the spline point to the final control points.

Referenced by G3D::UprightSplineManipulator::cyclic(), G3D::Spline< UprightFrame >::getControl(), and G3D::UprightSplineManipulator::setCyclic().

float G3D::SplineBase::finalInterval

inherited

For a cyclic spline, this is the time elapsed between the last control point and the first.

If less than or equal to zero this is assumed to be:

(time[0] - time[1] + . time[time.size() - 1] - time[time.size() - 2]) / 2.

Array<float> G3D::SplineBase::time

inherited

Times at which control points occur.

Must have the same number of elements as Spline::control.

Referenced by G3D::Spline< UprightFrame >::append(), G3D::Spline< UprightFrame >::clear(), G3D::Spline< UprightFrame >::evaluate(), G3D::Spline< UprightFrame >::getControl(), and G3D::Spline< UprightFrame >::size().

template<typename Control>

Control G3D::Spline< Control >::zero

protected

The additive identity control point.

Referenced by G3D::Spline< UprightFrame >::getControl(), and G3D::Spline< UprightFrame >::Spline().