CS::Math::Noise::Module::Perlin Class Reference (Crystal Space 2.0 Public API Reference)

| ## Public API Reference

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Protected Attributes
CS::Math::Noise::Module::Perlin Class Reference
Generator Modules

Noise module that outputs 3-dimensional Perlin noise. More...

`#include <cstool/noise/module/perlin.h>`

Inheritance diagram for CS::Math::Noise::Module::Perlin:

List of all members.

## Public Member Functions
double | GetFrequency () const
| Returns the frequency of the first octave.
double | GetLacunarity () const
| Returns the lacunarity of the Perlin noise.
CS::Math::Noise::NoiseQuality | GetNoiseQuality () const
| Returns the quality of the Perlin noise.
int | GetOctaveCount () const
| Returns the number of octaves that generate the Perlin noise.
double | GetPersistence () const
| Returns the persistence value of the Perlin noise.
int | GetSeed () const
| Returns the seed value used by the Perlin-noise function.
virtual int | GetSourceModuleCount () const
| Returns the number of source modules required by this noise module.
virtual double | GetValue (double x, double y, double z) const
| Generates an output value given the coordinates of the specified input value.
| Perlin ()
| Constructor.
void | SetFrequency (double frequency)
| Sets the frequency of the first octave.
void | SetLacunarity (double lacunarity)
| Sets the lacunarity of the Perlin noise.
void | SetNoiseQuality (CS::Math::Noise::NoiseQuality noiseQuality)
| Sets the quality of the Perlin noise.
void | SetOctaveCount (int octaveCount)
| Sets the number of octaves that generate the Perlin noise.
void | SetPersistence (double persistence)
| Sets the persistence value of the Perlin noise.
void | SetSeed (int seed)
| Sets the seed value used by the Perlin-noise function.
## Protected Attributes
double | m_frequency
| Frequency of the first octave.
double | m_lacunarity
| Frequency multiplier between successive octaves.
CS::Math::Noise::NoiseQuality | m_noiseQuality
| Quality of the Perlin noise.
int | m_octaveCount
| Total number of octaves that generate the Perlin noise.
double | m_persistence
| Persistence of the Perlin noise.
int | m_seed
| Seed value used by the Perlin-noise function.

## Detailed Description

Noise module that outputs 3-dimensional Perlin noise.

Perlin noise is the sum of several coherent-noise functions of ever-increasing frequencies and ever-decreasing amplitudes.

An important property of Perlin noise is that a small change in the input value will produce a small change in the output value, while a large change in the input value will produce a random change in the output value.

This noise module outputs Perlin-noise values that usually range from -1.0 to +1.0, but there are no guarantees that all output values will exist within that range.

For a better description of Perlin noise, see the links in the References and Acknowledgments section.

This noise module does not require any source modules.

Octaves

The number of octaves control the amount of detail of the Perlin noise. Adding more octaves increases the detail of the Perlin noise, but with the drawback of increasing the calculation time.

An octave is one of the coherent-noise functions in a series of coherent-noise functions that are added together to form Perlin noise.

An application may specify the frequency of the first octave by calling the SetFrequency() method.

An application may specify the number of octaves that generate Perlin noise by calling the SetOctaveCount() method.

These coherent-noise functions are called octaves because each octave has, by default, double the frequency of the previous octave. Musical tones have this property as well; a musical C tone that is one octave higher than the previous C tone has double its frequency.

Frequency

An application may specify the frequency of the first octave by calling the SetFrequency() method.

Persistence

The persistence value controls the roughness of the Perlin noise. Larger values produce rougher noise.

The persistence value determines how quickly the amplitudes diminish for successive octaves. The amplitude of the first octave is 1.0. The amplitude of each subsequent octave is equal to the product of the previous octave's amplitude and the persistence value. So a persistence value of 0.5 sets the amplitude of the first octave to 1.0; the second, 0.5; the third, 0.25; etc.

An application may specify the persistence value by calling the SetPersistence() method.

Lacunarity

The lacunarity specifies the frequency multipler between successive octaves.

