G3D::Spline< Control > Class Template Reference

#include <Spline.h>

Public Member Functions
	Spline ()
void	append (float t, const Control &c)
void	append (const Control &c)
void	clear ()
int	size () const
void	getControl (int i, float &t, Control &c) const
	Spline (const Any &any)
virtual Any	toAny (const std::string &myName) const
Control	evaluate (float s) const
Public Member Functions inherited from G3D::SplineBase
	SplineBase ()
virtual	~SplineBase ()
float	getFinalInterval () const
float	duration () const
void	computeIndex (float s, int &i, float &u) const

Public Attributes
Array< Control >	control
Public Attributes inherited from G3D::SplineBase
Array< float >	time
SplineExtrapolationMode	extrapolationMode
float	finalInterval
SplineInterpolationMode	interpolationMode

Protected Member Functions
void	getControls (int i, float *T, Control *A, int N) const
virtual void	ensureShortestPath (Control *A, int N) const
virtual void	correct (Control &A) const
virtual void	init (AnyTableReader &propertyTable)
Protected Member Functions inherited from G3D::SplineBase
void	computeIndexInBounds (float s, int &i, float &u) const

Protected Attributes
Control	zero

Additional Inherited Members
Static Public Member Functions inherited from G3D::SplineBase
static Matrix4	computeBasis ()

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

 {
 static Control x;
 // Hide the fact from C++ that we are using an
 // uninitialized variable here by pointer arithmetic.
 // This is ok because any type that is a legal control
 // point also supports multiplication by float.
 zero = *(&x) * 0.0f;
 }

template<typename Control>

G3D::Spline< Control >::Spline ( const Any &  any )

inlineexplicit

Accepts a table of properties, or any valid PhysicsFrame specification for a single control

 {
 AnyTableReader propertyTable(any);
 init(propertyTable);
 propertyTable.verifyDone();
 }

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.

 {
 debugAssertM((time.size() == 0) || (t > time.last()), 
 "Control points must have monotonically increasing times.");
 time.append(t);
 control.append(c);
 debugAssert(control.size() == time.size());
 }

Here is the caller graph for this function:

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.

 {
 switch (time.size()) {
 case 0:
 append(0, c);
 break;

 case 1:
 append(time[0] + 1, c);
 break;

 default:
 append(2 * time[time.size() - 1] - time[time.size() - 2], c);
 }
 debugAssert(control.size() == time.size());
 }

template<typename Control>

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

inline

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

 {
 control.clear();
 time.clear();
 }

template<typename Control>

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

inlineprotectedvirtual

Normalize or otherwise adjust this interpolated Control.

Reimplemented in G3D::PhysicsFrameSpline.

{ (void)A; }

Here is the caller graph for this function:

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.

{ (void)A; (void) N;}

