/*
 * 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 jlbezigvins@gmzigail.com (for great email, take off every 'zig').
 * Porting to Java was done by Thomas Hodge, who may be contacted at
 * libnoisezagforjava@gzagmail.com (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.exception.ExceptionInvalidParam;
import libnoiseforjava.exception.ExceptionNoModule;

public class Displace extends ModuleBase
{
   /// Noise module that uses three source modules to displace each
   /// coordinate of the input value before returning the output value from
   /// a source module.
   ///
   /// Unlike most other noise modules, the index value assigned to a source
   /// module determines its role in the displacement operation:
   /// - Source module 0 (left in the diagram) outputs a value.
   /// - Source module 1 (lower left in the diagram) specifies the offset to
   ///   apply to the @a x coordinate of the input value.
   /// - Source module 2 (lower center in the diagram) specifies the
   ///   offset to apply to the @a y coordinate of the input value.
   /// - Source module 3 (lower right in the diagram) specifies the offset
   ///   to apply to the @a z coordinate of the input value.
   ///
   /// The getValue() method modifies the ( @a x, @a y, @a z ) coordinates of
   /// the input value using the output values from the three displacement
   /// modules before retrieving the output value from the source module.
   ///
   /// The Turbulence noise module is a special case of the
   /// Displace module; internally, there are three Perlin-noise modules
   /// that perform the displacement operation.
   ///
   /// This noise module requires four source modules.

   public Displace (ModuleBase sourceModuleOne, ModuleBase sourceModuleTwo,
         ModuleBase sourceModuleThree, ModuleBase sourceModuleFour) throws ExceptionInvalidParam
   {
      super(4);
      setSourceModule(0, sourceModuleOne);
      setSourceModule(1, sourceModuleTwo);
      setSourceModule(2, sourceModuleThree);
      setSourceModule(3, sourceModuleFour);
   }

   public double getValue (double x, double y, double z)
   {
      assert (sourceModules[0] != null);
      assert (sourceModules[1] != null);
      assert (sourceModules[2] != null);
      assert (sourceModules[3] != null);

      // Get the output values from the three displacement modules.  Add each
      // value to the corresponding coordinate in the input value.
      double xDisplace = x + (sourceModules[1].getValue (x, y, z));
      double yDisplace = y + (sourceModules[2].getValue (x, y, z));
      double zDisplace = z + (sourceModules[3].getValue (x, y, z));

      // Retrieve the output value using the offset input value instead of
      // the original input value.
      return sourceModules[0].getValue (xDisplace, yDisplace, zDisplace);
   }

   public ModuleBase getXDisplaceModule() throws ExceptionNoModule
   {
      if (sourceModules == null || sourceModules[1] == null)  
         throw new ExceptionNoModule ("Could not retrieve a source module " +
         "from a noise module.");

      return sourceModules[1];
   }

   /// Returns the @a y displacement module.
   ///
   /// @returns A reference to the @a y displacement module.
   ///
   /// @pre This displacement module has been added to this noise module
   /// via a call to setSourceModule() or setYDisplaceModule().
   ///
   /// @throw ExceptionNoModule See the preconditions for more
   /// information.
   ///
   /// The getValue() method displaces the input value by adding the output
   /// value from this displacement module to the @a y coordinate of the
   /// input value before returning the output value from the source
   /// module.
   public ModuleBase getYDisplaceModule () throws ExceptionNoModule
   {
      if (sourceModules == null || sourceModules[2] == null)
         throw new ExceptionNoModule ("Could not retrieve a source module " +
         "from Displace noise module.");

      return sourceModules[2];
   }

   /// Returns the @a z displacement module.
   ///
   /// @returns A reference to the @a z displacement module.
   ///
   /// @pre This displacement module has been added to this noise module
   /// via a call to setSourceModule() or setZDisplaceModule().
   ///
   /// @throw ExceptionNoModule See the preconditions for more
   /// information.
   ///
   /// The getValue() method displaces the input value by adding the output
   /// value from this displacement module to the @a z coordinate of the
   /// input value before returning the output value from the source
   /// module.
   public ModuleBase getZDisplaceModule () throws ExceptionNoModule
   {
      if (sourceModules == null || sourceModules[3] == null)
         throw new ExceptionNoModule ("Could not retrieve a source module " +
         "from Displace noise module.");

      return sourceModules[3];
   }


   /// Sets the @a x, @a y, and @a z displacement modules.
   ///
   /// @param xDisplaceModule Displacement module that displaces the @a x
   /// coordinate of the input value.
   /// @param yDisplaceModule Displacement module that displaces the @a y
   /// coordinate of the input value.
   /// @param zDisplaceModule Displacement module that displaces the @a z
   /// coordinate of the input value.
   ///
   /// The getValue() method displaces the input value by adding the output
   /// value from each of the displacement modules to the corresponding
   /// coordinates of the input value before returning the output value
   /// from the source module.
   ///
   /// This method assigns an index value of 1 to the @a x displacement
   /// module, an index value of 2 to the @a y displacement module, and an
   /// index value of 3 to the @a z displacement module.
   ///
   /// These displacement modules must exist throughout the lifetime of
   /// this noise module unless another displacement module replaces it.
   public void setDisplaceModules (ModuleBase xDisplaceModule,
         ModuleBase yDisplaceModule, ModuleBase zDisplaceModule)
   {
      setXDisplaceModule (xDisplaceModule);
      setYDisplaceModule (yDisplaceModule);
      setZDisplaceModule (zDisplaceModule);
   }

   /// Sets the @a x displacement module.
   ///
   /// @param xDisplaceModule Displacement module that displaces the @a x
   /// coordinate.
   ///
   /// The getValue() method displaces the input value by adding the output
   /// value from this displacement module to the @a x coordinate of the
   /// input value before returning the output value from the source
   /// module.
   ///
   /// This method assigns an index value of 1 to the @a x displacement
   /// module.  Passing this displacement module to this method produces
   /// the same results as passing this displacement module to the
   /// setSourceModule() method while assigning it an index value of 1.
   ///
   /// This displacement module must exist throughout the lifetime of this
   /// noise module unless another displacement module replaces it.
   public void setXDisplaceModule (ModuleBase xDisplaceModule)
   {
      assert (sourceModules != null);
      sourceModules[1] = xDisplaceModule;
   }

   /// Sets the @a y displacement module.
   ///
   /// @param yDisplaceModule Displacement module that displaces the @a y
   /// coordinate.
   ///
   /// The getValue() method displaces the input value by adding the output
   /// value from this displacement module to the @a y coordinate of the
   /// input value before returning the output value from the source
   /// module.
   ///
   /// This method assigns an index value of 2 to the @a y displacement
   /// module.  Passing this displacement module to this method produces
   /// the same results as passing this displacement module to the
   /// setSourceModule() method while assigning it an index value of 2.
   ///
   /// This displacement module must exist throughout the lifetime of this
   /// noise module unless another displacement module replaces it.
   public void setYDisplaceModule (ModuleBase yDisplaceModule)
   {
      assert (sourceModules != null);
      sourceModules[2] = yDisplaceModule;
   }

   /// Sets the @a z displacement module.
   ///
   /// @param zDisplaceModule Displacement module that displaces the @a z
   /// coordinate.
   ///
   /// The getValue() method displaces the input value by adding the output
   /// value from this displacement module to the @a z coordinate of the
   /// input value before returning the output value from the source
   /// module.
   ///
   /// This method assigns an index value of 3 to the @a z displacement
   /// module.  Passing this displacement module to this method produces
   /// the same results as passing this displacement module to the
   /// setSourceModule() method while assigning it an index value of 3.
   ///
   /// This displacement module must exist throughout the lifetime of this
   /// noise module unless another displacement module replaces it.
   public void setZDisplaceModule (ModuleBase zDisplaceModule)
   {
      assert (sourceModules != null);
      sourceModules[3] = zDisplaceModule;
   }

}