An oscillating curve that accelerates quadratically. More...

#include <curve_util.h>

Detailed Description

An oscillating curve that accelerates quadratically.

The curve can either,

dampen (as in graph) if bias < 1,
grow if bias > 1,
or have constant amplitude if bias = 1.
```
              value
                ^
                |
```
typical delta value +–___ typical | –_ delta x | _ . | \ . | \ . | . _–_ target value +----------—+------—+-—+__+--—> x | _ _/ | -___-

When starting from zero velocity, the curve will travel typical_delta_value in typical_delta_x to intercept the target_value for the first time.

However, the spring motion can start from any value and velocity, and the calculated movement will mimic the typical momement mathematically. The start state is specified in current_value and current_derivative.

Classes
struct	Context
	Describe one portion of the QuadraticSpring curve. Useful for quickly evaluating the curve iteratively. More...

Public Member Functions
	QuadraticSpring ()
	Default constructor creates a curve at constant value 0.0f.

	QuadraticSpring (float current_value)
	Creates a curve at constant value `current_value` and constant derivative 0. More...

	QuadraticSpring (float current_value, float current_derivative, float target_value, float typical_delta_value, float typical_delta_x, float bias)
	Creates a curve that starts at `current_value` and oscillates about `target_value`. More...

void	IncrementContext (float external_x, Context *c) const
	Ensure Context `c` is valid for `external_x`. More...

Context	CalculateContext (float external_x) const
	Calculate a Context that describes the portion of the spring curve near `external_x`. More...

float	Evaluate (float external_x) const
	Calculate the spring curve value at `external_x`. More...

float	Derivative (float external_x) const
	Calculate the spring curve derivative at `external_x`. More...

float	SecondDerivative (float external_x) const
	Calculate the spring curve second derivative at `external_x`. More...

float	EvaluateWithContext (float external_x, const Context &c) const
	Quickly calculate the spring curve value at `external_x`. More...

float	DerivativeWithContext (float external_x, const Context &c) const
	Quickly calculate the spring curve derivative at `external_x`. More...

float	SecondDerivativeWithContext (float external_x, const Context &c) const
	Quickly calculate the spring curve second derivative at `external_x`. More...

float	ThirdDerivative (float external_x) const
	Return the spring curve's third derivative. More...

float	IterationX (float iterations) const
	Calculate the x for the `iterations`th peak of the spring curve. More...

float	target () const
	Get the `target_value` originally passed into the constructor. More...

Constructor & Destructor Documentation

motive::QuadraticSpring::QuadraticSpring ( float current_value )

inlineexplicit

Creates a curve at constant value current_value and constant derivative 0.

Parameters

current_value The constant value of the curve.

motive::QuadraticSpring::QuadraticSpring	(	float	current_value,
		float	current_derivative,
		float	target_value,
		float	typical_delta_value,
		float	typical_delta_x,
		float	bias
	)

Creates a curve that starts at current_value and oscillates about target_value.

Parameters

current_value	The starting value of the curve.
current_derivative	The starting derivative of the curve.
target_value	The value we oscillate about.
typical_delta_value	Together with typical_delta_x, describes how quickly the curve moves to the target. See class description for details.
typical_delta_x	Together with typical_delta_value, describes how quickly the curve moves to the target. See class description for details.
bias	Determines how quickly the curve settles down. That is, the tightness of the spring. The smaller, the tighter. < 1 ==> dampens down to zero eventually = 1 ==> oscilates with same amplitude indefinitely > 1 ==> amplitude grows with every oscillation Each peak has has the magnitude of the previous peak * bias.

Member Function Documentation

Context motive::QuadraticSpring::CalculateContext ( float external_x ) const

Calculate a Context that describes the portion of the spring curve near external_x.

It's significantly faster to call this function only once, and then, for succeeding xs, advance the Context by calling IncrementContext.

Parameters

external_x The x value that about which we want the returned Context to be valid.

