G3D::Random Class Reference

#include <Random.h>

Public Member Functions
	Random (uint32 seed=0xF018A4D2, bool threadsafe=true)
virtual	~Random ()
virtual void	reset (uint32 seed=0xF018A4D2, bool threadsafe=true)
virtual uint32	bits ()
virtual int	integer (int min, int max)
virtual float	uniform (float low, float high)
virtual float	uniform ()
virtual float	gaussian (float mean, float stdev)
virtual void	cosHemi (float &x, float &y, float &z)
virtual void	cosSphere (float &x, float &y, float &z)
virtual void	cosPowHemi (const float k, float &x, float &y, float &z)
virtual void	hemi (float &x, float &y, float &z)
virtual void	sphere (float &x, float &y, float &z)

Static Public Member Functions
static Random &	common ()

Protected Types
enum	{   N = 624, M = 397, R = 31, U = 11,   S = 7, T = 15, L = 18, A = 0x9908B0DF,   B = 0x9D2C5680, C = 0xEFC60000 }

Protected Member Functions
virtual void	generate ()
	Random (void *)

Protected Attributes
Spinlock	lock
uint32 *	state
int	index
bool	m_threadsafe

Private Member Functions
Random &	operator= (const Random &)
	Random (const Random &r)

Detailed Description

Random number generator.

Threadsafe.

Useful for generating consistent random numbers across platforms and when multiple threads are involved.

Uses the Fast Mersenne Twister (FMT-19937) algorithm.

On average, uniform() runs about 2x-3x faster than rand().

