TombsOfHarc/include/noise.hpp

/*
* libtcod 1.6.0
* Copyright (c) 2008,2009,2010,2012,2013 Jice & Mingos
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*     * Redistributions of source code must retain the above copyright
*       notice, this list of conditions and the following disclaimer.
*     * Redistributions in binary form must reproduce the above copyright
*       notice, this list of conditions and the following disclaimer in the
*       documentation and/or other materials provided with the distribution.
*     * The name of Jice or Mingos may not be used to endorse or promote products
*       derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY JICE AND MINGOS ``AS IS'' AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL JICE OR MINGOS BE LIABLE FOR ANY
* DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

#ifndef _TCOD_PERLIN_HPP
#define _TCOD_PERLIN_HPP

#include "noise_defaults.h"

/**
 @PageName noise
 @PageCategory Base toolkits
 @PageTitle Noise generator
 @PageDesc This toolkit provides several functions to generate Perlin noise and other derived noises. It can handle noise functions from 1 to 4 dimensions.
 @FuncDesc
	Usage example:
	1D noise : the variation of a torch intensity
	2D fbm : heightfield generation or clouds
	3D fbm : animated smoke
	If you don't know what is Perlin noise and derived functions, or what is the influence of the different fractal parameters, check the Perlin noise sample included with the library.
	<table width="800px" class="none">
		<tr><td align="center">Simplex noise, fbm, turbulence</td>
		<td align="center"><img border="1" src="simplex.png"></td>
		<td align="center"><img border="1" src="fbm_simplex.png"></td>
		<td align="center"><img border="1" src="turbulence_simplex.png"></td></tr>
		<tr><td align="center">Perlin noise, fbm, turbulence</td>
		<td align="center"><img border="1" src="perlin.png"></td>
		<td align="center"><img border="1" src="fbm_perlin.png"></td>
		<td align="center"><img border="1" src="turbulence_perlin.png"></td></tr>
		<tr><td align="center">Wavelet noise, fbm, turbulence</td>
		<td align="center"><img border="1" src="wavelet.png"></td>
		<td align="center"><img border="1" src="fbm_wavelet.png"></td>
		<td align="center"><img border="1" src="turbulence_wavelet.png"></td></tr>
	</table>
	<h6>Noise functions relative times</h6>

	For example, in 4D, Perlin noise is 17 times slower than simplex noise.
	<table border="1">
		<tr><td></td><td>1D</td><td>2D</td><td>3D</td><td>4D</td></tr>
		<tr><td>simplex</td><td>1</td><td>1</td><td>1</td><td>1</td></tr>
		<tr><td>Perlin</td><td>1.3</td><td>4</td><td>5</td><td>17</td></tr>
		<tr><td>wavelet</td><td>53</td><td>32</td><td>14</td><td>X</td></tr>
	</table>
 */
