diff options
Diffstat (limited to 'noiseutils/noiseutils.h')
| -rw-r--r-- | noiseutils/noiseutils.h | 2540 |
1 files changed, 2540 insertions, 0 deletions
diff --git a/noiseutils/noiseutils.h b/noiseutils/noiseutils.h new file mode 100644 index 0000000..d54f61d --- /dev/null +++ b/noiseutils/noiseutils.h @@ -0,0 +1,2540 @@ +// noiseutils.h
+//
+// Copyright (C) 2003-2005 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 NOISEUTILS_H
+#define NOISEUTILS_H
+
+#include <stdlib.h>
+#include <string.h>
+#include <string>
+
+#include <noise/noise.h>
+
+using namespace noise;
+
+namespace noise
+{
+
+ namespace utils
+ {
+
+ /// @mainpage noiseutils
+ ///
+ /// @section intro Introduction
+ ///
+ /// This library contains useful classes for creating and rendering
+ /// two-dimensional noise maps containing coherent noise that was
+ /// generated from the libnoise library. These classes are used to create
+ /// procedural textures and terrain height maps.
+ ///
+ /// noiseutils is known to compile under Windows 2000 Service Pack 4
+ /// (using Microsoft Visual C++ 5.0) and under Gentoo Linux 10.0 (using
+ /// gcc 3.3.4). It should be portable across all platforms that can
+ /// compile libnoise.
+ ///
+ /// @section classes Classes
+ ///
+ /// This library contains the following classes:
+ /// - A <i>noise map</i> class: This class implements a two-dimensional
+ /// array that stores floating-point values. It's designed to store
+ /// coherent-noise values generated by a noise module.
+ /// - Several <i>noise-map builder</i> classes: Each of these classes
+ /// fills a noise map with coherent-noise values generated by a noise
+ /// module. While filling a noise map, it iterates the coordinates of
+ /// the input value along the surface of a specific mathematical object.
+ /// Each of these classes implements a different mathematical object,
+ /// such as a plane, a cylinder, or a sphere.
+ /// - An <i>image</i> class: This class implements a two-dimensional array
+ /// that stores color values.
+ /// - Several <i>image-renderer</i> classes: these classes render images
+ /// given the contents of a noise map. Each of these classes renders an
+ /// image in a different way.
+ ///
+ /// @section contact Contact
+ ///
+ /// Contact jas for questions about noiseutils. The spam-resistant email
+ /// address is jlbezigvins@gmzigail.com (For great email, take off every
+ /// <a href=http://www.planettribes.com/allyourbase/story.shtml>zig</a>.)
+
+ /// The maximum width of a raster.
+ const int RASTER_MAX_WIDTH = 32767;
+
+ /// The maximum height of a raster.
+ const int RASTER_MAX_HEIGHT = 32767;
+
+ #ifndef DOXYGEN_SHOULD_SKIP_THIS
+ // The raster's stride length must be a multiple of this constant.
+ const int RASTER_STRIDE_BOUNDARY = 4;
+ #endif
+
+ /// A pointer to a callback function used by the NoiseMapBuilder class.
+ ///
+ /// The NoiseMapBuilder::Build() method calls this callback function each
+ /// time it fills a row of the noise map with coherent-noise values.
+ ///
+ /// This callback function has a single integer parameter that contains
+ /// a count of the rows that have been completed. It returns void. Pass
+ /// a function with this signature to the NoiseMapBuilder::SetCallback()
+ /// method.
+ typedef void(*NoiseMapCallback) (int row);
+
+ /// Number of meters per point in a Terragen terrain (TER) file.
+ const double DEFAULT_METERS_PER_POINT = 30.0;
+
+ /// Same as the DEFAULT_METERS_PER_POINT constant, but for us
+ /// canuckleheads.
+ const double DEFAULT_METRES_PER_POINT = DEFAULT_METERS_PER_POINT;
+
+ /// Defines a color.
+ ///
+ /// A color object contains four 8-bit channels: red, green, blue, and an
+ /// alpha (transparency) channel. Channel values range from 0 to 255.
+ ///
+ /// The alpha channel defines the transparency of the color. If the alpha
+ /// channel has a value of 0, the color is completely transparent. If the
+ /// alpha channel has a value of 255, the color is completely opaque.
+ class Color
+ {
+
+ public:
+
+ /// Constructor.
+ Color ()
+ {
+ }
+
+ /// Constructor.
+ ///
+ /// @param r Value of the red channel.
+ /// @param g Value of the green channel.
+ /// @param b Value of the blue channel.
+ /// @param a Value of the alpha (transparency) channel.
+ Color (noise::uint8 r, noise::uint8 g, noise::uint8 b,
+ noise::uint8 a):
+ red (r), green (g), blue (b), alpha (a)
+ {
+ }
+
+ /// Value of the red channel.
+ noise::uint8 red;
+
+ /// Value of the green channel.
+ noise::uint8 green;
+
+ /// Value of the blue channel.
+ noise::uint8 blue;
+
+ /// Value of the alpha (transparency) channel.
+ noise::uint8 alpha;
+
+ };
+
+ /// Defines a point used to build a color gradient.
+ ///
+ /// A color gradient is a list of gradually-changing colors. A color
+ /// gradient is defined by a list of <i>gradient points</i>. Each
+ /// gradient point has a position and a color. In a color gradient, the
+ /// colors between two adjacent gradient points are linearly interpolated.
+ ///
+ /// The ColorGradient class defines a color gradient by a list of these
+ /// objects.
+ struct GradientPoint
+ {
+
+ /// The position of this gradient point.
+ double pos;
+
+ /// The color of this gradient point.
+ Color color;
+
+ };
+
+ /// Defines a color gradient.
+ ///
+ /// A color gradient is a list of gradually-changing colors. A color
+ /// gradient is defined by a list of <i>gradient points</i>. Each
+ /// gradient point has a position and a color. In a color gradient, the
+ /// colors between two adjacent gradient points are linearly interpolated.
+ ///
+ /// To add a gradient point to the color gradient, pass its position and
+ /// color to the AddGradientPoint() method.
+ ///
+ /// To retrieve a color from a specific position in the color gradient,
+ /// pass that position to the GetColor() method.
+ ///
+ /// This class is a useful tool for coloring height maps based on
+ /// elevation.
+ ///
+ /// <b>Gradient example</b>
+ ///
+ /// Suppose a gradient object contains the following gradient points:
+ /// - -1.0 maps to black.
+ /// - 0.0 maps to white.
+ /// - 1.0 maps to red.
+ ///
+ /// If an application passes -0.5 to the GetColor() method, this method
+ /// will return a gray color that is halfway between black and white.
+ ///
+ /// If an application passes 0.25 to the GetColor() method, this method
+ /// will return a very light pink color that is one quarter of the way
+ /// between white and red.
+ class GradientColor
+ {
+
+ public:
+
+ /// Constructor.
+ GradientColor ();
+
+ /// Destructor.
+ ~GradientColor ();
+
+ /// Adds a gradient point to this gradient object.
+ ///
+ /// @param gradientPos The position of this gradient point.
+ /// @param gradientColor The color of this gradient point.
+ ///
+ /// @pre No two gradient points have the same position.
+ ///
+ /// @throw noise::ExceptionInvalidParam See the precondition.
+ ///
+ /// It does not matter which order these gradient points are added.
+ void AddGradientPoint (double gradientPos,
+ const Color& gradientColor);
+
+ /// Deletes all the gradient points from this gradient object.
+ ///
+ /// @post All gradient points from this gradient object are deleted.
+ void Clear ();
+
+ /// Returns the color at the specified position in the color gradient.
+ ///
+ /// @param gradientPos The specified position.
+ ///
+ /// @returns The color at that position.
+ const Color& GetColor (double gradientPos) const;
+
+ /// Returns a pointer to the array of gradient points in this object.
+ ///
+ /// @returns A pointer to the array of gradient points.
+ ///
+ /// Before calling this method, call GetGradientPointCount() to
+ /// determine the number of gradient 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 GradientPoint* GetGradientPointArray () const
+ {
+ return m_pGradientPoints;
+ }
+
+ /// Returns the number of gradient points stored in this object.
+ ///
+ /// @returns The number of gradient points stored in this object.
+ int GetGradientPointCount () const
+ {
+ return m_gradientPointCount;
+ }
+
+ private:
+
+ /// Determines the array index in which to insert the gradient point
+ /// into the internal gradient-point array.
+ ///
+ /// @param gradientPos The position of this gradient point.
+ ///
+ /// @returns The array index in which to insert the gradient point.
+ ///
+ /// @pre No two gradient points have the same input value.
+ ///
+ /// @throw noise::ExceptionInvalidParam See the precondition.
+ ///
+ /// By inserting the gradient point at the returned array index, this
+ /// object ensures that the gradient-point array is sorted by input
+ /// value. The code that maps a value to a color requires a sorted
+ /// gradient-point array.
+ int FindInsertionPos (double gradientPos);
+
+ /// Inserts the gradient point at the specified position in the
+ /// internal gradient-point array.
+ ///
+ /// @param insertionPos The zero-based array position in which to
+ /// insert the gradient point.
+ /// @param gradientPos The position of this gradient point.
+ /// @param gradientColor The color of this gradient point.
+ ///
+ /// To make room for this new gradient point, this method reallocates
+ /// the gradient-point array and shifts all gradient points occurring
+ /// after the insertion position up by one.
+ ///
+ /// Because this object requires that all gradient points in the array
+ /// must be sorted by the position, the new gradient point should be
+ /// inserted at the position in which the order is still preserved.
+ void InsertAtPos (int insertionPos, double gradientPos,
+ const Color& gradientColor);
+
+ /// Number of gradient points.
+ int m_gradientPointCount;
+
+ /// Array that stores the gradient points.
+ GradientPoint* m_pGradientPoints;
+
+ /// A color object that is used by a gradient object to store a
+ /// temporary value.
+ mutable Color m_workingColor;
+ };
+
+ /// Implements a noise map, a 2-dimensional array of floating-point
+ /// values.
+ ///
+ /// A noise map is designed to store coherent-noise values generated by a
+ /// noise module, although it can store values from any source. A noise
+ /// map is often used as a terrain height map or a grayscale texture.
+ ///
+ /// The size (width and height) of the noise map can be specified during
+ /// object construction or at any other time.
+ ///
+ /// The GetValue() and SetValue() methods can be used to access individual
+ /// values stored in the noise map.
+ ///
+ /// This class manages its own memory. If you copy a noise map object
+ /// into another noise map object, the original contents of the noise map
+ /// object will be freed.
+ ///
+ /// If you specify a new size for the noise map and the new size is
+ /// smaller than the current size, the allocated memory will not be
+ /// reallocated.
+ /// Call ReclaimMem() to reclaim the wasted memory.
+ ///
+ /// <b>Border Values</b>
+ ///
+ /// All of the values outside of the noise map are assumed to have a
+ /// common value known as the <i>border value</i>.
+ ///
+ /// To set the border value, call the SetBorderValue() method.
+ ///
+ /// The GetValue() method returns the border value if the specified value
+ /// lies outside of the noise map.
+ ///
+ /// <b>Internal Noise Map Structure</b>
+ ///
+ /// Internally, the values are organized into horizontal rows called @a
+ /// slabs. Slabs are ordered from bottom to top.
+ ///
+ /// Each slab contains a contiguous row of values in memory. The values
+ /// in a slab are organized left to right.
+ ///
+ /// The offset between the starting points of any two adjacent slabs is
+ /// called the <i>stride amount</i>. The stride amount is measured by
+ /// the number of @a float values between these two starting points, not
+ /// by the number of bytes. For efficiency reasons, the stride is often a
+ /// multiple of the machine word size.
+ ///
+ /// The GetSlabPtr() and GetConstSlabPtr() methods allow you to retrieve
+ /// pointers to the slabs themselves.
+ class NoiseMap
+ {
+
+ public:
+
+ /// Constructor.
+ ///
+ /// Creates an empty noise map.
+ NoiseMap ();
+
+ /// Constructor.
+ ///
+ /// @param width The width of the new noise map.
+ /// @param height The height of the new noise map.
+ ///
+ /// @pre The width and height values are positive.
+ /// @pre The width and height values do not exceed the maximum
+ /// possible width and height for the noise map.
+ ///
+ /// @throw noise::ExceptionInvalidParam See the preconditions.
+ /// @throw noise::ExceptionOutOfMemory Out of memory.
+ ///
+ /// Creates a noise map with uninitialized values.
+ ///
+ /// It is considered an error if the specified dimensions are not
+ /// positive.
+ NoiseMap (int width, int height);
+
+ /// Copy constructor.
+ ///
+ /// @throw noise::ExceptionOutOfMemory Out of memory.
+ NoiseMap (const NoiseMap& rhs);
+
+ /// Destructor.
+ ///
+ /// Frees the allocated memory for the noise map.
+ ~NoiseMap ();
+
+ /// Assignment operator.
+ ///
+ /// @throw noise::ExceptionOutOfMemory Out of memory.
+ ///
+ /// @returns Reference to self.
+ ///
+ /// Creates a copy of the noise map.
+ NoiseMap& operator= (const NoiseMap& rhs);
+
+ /// Clears the noise map to a specified value.
+ ///
+ /// @param value The value that all positions within the noise map are
+ /// cleared to.
+ void Clear (float value);
+
+ /// Returns the value used for all positions outside of the noise map.
+ ///
+ /// @returns The value used for all positions outside of the noise
+ /// map.
+ ///
+ /// All positions outside of the noise map are assumed to have a
+ /// common value known as the <i>border value</i>.
+ float GetBorderValue () const
+ {
+ return m_borderValue;
+ }
+
+ /// Returns a const pointer to a slab.
+ ///
+ /// @returns A const pointer to a slab at the position (0, 0), or
+ /// @a NULL if the noise map is empty.
+ const float* GetConstSlabPtr () const
+ {
+ return m_pNoiseMap;
+ }
+
+ /// Returns a const pointer to a slab at the specified row.
+ ///
+ /// @param row The row, or @a y coordinate.
+ ///
+ /// @returns A const pointer to a slab at the position ( 0, @a row ),
+ /// or @a NULL if the noise map is empty.
+ ///
+ /// @pre The coordinates must exist within the bounds of the noise
+ /// map.
+ ///
+ /// This method does not perform bounds checking so be careful when
+ /// calling it.
+ const float* GetConstSlabPtr (int row) const
+ {
+ return GetConstSlabPtr (0, row);
+ }
+
+ /// Returns a const pointer to a slab at the specified position.
+ ///
+ /// @param x The x coordinate of the position.
+ /// @param y The y coordinate of the position.
+ ///
+ /// @returns A const pointer to a slab at the position ( @a x, @a y ),
+ /// or @a NULL if the noise map is empty.
+ ///
+ /// @pre The coordinates must exist within the bounds of the noise
+ /// map.
+ ///
+ /// This method does not perform bounds checking so be careful when
+ /// calling it.
+ const float* GetConstSlabPtr (int x, int y) const
+ {
+ return m_pNoiseMap + (size_t)x + (size_t)m_stride * (size_t)y;
+ }
+
+ /// Returns the height of the noise map.
+ ///
+ /// @returns The height of the noise map.
+ int GetHeight () const
+ {
+ return m_height;
+ }
+
+ /// Returns the amount of memory allocated for this noise map.
+ ///
+ /// @returns The amount of memory allocated for this noise map.
+ ///
+ /// This method returns the number of @a float values allocated.
+ size_t GetMemUsed () const
+ {
+ return m_memUsed;
+ }
+
+ /// Returns a pointer to a slab.
+ ///
+ /// @returns A pointer to a slab at the position (0, 0), or @a NULL if
+ /// the noise map is empty.
+ float* GetSlabPtr ()
+ {
+ return m_pNoiseMap;
+ }
+
+ /// Returns a pointer to a slab at the specified row.
+ ///
+ /// @param row The row, or @a y coordinate.
+ ///
+ /// @returns A pointer to a slab at the position ( 0, @a row ), or
+ /// @a NULL if the noise map is empty.
+ ///
+ /// @pre The coordinates must exist within the bounds of the noise
+ /// map.
+ ///
+ /// This method does not perform bounds checking so be careful when
+ /// calling it.
+ float* GetSlabPtr (int row)
+ {
+ return GetSlabPtr (0, row);
+ }
+
+ /// Returns a pointer to a slab at the specified position.
+ ///
+ /// @param x The x coordinate of the position.
+ /// @param y The y coordinate of the position.
+ ///
+ /// @returns A pointer to a slab at the position ( @a x, @a y ) or
+ /// @a NULL if the noise map is empty.
+ ///
+ /// @pre The coordinates must exist within the bounds of the noise
+ /// map.
+ ///
+ /// This method does not perform bounds checking so be careful when
+ /// calling it.
+ float* GetSlabPtr (int x, int y)
+ {
+ return m_pNoiseMap + (size_t)x + (size_t)m_stride * (size_t)y;
+ }
+
+ /// Returns the stride amount of the noise map.
+ ///
+ /// @returns The stride amount of the noise map.
+ ///
+ /// - The <i>stride amount</i> is the offset between the starting
+ /// points of any two adjacent slabs in a noise map.
+ /// - The stride amount is measured by the number of @a float values
+ /// between these two points, not by the number of bytes.
+ int GetStride () const
+ {
+ return m_stride;
+ }
+
+ /// Returns a value from the specified position in the noise map.
+ ///
+ /// @param x The x coordinate of the position.
+ /// @param y The y coordinate of the position.
+ ///
+ /// @returns The value at that position.
+ ///
+ /// This method returns the border value if the coordinates exist
+ /// outside of the noise map.
+ float GetValue (int x, int y) const;
+
+ /// Returns the width of the noise map.
+ ///
+ /// @returns The width of the noise map.
+ int GetWidth () const
+ {
+ return m_width;
+ }
+
+ /// Reallocates the noise map to recover wasted memory.
+ ///
+ /// @throw noise::ExceptionOutOfMemory Out of memory. (Yes, this
+ /// method can return an out-of-memory exception because two noise
+ /// maps will temporarily exist in memory during this call.)
+ ///
+ /// The contents of the noise map is unaffected.
+ void ReclaimMem ();
+
+ /// Sets the value to use for all positions outside of the noise map.
+ ///
+ /// @param borderValue The value to use for all positions outside of
+ /// the noise map.
+ ///
+ /// All positions outside of the noise map are assumed to have a
+ /// common value known as the <i>border value</i>.
+ void SetBorderValue (float borderValue)
+ {
+ m_borderValue = borderValue;
+ }
+
+ /// Sets the new size for the noise map.
+ ///
+ /// @param width The new width for the noise map.
+ /// @param height The new height for the noise map.
+ ///
+ /// @pre The width and height values are positive.
+ /// @pre The width and height values do not exceed the maximum
+ /// possible width and height for the noise map.
+ ///
+ /// @throw noise::ExceptionInvalidParam See the preconditions.
+ /// @throw noise::ExceptionOutOfMemory Out of memory.
+ ///
+ /// On exit, the contents of the noise map are undefined.
+ ///
+ /// If the @a OUT_OF_MEMORY exception occurs, this noise map object
+ /// becomes empty.
+ ///
+ /// If the @a INVALID_PARAM exception occurs, the noise map is
+ /// unmodified.
+ void SetSize (int width, int height);
+
+ /// Sets a value at a specified position in the noise map.
+ ///
+ /// @param x The x coordinate of the position.
+ /// @param y The y coordinate of the position.
+ /// @param value The value to set at the given position.
+ ///
+ /// This method does nothing if the noise map object is empty or the
+ /// position is outside the bounds of the noise map.
+ void SetValue (int x, int y, float value);
+
+ /// Takes ownership of the buffer within the source noise map.
+ ///
+ /// @param source The source noise map.
+ ///
+ /// On exit, the source noise map object becomes empty.
+ ///
+ /// This method only moves the buffer pointer so this method is very
+ /// quick.
+ void TakeOwnership (NoiseMap& source);
+
+ private:
+
+ /// Returns the minimum amount of memory required to store a noise map
+ /// of the specified size.
+ ///
+ /// @param width The width of the noise map.
+ /// @param height The height of the noise map.
+ ///
+ /// @returns The minimum amount of memory required to store the noise
+ /// map.
+ ///
+ /// The returned value is measured by the number of @a float values
+ /// required to store the noise map, not by the number of bytes.
+ size_t CalcMinMemUsage (int width, int height) const
+ {
+ return CalcStride ((size_t)width) * (size_t)height;
+ }
+
+ /// Calculates the stride amount for a noise map.
+ ///
+ /// @param width The width of the noise map.
+ ///
+ /// @returns The stride amount.
+ ///
+ /// - The <i>stride amount</i> is the offset between the starting
+ /// points of any two adjacent slabs in a noise map.
+ /// - The stride amount is measured by the number of @a float values
+ /// between these two points, not by the number of bytes.
+ size_t CalcStride (int width) const
+ {
+ return (size_t)(((width + RASTER_STRIDE_BOUNDARY - 1)
+ / RASTER_STRIDE_BOUNDARY) * RASTER_STRIDE_BOUNDARY);
+ }
+
+ /// Copies the contents of the buffer in the source noise map into
+ /// this noise map.
+ ///
+ /// @param source The source noise map.
+ ///
+ /// @throw noise::ExceptionOutOfMemory Out of memory.
+ ///
+ /// This method reallocates the buffer in this noise map object if
+ /// necessary.
+ ///
+ /// @warning This method calls the standard library function
+ /// @a memcpy, which probably violates the DMCA because it can be used
+ //. to make a bitwise copy of anything, like, say, a DVD. Don't call
+ /// this method if you live in the USA.
+ void CopyNoiseMap (const NoiseMap& source);
+
+ /// Resets the noise map object.
+ ///
+ /// This method is similar to the InitObj() method, except this method
+ /// deletes the buffer in this noise map.
+ void DeleteNoiseMapAndReset ();
+
+ /// Initializes the noise map object.
+ ///
+ /// @pre Must be called during object construction.
+ /// @pre The noise map buffer must not exist.
+ void InitObj ();
+
+ /// Value used for all positions outside of the noise map.
+ float m_borderValue;
+
+ /// The current height of the noise map.
+ int m_height;
+
+ /// The amount of memory allocated for this noise map.
+ ///
+ /// This value is equal to the number of @a float values allocated for
+ /// the noise map, not the number of bytes.
+ size_t m_memUsed;
+
+ /// A pointer to the noise map buffer.
+ float* m_pNoiseMap;
+
+ /// The stride amount of the noise map.
+ int m_stride;
+
+ /// The current width of the noise map.
+ int m_width;
+
+ };
+
+ /// Implements an image, a 2-dimensional array of color values.
+ ///
+ /// An image can be used to store a color texture.
+ ///
+ /// These color values are of type Color.
+ ///
+ /// The size (width and height) of the image can be specified during
+ /// object construction or at any other time.
+ ///
+ /// The GetValue() and SetValue() methods can be used to access individual
+ /// color values stored in the image.
+ ///
+ /// This class manages its own memory. If you copy an image object into
+ /// another image object, the original contents of the image object will
+ /// be freed.
+ ///
+ /// If you specify a new size for the image and the new size is smaller
+ /// than the current size, the allocated memory will not be reallocated.
+ /// Call ReclaimMem() to reclaim the wasted memory.
+ ///
+ /// <b>Border Values</b>
+ ///
+ /// All of the color values outside of the image are assumed to have a
+ /// common color value known as the <i>border value</i>.
+ ///
+ /// To set the border value, call the SetBorderValue() method.
+ ///
+ /// The GetValue() method returns the border value if the specified
+ /// position lies outside of the image.
+ ///
+ /// <b>Internal Image Structure</b>
+ ///
+ /// Internally, the color values are organized into horizontal rows called
+ /// @a slabs. Slabs are ordered from bottom to top.
+ ///
+ /// Each slab contains a contiguous row of color values in memory. The
+ /// color values in a slab are organized left to right. These values are
+ /// of type Color.
+ ///
+ /// The offset between the starting points of any two adjacent slabs is
+ /// called the <i>stride amount</i>. The stride amount is measured by the
+ /// number of Color objects between these two starting points, not by the
+ /// number of bytes. For efficiency reasons, the stride is often a
+ /// multiple of the machine word size.
+ ///
+ /// The GetSlabPtr() methods allow you to retrieve pointers to the slabs
+ /// themselves.
+ class Image
+ {
+
+ public:
+
+ /// Constructor.
+ ///
+ /// Creates an empty image.
+ Image ();
+
+ /// Constructor.
+ ///
+ /// @param width The width of the new image.
+ /// @param height The height of the new image.
+ ///
+ /// @pre The width and height values are positive.
+ /// @pre The width and height values do not exceed the maximum
+ /// possible width and height for the image.
+ ///
+ /// @throw noise::ExceptionInvalidParam See the preconditions.
+ /// @throw noise::ExceptionOutOfMemory Out of memory.
+ ///
+ /// Creates an image with uninitialized color values.
+ ///
+ /// It is considered an error if the specified dimensions are not
+ /// positive.
+ Image (int width, int height);
+
+ /// Copy constructor.
+ ///
+ /// @throw noise::ExceptionOutOfMemory Out of memory.
+ Image (const Image& rhs);
+
+ /// Destructor.
+ ///
+ /// Frees the allocated memory for the image.
+ ~Image ();
+
+ /// Assignment operator.
+ ///
+ /// @throw noise::ExceptionOutOfMemory Out of memory.
+ ///
+ /// @returns Reference to self.
+ ///
+ /// Creates a copy of the image.
+ Image& operator= (const Image& rhs);
+
+ /// Clears the image to a specified color value.
+ ///
+ /// @param value The color value that all positions within the image
+ /// are cleared to.
+ void Clear (const Color& value);
+
+ /// Returns the color value used for all positions outside of the
+ /// image.
+ ///
+ /// @returns The color value used for all positions outside of the
+ /// image.
+ ///
+ /// All positions outside of the image are assumed to have a common
+ /// color value known as the <i>border value</i>.
+ Color GetBorderValue () const
+ {
+ return m_borderValue;
+ }
+
+ /// Returns a const pointer to a slab.
+ ///
+ /// @returns A const pointer to a slab at the position (0, 0), or
+ /// @a NULL if the image is empty.
+ const Color* GetConstSlabPtr () const
+ {
+ return m_pImage;
+ }
+
+ /// Returns a const pointer to a slab at the specified row.
+ ///
+ /// @param row The row, or @a y coordinate.
+ ///
+ /// @returns A const pointer to a slab at the position ( 0, @a row ),
+ /// or @a NULL if the image is empty.
+ ///
+ /// @pre The coordinates must exist within the bounds of the image.
+ ///
+ /// This method does not perform bounds checking so be careful when
+ /// calling it.
+ const Color* GetConstSlabPtr (int row) const
+ {
+ return GetConstSlabPtr (0, row);
+ }
+
+ /// Returns a const pointer to a slab at the specified position.
+ ///
+ /// @param x The x coordinate of the position.
+ /// @param y The y coordinate of the position.
+ ///
+ /// @returns A const pointer to a slab at the position ( @a x, @a y ),
+ /// or @a NULL if the image is empty.
+ ///
+ /// @pre The coordinates must exist within the bounds of the image.
+ ///
+ /// This method does not perform bounds checking so be careful when
+ /// calling it.
+ const Color* GetConstSlabPtr (int x, int y) const
+ {
+ return m_pImage + (size_t)x + (size_t)m_stride * (size_t)y;
+ }
+
+ /// Returns the height of the image.
+ ///
+ /// @returns The height of the image.
+ int GetHeight () const
+ {
+ return m_height;
+ }
+
+ /// Returns the amount of memory allocated for this image.
+ ///
+ /// @returns The amount of memory allocated for this image.
+ ///
+ /// This method returns the number of Color objects allocated.
+ size_t GetMemUsed () const
+ {
+ return m_memUsed;
+ }
+
+ /// Returns a pointer to a slab.
+ ///
+ /// @returns A pointer to a slab at the position (0, 0), or @a NULL if
+ /// the image is empty.
+ Color* GetSlabPtr ()
+ {
+ return m_pImage;
+ }
+
+ /// Returns a pointer to a slab at the specified row.
+ ///
+ /// @param row The row, or @a y coordinate.
+ ///
+ /// @returns A pointer to a slab at the position ( 0, @a row ), or
+ /// @a NULL if the image is empty.
+ ///
+ /// @pre The coordinates must exist within the bounds of the image.
+ ///
+ /// This method does not perform bounds checking so be careful when
+ /// calling it.
+ Color* GetSlabPtr (int row)
+ {
+ return GetSlabPtr (0, row);
+ }
+
+ /// Returns a pointer to a slab at the specified position.
+ ///
+ /// @param x The x coordinate of the position.
+ /// @param y The y coordinate of the position.
+ ///
+ /// @returns A pointer to a slab at the position ( @a x, @a y ), or
+ /// @a NULL if the image is empty.
+ ///
+ /// @pre The coordinates must exist within the bounds of the image.
+ ///
+ /// This method does not perform bounds checking so be careful when
+ /// calling it.
+ Color* GetSlabPtr (int x, int y)
+ {
+ return m_pImage + (size_t)x + (size_t)m_stride * (size_t)y;
+ }
+
+ /// Returns the stride amount of the image.
+ ///
+ /// @returns The stride amount of the image.
+ ///
+ /// - The <i>stride amount</i> is the offset between the starting
+ /// points of any two adjacent slabs in an image.
+ /// - The stride amount is measured by the number of Color objects
+ /// between these two points, not by the number of bytes.
+ int GetStride () const
+ {
+ return m_stride;
+ }
+
+ /// Returns a color value from the specified position in the image.
+ ///
+ /// @param x The x coordinate of the position.
+ /// @param y The y coordinate of the position.
+ ///
+ /// @returns The color value at that position.
+ ///
+ /// This method returns the border value if the coordinates exist
+ /// outside of the image.
+ Color GetValue (int x, int y) const;
+
+ /// Returns the width of the image.
+ ///
+ /// @returns The width of the image.
+ int GetWidth () const
+ {
+ return m_width;
+ }
+
+ /// Reallocates the image to recover wasted memory.
+ ///
+ /// @throw noise::ExceptionOutOfMemory Out of memory. (Yes, this
+ /// method can return an out-of-memory exception because two images
+ /// will exist temporarily in memory during this call.)
+ ///
+ /// The contents of the image is unaffected.
+ void ReclaimMem ();
+
+ /// Sets the color value to use for all positions outside of the
+ /// image.
+ ///
+ /// @param borderValue The color value to use for all positions
+ /// outside of the image.
+ ///
+ /// All positions outside of the image are assumed to have a common
+ /// color value known as the <i>border value</i>.
+ void SetBorderValue (const Color& borderValue)
+ {
+ m_borderValue = borderValue;
+ }
+
+ /// Sets the new size for the image.
+ ///
+ /// @param width The new width for the image.
+ /// @param height The new height for the image.
+ ///
+ /// @pre The width and height values are positive.
+ /// @pre The width and height values do not exceed the maximum
+ /// possible width and height for the image.
+ ///
+ /// @throw noise::ExceptionInvalidParam See the preconditions.
+ /// @throw noise::ExceptionOutOfMemory Out of memory.
+ ///
+ /// On exit, the contents of the image are undefined.
+ ///
+ /// If the @a OUT_OF_MEMORY exception occurs, this image becomes
+ /// empty.
+ / |