Module org.spongepowered.noise
Package org.spongepowered.noise.module

Class NoiseModule

java.lang.Object
org.spongepowered.noise.module.NoiseModule
Direct Known Subclasses:
Abs, Add, Billow, Blend, Cache, Checkerboard, Clamp, Const, Curve, Cylinders, Displace, Exponent, Invert, Max, Min, Multiply, Perlin, Power, Range, RidgedMulti, RidgedMultiSimplex, RotatePoint, ScaleBias, ScalePoint, Select, Simplex, Spheres, Terrace, TranslatePoint, Turbulence, Voronoi
public abstract class NoiseModule extends Object
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:

  • Calculating a value using a coherent-noise function or some other mathematical function.
  • Mathematically changing the output value from another noise module in various ways.
  • Combining the output values from two noise modules in various ways.

An application can use the output values from these noise modules in the following ways:

  • It can be used as an elevation value for a terrain height map
  • It can be used as a grayscale (or an RGB-channel) value for a procedural texture
  • It can be used as a position value for controlling the movement of a simulated lifeform.

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:

  • Const: Outputs a constant value.
  • Perlin: Outputs a value generated by a Perlin-noise function.
  • Voronoi: Outputs a value generated by a Voronoi-cell function.

Modifier Modules

A modifier module mathematically modifies the output value from a source module.

Examples of modifier modules include:

  • Curve: Maps the output value from the source module onto an arbitrary function curve.
  • Invert: Inverts the output value from the source module.

Combiner Modules

A combiner module mathematically combines the output values from two or more source modules together.

Examples of combiner modules include:

  • Add: Adds the two output values from two source modules.
  • Max: Outputs the larger of the two output values from two source modules.

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:

  • Blend: Outputs a value that is linearly interpolated between the output values from two source modules; the interpolation weight is determined by the output value from the control module.
  • Select: Outputs the value selected from one of two source modules chosen by the output value from a control module.

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:

  • RotatePoint: Rotates the coordinates of the input value around the origin before retrieving the output value from the source module.
  • ScalePoint: Multiplies each coordinate of the input value by a constant value before retrieving the output value from the source module.

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(int, NoiseModule) method.

The application must also pass an index value to setSourceModule(int, NoiseModule). 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 sourceModule(int) method.

Each noise module requires the attachment of a certain number of source modules before it can output a value. For example, the Add module requires two source modules, while the Perlin module requires none. Call the sourceModule(int) method or consult Javadoc 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 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 get(double, double, double) 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 get(double, double, double) 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 extends from NoiseModule.

In the constructor, call the base class' constructor while passing the required number of souce modules to it.

Override the get(double, double, double) 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 sourceModule 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(int, NoiseModule) method and then attempts to call the get(double, double, double) method, your module will throw an exception.

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 Add, which is a very simple noise module.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected NoiseModule[]
    sourceModule
    An array containing references to each source module required by this noise module.

  • Constructor Summary

    Constructors
    Constructor
    Description
    NoiseModule(int sourceModuleCount)
    Create a new module.

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract double
    get(double x, double y, double z)
    Generates an output value given the coordinates of the specified input value.
    void
    setSourceModule(int index, NoiseModule sourceModule)
    Connects a source module to this noise module.
    NoiseModule
    sourceModule(int index)
    Get a source module connected to this noise module.
    final int
    sourceModuleCount()
    Get the number of source modules required by this noise module.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • sourceModule

      protected NoiseModule[] sourceModule
      An array containing references to each source module required by this noise module.

  • Constructor Details

    • NoiseModule

      public NoiseModule(int sourceModuleCount)
      Create a new module.
      Parameters:
      sourceModuleCount - the number of source modules required by this module

  • Method Details

    • sourceModule

      public NoiseModule sourceModule(int index)
      Get a source module connected to this noise module.

      Each noise module requires the attachment of a certain number of source modules before an application can call the get(double, double, double) method.

      Parameters:
      index - the index value assigned to the source module
      Returns:
      the source module if one is set, or else throws NoModuleException
      Throws:
      NoModuleException - if no module has been set for the specified index or the index is out of the range from 0 to sourceModuleCount()

    • setSourceModule

      public void setSourceModule(int index, NoiseModule sourceModule)
      Connects a source module to this noise module.

      A noise module mathematically combines the output values from the source modules to generate the value returned by get(double, double, double).

      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 get(double, double, double) method, it must first connect all the required source modules. To determine the number of source modules required by the noise module, call the sourceModuleCount() method.

      A noise module does not modify a souce module, it only modifies its output values.

      Parameters:
      index - an index value to assign to this source module, must be in the range [0, sourceModuleCount())
      sourceModule - the source module to attach
      Throws:
      IllegalArgumentException - if the index is out of bounds

    • sourceModuleCount

      public final int sourceModuleCount()
      Get the number of source modules required by this noise module.
      Returns:
      the number of source modules required by this noise module

    • get

      public abstract double get(double x, double y, double z)
      Generates an output value given the coordinates of the specified input value.

      All source modules required by this module must have been connected with the setSourceModule(int, NoiseModule) method. If these source modules are not connected, this method will throw a NoModuleException.

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

      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