diff options
Diffstat (limited to 'noiseutils/noiseutils.h')
| -rw-r--r-- | noiseutils/noiseutils.h | 2540 |
1 files changed, 0 insertions, 2540 deletions
diff --git a/noiseutils/noiseutils.h b/noiseutils/noiseutils.h deleted file mode 100644 index d54f61d..0000000 --- a/noiseutils/noiseutils.h +++ /dev/null @@ -1,2540 +0,0 @@ -// 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.
- ///
- /// If the @a INVALID_PARAM exception occurs, the image is unmodified.
|