gam::scl Namespace Reference

Scalar rank functions for numerical types. More...

Functions
bool	almostEqual (float a, float b, int maxULP=10)
	Tests whether two values are close in value.
float	clipMag (float value, float max=1.f, float min=0.f)
	Returns value whose magnitude is clipped to [min, max].
double	freq (const char *note)
	Returns frequency in Hz from a 12-TET note string.
float	sqrtLog2 (float v)
	Approximate square root using a quick log base-2 method.
double	sqrtLog2 (double v)
	Approximate square root using a quick log base-2 method.
template<int N, class T >
void	sqrtNewton (T &v, T v0)
	Approximate square root using Newton's method.
template<uint32_t N, class T >
T	sqrt (T v)
	Approximate square root using log base-2 and Newton methods.
template<int N, class T >
void	invSqrtNewton (T &v, T v0)
	Approximate inverse square root using Newton's method.
template<class T >
T	invSqrtLog2 (T v)
	Approximate inverse square root using a quick log base-2 method.
template<uint32_t N, class T >
T	invSqrt (T v)
	Approximate inverse square root using log base-2 and Newton methods.
template<class T >
T	atan2Fast (T y, T x)
	Fast approximation to atan2().
template<class T >
T	ceil (T val)
	Returns floating point value rounded to next highest integer.
uint32_t	ceilPow2 (uint32_t value)
	Returns power of two ceiling of value.
template<class T >
T	clip (T value, T hi=T(1), T lo=T(0))
	Returns value clipped to [lo, hi].
template<class T >
T	clipS (T value, T hi=T(1))
	Returns value clipped to [-hi, hi].
template<class T >
T	clip (T value, int &clipFlag, T hi, T lo)
	Returns value clipped to [lo, hi] and signifies clipping behavior.
template<class T >
T	cosP3 (T u)
	Third order polynomial approximation to first half of cosine.
template<class T >
T	cosT8 (T radians)
	8th order Taylor series approximation to a cosine.
template<class T >
T	dBToAmp (const T &db)
	Convert decibels to amplitude.
template<class T >
T	ampTodB (const T &amp)
	Convert amplitude to decibels.
template<class T >
void	fadeLin (T &weight1, T &weight2, T fade)
	Returns weights for linear fade.
template<class T >
void	fadeTri (T &weight1, T &weight2, T fade)
	Returns weights for triangular window fade.
template<class T >
T	fejer (T k, T n)
	Return Fejer weighting factor for kth harmonic in a Fourier series of length n.
template<class T >
T	floor (T val)
	Returns floor of floating point value.
template<class T >
T	fold (T value, T hi=T(1), T lo=T(0))
	Returns value folded into [lo, hi].
template<class T >
T	foldOnce (T value, T hi=T(1), T lo=T(0))
	Returns value folded into [lo, hi] one time.
template<class T >
T	linLog2 (T v, T recMin)
	Convert linear value to log2 in range [0, 1].
uint32_t	log2 (uint32_t v)
	Returns base 2 logarithm of value.
float	log2Fast (float v)
	Fast base 2 logarithm. For value <= 0, behavior is undefined.
template<class T >
T	mapDepth (T v, T depth)
	Maps value from [-1,1] to [depth, 1].
template<class T >
T	mapInvPow2 (T v)
	Inverse 2nd power mapping for interval [0, 1].
template<class T >
void	mapLin (T i0, T i1, T o0, T o1, T &scale, T &offset)
	Computes scale and offset necessary to map value from [i0, i1] to [o0, o1].
template<class T >
T	mapLin (T v, T i0, T i1, T o0, T o1)
	Linearly maps value from [i0, i1] to [o0, o1].
double	mapPower (double v, double bound1, double bound0, double power=1.)
	Returns v^power linearly mapped to [bound0, bound1].
template<class T >
T	mapSinSS (T v)
	Map a value in [-1,1] to a cubic approximating sin(pi/2 x)
template<class T >
T	mapSinSU (T v)
	Map a value in [-1,1] to a cubic approximating 1/2 sin(pi/2 x) + 1/2.
template<class T >
T	mapSinUS (T v)
	Map a value in [ 0,1] to a cubic approximating -cos(pi x)
