source/blender/blenlib/BLI_rand.h

   1 /*
   2  * ***** BEGIN GPL LICENSE BLOCK *****
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software Foundation,
  16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  17  *
  18  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
  19  * All rights reserved.
  20  *
  21  * The Original Code is: all of this file.
  22  *
  23  * Contributor(s): none yet.
  24  *
  25  * ***** END GPL LICENSE BLOCK *****
  26  */
  27
  28 #ifndef __BLI_RAND_H__
  29 #define __BLI_RAND_H__
  30
  31 /** \file BLI_rand.h
  32  *  \ingroup bli
  33  *  \brief Random number functions.
  34  */
  35
  36 /* RNG is an abstract random number generator type that avoids using globals.
  37  * Always use this instead of the global RNG unless you have a good reason,
  38  * the global RNG is not thread safe and will not give repeatable results.
  39  */
  40 struct RNG;
  41 typedef struct RNG RNG;
  42
  43 struct RNG_THREAD_ARRAY;
  44 typedef struct RNG_THREAD_ARRAY RNG_THREAD_ARRAY;
  45
  46 struct RNG *BLI_rng_new(unsigned int seed);
  47 struct RNG *BLI_rng_new_srandom(unsigned int seed);
  48 void        BLI_rng_free(struct RNG *rng) ATTR_NONNULL(1);
  49
  50 void        BLI_rng_seed(struct RNG *rng, unsigned int seed) ATTR_NONNULL(1);
  51 void        BLI_rng_srandom(struct RNG *rng, unsigned int seed) ATTR_NONNULL(1);
  52 void        BLI_rng_get_char_n(RNG *rng, char *bytes, size_t bytes_len) ATTR_NONNULL(1, 2);
  53 int         BLI_rng_get_int(struct RNG *rng) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
  54 unsigned int BLI_rng_get_uint(struct RNG *rng) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
  55 double      BLI_rng_get_double(struct RNG *rng) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
  56 float       BLI_rng_get_float(struct RNG *rng) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
  57 void        BLI_rng_get_float_unit_v2(struct RNG *rng, float v[2]) ATTR_NONNULL(1, 2);
  58 void        BLI_rng_get_float_unit_v3(struct RNG *rng, float v[3]) ATTR_NONNULL(1, 2);
  59 void        BLI_rng_get_tri_sample_float_v2(
  60         struct RNG *rng, const float v1[2], const float v2[2], const float v3[2],
  61         float r_pt[2]) ATTR_NONNULL();
  62 void        BLI_rng_shuffle_array(struct RNG *rng, void *data, unsigned int elem_size_i, unsigned int elem_tot) ATTR_NONNULL(1, 2);
  63
  64 /** Note that skipping is as slow as generating n numbers! */
  65 void        BLI_rng_skip(struct RNG *rng, int n) ATTR_NONNULL(1);
  66
  67 /** Return a pseudo-random number N where 0.0f<=N<1.0f */
  68 /* !!!!! NOTE: DO NOT USE IT IN NEW CODE !!!!! */
  69 float   BLI_frand(void) ATTR_WARN_UNUSED_RESULT;
  70
  71 /** Return a pseudo-random (hash) float from an integer value */
  72 float   BLI_hash_frand(unsigned int seed) ATTR_WARN_UNUSED_RESULT;
  73
  74 /** Shuffle an array randomly using the given seed.
  75  * contents. This routine does not use nor modify
  76  * the state of the BLI random number generator.
  77  */
  78 void    BLI_array_randomize(void *data, unsigned int elem_size, unsigned int elem_tot, unsigned int seed);
  79
  80
  81 /** Better seed for the random number generator, using noise.c hash[] */
  82 /** Allows up to BLENDER_MAX_THREADS threads to address */
  83 void    BLI_thread_srandom(int thread, unsigned int seed);
  84
  85 /** Return a pseudo-random number N where 0<=N<(2^31) */
  86 /** Allows up to BLENDER_MAX_THREADS threads to address */
  87 int     BLI_thread_rand(int thread) ATTR_WARN_UNUSED_RESULT;
  88
  89 /** Return a pseudo-random number N where 0.0f<=N<1.0f */
  90 /** Allows up to BLENDER_MAX_THREADS threads to address */
  91 float   BLI_thread_frand(int thread) ATTR_WARN_UNUSED_RESULT;
  92
  93 /** array versions for thread safe random generation */
  94 RNG_THREAD_ARRAY *BLI_rng_threaded_new(void);
  95 void  BLI_rng_threaded_free(struct RNG_THREAD_ARRAY *rngarr) ATTR_NONNULL(1);
  96 int   BLI_rng_thread_rand(RNG_THREAD_ARRAY *rngarr, int thread) ATTR_WARN_UNUSED_RESULT;
  97
  98 /** Low-discrepancy sequences **/
  99
 100 /** Return the _n_th number of the given low-discrepancy sequence. */
 101 void BLI_halton_1D(unsigned int prime, double offset, int n, double *r);
 102 void BLI_halton_2D(unsigned int prime[2], double offset[2], int n, double *r);
 103 void BLI_halton_3D(unsigned int prime[3], double offset[3], int n, double *r);
 104 void BLI_hammersley_1D(unsigned int n, double *r);
 105
 106 /** Return the whole low-discrepancy sequence up to _n_. */
 107 void BLI_halton_2D_sequence(unsigned int prime[2], double offset[2], int n, double *r);
 108 void BLI_hammersley_2D_sequence(unsigned int n, double *r);
 109
 110 #endif  /* __BLI_RAND_H__ */