class TCODLIB_API TCODNoise {
	public :
		/**
		@PageName noise_init
		@PageFather noise
		@PageTitle Creating a noise generator
		@FuncDesc Those functions initialize a noise generator from a number of dimensions (from 1 to 4), some fractal parameters and a random number generator.
			The C++ version provides several constructors. When the hurst and lacunarity parameters are omitted, default values (TCOD_NOISE_DEFAULT_HURST = 0.5f and TCOD_NOISE_DEFAULT_LACUNARITY = 2.0f) are used.
		@Cpp
			TCODNoise::TCODNoise(int dimensions, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
			TCODNoise::TCODNoise(int dimensions, TCODRandom *random, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
			TCODNoise::TCODNoise(int dimensions, float hurst, float lacunarity, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
			TCODNoise::TCODNoise(int dimensions, float hurst, float lacunarity, TCODRandom *random, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
		@C TCOD_noise_t TCOD_noise_new(int dimensions, float hurst, float lacunarity, TCOD_random_t random)
		@Py noise_new(dimensions, hurst=TCOD_NOISE_DEFAULT_HURST, lacunarity=TCOD_NOISE_DEFAULT_LACUNARITY, random=0)
		@C#
			TCODNoise::TCODNoise(int dimensions)
			TCODNoise::TCODNoise(int dimensions, TCODRandom random)
			TCODNoise::TCODNoise(int dimensions, float hurst, float lacunarity)
			TCODNoise::TCODNoise(int dimensions, float hurst, float lacunarity, TCODRandom random)
		@Param dimensions	From 1 to 4.
		@Param hurst	For fractional brownian motion and turbulence, the fractal Hurst exponent. You can use the default value TCOD_NOISE_DEFAULT_HURST = 0.5f.
		@Param lacunarity	For fractional brownian motion and turbulence, the fractal lacunarity. You can use the default value TCOD_NOISE_DEFAULT_LACUNARITY = 2.0f.
		@Param random	A random number generator obtained with the Mersenne twister toolkit or NULL to use the default random number generator.
		@CppEx
			// 1 dimension generator
			TCODNoise * noise1d = new TCODNoise(1);
			// 2D noise with a predefined random number generator
			TCODRandom *myRandom = new TCODRandom();
			TCODNoise *noise2d = new TCODNoise(2,myRandom);
			// a 3D noise generator with a specific fractal parameters
			TCODNoise *noise3d = new TCODNoise(3,0.7f,1.4f);
		@CEx
			// 1 dimension generator
			TCOD_noise_t noise1d = TCOD_noise_new(1,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL);
			// 2D noise with a predefined random number generator
			TCOD_random_t my_random = TCOD_random_new();
			TCOD_noise_t noise2d = TCOD_noise_new(2,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,my_random);
			// a 3D noise generator with a specific fractal parameters
			TCOD_noise_t noise3d = TCOD_noise_new(3,0.7f, 1.4f,NULL);
		@PyEx
			# 1 dimension generator
			noise1d = libtcod.noise_new(1)
			# 2D noise with a predefined random number generator
			my_random = libtcod.random_new();
			noise2d = libtcod.noise_new(2,libtcod.NOISE_DEFAULT_HURST, libtcod.NOISE_DEFAULT_LACUNARITY,my_random)
			# a 3D noise generator with a specific fractal parameters
			noise3d = libtcod.noise_new(3, 0.7, 1.4)
		*/
		TCODNoise(int dimensions, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT);
		TCODNoise(int dimensions, TCODRandom *random, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT);
		TCODNoise(int dimensions, float hurst, float lacunarity, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT);
		TCODNoise(int dimensions, float hurst, float lacunarity, TCODRandom *random, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT);

		/**
		@PageName noise_init
		@FuncDesc To release ressources used by a generator, use those functions :
		@Cpp TCODNoise::~TCODNoise()
		@C void TCOD_noise_delete(TCOD_noise_t noise)
		@Py noise_delete(noise)
		@C# void TCODNoise::Dispose()
		@Param noise	In the C and python versions, the generator handler, returned by the initialization function.
		@CppEx
			// create a generator
			TCODNoise *noise = new TCODNoise(2);
			// use it
			...
			// destroy it
			delete noise;
		@CEx
			// create a generator
			TCOD_noise_t noise = TCOD_noise_new(2,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAUT_LACUNARITY, NULL);
			// use it
			...
			// destroy it
			TCOD_noise_delete(noise);
		@PyEx
			# create a generator
			noise = libtcod.noise_new(2,litbcod.NOISE_DEFAULT_HURST, litbcod.NOISE_DEFAUT_LACUNARITY, 0)
			# use it
			...
			# destroy it
			litbcod.noise_delete(noise)
		*/
		virtual ~TCODNoise();

