![]() |
Public API Reference |
![]() |
Abstract base class for noise modules. More...
#include <cstool/noise/module/modulebase.h>
Public Member Functions | |
virtual const Module & | GetSourceModule (int index) const |
Returns a reference to a source module connected to this noise module. | |
virtual int | GetSourceModuleCount () const =0 |
Returns the number of source modules required by this noise module. | |
virtual double | GetValue (double x, double y, double z) const =0 |
Generates an output value given the coordinates of the specified input value. | |
Module (int sourceModuleCount) | |
Constructor. | |
virtual void | SetSourceModule (int index, const Module &sourceModule) |
Connects a source module to this noise module. | |
~Module () | |
Destructor. | |
Protected Attributes | |
const Module ** | m_pSourceModule |
An array containing the pointers to each source module required by this noise module. |
Abstract base class for noise modules.
A noise module is an object that calculates and outputs a value given a three-dimensional input value.
Each type of noise module uses a specific method to calculate an output value. Some of these methods include:
An application can use the output values from these noise modules in the following ways:
A noise module defines a near-infinite 3-dimensional texture. Each position in this "texture" has a specific value.
Combining noise modules
Noise modules can be combined with other noise modules to generate complex output values. A noise module that is used as a source of output values for another noise module is called a source module. Each of these source modules may be connected to other source modules, and so on.
There is no limit to the number of noise modules that can be connected together in this way. However, each connected noise module increases the time required to calculate an output value.
Noise-module categories
The noise module classes that are included in libnoise can be roughly divided into five categories.
Generator Modules
A generator module outputs a value generated by a coherent-noise function or some other mathematical function.
Examples of generator modules include:
Modifier Modules
A modifer module mathematically modifies the output value from a source module.
Examples of modifier modules include:
Combiner Modules
A combiner module mathematically combines the output values from two or more source modules together.
Examples of combiner modules include:
Selector Modules
A selector module uses the output value from a control module to specify how to combine the output values from its source modules.
Examples of selector modules include:
Transformer Modules
A transformer module applies a transformation to the coordinates of the input value before retrieving the output value from the source module. A transformer module does not modify the output value.
Examples of transformer modules include:
Connecting source modules to a noise module
An application connects a source module to a noise module by passing the source module to the SetSourceModule() method.
The application must also pass an index value to SetSourceModule() as well. An index value is a numeric identifier for that source module. Index values are consecutively numbered starting at zero.
To retrieve a reference to a source module, pass its index value to the GetSourceModule() method.
Each noise module requires the attachment of a certain number of source modules before it can output a value. For example, the CS::Math::Noise::Module::Add module requires two source modules, while the CS::Math::Noise::Module::Perlin module requires none. Call the GetSourceModuleCount() method to retrieve the number of source modules required by that module.
For non-selector modules, it usually does not matter which index value an application assigns to a particular source module, but for selector modules, the purpose of a source module is defined by its index value. For example, consider the CS::Math::Noise::Module::Select noise module, which requires three source modules. The control module is the source module assigned an index value of 2. The control module determines whether the noise module will output the value from the source module assigned an index value of 0 or the output value from the source module assigned an index value of 1.
Generating output values with a noise module
Once an application has connected all required source modules to a noise module, the application can now begin to generate output values with that noise module.
To generate an output value, pass the ( x, y, z ) coordinates of an input value to the GetValue() method.
Using a noise module to generate terrain height maps or textures
One way to generate a terrain height map or a texture is to first allocate a 2-dimensional array of floating-point values. For each array element, pass the array subscripts as x and y coordinates to the GetValue() method (leaving the z coordinate set to zero) and place the resulting output value into the array element.
Creating your own noise modules
Create a class that publicly derives from CS::Math::Noise::Module::Module.
In the constructor, call the base class' constructor while passing the return value from GetSourceModuleCount() to it.
Override the GetSourceModuleCount() pure virtual method. From this method, return the number of source modules required by your noise module.
Override the GetValue() pure virtual method. For generator modules, calculate and output a value given the coordinates of the input value. For other modules, retrieve the output values from each source module referenced in the protected m_pSourceModule array, mathematically combine those values, and return the combined value.
When developing a noise module, you must ensure that your noise module does not modify any source module or control module connected to it; a noise module can only modify the output value from those source modules. You must also ensure that if an application fails to connect all required source modules via the SetSourceModule() method and then attempts to call the GetValue() method, your module will raise an assertion.
It shouldn't be too difficult to create your own noise module. If you still have some problems, take a look at the source code for CS::Math::Noise::Module::Add, which is a very simple noise module.
Definition at line 222 of file modulebase.h.
CS::Math::Noise::Module::Module::Module | ( | int | sourceModuleCount | ) |
Constructor.
Destructor.
virtual const Module& CS::Math::Noise::Module::Module::GetSourceModule | ( | int | index | ) | const [inline, virtual] |
Returns a reference to a source module connected to this noise module.
index | The index value assigned to the source module. |
CS::Math::Noise::ExceptionNoModule | See the preconditions for more information. |
Each noise module requires the attachment of a certain number of source modules before an application can call the GetValue() method.
Definition at line 251 of file modulebase.h.
virtual int CS::Math::Noise::Module::Module::GetSourceModuleCount | ( | ) | const [pure virtual] |
Returns the number of source modules required by this noise module.
Implemented in CS::Math::Noise::Module::Perlin, CS::Math::Noise::Module::RidgedMulti, CS::Math::Noise::Module::Turbulence, CS::Math::Noise::Module::Billow, CS::Math::Noise::Module::Select, CS::Math::Noise::Module::Voronoi, CS::Math::Noise::Module::Terrace, CS::Math::Noise::Module::Curve, CS::Math::Noise::Module::Blend, CS::Math::Noise::Module::ScaleBias, CS::Math::Noise::Module::Clamp, CS::Math::Noise::Module::Cylinders, CS::Math::Noise::Module::Spheres, CS::Math::Noise::Module::RotatePoint, CS::Math::Noise::Module::TranslatePoint, CS::Math::Noise::Module::ScalePoint, CS::Math::Noise::Module::Exponent, CS::Math::Noise::Module::Displace, CS::Math::Noise::Module::Const, CS::Math::Noise::Module::Cache, CS::Math::Noise::Module::Checkerboard, CS::Math::Noise::Module::Power, CS::Math::Noise::Module::Abs, CS::Math::Noise::Module::Add, CS::Math::Noise::Module::Max, CS::Math::Noise::Module::Min, CS::Math::Noise::Module::Multiply, and CS::Math::Noise::Module::Invert.
virtual double CS::Math::Noise::Module::Module::GetValue | ( | double | x, |
double | y, | ||
double | z | ||
) | const [pure virtual] |
Generates an output value given the coordinates of the specified input value.
x | The x coordinate of the input value. |
y | The y coordinate of the input value. |
z | The z coordinate of the input value. |
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.
Implemented in CS::Math::Noise::Module::Perlin, CS::Math::Noise::Module::RidgedMulti, CS::Math::Noise::Module::Voronoi, CS::Math::Noise::Module::Turbulence, CS::Math::Noise::Module::Select, CS::Math::Noise::Module::Billow, CS::Math::Noise::Module::Terrace, CS::Math::Noise::Module::Curve, CS::Math::Noise::Module::Clamp, CS::Math::Noise::Module::Blend, CS::Math::Noise::Module::ScaleBias, CS::Math::Noise::Module::Cylinders, CS::Math::Noise::Module::Spheres, CS::Math::Noise::Module::RotatePoint, CS::Math::Noise::Module::TranslatePoint, CS::Math::Noise::Module::ScalePoint, CS::Math::Noise::Module::Exponent, CS::Math::Noise::Module::Const, CS::Math::Noise::Module::Displace, CS::Math::Noise::Module::Cache, CS::Math::Noise::Module::Checkerboard, CS::Math::Noise::Module::Power, CS::Math::Noise::Module::Abs, CS::Math::Noise::Module::Add, CS::Math::Noise::Module::Max, CS::Math::Noise::Module::Min, CS::Math::Noise::Module::Multiply, and CS::Math::Noise::Module::Invert.
virtual void CS::Math::Noise::Module::Module::SetSourceModule | ( | int | index, |
const Module & | sourceModule | ||
) | [inline, virtual] |
Connects a source module to this noise module.
index | An index value to assign to this source module. |
sourceModule | The source module to attach. |
CS::Math::Noise::ExceptionInvalidParam | An invalid parameter was specified; see the preconditions for more information. |
A noise module mathematically combines the output values from the source modules to generate the value returned by GetValue().
The index value to assign a source module is a unique identifier for that source module. If an index value has already been assigned to a source module, this noise module replaces the old source module with the new source module.
Before an application can call the GetValue() method, it must first connect all required source modules. To determine the number of source modules required by this noise module, call the GetSourceModuleCount() method.
This source module must exist throughout the lifetime of this noise module unless another source module replaces that source module.
A noise module does not modify a source module; it only modifies its output values.
Reimplemented in CS::Math::Noise::Module::Cache.
Definition at line 328 of file modulebase.h.
const Module** CS::Math::Noise::Module::Module::m_pSourceModule [protected] |
An array containing the pointers to each source module required by this noise module.
Definition at line 342 of file modulebase.h.