BRL-CAD
rand.h
Go to the documentation of this file.
1 /* R A N D . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this file; see the file named COPYING for more
18  * information.
19  */
20 
21 /*----------------------------------------------------------------------*/
22 /* @file rand.h */
23 /** @addtogroup rnd */
24 /** @{ */
25 
26 /**
27  * @brief
28  * A supply of fast pseudo-random numbers from table in bn/rand.c.
29  * The values are in the open interval (i.e. exclusive) of 0.0 to 1.0
30  * range with a period of 4096.
31  *
32  * @par Usage:
33  @code
34  unsigned idx;
35  float f;
36 
37  BN_RANDSEED(idx, integer_seed);
38 
39  while (NEED_MORE_RAND_NUMBERS) {
40  f = BN_RANDOM(idx);
41  }
42  @endcode
43  *
44  * Note that the values from bn_rand_half() become all 0.0 when the
45  * benchmark flag is set (bn_rand_halftab is set to all 0's). The
46  * numbers from bn_rand_table do not change, because the procedural
47  * noise would cease to exist.
48  */
49 
50 #ifndef BN_RAND_H
51 #define BN_RAND_H
52 
53 #include "common.h"
54 #include "bn/defines.h"
55 
57 
58 #define BN_RAND_TABSIZE 4096
59 #define BN_RAND_TABMASK 0xfff
60 #define BN_RANDSEED(_i, _seed) _i = ((unsigned)_seed) % BN_RAND_TABSIZE
61 
62 /**
63  * This is our table of random numbers. Rather than calling drand48()
64  * or random() or rand() we just pick numbers out of this table. This
65  * table has 4096 unique entries with floating point values ranging
66  * from the open interval (i.e. exclusive) 0.0 to 1.0 range.
67  *
68  * There are convenience macros for access in the bn.h header.
69  */
70 BN_EXPORT extern const float bn_rand_table[BN_RAND_TABSIZE];
71 
72 /** BN_RANDOM always gives numbers between the open interval 0.0 to 1.0 */
73 #define BN_RANDOM(_i) bn_rand_table[ _i = (_i+1) % BN_RAND_TABSIZE ]
74 
75 /** BN_RANDHALF always gives numbers between the open interval -0.5 and 0.5 */
76 #define BN_RANDHALF(_i) (bn_rand_table[ _i = (_i+1) % BN_RAND_TABSIZE ]-0.5)
77 #define BN_RANDHALF_INIT(_p) _p = bn_rand_table
78 
79 #define BN_RANDHALFTABSIZE 16535 /* Powers of two give streaking */
80 BN_EXPORT extern int bn_randhalftabsize;
81 
82 /**
83  * The actual table of random floating point numbers with values in
84  * the closed interval (i.e. inclusive) -0.5 to +0.5 range.
85  *
86  * For benchmarking purposes, this table is zeroed.
87  */
88 BN_EXPORT extern float bn_rand_halftab[BN_RANDHALFTABSIZE];
89 
90 /**
91  * random numbers between the closed interval -0.5 to 0.5 inclusive,
92  * except when benchmark flag is set, when this becomes a constant 0.0
93  *
94  * @param _p float pointer type initialized by bn_rand_init()
95  *
96  */
97 #define bn_rand_half(_p) \
98  ((++(_p) >= &bn_rand_halftab[bn_randhalftabsize] || \
99  (_p) < bn_rand_halftab) ? \
100  *((_p) = bn_rand_halftab) : *(_p))
101 
102 /**
103  * initialize the seed for the large random number table (halftab)
104  *
105  * @param _p float pointer to be initialized, used for bn_rand0to1()
106  * and bn_rand_half()
107  * @param _seed Integer SEED for offset in the table.
108  *
109  */
110 #define bn_rand_init(_p, _seed) \
111  (_p) = &bn_rand_halftab[ \
112  (int)(\
113  (bn_rand_halftab[(_seed)%bn_randhalftabsize] + 0.5) * \
114  (bn_randhalftabsize-1)) ]
115 
116 /**
117  * random numbers in the closed interval 0.0 to 1.0 range (inclusive)
118  * except when benchmarking, when this is always 0.5
119  *
120  * @param _q float pointer type initialized by bn_rand_init()
121  *
122  */
123 #define bn_rand0to1(_q) (bn_rand_half(_q)+0.5)
124 
125 #define BN_SINTABSIZE 2048
126 
127 #define bn_tab_sin(_a) (((_a) > 0) ? \
128  (bn_sin_table[(int)((0.5+ (_a)*(BN_SINTABSIZE / M_2PI)))&(BN_SINTABSIZE-1)]) :\
129  (-bn_sin_table[(int)((0.5- (_a)*(BN_SINTABSIZE / M_2PI)))&(BN_SINTABSIZE-1)]))
130 
131 /**
132  * table of floating point sine values in the closed (i.e. inclusive)
133  * interval -1.0 to 1.0 range.
134  */
135 BN_EXPORT extern const float bn_sin_table[BN_SINTABSIZE];
136 
137 /**
138  *@brief
139  * For benchmarking purposes, make the random number table predictable.
140  * Setting to all zeros keeps dithered values at their original values.
141  */
142 BN_EXPORT extern void bn_mathtab_constant(void);
143 
145 
146 #endif /* BN_RAND_H */
147 /** @} */
148 /*
149  * Local Variables:
150  * mode: C
151  * tab-width: 8
152  * indent-tabs-mode: t
153  * c-file-style: "stroustrup"
154  * End:
155  * ex: shiftwidth=4 tabstop=8
156  */
void bn_mathtab_constant(void)
For benchmarking purposes, make the random number table predictable. Setting to all zeros keeps dithe...
Definition: rand.c:3619
#define BN_SINTABSIZE
Definition: rand.h:125
Header file for the BRL-CAD common definitions.
#define BN_RANDHALFTABSIZE
Definition: rand.h:79
const float bn_sin_table[BN_SINTABSIZE]
Definition: rand.c:723
#define __BEGIN_DECLS
Definition: common.h:73
#define BN_RAND_TABSIZE
A supply of fast pseudo-random numbers from table in bn/rand.c. The values are in the open interval (...
Definition: rand.h:58
float bn_rand_halftab[BN_RANDHALFTABSIZE]
Definition: rand.c:1240
#define __END_DECLS
Definition: common.h:74
const float bn_rand_table[BN_RAND_TABSIZE]
Definition: rand.c:36
int bn_randhalftabsize
Definition: rand.c:1238