The effect of modifying the lacunarity is subtle; you may need to play with the lacunarity value to determine the effects. For best results, set the lacunarity to a number between 1.5 and 3.5.

References & acknowledgments

The Noise Machine - From the master, Ken Perlin himself. This page contains a presentation that describes Perlin noise and some of its variants. He won an Oscar for creating the Perlin noise algorithm!

Perlin Noise - Hugo Elias's webpage contains a very good description of Perlin noise and describes its many applications. This page gave me the inspiration to create libnoise in the first place. Now that I know how to generate Perlin noise, I will never again use cheesy subdivision algorithms to create terrain (unless I absolutely need the speed.)

The Perlin noise math FAQ - A good page that describes Perlin noise in plain English with only a minor amount of math. During development of libnoise, I noticed that my coherent-noise function generated terrain with some "regularity" to the terrain features. This page describes a better coherent-noise function called gradient noise. This version of CS::Math::Noise::Module::Perlin uses gradient coherent noise to generate Perlin noise.

Definition at line 159 of file perlin.h.

## Constructor & Destructor Documentation

CS::Math::Noise::Module::Perlin::Perlin | ( |  | ) |

Constructor.

The default frequency is set to CS::Math::Noise::Module::DEFAULT_PERLIN_FREQUENCY.

The default lacunarity is set to CS::Math::Noise::Module::DEFAULT_PERLIN_LACUNARITY.

The default number of octaves is set to CS::Math::Noise::Module::DEFAULT_PERLIN_OCTAVE_COUNT.

The default persistence value is set to CS::Math::Noise::Module::DEFAULT_PERLIN_PERSISTENCE.

The default seed value is set to CS::Math::Noise::Module::DEFAULT_PERLIN_SEED.

## Member Function Documentation

double CS::Math::Noise::Module::Perlin::GetFrequency | ( |  | ) | const`[inline]`

Returns the frequency of the first octave.

Returns:
  The frequency of the first octave.

Definition at line 185 of file perlin.h.

double CS::Math::Noise::Module::Perlin::GetLacunarity | ( |  | ) | const`[inline]`

Returns the lacunarity of the Perlin noise.

Returns:
  The lacunarity of the Perlin noise.

The lacunarity is the frequency multiplier between successive octaves.

Definition at line 196 of file perlin.h.

CS::Math::Noise::NoiseQuality CS::Math::Noise::Module::Perlin::GetNoiseQuality | ( |  | ) | const`[inline]`

Returns the quality of the Perlin noise.

Returns:
  The quality of the Perlin noise.

See CS::Math::Noise::NoiseQuality for definitions of the various coherent-noise qualities.

Definition at line 207 of file perlin.h.

int CS::Math::Noise::Module::Perlin::GetOctaveCount | ( |  | ) | const`[inline]`

Returns the number of octaves that generate the Perlin noise.

Returns:
  The number of octaves that generate the Perlin noise.

The number of octaves controls the amount of detail in the Perlin noise.

Definition at line 218 of file perlin.h.

double CS::Math::Noise::Module::Perlin::GetPersistence | ( |  | ) | const`[inline]`

Returns the persistence value of the Perlin noise.

Returns:
  The persistence value of the Perlin noise.

The persistence value controls the roughness of the Perlin noise.

Definition at line 228 of file perlin.h.

int CS::Math::Noise::Module::Perlin::GetSeed | ( |  | ) | const`[inline]`

Returns the seed value used by the Perlin-noise function.

Returns:
  The seed value.

Definition at line 236 of file perlin.h.

virtual int CS::Math::Noise::Module::Perlin::GetSourceModuleCount | ( |  | ) | const`[inline, virtual]`

Returns the number of source modules required by this noise module.

Returns:
  The number of source modules required by this noise module.

Implements CS::Math::Noise::Module::Module.

Definition at line 241 of file perlin.h.

virtual double CS::Math::Noise::Module::Perlin::GetValue | ( | double | x,
|  | double | y,
|  | double | z
| ) |  | const`[virtual]`

Generates an output value given the coordinates of the specified input value.