   		/**
   		@PageName noise_setType
		@PageFather noise
		@PageTitle Choosing a noise type
		@FuncTitle Choosing a noise type
		@FuncDesc Use this function to define the default algorithm used by the noise functions. 
			The default algorithm is simplex. It's much faster than Perlin, especially in 4 dimensions. It has a better contrast too.
		@Cpp void TCODNoise::setType(TCOD_noise_type_t type)
		@C void TCOD_noise_set_type(TCOD_noise_t noise, TCOD_noise_type_t type)
		@Py noise_set_type(noise, type)
		@C# void TCODNoise::setType(type)
		@Param noise	In the C version, the generator handler, returned by the initialization function.
		@Param type		The algorithm to use, either TCOD_NOISE_SIMPLEX, TCOD_NOISE_PERLIN or TCOD_NOISE_WAVELET.
		@CppEx
			TCODNoise * noise1d = new TCODNoise(1);
			noise1d->setType(TCOD_NOISE_PERLIN);
		@CEx
			TCOD_noise_t noise1d = TCOD_noise_new(1,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL);
			TCOD_noise_set_type(noise1d,TCOD_NOISE_PERLIN);
		@PyEx
			noise1d = libtcod.noise_new(1)
			libtcod.noise_set_type(noise1d,libtcod.NOISE_PERLIN)
   		*/
		void setType (TCOD_noise_type_t type);
   		/**
   		@PageName noise_get
		@PageFather noise
		@PageTitle Getting flat noise
		@FuncDesc This function returns the noise function value between -1.0 and 1.0 at given coordinates.
		@Cpp float TCODNoise::get(float *f, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
		@C	float TCOD_noise_get(TCOD_noise_t noise, float *f)
float TCOD_noise_get_ex(TCOD_noise_t noise, float *f, TCOD_noise_type_t type)
		@Py noise_get(noise, f, type=NOISE_DEFAULT)
		@C# float TCODNoise::get(float[] f, type=NoiseDefault)
		@Param noise	In the C version, the generator handler, returned by the initialization function.
		@Param f	An array of coordinates, depending on the generator dimensions (between 1 and 4). The same array of coordinates will always return the same value.
		@Param type	The algorithm to use. If not defined, use the default one (set with setType or simplex if not set) 
		@CppEx
			// 1d noise
			TCODNoise * noise1d = new TCODNoise(1);
			float p=0.5f;
			// get a 1d simplex value
			float value = noise1d->get(&p);
			// 2d noise
			TCODNoise * noise2d = new TCODNoise(2);
			float p[2]={0.5f,0.7f};
			// get a 2D Perlin value
			float value = noise2d->get(p, TCOD_NOISE_PERLIN);
		@CEx
			// 1d noise
			TCOD_noise_t noise1d = TCOD_noise_new(1,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL);
			float p=0.5f;
			// get a 1d simplex value
			float value = TCOD_noise_get(noise1d,&p);
			// 2d noise
			TCOD_noise_t noise2d = TCOD_noise_new(2,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL);
			float p[2]={0.5f,0.7f};
			// get a 2d perlin value
			float value = TCOD_noise_get_ex(noise2d,p,TCOD_NOISE_PERLIN);
		@PyEx
			# 1d noise
			noise1d = libtcod.noise_new(1)
			# get a 1d simplex value
			value = libtcod.noise_get(noise1d,[0.5])
			# 2d noise
			noise2d = libtcod.noise_new(2)
			# get a 2d perlin value
			value = libtcod.noise_get(noise2d,[0.5,0.7], libtcod.NOISE_PERLIN)
   		*/
		float get(float *f, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT);
		/**
		@PageName noise_get_fbm
		@PageFather noise
		@PageTitle Getting fbm noise
		@FuncDesc This function returns the fbm function value between -1.0 and 1.0 at given coordinates, using fractal hurst and lacunarity defined when the generator has been created.
		@Cpp float TCODNoise::getFbm(float *f, float octaves, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
		@C	float TCOD_noise_get_fbm(TCOD_noise_t noise, float *f, float octaves)
float TCOD_noise_get_fbm(TCOD_noise_t noise, float *f, float octaves, TCOD_noise_type_t type)
		@Py noise_get_fbm(noise, f, octaves, type=NOISE_DEFAULT)
		@C# float TCODNoise::getBrownianMotion(float[] f, float octaves, type=NoiseDefault)
		@Param noise	In the C version, the generator handler, returned by the initialization function.
		@Param f	An array of coordinates, depending on the generator dimensions (between 1 and 4). The same array of coordinates will always return the same value.
		@Param octaves	Number of iterations. Must be < TCOD_NOISE_MAX_OCTAVES = 128
		@Param type	The algorithm to use. If not defined, use the default one (set with setType or simplex if not set) 
		@CppEx
			// 1d fbm
			TCODNoise * noise1d = new TCODNoise(1);
			float p=0.5f;
			// get a 1d simplex fbm
			float value = noise1d->getFbm(&p,32.0f);
			// 2d fbm
			TCODNoise * noise2d = new TCODNoise(2);
			float p[2]={0.5f,0.7f};
			// get a 2d perlin fbm
			float value = noise2d->getFbm(p,32.0f, TCOD_NOISE_PERLIN);
		@CEx
			// 1d fbm
			TCOD_noise_t noise1d = TCOD_noise_new(1,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL);
			float p=0.5f;
			// get a 1d simplex fbm
			float value = TCOD_noise_get_fbm(noise1d,&p,32.0f);
			// 2d fbm
			TCOD_noise_t noise2d = TCOD_noise_new(2,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL);
			float p[2]={0.5f,0.7f};
			// get a 2d perlin fbm
			float value = TCOD_noise_get_fbm_ex(noise2d,p,32.0f,TCOD_NOISE_PERLIN);
		@PyEx
			# 1d noise
			noise1d = libtcod.noise_new(1)
			# 1d simplex fbm
			value = libtcod.noise_get_fbm(noise1d,[0.5],32.0)
			# 2d noise
			noise2d = libtcod.noise_new(2)
			# 2d perlin fbm
			value = libtcod.noise_get_fbm(noise2d,[0.5,0.7],32.0, libtcod.NOISE_PERLIN)
		*/
		float getFbm(float *f, float octaves, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT);
		/**
		@PageName noise_get_turbulence
		@PageFather noise
		@PageTitle Getting turbulence
		@FuncDesc This function returns the turbulence function value between -1.0 and 1.0 at given coordinates, using fractal hurst and lacunarity defined when the generator has been created.
		@Cpp float TCODNoise::getTurbulence(float *f, float octaves, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT)
		@C	float TCOD_noise_get_turbulence(TCOD_noise_t noise, float *f, float octaves)
float TCOD_noise_get_turbulence_ex(TCOD_noise_t noise, float *f, float octaves, TCOD_noise_type_t)
		@Py noise_get_turbulence(noise, f, octaves, type=NOISE_DEFAULT)
		@C# float TCODNoise::getTurbulence(float[] f, float octaves, type=NoiseDefault)
		@Param noise	In the C version, the generator handler, returned by the initialization function.
		@Param f	An array of coordinates, depending on the generator dimensions (between 1 and 4). The same array of coordinates will always return the same value.
		@Param octaves	Number of iterations. Must be < TCOD_NOISE_MAX_OCTAVES = 128
		@CppEx
			// 1d fbm
			TCODNoise * noise1d = new TCODNoise(1);
			float p=0.5f;
			// a 1d simplex turbulence
			float value = noise1d->getTurbulence(&p,32.0f);
			// 2d fbm
			TCODNoise * noise2d = new TCODNoise(2);
			float p[2]={0.5f,0.7f};
			// a 2d perlin turbulence
			float value = noise2d->getTurbulence(p,32.0f, TCOD_NOISE_PERLIN);
		@CEx
			// 1d fbm
			TCOD_noise_t noise1d = TCOD_noise_new(1,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL);
			float p=0.5f;
			// a 1d simplex turbulence
			float value = TCOD_noise_get_turbulence(noise1d,&p,32.0f);
			// 2d fbm
			TCOD_noise_t noise2d = TCOD_noise_new(2,TCOD_NOISE_DEFAULT_HURST, TCOD_NOISE_DEFAULT_LACUNARITY,NULL);
			float p[2]={0.5f,0.7f};
			// a 2d perlin turbulence
			float value = TCOD_noise_get_turbulence_ex(noise2d,p,32.0f, TCOD_NOISE_PERLIN);
		@PyEx
			# 1d noise
			noise1d = libtcod.noise_new(1)
			# 1d simplex turbulence
			value = libtcod.noise_get_turbulence(noise1d,[0.5],32.0)
			# 2d noise
			noise2d = libtcod.noise_new(2)
			# 2d perlin turbulence
			value = libtcod.noise_get_turbulence(noise2d,[0.5,0.7],32.0,libtcod.NOISE_PERLIN)
		*/
		float getTurbulence(float *f, float octaves, TCOD_noise_type_t type = TCOD_NOISE_DEFAULT);

	protected :
		friend class TCODLIB_API TCODHeightMap;
		TCOD_noise_t data;
};

#endif