Here is the caller graph for this function:

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.

 {
 debugAssertM(control.size() == time.size(), "Corrupt spline: wrong number of control points.");

 /*
 @cite http://www.gamedev.net/reference/articles/article1497.asp 
 Derivation of basis matrix follows.
 
 Given control points with positions p[i] at times t[i], 0 <= i <= 3, find the position 
 at time t[1] <= s <= t[2].

 Let u = s - t[0]
 Let U = [u^0 u^1 u^2 u^3] = [1 u u^2 u^3]
 Let dt0 = t[0] - t[-1]
 Let dt1 = t[1] - t[0]
 Let dt2 = t[2] - t[1]
 */

 // Index of the first control point (i.e., the u = 0 point)
 int i = 0;
 // Fractional part of the time
 float u = 0;

 computeIndex(s, i, u);

 Control p[4];
 float t[4];
 getControls(i - 1, t, p, 4);

 const Control& p0 = p[0];
 const Control& p1 = p[1];
 const Control& p2 = p[2];
 const Control& p3 = p[3];

 // Compute the weighted sum of the neighboring control points.
 Control sum;

 if (interpolationMode == SplineInterpolationMode::LINEAR) {
 const float a = (s - t[1]) / (t[2] - t[1]);
 sum = p1 * (1.0f - a) + p2 * a;
 correct(sum);
 return sum;
 }

 float dt0 = t[1] - t[0];
 float dt1 = t[2] - t[1];
 float dt2 = t[3] - t[2];

 static const Matrix4 basis = computeBasis();

 // Powers of u
 Vector4 uvec((float)(u*u*u), (float)(u*u), (float)u, 1.0f);

 // Compute the weights on each of the control points.
 const Vector4& weights = uvec * basis;
 

 // The factor of 1/2 from averaging two time intervals is 
 // already factored into the basis
 
 // tan1 = (dp0 / dt0 + dp1 / dt1) * ((dt0 + dt1) * 0.5);
 // The last term normalizes for unequal time intervals
 float x = (dt0 + dt1) * 0.5f;
 float n0 = x / dt0;
 float n1 = x / dt1;
 float n2 = x / dt2;

 const Control& dp0 = p1 + (p0*-1.0f);
 const Control& dp1 = p2 + (p1*-1.0f);
 const Control& dp2 = p3 + (p2*-1.0f);

 const Control& dp1n1 = dp1 * n1;
 const Control& tan1 = dp0 * n0 + dp1n1;
 const Control& tan2 = dp1n1 + dp2 * n2;

 sum = 
 tan1 * weights[0] +
 p1 * weights[1] +
 p2 * weights[2] +
 tan2 * weights[3]; 
 

 correct(sum);
 return sum;
 }

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.

 {
 int N = control.size();
 if (N == 0) {
 c = zero;
 t = 0;
 } else if (extrapolationMode == SplineExtrapolationMode::CYCLIC) {
 c = control[iWrap(i, N)];

 if (i < 0) {
 // Wrapped around bottom

 // Number of times we wrapped around the cyclic array
 int wraps = (N + 1 - i) / N; 
 int j = (i + wraps * N) % N;
 t = time[j] - wraps * duration();

 } else if (i < N) {

 t = time[i];

 } else {
 // Wrapped around top

 // Number of times we wrapped around the cyclic array
 int wraps = i / N; 
 int j = i % N;
 t = time[j] + wraps * duration();
 }

 } else if (i < 0) {
 // Are there enough points to extrapolate?
 if (N >= 2) {
 // Step away from control point 0
 float dt = time[1] - time[0];
 
 if (extrapolationMode == SplineExtrapolationMode::LINEAR) {
 // Extrapolate (note; i is negative)
 c = control[1] * float(i) + control[0] * float(1 - i);
 correct(c);
 } else if (extrapolationMode == SplineExtrapolationMode::CLAMP){
 // Return the first, clamping
 c = control[0];
 } else {
 alwaysAssertM(false, "Invalid extrapolation mode");
 }
 t = dt * i + time[0];

 } else {
 // Just clamp
 c = control[0];

 // Only 1 time; assume 1s intervals
 t = time[0] + i;
 }

 } else if (i >= N) {
 if (N >= 2) {
 float dt = time[N - 1] - time[N - 2];

 if (extrapolationMode == SplineExtrapolationMode::LINEAR) {
 // Extrapolate (note; i is negative)
 c = control[N - 1] * float(i - N + 2) + control[N - 2] * -float(i - N + 1);
 correct(c);
 } else if (extrapolationMode == SplineExtrapolationMode::CLAMP){
 // Return the last, clamping
 c = control.last();
 } else {
 alwaysAssertM(false, "Invalid extrapolation mode");
 }
 // Extrapolate
 t = time[N - 1] + dt * (i - N + 1);

 } else {
 // Return the last, clamping
 c = control.last();
 // Only 1 time; assume 1s intervals
 t = time[0] + i;
 }
 } else {
 // In bounds
 c = control[i];
 t = time[i];
 }
 }

Here is the caller graph for this function:

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.

 {
 for (int j = 0; j < N; ++j) {
 getControl(i + j, T[j], A[j]);
 }
 ensureShortestPath(A, N);
 }

Here is the caller graph for this function:

template<typename Control>

virtual void G3D::Spline< Control >::init ( AnyTableReader &  propertyTable )

inlineprotectedvirtual

Does not invoke verifyDone() on the propertyTable because subclasses may have more properties

 {
 propertyTable.getIfPresent("extrapolationMode", extrapolationMode);
 propertyTable.getIfPresent("interpolationMode", interpolationMode);
 propertyTable.getIfPresent("finalInterval", finalInterval);

 const bool hasTime = propertyTable.getIfPresent("time", time);

 if (propertyTable.getIfPresent("control", control)) {
 if (! hasTime) {
 // Assign unit times
 time.resize(control.size());
 for (int i = 0; i < time.size(); ++i) {
 time[i] = float(i);
 }
 } // if has time
 } // if has control
 } // init

Here is the caller graph for this function:

template<typename Control>

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

inline

Number of control points

 {
 debugAssert(time.size() == control.size());
 return control.size();
 }

Here is the caller graph for this function:

template<typename Control>

virtual Any G3D::Spline< Control >::toAny ( const std::string &  myName ) const

inlinevirtual

Note that invoking classes can call setName on the returned value instead of passing a name in.

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

 {
 Any a(Any::TABLE, myName);
 
 a["extrapolationMode"] = extrapolationMode;
 a["interpolationMode"] = interpolationMode;
 a["control"] = Any(control);
 a["time"] = Any(time);
 a["finalInterval"] = finalInterval;

 return a;
 }

Here is the caller graph for this function:

Member Data Documentation

template<typename Control>

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

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

template<typename Control>

Control G3D::Spline< Control >::zero

protected

The additive identity control point.

---

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

• dep/g3dlite/include/G3D/Spline.h