template<class T >
T	mapSinUU (T v)
	Map a value in [ 0,1] to a cubic approximating -1/2 cos(pi x) + 1/2.
template<class T >
void	mix2 (T &io1, T &io2, T mix)
	Mixes two values together (1 = thru, 0.5 = mono, 0 = swap).
template<class T >
T	nearest (T v, const char *intervals="2212221", long mod=12)
	Returns nearest "note" within a pitch class set.
template<class T >
T	nextAfter (T x, T y)
	Returns the next representable floating-point or integer value following x in the direction of y.
template<class T >
T	pow2 (T v)
	Returns value to the 2nd power.
template<class T >
T	pow3 (T v)
	Returns value to the 3rd power.
template<class T >
T	pow4 (T v)
	Returns value to the 4th power.
double	radius60 (double dcy, double ups)
	Returns pole radius given a T60 decay length and units/sample.
template<class T >
T	ratioET (T pitch, T divs=12, T octave=2)
	Returns equal temperament ratio- octave^(pitch/divs)
template<class T >
T	round (T v)
	Returns floating point value rounded to nearest integer.
template<class T >
T	round (T v, T step)
	Returns floating point value rounded to nearest integer multiple of 'step'.
template<class T >
T	round (T v, T step, T recStep)
	Returns floating point value rounded to nearest integer multiple of 'step'. Faster version to avoid 1/step divide.
template<class T >
T	roundAway (T v)
	Returns value rounded to nearest integer away from zero.
template<class T >
T	roundAway (T v, T step)
	Returns value rounded to nearest to nearest integer multiple of 'step' away from zero.
int	section (int v, int num, int divs)
	Returns the section 'v' lies in in [0,num] divided into 'div' sections.
template<class T >
T	sinP7 (T normal)
	7th order minimax polynomial approximation to a sine.
template<class T >
T	sinP9 (T normal)
	9th order minimax polynomial approximation to a sine.
template<class T >
T	sinT7 (T radians)
	7th order Taylor series approximation to a sine.
template<class T >
T	sinT9 (T radians)
	9th order Taylor series approximation to a sine.
template<class T >
T	smoothNeg (T v, T bw)
	Smooth negative map.
template<class T >
T	smoothNeg (T v, T bw, T amt)
	Same as smoothNeg(T,T), but 'amt' controls positive level (0,1) -> (-1,1)
template<class T >
T	smoothPos (T v, T bw)
	Smooth positive map.
template<class T >
T	smoothPeak (T v, T bw)
	Peak function.
template<class T >
T	smoothSign (T v, T bw)
	Continuous sign map.
template<class T , class F >
T	smoothZero (T v, T bw, F f)
	Same as smoothZero(), but takes a unary function to be applied to the value.
template<class T >
T	smoothZero (T v, T bw)
	Returns a continuous value measuring how close to zero the value is.
template<class T >
T	trunc (T value)
	Truncates floating point value at decimal.
template<class T >
T	trunc (T value, T step)
	Truncates floating point value to step.
template<class T >
T	trunc (T value, T step, T recStep)
	Truncates floating point value to step. Faster version to avoid 1/step divide.
double	t60 (double samples)
	Returns multiplicaton factor for reaching -60 dB after 'samples' iterations.
template<class T >
T	wrap (T value, T hi=(T) 1, T lo=(T) 0)
	Returns value wrapped in [lo, hi).
template<class T >
T	wrap (T value, long &numWraps, T hi=(T) 1, T lo=(T) 0)
	Returns value wrapped in [lo, hi).
template<class T >
T	wrapAdd1 (T v, T max)
	Returns value incremented by 1 and wrapped into interval [0, max).
template<class T >
T	wrapOnce (T value, T hi=(T) 1)
	Like wrap(), but only adds or subtracts 'hi' once from value.
template<class T >
T	wrapPhase (T radians)
	Returns value wrapped in [-pi, pi)
template<class T >
T	wrapPhaseOnce (T radians)
	Like wrapPhase(), but only wraps once.
template<class T >
bool	even (T v)
	Returns whether or not an integer value is even.
template<class T >
T	max (T v1, T v2, T v3)
	Returns maximum of three values.
template<class T >
T	min (T v1, T v2, T v3)
	Returns minimum of three values.
