Noise-1.0.0: libnoise/noise/src/module/curve.h
// curve.h
//
// Copyright (C) 2003, 2004 Jason Bevins
//
// This library is free software; you can redistribute it and/or modify it
// under the terms of the GNU Lesser General Public License as published by
// the Free Software Foundation; either version 2.1 of the License, or (at
// your option) any later version.
//
// This library 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 Lesser General Public
// License (COPYING.txt) for more details.
//
// You should have received a copy of the GNU Lesser General Public License
// along with this library; if not, write to the Free Software Foundation,
// Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
//
// The developer's email is jlbezigvins@gmzigail.com (for great email, take
// off every 'zig'.)
//
#ifndef NOISE_MODULE_CURVE_H
#define NOISE_MODULE_CURVE_H
#include "modulebase.h"
namespace noise
{
namespace module
{
/// @addtogroup libnoise
/// @{
/// This structure defines a control point.
///
/// Control points are used for defining splines.
struct ControlPoint
{
/// The input value.
double inputValue;
/// The output value that is mapped from the input value.
double outputValue;
};
/// @addtogroup modules
/// @{
/// @addtogroup modifiermodules
/// @{
/// Noise module that maps the output value from a source module onto an
/// arbitrary function curve.
///
/// @image html modulecurve.png
///
/// This noise module maps the output value from the source module onto an
/// application-defined curve. This curve is defined by a number of
/// <i>control points</i>; each control point has an <i>input value</i>
/// that maps to an <i>output value</i>. Refer to the following
/// illustration:
///
/// @image html curve.png
///
/// To add the control points to this curve, call the AddControlPoint()
/// method.
///
/// Since this curve is a cubic spline, an application must add a minimum
/// of four control points to the curve. If this is not done, the
/// GetValue() method fails. Each control point can have any input and
/// output value, although no two control points can have the same input
/// value. There is no limit to the number of control points that can be
/// added to the curve.
///
/// This noise module requires one source module.
class Curve: public Module
{
public:
/// Constructor.
Curve ();
/// Destructor.
~Curve ();
/// Adds a control point to the curve.
///
/// @param inputValue The input value stored in the control point.
/// @param outputValue The output value stored in the control point.
///
/// @pre No two control points have the same input value.
///
/// @throw noise::ExceptionInvalidParam An invalid parameter was
/// specified; see the preconditions for more information.
///
/// It does not matter which order these points are added.
void AddControlPoint (double inputValue, double outputValue);
/// Deletes all the control points on the curve.
///
/// @post All points on the curve are deleted.
void ClearAllControlPoints ();
/// Returns a pointer to the array of control points on the curve.
///
/// @returns A pointer to the array of control points.
///
/// Before calling this method, call GetControlPointCount() to
/// determine the number of control points in this array.
///
/// It is recommended that an application does not store this pointer
/// for later use since the pointer to the array may change if the
/// application calls another method of this object.
const ControlPoint* GetControlPointArray () const
{
return m_pControlPoints;
}
/// Returns the number of control points on the curve.
///
/// @returns The number of control points on the curve.
int GetControlPointCount () const
{
return m_controlPointCount;
}
virtual int GetSourceModuleCount () const
{
return 1;
}
virtual double GetValue (double x, double y, double z) const;
protected:
/// Determines the array index in which to insert the control point
/// into the internal control point array.
///
/// @param inputValue The input value of the control point.
///
/// @returns The array index in which to insert the control point.
///
/// @pre No two control points have the same input value.
///
/// @throw noise::ExceptionInvalidParam An invalid parameter was
/// specified; see the preconditions for more information.
///
/// By inserting the control point at the returned array index, this
/// class ensures that the control point array is sorted by input
/// value. The code that maps a value onto the curve requires a
/// sorted control point array.
int FindInsertionPos (double inputValue);
/// Inserts the control point at the specified position in the
/// internal control point array.
///
/// @param insertionPos The zero-based array position in which to
/// insert the control point.
/// @param inputValue The input value stored in the control point.
/// @param outputValue The output value stored in the control point.
///
/// To make room for this new control point, this method reallocates
/// the control point array and shifts all control points occurring
/// after the insertion position up by one.
///
/// Because the curve mapping algorithm used by this noise module
/// requires that all control points in the array must be sorted by
/// input value, the new control point should be inserted at the
/// position in which the order is still preserved.
void InsertAtPos (int insertionPos, double inputValue,
double outputValue);
/// Number of control points on the curve.
int m_controlPointCount;
/// Array that stores the control points.
ControlPoint* m_pControlPoints;
};
/// @}
/// @}
/// @}
}
}
#endif