Parameters:

  x | The x coordinate of the input value.
  y | The y coordinate of the input value.
  z | The z coordinate of the input value.

Returns:
  The output value.

Precondition:
  All source modules required by this noise module have been passed to the SetSourceModule() method.

Before an application can call this method, it must first connect all required source modules via the SetSourceModule() method. If these source modules are not connected to this noise module, this method raises a debug assertion.

To determine the number of source modules required by this noise module, call the GetSourceModuleCount() method.

Implements CS::Math::Noise::Module::Module.

void CS::Math::Noise::Module::Perlin::SetFrequency | ( | double | frequency | ) | `[inline]`

Sets the frequency of the first octave.

Parameters:

  frequency | The frequency of the first octave.

Definition at line 251 of file perlin.h.

void CS::Math::Noise::Module::Perlin::SetLacunarity | ( | double | lacunarity | ) | `[inline]`

Sets the lacunarity of the Perlin noise.

Parameters:

  lacunarity | The lacunarity of the Perlin noise.

The lacunarity is the frequency multiplier between successive octaves.

For best results, set the lacunarity to a number between 1.5 and 3.5.

Definition at line 265 of file perlin.h.

void CS::Math::Noise::Module::Perlin::SetNoiseQuality | ( | CS::Math::Noise::NoiseQuality | noiseQuality | ) | `[inline]`

Sets the quality of the Perlin noise.

Parameters:

  noiseQuality | The quality of the Perlin noise.

See CS::Math::Noise::NoiseQuality for definitions of the various coherent-noise qualities.

Definition at line 276 of file perlin.h.

void CS::Math::Noise::Module::Perlin::SetOctaveCount | ( | int | octaveCount | ) | `[inline]`

Sets the number of octaves that generate the Perlin noise.

Parameters:

  octaveCount | The number of octaves that generate the Perlin noise.

Precondition:
  The number of octaves ranges from 1 to CS::Math::Noise::Module::PERLIN_MAX_OCTAVE.

Exceptions:

  CS::Math::Noise::ExceptionInvalidParam | An invalid parameter was specified; see the preconditions for more information.

The number of octaves controls the amount of detail in the Perlin noise.

The larger the number of octaves, the more time required to calculate the Perlin-noise value.

Definition at line 297 of file perlin.h.

void CS::Math::Noise::Module::Perlin::SetPersistence | ( | double | persistence | ) | `[inline]`

Sets the persistence value of the Perlin noise.

Parameters:

  persistence | The persistence value of the Perlin noise.

The persistence value controls the roughness of the Perlin noise.

For best results, set the persistence to a number between 0.0 and 1.0.

Definition at line 314 of file perlin.h.

void CS::Math::Noise::Module::Perlin::SetSeed | ( | int | seed | ) | `[inline]`

Sets the seed value used by the Perlin-noise function.

Parameters:

  seed | The seed value.

Definition at line 322 of file perlin.h.

## Member Data Documentation

double CS::Math::Noise::Module::Perlin::m_frequency`[protected]`

Frequency of the first octave.

Definition at line 330 of file perlin.h.

double CS::Math::Noise::Module::Perlin::m_lacunarity`[protected]`

Frequency multiplier between successive octaves.

Definition at line 333 of file perlin.h.

CS::Math::Noise::NoiseQuality CS::Math::Noise::Module::Perlin::m_noiseQuality`[protected]`

Quality of the Perlin noise.

Definition at line 336 of file perlin.h.

int CS::Math::Noise::Module::Perlin::m_octaveCount`[protected]`

Total number of octaves that generate the Perlin noise.

Definition at line 339 of file perlin.h.

double CS::Math::Noise::Module::Perlin::m_persistence`[protected]`

Persistence of the Perlin noise.

Definition at line 342 of file perlin.h.

int CS::Math::Noise::Module::Perlin::m_seed`[protected]`

Seed value used by the Perlin-noise function.

Definition at line 345 of file perlin.h.

The documentation for this class was generated from the following file:

- cstool/noise/module/perlin.h