[http://www.math.sci.hiroshima-u.ac.jp/]~m-mat/MT/SFMT/index.html

On OS X, Random is about 10x faster than drand48() (which is threadsafe) and 4x faster than rand() (which is not threadsafe).

See also

Noise

Member Enumeration Documentation

anonymous enum

protected

Constants (important for the algorithm; do not modify)

Enumerator
N
M
R
U
S
T
L
A
B
C

 {
 N = 624,
 M = 397,
 R = 31,
 U = 11,
 S = 7,
 T = 15,
 L = 18,
 A = 0x9908B0DF,
 B = 0x9D2C5680,
 C = 0xEFC60000};

Constructor & Destructor Documentation

G3D::Random::Random ( void *  x )

protected

For subclasses. The void* parameter is just to distinguish this from the public constructor.

 : state(NULL), m_threadsafe(false) {
 (void)x;
}

G3D::Random::Random ( const Random &  r )

inlineprivate

 {
 *this = r;
 }

G3D::Random::Random	(	uint32	seed = 0xF018A4D2,
		bool	threadsafe = true
	)

Parameters

threadsafe

Set to false if you know that this random will only be used on a single thread. This eliminates the lock and improves performance on some platforms.

 : m_threadsafe(threadsafe) {
 state = new uint32[N];
 reset(seed, threadsafe);
}

Here is the call graph for this function:

G3D::Random::~Random ( )

virtual

 {
 delete[] state;
 state = NULL;
}

Member Function Documentation

uint32 G3D::Random::bits ( )

virtual

Each bit is random. Subclasses can choose to override just this method and the other methods will all work automatically.

Reimplemented in G3D::PrecomputedRandom.

 {
 // See http://en.wikipedia.org/wiki/Mersenne_twister

 // Make a local copy of the index variable to ensure that it
 // is not out of bounds
 int localIndex = index;

 // Automatically checks for index < 0 if corrupted
 // by unsynchronized threads.
 if ((unsigned int)localIndex >= (unsigned int)N) {
 generate();
 localIndex = 0;
 }
 // Increment the global index. It may go out of bounds on
 // multiple threads, but the above check ensures that the
 // array index actually used never goes out of bounds.
 // It doesn't matter if we grab the same array index twice
 // on two threads, since the distribution of random numbers
 // will still be uniform.
 ++index;
 // Return the next random in the sequence
 uint32 r = state[localIndex];

 // Temper the result
 r ^= r >> U;
 r ^= (r << S) & B;
 r ^= (r << T) & C;
 r ^= r >> L;
 
 return r; 
}

Here is the call graph for this function:

Here is the caller graph for this function:

Random & G3D::Random::common ( )

static

A shared instance for when the performance and features but not consistency of the class are desired. It is slightly (10%) faster to use a distinct instance than to use the common one.

Threadsafe.

 {
 static Random r;
 return r;
}

void G3D::Random::cosHemi ( float &  x, float &  y, float &  z  )

virtual

Returns 3D unit vectors distributed according to a cosine distribution about the positive z-axis.

Reimplemented in G3D::PrecomputedRandom.

 {
 const float e1 = uniform();
 const float e2 = uniform();

 // Jensen's method 
 const float sin_theta = sqrtf(1.0f - e1);
 const float cos_theta = sqrtf(e1);
 const float phi = 6.28318531f * e2;

 x = cos(phi) * sin_theta;
 y = sin(phi) * sin_theta;
 z = cos_theta;

 // We could also use Malley's method (pbrt p.657), since they are the same cost:
 //
 // r = sqrt(e1);
 // t = 2*pi*e2;
 // x = cos(t)*r;
 // y = sin(t)*r;
 // z = sqrt(1.0 - x*x + y*y);
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Random::cosPowHemi ( const float  k, float &  x, float &  y, float &  z  )

virtual

Returns 3D unit vectors distributed according to a cosine power distribution ( ) about the z-axis.

Reimplemented in G3D::PrecomputedRandom.

 {
 const float e1 = uniform();
 const float e2 = uniform();

 const float cos_theta = pow(e1, 1.0f / (k + 1.0f));
 const float sin_theta = sqrtf(1.0f - square(cos_theta));
 const float phi = 6.28318531f * e2;

 x = cos(phi) * sin_theta;
 y = sin(phi) * sin_theta;
 z = cos_theta;
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Random::cosSphere ( float &  x, float &  y, float &  z  )

virtual

Returns 3D unit vectors distributed according to a cosine distribution about the z-axis.

 {
 cosHemi(x, y, z);
 if (bits() & 1) {
 // Choose the axis direction uniformly at random
 z = -z;
 }
}

Here is the call graph for this function:

Here is the caller graph for this function:

float G3D::Random::gaussian ( float  mean, float  stdev  )

virtual

Normally distributed reals.

 {

 // Using Box-Mueller method from http://www.taygeta.com/random/gaussian.html
 // Modified to specify standard deviation and mean of distribution
 float w, x1, x2;

 // Loop until w is less than 1 so that log(w) is negative
 do {
 x1 = uniform(-1.0, 1.0);
 x2 = uniform(-1.0, 1.0);

 w = float(square(x1) + square(x2));
 } while (w > 1.0f);

 // Transform to gassian distribution
 // Multiply by sigma (stdev ^ 2) and add mean.
 return x2 * (float)square(stdev) * sqrtf((-2.0f * logf(w) ) / w) + mean; 
}

Here is the call graph for this function:

void G3D::Random::generate ( )

protectedvirtual

Generate the next N ints, and store them for readback later. Called from bits()

Generate the next N ints, and store them for readback later

 {
 // Lower R bits
 static const uint32 LOWER_MASK = (1LU << R) - 1;

 // Upper (32 - R) bits
 static const uint32 UPPER_MASK = 0xFFFFFFFF << R;
 static const uint32 mag01[2] = {0UL, (uint32)A};

 if (m_threadsafe) {
 bool contention = ! lock.lock();
 if (contention) {
 // Another thread just generated a set of numbers; no need for
 // this thread to do it too
 lock.unlock();
 return;
 }
 }

 // First N - M
 for (unsigned int i = 0; i < N - M; ++i) { 
 uint32 x = (state[i] & UPPER_MASK) | (state[i + 1] & LOWER_MASK);
 state[i] = state[i + M] ^ (x >> 1) ^ mag01[x & 1];
 }

 // Rest
 for (unsigned int i = N - M + 1; i < N - 1; ++i) { 
 uint32 x = (state[i] & UPPER_MASK) | (state[i + 1] & LOWER_MASK);
 state[i] = state[i + (M - N)] ^ (x >> 1) ^ mag01[x & 1];
 }
 
 uint32 y = (state[N - 1] & UPPER_MASK) | (state[0] & LOWER_MASK);
 state[N - 1] = state[M - 1] ^ (y >> 1) ^ mag01[y & 1];
 index = 0;

 if (m_threadsafe) {
 lock.unlock();
 }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Random::hemi ( float &  x, float &  y, float &  z  )

virtual

Returns 3D unit vectors uniformly distributed on the hemisphere about the z-axis.

 {
 sphere(x, y, z);
 z = fabsf(z);
}

Here is the call graph for this function:

int G3D::Random::integer ( int  min, int  max  )

virtual

Uniform random integer on the range [min, max]

 {
 debugAssert(high >= low);
 int r = iFloor(low + (high - low + 1) * (double)bits() / 0xFFFFFFFFUL);

 // There is a *very small* chance of generating
 // a number larger than high.
 if (r > high) {
 return high;
 } else {
 return r;
 }
}

Here is the call graph for this function:

Random& G3D::Random::operator= ( const Random &  )

inlineprivate

 {
 alwaysAssertM(false,
 "There is no copy constructor or assignment operator for Random because you "
 "probably didn't actually want to copy the state--it would "
 "be slow and duplicate the state of a pseudo-random sequence. Maybe you could "
 "provide arguments to a member variable in the constructor, "
 "or pass the Random by reference?");
 return *this;
 }

void G3D::Random::reset ( uint32  seed = 0xF018A4D2, bool  threadsafe = true  )

virtual

 {
 m_threadsafe = threadsafe;
 
 const uint32 X = 1812433253UL;

 state[0] = seed;
 for (index = 1; index < (int)N; ++index) {
 state[index] = X * (state[index - 1] ^ (state[index - 1] >> 30)) + index;
 }
}

Here is the caller graph for this function:

void G3D::Random::sphere ( float &  x, float &  y, float &  z  )

virtual

Returns 3D unit vectors uniformly distributed on the sphere

Reimplemented in G3D::PrecomputedRandom.

 {
 // Squared magnitude
 float m2;

 // Rejection sample
 do {
 x = uniform() * 2.0f - 1.0f, 
 y = uniform() * 2.0f - 1.0f,
 z = uniform() * 2.0f - 1.0f;
 m2 = x*x + y*y + z*z;
 } while (m2 >= 1.0f);

 // Divide by magnitude to produce a unit vector
 float s = rsqrt(m2);
 x *= s;
 y *= s;
 z *= s;
}

Here is the call graph for this function:

Here is the caller graph for this function:

virtual float G3D::Random::uniform ( float  low, float  high  )

inlinevirtual

Uniform random float on the range [min, max]

Reimplemented in G3D::PrecomputedRandom.

 {
 // We could compute the ratio in double precision here for
 // about 1.5x slower performance and slightly better
 // precision.
 return low + (high - low) * ((float)bits() / (float)0xFFFFFFFFUL);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

virtual float G3D::Random::uniform ( )

inlinevirtual

Uniform random float on the range [0, 1]

Reimplemented in G3D::PrecomputedRandom.

 {
 // We could compute the ratio in double precision here for
 // about 1.5x slower performance and slightly better
 // precision.
 const float norm = 1.0f / (float)0xFFFFFFFFUL;
 return (float)bits() * norm;
 }

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

int G3D::Random::index

protected

Index into state

Spinlock G3D::Random::lock

protected

Prevents multiple overlapping calls to generate().

bool G3D::Random::m_threadsafe

protected

uint32* G3D::Random::state

protected

State vector (these are the next N values that will be returned)

---

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

• dep/g3dlite/include/G3D/Random.h
• dep/g3dlite/source/Random.cpp