Returns: A Context that describes a portion of the spring curve. Use it in calls to EvaluateWithContext, etc.

float motive::QuadraticSpring::Derivative ( float external_x ) const

inline

Calculate the spring curve derivative at external_x.

Note: This function is significantly slower than DerivativeWithContext. Consider maintaining a Context externally and then calling IncrementContext and DerivativeWithContext instead of just Derivative.

Parameters

external_x x value since the start of the curve.

Returns: The spring curve derivative at external_x.

float motive::QuadraticSpring::DerivativeWithContext	(	float	external_x,
		const Context &	c
	)		const

inline

Quickly calculate the spring curve derivative at external_x.

Parameters

external_x	x value since the start of the curve.
c	Context that describes the portion of the spring curve around `external_x`. Note that you should call IncrementContext with this `external_x` and `c` before calling this function.

Returns: The spring curve derivative at external_x.

float motive::QuadraticSpring::Evaluate ( float external_x ) const

inline

Calculate the spring curve value at external_x.

Note: This function is significantly slower than EvaluateWithContext. Consider maintaining a Context externally and then calling IncrementContext and EvaluateWithContext instead of just Evaluate.

Parameters

external_x x value since the start of the curve, as specified by current_value and current_derivative in the constructor.

Returns: The spring curve value at external_x.

float motive::QuadraticSpring::EvaluateWithContext	(	float	external_x,
		const Context &	c
	)		const

inline

Quickly calculate the spring curve value at external_x.

Parameters

external_x	x value since the start of the curve.
c	Context that describes the portion of the spring curve around `external_x`. Note that you should call IncrementContext with this `external_x` and `c` before calling this function.

Returns: The spring curve value at external_x.

void motive::QuadraticSpring::IncrementContext	(	float	external_x,
		Context *	c
	)		const

inline

Ensure Context c is valid for external_x.

Most times, external_x will already be within the valid x-range of c. When it's not, we advance c to the next quadratic in the series of curves that compose the spring curve. We continue until external_x is again in the valid range of c.

Parameters

external_x	The current x value we're evaluating. The expectation is that `external_x` will be incrementing at a reasonably small and steady rate. When this happens, `c` only has to be updated when `external_x` exceeds the portion of the spring curve that `c` describes.
c	The current evaluation context. It describes one portion of the spring curve. After updating `c` with this function, you can pass it into EvaluateWithContext and other such functions to calculate the curve values quickly.

float motive::QuadraticSpring::IterationX ( float iterations ) const

Calculate the x for the iterationsth peak of the spring curve.

Parameters

iterations The number of iterations to be completed, where an iteration is defined as one peak to the next.

Returns: x for the iterationsth peak.

float motive::QuadraticSpring::SecondDerivative ( float external_x ) const

inline

Calculate the spring curve second derivative at external_x.

Note: This function is significantly slower than SecondDerivativeWithContext. Consider maintaining a Context externally and then calling IncrementContext and SecondDerivativeWithContext instead of just SecondDerivative.

Parameters

external_x x value since the start of the curve.

Returns: The spring curve second derivative at external_x. Note that there are only two possible second derivatives: one towards the target and one away from the target. This is a concequence of our usage of quadratic functions.

float motive::QuadraticSpring::SecondDerivativeWithContext	(	float	external_x,
		const Context &	c
	)		const

inline

Quickly calculate the spring curve second derivative at external_x.

Parameters

external_x	x value since the start of the curve.
c	Context that describes the portion of the spring curve around `external_x`. Note that you should call IncrementContext with this `external_x` and `c` before calling this function.

Returns: The spring curve second derivative at external_x.

float motive::QuadraticSpring::target ( ) const

inline

Get the target_value originally passed into the constructor.

Returns: The value about which we're oscillating.

float motive::QuadraticSpring::ThirdDerivative ( float external_x ) const

inline

Return the spring curve's third derivative.

Returns: Return value is always 0 because internally we return quadratics.

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

curve_util.h

Detailed Description

Classes

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation