1 files changed, 357 insertions, 0 deletions
diff --git a/src/libnoiseforjava/module/Perlin.java b/src/libnoiseforjava/module/Perlin.java
new file mode 100644
index 0000000..70fb22e
--- /dev/null
+++ b/src/libnoiseforjava/module/Perlin.java
@@ -0,0 +1,357 @@
+/*
+ * Copyright (C) 2003, 2004 Jason Bevins (original libnoise code)
+ * Copyright  2010 Thomas J. Hodge (java port of libnoise)
+ * 
+ * This file is part of libnoiseforjava.
+ * 
+ * libnoiseforjava is a Java port of the C++ library libnoise, which may be found at 
+ * http://libnoise.sourceforge.net/.  libnoise was developed by Jason Bevins, who may be 
+ * contacted at [email protected] (for great email, take off every 'zig').
+ * Porting to Java was done by Thomas Hodge, who may be contacted at
+ * [email protected] (remove every 'zag').
+ * 
+ * libnoiseforjava is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ * 
+ * libnoiseforjava is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License along with
+ * libnoiseforjava.  If not, see <http://www.gnu.org/licenses/>.
+ * 
+ */
+
+package libnoiseforjava.module;
+
+import libnoiseforjava.NoiseGen;
+import libnoiseforjava.NoiseGen.NoiseQuality;
+import libnoiseforjava.exception.ExceptionInvalidParam;
+
+public class Perlin extends ModuleBase
+{
+   /// 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
+   /// <i>References and Acknowledgments</i> section.
+   ///
+   /// This noise module does not require any source modules.
+   ///
+   /// <b>Octaves</b>
+   ///
+   /// The number of octaves control the <i>amount of detail</i> 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.
+   ///
+   /// <b>Frequency</b>
+   ///
+   /// An application may specify the frequency of the first octave by
+   /// calling the setFrequency() method.
+   ///
+   /// <b>Persistence</b>
+   ///
+   /// The persistence value controls the <i>roughness</i> 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.
+   ///
+   /// <b>Lacunarity</b>
+   ///
+   /// 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.
+   ///
+   /// <b>References &amp; acknowledgments</b>
+   ///
+   /// <a href=http://www.noisemachine.com/talk1/>The Noise Machine</a> -
+   /// 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!
+   ///
+   /// <a
+   /// href=http://freespace.virgin.net/hugo.elias/models/m_perlin.htm>
+   /// Perlin Noise</a> - 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.)
+   ///
+   /// <a
+   /// href=http://www.robo-murito.net/code/perlin-noise-math-faq.html>The
+   /// Perlin noise math FAQ</a> - 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 <i>gradient noise</i>.  This
+   /// version of the Perlin module uses gradient coherent noise to
+   /// generate Perlin noise.
+
+
+   /// Default frequency for the noise::module::Perlin noise module.
+   static final double DEFAULT_PERLIN_FREQUENCY = 1.0;
+
+   /// Default lacunarity for the noise::module::Perlin noise module.
+   static final double DEFAULT_PERLIN_LACUNARITY = 2.0;
+
+   /// Default number of octaves for the noise::module::Perlin noise module.
+   static final int DEFAULT_PERLIN_OCTAVE_COUNT = 6;
+
+   /// Default persistence value for the noise::module::Perlin noise module.
+   static final double DEFAULT_PERLIN_PERSISTENCE = 0.5;
+
+   /// Default noise quality for the noise::module::Perlin noise module.
+   static final NoiseQuality DEFAULT_PERLIN_QUALITY = NoiseQuality.QUALITY_STD;
+
+   /// Default noise seed for the noise::module::Perlin noise module.
+   static final int DEFAULT_PERLIN_SEED = 0;
+
+   /// Maximum number of octaves for the noise::module::Perlin noise module.
+   static final int PERLIN_MAX_OCTAVE = 30;
+
+
+   /// Frequency of the first octave.
+   double frequency;
+
+   /// Frequency multiplier between successive octaves.
+   double lacunarity;
+
+   /// Quality of the Perlin noise.
+   NoiseQuality noiseQuality;
+
+   /// Total number of octaves that generate the Perlin noise.
+   int octaveCount;
+
+   /// Persistence of the Perlin noise.
+   double persistence;
+
+   /// Seed value used by the Perlin-noise function.
+   int seed;
+
+
+   public Perlin ()
+   {
+      super(0);
+      frequency = DEFAULT_PERLIN_FREQUENCY;
+      lacunarity = DEFAULT_PERLIN_LACUNARITY;
+      noiseQuality = DEFAULT_PERLIN_QUALITY;
+      octaveCount = DEFAULT_PERLIN_OCTAVE_COUNT;
+      persistence = DEFAULT_PERLIN_PERSISTENCE;
+      seed = DEFAULT_PERLIN_SEED;
+   }
+
+   public double getValue (double x, double y, double z)
+   {
+      double value = 0.0;
+      double signal = 0.0;
+      double curPersistence = 1.0;
+      double nx, ny, nz;
+      int curSeed;
+
+      x *= frequency;
+      y *= frequency;
+      z *= frequency;
+
+      for (int curOctave = 0; curOctave < octaveCount; curOctave++)
+      {
+
+         // Make sure that these floating-point values have the same range as a 32-
+         // bit integer so that we can pass them to the coherent-noise functions.
+         nx = NoiseGen.MakeInt32Range (x);
+         ny = NoiseGen.MakeInt32Range (y);
+         nz = NoiseGen.MakeInt32Range (z);
+
+         // Get the coherent-noise value from the input value and add it to the
+         // final result.
+         curSeed = (seed + curOctave) & 0xffffffff;
+         signal = NoiseGen.GradientCoherentNoise3D (nx, ny, nz, curSeed, noiseQuality);
+         value += signal * curPersistence;
+
+         // Prepare the next octave.
+         x *= lacunarity;
+         y *= lacunarity;
+         z *= lacunarity;
+         curPersistence *= persistence;
+      }
+
+      return value;
+   }
+
+   /// Returns the frequency of the first octave.
+   ///
+   /// @returns The frequency of the first octave.
+   public double getFrequency ()
+   {
+      return frequency;
+   }
+
+   /// Returns the lacunarity of the Perlin noise.
+   ///
+   /// @returns The lacunarity of the Perlin noise.
+   /// 
+   /// The lacunarity is the frequency multiplier between successive
+   /// octaves.
+   public double getLacunarity ()
+   {
+      return lacunarity;
+   }
+
+   /// Returns the quality of the Perlin noise.
+   ///
+   /// @returns The quality of the Perlin noise.
+   ///
+   /// See NoiseQuality for definitions of the various
+   /// coherent-noise qualities.
+   public NoiseQuality getNoiseQuality ()
+   {
+      return noiseQuality;
+   }
+
+   /// 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.
+   public int getOctaveCount ()
+   {
+      return octaveCount;
+   }
+
+   /// 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.
+   public double getPersistence ()
+   {
+      return persistence;
+   }
+
+   /// Returns the seed value used by the Perlin-noise function.
+   ///
+   /// @returns The seed value.
+   public int getSeed ()
+   {
+      return seed;
+   }
+
+   /// Sets the frequency of the first octave.
+   ///
+   /// @param frequency The frequency of the first octave.
+   public void setFrequency (double frequency)
+   {
+      this.frequency = frequency;
+   }
+
+   /// Sets the lacunarity of the Perlin noise.
+   ///
+   /// @param 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.
+   public void setLacunarity (double lacunarity)
+   {
+      this.lacunarity = lacunarity;
+   }
+
+   /// Sets the quality of the Perlin noise.
+   ///
+   /// @param noiseQuality The quality of the Perlin noise.
+   ///
+   /// See NoiseQuality for definitions of the various
+   /// coherent-noise qualities.
+   public void setNoiseQuality (NoiseQuality noiseQuality)
+   {
+      this.noiseQuality = noiseQuality;
+   }
+
+   /// Sets the number of octaves that generate the Perlin noise.
+   ///
+   /// @param octaveCount The number of octaves that generate the Perlin
+   /// noise.
+   ///
+   /// @pre The number of octaves ranges from 1 to PERLIN_MAX_OCTAVE.
+   ///
+   /// @throw 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.
+   public void setOctaveCount (int octaveCount) throws ExceptionInvalidParam
+   {
+      if (octaveCount < 1 || octaveCount > PERLIN_MAX_OCTAVE)
+      {
+         throw new ExceptionInvalidParam ("Invalid parameter In Perlin Noise Module");
+      }
+
+      this.octaveCount = octaveCount;
+   }
+
+   /// Sets the persistence value of the Perlin noise.
+   ///
+   /// @param 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.
+   public void setPersistence (double persistence)
+   {
+      this.persistence = persistence;
+   }
+
+   /// Sets the seed value used by the Perlin-noise function.
+   ///
+   /// @param seed The seed value.
+   public void setSeed (int seed)
+   {
+      this.seed = seed;
+   }
+   
+}