template<class T >
bool	odd (T v)
	Returns whether or not an integer value is odd.
template<class T >
T	slope (T x1, T y1, T x2, T y2)
	Returns slope of line passing through two points.
uint32_t	trailingZeroes (uint32_t v)
	Returns number of trailing zeros in 32-bit int.
template<class T >
bool	within (T v, T lo, T hi)
	Returns whether value is within [lo, hi].
bool	zeroCrossP (float prev, float now)
	Returns whether a positive zero crossing occured.
uint32_t	quantizePow2 (uint32_t value, uint32_t q)
	Returns value quantized to multiples of 2^q.
float	rampDown (uint32_t phase)
	Returns value of bipolar downward ramp function.
float	rampUp (uint32_t phase)
	Returns value of bipolar upward ramp function.
float	square (uint32_t phase)
	Returns value of bipolar square function.
float	triangle (uint32_t phase)
	Returns value of bipolar triangle function.
float	pulse (uint32_t phase, uint32_t width)
	Returns value of bipolar pulse function (rampDown() + rampUp()).
float	stair (uint32_t phase, uint32_t width)
	Returns value of bipolar stair function (square() + square()).
float	rampUp2 (uint32_t phase, uint32_t width)
	Returns value of bipolar dual upward ramp function (rampUp() + rampUp()).
float	pulseU (uint32_t phase, uint32_t width)
	Returns value of unipolar pulse function.
float	rampUpU (uint32_t phase)
	Returns value of unipolar downward ramp function.
float	rampUp2U (uint32_t phase)
	Returns value of unipolar upward ramp2 function.
float	rampDownU (uint32_t phase)
	Returns value of unipolar upward ramp function.
float	squareU (uint32_t phase)
	Returns value of unipolar square function.
float	stairU (uint32_t phase, uint32_t width)
	Returns value of unipolar stair function.
float	triangleU (uint32_t phase)
	Returns value of unipolar triangle function.
template<class T >
T	bartlett (T nphase)
	Bartlett window. nphase => [-1, 1)
template<class T >
T	blackman (T phase)
	Blackman window function.
template<class T >
T	blackmanHarris (T phase)
	Blackman-Harris window function.
template<class T >
T	hamming (T phase)
	Hamming window function.
template<class T >
T	hann (T phase)
	von Hann window function.
template<class T >
T	raisedCosine (T phase, T a, T b)
	Raised cosine f(x) = a - b cos(x).
template<class T >
T	welch (T nphase)
	Welch window function. nphase => [-1, 1)

---

Detailed Description

Scalar rank functions for numerical types.

---

Function Documentation

bool almostEqual	(	float	a,
		float	b,
		int	maxULP = 10
	)

Tests whether two values are close in value.

'maxULP' (maximum units in the last place) is the maximum difference allowed between the values punned as integers. Code taken from Bruce Dawson, "Comparing floating point numbers."

uint32_t ceilPow2

(

uint32_t

value

)

Returns power of two ceiling of value.

This uses an algorithm devised by Sean Anderson, Sep. 2001. From "Bit Twiddling Hacks", http://graphics.stanford.edu/~seander/bithacks.html.

T clip	(	T	value,
		int &	clipFlag,
		T	hi,
		T	lo
	)

Returns value clipped to [lo, hi] and signifies clipping behavior.

clipFlag signifies if and where clipping occured. 0 means no clipping occured, -1 means clipping occured at the lower bound, and 1 means clipping at the upper bound.

T cosP3

(

T

u

)

Third order polynomial approximation to first half of cosine.

'u' must be in the range [0, 0.5] which corresponds to the first half of the cosine.

T cosT8

(

T

radians

)

8th order Taylor series approximation to a cosine.

'radians' must be in [-pi, pi].

void fadeTri	(	T &	weight1,
		T &	weight2,
		T	fade
	)

Returns weights for triangular window fade.

The weights returned are from two overlapping normalized unipolar triangular windows in the fade interval [0, 2/3] and [1/3, 1].
fade weight1 weight2
0.25 1 0
0.5 0.5 0.5
0.75 0 1

T gam::scl::fejer	(	T	k,
		T	n
	)

Return Fejer weighting factor for kth harmonic in a Fourier series of length n.

