Tutorial 2: Introduction to libnoise

In this tutorial, you'll write a program that uses libnoise to generate and output a coherent-noise value.

Table of contents

1. A quick introduction to coherent noise
2. Generating a coherent-noise value
3. Changing the coordinates of the input value
4. Conclusion

A quick introduction to coherent noise

Coherent noise is a type of smooth pseudorandom noise. This definition may make more sense if you examine the output of a one-dimensional coherent-noise function and compare it to the output of a non-coherent-noise function:

Coherent noise	Non-coherent noise

Note that a small change in the input value produces a small change in the output value, while a large change in the input value produces a random change in the output value. Also note that most of the output values range from -1 to +1.

Note: libnoise makes no guarantee that all output values will exist within that range, although nearly all values will.

Instead of generating one-dimensional coherent noise, libnoise generates three-dimensional coherent noise. Three-dimensional coherent noise extends almost infinitely in all three dimensions, forming a non-repeating three-dimensional texture. Because of this property, coherent noise is often used to generate solid textures resembling granite, wood, marble, and other natural materials.

Generating a coherent-noise value

Now that you have some understanding of coherent noise, you are ready to write a program that generates it. Create a new source file.

First, you'll include the iostream headers and the libnoise headers. Then you'll set up the source file to use the noise namespace. Add the following code:

#include <iostream>
#include <noise/noise.h>

using namespace noise;

Next, you'll create the main() function. Add the following code after the headers:

int main (int argc, char** argv)
{
  return 0;
}

In libnoise, you generate coherent noise by using an object called a noise module. libnoise provides several types of noise modules, all of which are derived from the module::Module abstract base class.

For this tutorial, you'll instantiate a Perlin-noise module. Perlin noise is often used to generate realistic terrain and natural textures. To create this noise module, add the following code before the return statement:

  module::Perlin myModule;

The GetValue() method generates and returns a coherent-noise value given the coordinates of a three-dimensional input value. All noise modules implement this method.

In this tutorial, you'll generate a coherent-noise value from an input value with coordinates (1.25, 0.75, 0.5). Add the following highlighted code:

  module::Perlin myModule;
  double value = myModule.GetValue (1.25, 0.75, 0.5);

Now you'll output this value to stdout. Add the following highlighted code:

  module::Perlin myModule;
  double value = myModule.GetValue (1.25, 0.75, 0.50);
  std::cout << value << std::endl;

The completed source code should now look like the following:

#include <iostream>
#include <noise/noise.h>

using namespace noise;

int main (int argc, char** argv)
{
  module::Perlin myModule;
  double value = myModule.GetValue (1.25, 0.75, 0.50);
  std::cout << value << std::endl;
  return 0;
}

That's it! Compile and run the program. This program outputs the following coherent-noise value to stdout:

0.686347

Note: Your program may output a slightly different value due to the varying precision of floating-point maths between operating systems and compilers.

If you run it again, you'll get the same output. This is because all noise modules will generate the same output value given the same input value. This property allows you, for example, to store a massive terrain or texture in a tiny program; by simply running the program again, you can regenerate this data.

Changing the coordinates of the input value

If you slightly change the coordinates of the input value, the output value of the noise module will slightly change.

To see this in action, modify the input value by adding 0.0001 to each coordinate. Make the following highlighted changes to your source code:

  module::Perlin myModule;
  double value = myModule.GetValue (1.2501, 0.7501, 0.5001);
  std::cout << value << std::endl;

When you run the program, note that the new output value differs from the original value by only 0.000703:

0.685644

However, if you make a large change to the coordinates of the input value, the output value of the noise module may significantly change. Make the following highlighted changes to your source code:

  module::Perlin myModule;
  double value = myModule.GetValue (14.50, 20.25, 75.75);
  std::cout << value << std::endl;

Now run the program. Note that this value is completely different from the first two values you generated:

-0.972999

Conclusion

In this tutorial, you've created a simple program that demonstrates the three major properties of the coherent-noise function within a noise module:

1. Passing in the same input value will always return the same output value.
2. A small change in the input value will produce a small change in the output value.
3. A large change in the input value may produce a larger, random change in the output value.

You may be disappointed that you did not produce any "pretty pictures" in this tutorial, but in the next tutorial, you will learn how to use libnoise to generate and render a terrain height map.

<< Previous tutorial | Next tutorial >>