1

/* $Id$ */

     2

     3

/** @file random_func.h */

     4

     5

#ifndef RANDOM_FUNC_HPP

     6

#define RANDOM_FUNC_HPP

     7

    13

/**************

    14

 * Warning: DO NOT enable this unless you understand what it does

    15

 *

    16

 * If enabled, in a network game all randoms will be dumped to the

    17

 *  stdout if the first client joins (or if you are a client). This

    18

 *  is to help finding desync problems.

    19

 *

    20

 * Warning: DO NOT enable this unless you understand what it does

    21

 **************/

    22

    23

//#define RANDOM_DEBUG

    24

    25

    26

// Enable this to produce higher quality random numbers.

    27

// Doesn't work with network yet.

    28

// #define MERSENNE_TWISTER

    29

    30

void SetRandomSeed(uint32 seed);

    31

#ifdef RANDOM_DEBUG

    32

	#define Random() DoRandom(__LINE__, __FILE__)

    33

	uint32 DoRandom(int line, const char *file);

    34

	#define RandomRange(max) DoRandomRange(max, __LINE__, __FILE__)

    35

	uint DoRandomRange(uint max, int line, const char *file);

    36

#else

    37

	uint32 Random();

    38

	uint RandomRange(uint max);

    39

#endif

    40

    41

uint32 InteractiveRandom(); // Used for random sequences that are not the same on the other end of the multiplayer link

    42

uint InteractiveRandomRange(uint max);

    43

    44

/**

    45

 * Checks if a given randomize-number is below a given probability.

    46

 *

    47

 * This function is used to check if the given probability by the fraction of (a/b)

    48

 * is greater than low 16 bits of the given randomize-number v.

    49

 *

    50

 * Do not use this function twice on the same random 16 bits as it will yield

    51

 * the same result. One can use a random number for two calls to Chance16I,

    52

 * where one call sends the low 16 bits and the other the high 16 bits.

    53

 *

    54

 * @param a The numerator of the fraction

    55

 * @param b The denominator of the fraction, must of course not be null

    56

 * @param r The given randomize-number

    57

 * @return True if v is less or equals (a/b)

    58

 */

    59

static inline bool Chance16I(const uint a, const uint b, const uint32 r)

    60

{

    61

	assert(b != 0);

    62

	return (uint16)r < (uint16)((a << 16) / b);

    63

}

    64

    65

/**

    66

 * Flips a coin with a given probability.

    67

 *

    68

 * This macro can be used to get true or false randomized according to a

    69

 * given probability. The parameter a and b create a percent value with

    70

 * (a/b). The macro returns true in (a/b) percent.

    71

 *

    72

 * @see Chance16I()

    73

 * @param a The numerator of the fraction

    74

 * @param b The denominator of the fraction

    75

 * @return True in (a/b) percent

    76

 */

    77

static inline bool Chance16(const uint a, const uint b)

    78

{

    79

	return Chance16I(a, b, Random());

    80

}

    81

    82

/**

    83

 * Flips a coin with a given probability and saves the randomize-number in a variable.

    84

 *

    85

 * This function uses the same parameters as Chance16. The third parameter

    86

 * must be a variable the randomize-number from Random() is saved in.

    87

 *

    88

 * The low 16 bits of r will already be used and can therefor not be passed to

    89

 * Chance16I. One can only send the high 16 bits to Chance16I.

    90

 *

    91

 * @see Chance16I()

    92

 * @param a The numerator of the fraction

    93

 * @param b The denominator of the fraction

    94

 * @param r The variable to save the randomize-number from Random()

    95

 * @return True in (a/b) percent

    96

 */

    97

static inline bool Chance16R(const uint a, const uint b, uint32 &r)

    98

{

    99

	r = Random();

   100

	return Chance16I(a, b, r);

   101

}

   102

   103

#endif /* RANDOM_FUNC_HPP */