The function is a line from (0,1) to (n,0). This is used for reducing the Gibbs effect from a Fourier series summation.

T fold	(	T	value,
		T	hi = T(1),
		T	lo = T(0)
	)

Returns value folded into [lo, hi].

For out-of-range values, the boundaries act like mirrors reflecting the value into the range. For an even number of periods out of the range this is identical to a wrap().

double freq

(

const char *

note

)

Returns frequency in Hz from a 12-TET note string.

Notes are specified by a letter in [a, g], followed optionally by one of '+', '-', ' ', to specify a sharp, flat or natural, and finally an integer in [0,9] representing the octave number. For example, middle C is specified as "c5" or "c 5" and the A sharp below that as "a+4".

T gam::scl::invSqrt

(

T

v

)

Approximate inverse square root using log base-2 and Newton methods.

'N' determines the accuracy of the approximation. For N=0, a quick and dirty log base-2 approximation is performed. For N>0, N-1 Newton iterations are applied to improve the result.

uint32_t log2

(

uint32_t

v

)

Returns base 2 logarithm of value.

If the value is not an exact power of two, the logarithm of the next highest power of two will taken. This uses an algorithm devised by Eric Cole, Jan. 2006. From "Bit Twiddling Hacks", http://graphics.stanford.edu/~seander/bithacks.html.

T nearest	(	T	v,
		const char *	intervals = "2212221",
		long	mod = 12
	)

Returns nearest "note" within a pitch class set.

Parameters:

[in]	v	the value to match
[in]	intervals	sequence of base-36 intervals
[in]	mod	modulo amount

The sum of the values in the interval array should be equal to 'mod'.

T ratioET	(	T	pitch,
		T	divs = 12,
		T	octave = 2
	)

Returns equal temperament ratio- octave^(pitch/divs)

Parameters:

[in]	pitch	pitch class
[in]	divs	number of equally tempered divisions in octave
[in]	octave	base multiplier of (pseudo) octave

T sinT7

(

T

radians

)

7th order Taylor series approximation to a sine.

'radians' must be in [-pi, pi].

T sinT9

(

T

radians

)

9th order Taylor series approximation to a sine.

'radians' must be in [-pi, pi].

T smoothNeg	(	T	v,
		T	bw
	)

Smooth negative map.

The return value is close to 1 if v < 0 and close to 0 if v > 0. The smoothness is controlled with the bw argument.

T smoothPeak	(	T	v,
		T	bw
	)

Peak function.

When v is the output of y=x^2, this formula approximates the true formula for a resonant peak 1/(1 - 2rcos(theta) + r^2). The argument bw is equivalent to (1-r)^2. In general, the approximation has a slightly smaller bandwidth than the true response. Also, the true response is periodic, while this one is not.

T smoothPos	(	T	v,
		T	bw
	)

Smooth positive map.

The return value is close to 1 if v > 0 and close to 0 if v < 0. The smoothness is controlled with the bw argument.

T smoothSign	(	T	v,
		T	bw
	)

Continuous sign map.

The return value is close to 1 if v > 0 and close to -1 if v < 0. 'bw' controls the width of the transition region. If 'bw' is 0, then this turns into a signum function.

T smoothZero	(	T	v,
		T	bw
	)

Returns a continuous value measuring how close to zero the value is.

The graph of this function resembles a resonant peak. The function uses the square of the value for evaluation.

T gam::scl::sqrt

(

T

v

)

Approximate square root using log base-2 and Newton methods.

'N' determines the accuracy of the approximation. For N=0, a quick and dirty log base-2 approximation is performed. For N>0, N-1 Newton iterations are applied to improve the result.

uint32_t trailingZeroes

(

uint32_t

v

)

Returns number of trailing zeros in 32-bit int.

This implements an algorithm from the paper "Using de Bruijn Sequences to Index 1 in a Computer Word" by Charles E. Leiserson, Harald Prokof, and Keith H. Randall.

T wrap	(	T	value,
		long &	numWraps,
		T	hi = (T)1,
		T	lo = (T)0
	)

Returns value wrapped in [lo, hi).

'numWraps' reports how many wrappings occured where the sign, + or -, signifies above 'hi' or below 'lo', respectively.