random.h

Go to the documentation of this file.

/*********************************************************************
* lescegra                                                           *
*                                                                    *
* http://geeky.kicks-ass.org/projects/lescegra.html                  *
*                                                                    *
* Copyright 2003 by Enno Cramer <uebergeek@web.de>                   *
*                                                                    *
* This library is free software; you can redistribute it and/or      *
* modify it under the terms of the GNU Library General Public        *
* License as published by the Free Software Foundation; either       *
* version 2 of the License, or (at your option) any later version.   *
*                                                                    *
* This library is distributed in the hope that it will be useful,    *
* but WITHOUT ANY WARRANTY; without even the implied warranty of     *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU  *
* Library General Public License for more details.                   *
*                                                                    *
* You should have received a copy of the GNU Library General Public  *
* License along with this library; if not, write to the Free         *
* Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. *
*********************************************************************/

#ifndef LSG_RANDOM_H
#define LSG_RANDOM_H 1

/**
 * \file  random.h
 * \brief Pseudo random number generator
 */
 
#include <lescegra/util/object.h>

#define LSG_RANDOM_STATE_SIZE 624
 
/**
 * \ingroup util
 * \brief   Pseudo random number generator
 *
 * A pseudo random number generator utilizing the Mersenne Twister algorithm.
 * \see http://www.math.keio.ac.jp/~matumoto/emt.html
 */
typedef struct {
    LsgObject super;
    unsigned long int state[LSG_RANDOM_STATE_SIZE];
    int i;
} LsgRandom;

/**
 * \relates LsgRandom
 * Allocate and initialize a new LsgRandom instance with the given seed value.
 * @param seed      The seed value
 * @return a new LsgRandom instance
 */
LsgRandom* LsgRandom_create(unsigned long int seed);

/**
 * \relates LsgRandom
 * Initialize the instance with a given seed.
 * @param self      The instance variable
 * @param seed      The seed value
 */
void LsgRandom_init(LsgRandom* self, unsigned long int seed);

/**
 * \relates LsgRandom
 * Return a random \c unsigned \c long \c int between \c 0 and \c MAX_ULONG
 * inclusive.
 * @param self      The instance variable
 * @return a random value between \c 0 and \c MAX_ULONG
 */
unsigned long int LsgRandom_generate(LsgRandom* self);

/**
 * \relates LsgRandom
 * Return a random \c float between \c 0.0 and \c 1.0 inclusive.
 * @param self      The instance variable
 * @return a random value between \c 0.0 and \c 1.0
 */
float LsgRandom_random(LsgRandom* self);

/**
 * \relates LsgRandom
 * Return a random \c float between \c 0.0 and a given maximal value (inclusive).
 * @param self      The instance variable
 * @param self      The highest allowed return value
 * @return a random value between \c 0.0 and \a limit
 */
float LsgRandom_randomMax(LsgRandom* self, float limit);

/**
 * \relates LsgRandom
 * Return a random \c float between \c -1.0 and \c +1.0 inclusive.
 * @param self      The instance variable
 * @return a random value between \c -1.0 and \c +1.0
 */
float LsgRandom_randomError(LsgRandom* self);

/**
 * \relates LsgRandom
 * Return a random \c float from a given interval.
 * @param self      The instance variable
 * @param base      The center of the interval
 * @param error     The maximum distance between the return value and \a base
 * @return a random value from the interval [ \a base - \a error, \a base + \a error ]
 */
float LsgRandom_randomRange(LsgRandom* self, float base, float error);

/**
 * Seed the random number generator.
 * @param seed The new seed
 */
void random_seed(unsigned long int seed);

/**
 * Compute a pseudo random float between 0.0 and 1.0 exclusive.
 * @return A random float in the range [0.0, 1.0]
 */
float random(void);

/**
 * Compute a pseudo random number between 0.0 and a given maximum.
 * @param max   The upper limit for the generated random number
 * @return A random number in the range [0.0, max]
 */ 
float random_max(float max);

/**
 * Compute a pseudo random number between -1.0 and +1.0.
 * @param A random number in the range [-1.0, +1.0]
 */
float random_error(void);

/**
 * Compute a pseudo random number in a range defined by its center and extent.
 * @param base  The center of the range
 * @param error The extent of the range in each direction
 * @return A random number in the range [base - error, base + error]
 */
float random_range(float base, float error);

#endif

---

(c) 2003, by Enno Cramer
generated on 13 Jul 2003
lescegra - doxygen