Noise Functions

The functions in this group provide pseudo-random numbers, quasi-Monte Carlo numbers (using low-discrepancy sequences that converge faster than pseudo-random numbers), and deterministic Perlin noise.

mi_random

miScalar mi_random(void)

Return a random number in the range [0, 1). This is similar to drand48 in the standard Unix libraries, but it is available on all platforms including Windows NT, which does not support drand48.

mi_srandom

void mi_srandom(
    long            seed)

Begin a new random number sequence for mi_random. This is equivalent to the standard Unix library function srand48.

mi_erandom

miScalar mi_erandom(
    unsigned short  seed[3])

Return a random number in the range [0, 1), based on the given seed. This allows shaders to create private random number generators by initializing a private seed array to some arbitrary but constant values, and passing it to mi_erandom without the chance of other functions or threads disturbing the sequence by "stealing" random numbers (assuming they do not have access to the private seed). This is equivalent to the standard Unix library function erand48.

mi_par_random

miScalar mi_par_random(
    miState         *state)

Return a parallel-safe random number in the range [0, 1). Parallel-safe random numbers can be used in parallel rendering to produce consistent results that do not change when the number of machines or threads changes, or when the execution order changes. All shaders that use this function share the same internal seed value. This function should not be used in geometry shaders, displacement shaders, photon shaders, output shaders, or _init functions of shaders because the initial seed of the random number sequence is undefined in these cases.

mi_spline

miScalar mi_spline(
    miScalar         t,
    const int        n,
    miScalar * const ctl)

This function calculates a one-dimensional cardinal spline at location t. The t parameter must be in the range 0…1. The spline is defined by n control points specified in the array ctl. There must be at least two control points. To calculate multi-dimensional splines, this function must be called once for each dimension. For example, spline can be used three times to interpolate colors smoothly.

mi_noise_1d

miScalar mi_noise_1d(
    const miScalar   p)

Return a one-dimensional coherent noise function of p. All six noise functions compute a modified Perlin noise function from the given one, two, or three dimension parameters such that the noise changes gradually with changing parameters. The modification of the classical algorithm avoids large-scale periodical behavior at lattice points, such that the noise is smooth on all levels. (This makes the algorithm perform slower than classical Perlin noise.) The returned values are in the range 0…1, with a bell-shaped distribution centered at 0.5 and falling off to both sides. This means that 0.5 is returned most often, and values of less than 0.0 and more than 1.0 are never returned. See Perlin85.

mi_noise_2d

miScalar mi_noise_2d(
    const miScalar   u,
    const miScalar   v)

Return a two-dimensional noise function of u, v.

mi_noise_3d

miScalar mi_noise_3d(
    miVector * const p)

Return a three-dimensional noise function of the vector p. This is probably the most useful noise function; a simple procedural texture shader can be written that converts a copy of the state→point vector to object space, passes it to mi_noise_3d, and assigns the returned value to the red, green, and blue components of the result color. The average feature size of the texture will be approximately one unit in space.

mi_noise_1d_grad

miScalar mi_noise_1d_grad(
    const miScalar   p,
    miScalar * const g)

Return a one-dimensional noise function of p. The gradient of the computed texture at the location p is assigned to * g. Gradients are not normalized.

mi_noise_2d_grad

miScalar mi_noise_2d_grad(
    const miScalar   u,
    const miScalar   v,
    miScalar * const gu,
    miScalar * const gv)

Return a two-dimensional noise function of u, v. The gradient is assigned to * gu and * gv.

mi_noise_3d_grad

miScalar mi_noise_3d_grad(
    miVector * const p,
    miVector * const g)

Return a three-dimensional noise function of the vector p. The gradient is assigned to the vector g.

mi_unoise_1d
mi_unoise_2d
mi_unoise_3d
mi_unoise_1d_grad
mi_unoise_2d_grad
mi_unoise_3d_grad

miScalar mi_unoise_1d()
miScalar mi_unoise_2d()
miScalar mi_unoise_3d()
miScalar mi_unoise_1d_grad()
miScalar mi_unoise_2d_grad()
miScalar mi_unoise_3d_grad()

These functions are similar to the regular noise functions, except that the returned distribution is uniform. All returned values are roughly equally likely.