image.h

Go to the documentation of this file.

/*! \file
  \brief  The Image class.  All textures are converted internally into Images.
 
  \par Copyright Information
 
  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>
 
  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.
 
  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
 
  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).
 
  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.
 
*/
 
#ifndef _IMAGE_LIB_H
#define _IMAGE_LIB_H
 
#include "IFontImage.h"
#include "file_path_class.h"
#include "gls_include.h"
#include "list.h"
#include "util.h"
#include <stdio.h>
 
#ifdef QNX
#    include <time.h>
#endif
 
namespace disti
{
class Mutex;
const int IMG_TRANSPARENT     = 0;   /**< Alpha value for a transparent pixel */
const int IMG_NON_TRANSPARENT = 255; /**< Alpha value for a non-transparent pixel */
const int MAX_MIP_MAP_IMAGES  = 16;  /**< Maximum number of mipmapping levels */
 
/// \details The glsImageCodec enum. Describes the compression level of a texture.
typedef enum
{
    GLS_CODEC_RAW,  /**< Image data is not compressed */
    GLS_CODEC_LZ77, /**< Image data is compressed with LZ77 (Z-Lib) */
    GLS_CODEC_JPEG  /**< Image data is compressed with lossy JPEG */
} glsImageCodec;
 
/// \details The ImageNPOTMode enum. Describes whether NPOT textures are allowed.
typedef enum
{
    GLS_NPOT_AUTO,    /**< Allow Non Power Of Two textures if able */
    GLS_NPOT_ENABLED, /**< Always allow Non Power Of Two textures */
    GLS_NPOT_DISABLED /**< Never allow Non Power Of Two textures */
} ImageNPOTMode;
 
/** The glsInlineImage structure.  This structure is generated and contains information needed to
  * create reconstruct an inline generated image.
  */
struct glsInlineImage
{
    typedef const unsigned char* const _BufferType;             ///< Typedef for the type of buffer used by images.
    unsigned int                       _width;                  ///< Width of image in pixels.
    unsigned int                       _height;                 ///< Height of image in pixels.
    unsigned int                       _components;             ///< Number of components in image.
    unsigned int                       _pixel_format;           ///< GL_RGB, GL_RGBA ...
    glsImageCodec                      _codec;                  ///< CODEC used to compress image.
    unsigned long                      _crc;                    ///< CRC of image data (compressed or uncompressed?).
    bool                               _gl_texture_compression; ///< Value of GlTextureCompression.
    unsigned long                      _image_data_size;        ///< Size of RGB data (compressed).
    unsigned long                      _alpha_data_size;        ///< Size of Alpha data (compressed). Zero if no alpha channel present.
    unsigned int                       _line_length;            ///< Length of each line of inline data, in bytes.
    _BufferType*                       _rgb_buffer;             ///< Pointer to the static compressed rgb buffer for the image.
    _BufferType*                       _alpha_buffer;           ///< Pointer to the static compressed alpha layer for the image.
 
    /// Constructor
    /// \param width Width of image in pixels.
    /// \param height Height of image in pixels.
    /// \param components Number of components in image.
    /// \param pixel_format GL_RGB, GL_RGBA ...
    /// \param codec CODEC used to compress image.
    /// \param crc CRC of image data (compressed or uncompressed?).
    /// \param gl_tex_compress Value of GlTextureCompression.
    /// \param image_data_size Size of RGB data (compressed).
    /// \param alpha_data_size Size of Alpha data (compressed). Zero if no alpha channel present.
    /// \param line_length Length of each line of inline data, in bytes.
    /// \param rgb_buffer Pointer to the static compressed rgb buffer for the image.
    /// \param alpha_buffer Pointer to the static compressed alpha layer for the image.
    glsInlineImage( unsigned int    width,
        unsigned int                height,
        unsigned int                components,
        unsigned int                pixel_format,
        glsImageCodec               codec,
        unsigned long               crc,
        bool                        gl_tex_compress,
        unsigned long               image_data_size,
        unsigned long               alpha_data_size,
        unsigned int                line_length,
        const unsigned char* const* rgb_buffer,
        const unsigned char* const* alpha_buffer )
        : _width( width )
        , _height( height )
        , _components( components )
        , _pixel_format( pixel_format )
        , _codec( codec )
        , _crc( crc )
        , _gl_texture_compression( gl_tex_compress )
        , _image_data_size( image_data_size )
        , _alpha_data_size( alpha_data_size )
        , _line_length( line_length )
        , _rgb_buffer( rgb_buffer )
        , _alpha_buffer( alpha_buffer )
    {
    }
};
 
/** Enable/Disable global Non Power Of Two capability.  This will override the 
  * texture's setting from the editor.
  * \note NPOT detection is not currently supported. (GLS-5940)
  * \param state The state to set it to.  Will enable, disable, or apply auto detection
                 for if NPOT support is available.
  */
GLS_EXPORT void SetNPOTState( ImageNPOTMode state );
 
/** Determines if Non Power Of Two textures are supported.
  * \return GLS_NPOT_ENABLED if NPOT textures are supported, GLS_NPOT_DISABLED otherwise.
  */
GLS_EXPORT ImageNPOTMode DoesSystemSupportNPOT();
 
/** By default, Image instances release their texture data in main memory after loading it to the GPU. 
  * This flag controls that default behavior for new Image instances. Set to false if you want all
  * Images to keep a copy of their texture data loaded in main memory. (Note: This can dramatically
  * increase memory usage.)
  * 
  * \note The default applies only to Image instances created after this flag is set. To set or get
  *       the value behavior for a particular Image instance, call Image::SetReleaseImageDataEnabled()
  *       or Image::IsReleaseImageDataEnabled(), respectively.
  *
  * \note Default value: true
  * 
  * \param enable The new default value
  * 
  * \sa disti::Image::SetReleaseImageDataEnabled(), disti::Image::IsReleaseImageDataEnabled()
  */
GLS_EXPORT void SetReleaseImageDataDefault( bool enable );
 
/// See SetReleaseImageDataDefault() for more details.
/// \sa disti::SetReleaseImageDataDefault( bool )
/// \return The current value for the flag controlling the default behavior for new Image instances.
GLS_EXPORT bool GetReleaseImageDataDefault();
 
/**
  The Image class.  Implements loading 2D image files.
*/
class Image
    : virtual public IFontImage
{
protected:
    unsigned int _textureHandle; /**< The texture handle of the image. */
    int          _pixelFormat;   /**< Pixel format for the image */
    int          _pixelSize;     /**< Size of a pixel in bytes */
    int          _errorFound;    /**< Error found reading image file flag. */
    char*        _errorMessage;  /**< Error message in string format. */
    int          _width;         /**< Actual width of image in pixels. */
    int          _height;        /**< Actual height of image in pixels. */
    int          _texWidth;      /**< Texture width (power of 2) of the image in pixels. */
    int          _texHeight;     /**< Texture height (power of 2) of the image in pixels. */
 
    float _texCoord[ 2 ]; /**< Texture coordinates of upper right corner
                                    * of image. This will be (1.0,1.0) for a
                                    * square power of two image */
 
    unsigned char* _rgbBuf; /**< Pointer to the image data for this image. */
 
    bool           _mipMap;                      /**< True if this image should use mip mapping */
    unsigned char* _mmBuf[ MAX_MIP_MAP_IMAGES ]; /**< Pointers to the smaller versions of _rgbBuf */
 
    unsigned long _crcValue; /**< CRC value used to determine if two images are the same */
 
    int _numUsers; /**< Count of number of objects that reference this one */
 
    bool _replaceImageFlag; /**< Indicates the images has been changed and needs to be re-bound */
 
    bool _releaseImageData; /**< true to allow image data for image to be unloaded from main memory else false */
 
    static bool _glTextureCompressionSupported; /**< Indicates if GL Texture compression is supported on the
                                                  Machine that this program is running on. */
 
    bool _glTextureCompression; /**< Indicates if GL Texture compression is enabled for this image */
 
    glsInlineImage* _staticInlineImage; /**< Inline image data for this image, if applicable. */
 
    bool _allowImageSharing; /**< If false, causes Image::CrcValue() to always return 0, disabling duplicate checking. */
 
    bool _allowNPOT; /**< If true, this texture is not scaled to power of two. */
 
#ifdef GLES
    unsigned int _stateManagerHandle; /**< Handle used by the OpenGL ES state manager to quickly find this texture */
#endif
 
    /** Convert Luminance Alpha texture to Alpha texture.
      * Used on OpenGL ES target to speedup texturing for fonts
      */
    void ConvertLuminanceAlphaToAlpha();
 
public:
    static GLS_EXPORT bool _globalMipMapEnabled; /**< Determines the default value for _mipMap, and does not
                                                   * do mip mapping if false */
 
    /// All images get added to the InstanceList.
    /// \return A modifiable refernce to the image list.
    static GLS_EXPORT List_c& InstanceList();
 
    /// Use this Mutex when accessing the InstanceList.
    /// \return A mutex for accessing the image list.
    static GLS_EXPORT disti::Mutex& InstanceListMutex();
 
    /** Empties the InstanceList
      * This is done when loading objects which will be drawn in different
      * OpenGL contexts.
      */
    static GLS_EXPORT void EmptyInstanceList();
 
    /** Determines whether this image will release its image data from main memory when it is not needed.
      *
      * When enabled (true), the the Image will release the main memory copy of the data when it is not
      * needed in order to save memory. This flag is enabled by default and should be disabled in situations
      * such as when the ImageData for this Image cannot be re-created from permanent storage.
      *
      * \note The default value is determined by disti::GetReleaseImageDataDefault().
      * 
      * \param enable Whether release of image data is enabled.
      * 
      * \sa IsReleaseImageDataEnabled()
      * \sa disti::SetReleaseImageDataDefault()
      * 
      * \note The static methods SetUnloadImageDataEnabled() and IsUnloadImageDataEnabled() from Image and Image::InstanceListEntry
      * were removed to disambiguate between the per-instance setting and the global setting. Code that was calling 
      * Image::SetUnloadImageDataEnabled() to set the default flag for all instances should now call disti::SetReleaseImageDataDefault(). 
      * Code that was calling Image::InstanceListEntry::SetUnloadImageDataEnabled() to set the flag for only one instance 
      * should call this method.
      */
    GLS_EXPORT void SetReleaseImageDataEnabled( bool enable );
 
    /// \return Whether or not release of image data is enabled.
    /// \sa SetReleaseImageDataEnabled()
    /// \sa disti::GetReleaseImageDataDefault()
    /// \note The static methods SetUnloadImageDataEnabled() and IsUnloadImageDataEnabled() from Image and Image::InstanceListEntry
    /// were removed to disambiguate between the per-instance setting and the global setting. Code that was calling
    /// Image::IsUnloadImageDataEnabled() to get the default flag for all instances should now call disti::GetReleaseImageDataDefault().
    /// Code that was calling Image::InstanceListEntry::IsUnloadImageDataEnabled() to get the flag for only one instance
    /// should call this method.
    GLS_EXPORT bool IsReleaseImageDataEnabled();
 
#ifdef GLES
    /** see IFontImage */
    virtual unsigned int StateManagerHandle() const { return _stateManagerHandle; }
 
    /** see IFontImage */
    virtual void StateManagerHandle( unsigned int handle ) { _stateManagerHandle = handle; }
#endif
 
    /** These are options that are possibly used during loading of the image. */
    class LoadOptions
    {
    public:
        LoadOptions()
            : _reverseAlpha( FALSE )
        {
        }
 
        bool _reverseAlpha; ///< For compatibility with images with the alpha channel reversed.
 
        /// Equality operator
        /// \param rhs The object to compare against.
        /// \return Whether or not the objects are equal.
        bool operator==( const LoadOptions& rhs ) const
        {
            return ( _reverseAlpha == rhs._reverseAlpha );
        }
    }; // class LoadOptions
 
    /** an entry in the Image::InstanceList */
    class InstanceListEntry
    {
    public:
        /** holds absolute file path, file size, mod time and image load options */
        class FileID
        {
        public:
            /** default ctor - no file */
            GLS_EXPORT FileID();
 
            /** ctor
              * \param path path for file ( can be relative or absolute, will ultimately be stored in the FileID as an absolute path )
              * \param loadOptions image loading options for file
              */
            GLS_EXPORT FileID( const FilePathClass& path, const LoadOptions& loadOptions );
 
            /** copy ctor
              * \param src FileID to copy
              */
            GLS_EXPORT FileID( const FileID& src );
 
            /** get the absolute path for the file
              * \return the absolute path for the file
              */
            GLS_EXPORT const FilePathClass& GetPath() const;
 
            /** get the image load options for the file
              * \return the image load options for the file
              */
            GLS_EXPORT const LoadOptions& GetLoadOptions() const;
 
            /** get the file size for the file
              * \return the file size for the file
              */
            GLS_EXPORT off_t GetFileSize() const;
 
            /** get the modification time for the file
              * \return the modification time for the file
              */
            GLS_EXPORT time_t GetModTime() const;
 
            /** compare two FileID's checking for same absolute path and load options
              * \note file size and mod time are not compared here, just absolute path and load options
              * \param rhs FileID to compare
              * \return true if equal absolute paths and load options
              */
            GLS_EXPORT bool operator==( const FileID& rhs ) const;
 
            /// Assigment operator
            /// \param rhs The object to copy from.
            /// \return The resulting object (this).
            GLS_EXPORT FileID& operator=( const FileID& rhs );
 
            /** get the absolute path for the given path
              * \param imgPath path in question
              * \return the absolute path for the given path
              */
            static FilePathClass GetAbsoluteFilePath( const FilePathClass& imgPath );
 
        protected:
            FilePathClass _path;        /**< absolute path for image file */
            LoadOptions   _loadOptions; /**< load options associated with image */
            off_t         _fileSize;    /**< size in bytes of image file */
            time_t        _modTime;     /**< file mod time for image file */
        };                              // class FileID
 
        /** array of FileID */
        typedef DynamicArray<FileID> FileIDArray;
 
        /** ctor
          * \param img image for list entry
          * \param imgPath [optional, defaults to ""] optional path to image file associated with image
          * \param imgLoadOptions [optional] optional load options associated with image
          */
        GLS_EXPORT InstanceListEntry( Image* img, const FilePathClass& imgPath = FilePathClass(), const LoadOptions& imgLoadOptions = LoadOptions() );
 
        /** dtor -- NOTE: image associated with entry is not destroyed */
        GLS_EXPORT ~InstanceListEntry();
 
        /** get the image associated with the entry
          * \return the image associated with the entry
          */
        GLS_EXPORT Image* GetImage();
 
        /** get the image files associated with the entry
          * \return the image files associated with the entry
          */
        GLS_EXPORT FileIDArray& GetAssociatedFiles();
 
        /** determine if the given fileID is associated with this entry
          * \param fileID file ID in question
          * \param foundFileID [out] receives associated file ID if the given fileID is associated with this entry
          * \return true if the given fileID is associated with this entry else false
          */
        GLS_EXPORT bool FileIsAssociatedWithImage( const FileID& fileID, FileID& foundFileID );
 
        /** associate the given fileID with the image in this entry
          * \param fileID file ID in question
          */
        GLS_EXPORT void AssociateFileWithImage( const FileID& fileID );
 
        /** disassociate the given fileID with the image in this entry
          * \param fileID file ID in question
          */
        GLS_EXPORT void DisassociateFileWithImage( const FileID& fileID );
 
        /** Attempt to reload the associated image from an associated image file. Associated image will
          * be marked as no longer being a candidate for unloading.
          * NOTE: Image::InstanceListMutex() cannot be locked when calling this method
          * \return true if reload succeeded else false
          * \pre Image::InstanceListMutex() is not locked
          */
        GLS_EXPORT bool ReloadImageFromFile();
 
    protected:
        Image*      _img;             /**< image associated with entry */
        FileIDArray _associatedFiles; /**< files associated with image else empty array */
 
    private:
        // disallow
        InstanceListEntry( const InstanceListEntry& src );
        InstanceListEntry operator=( const InstanceListEntry& rhs );
    }; // class InstanceListEntry
 
protected:
    /** Add this image to the Image Sharing Instance List */
    GLS_EXPORT void AddSelfToInstanceList();
 
    /** Set the Image _texWidth, _texHeight, _texWidth, _texCoord[0],
      * and _texCoord[1].  Width and height must be set before calling
      * this function. */
    virtual GLS_EXPORT void SetTexWidthHeight();
 
    /** Allocate and initialize the pixel buffer memory for this image
      * _texWidth, _textHeight and _pixelSize must be initialized prior to
      * calling! _rgbBuf is set to the initialized memory.
      * \param zeroOut  Whether or not to clear the memory to zero on allocation.
      * \return   True if allocated. false on failure.
      */
    virtual GLS_EXPORT bool AllocatePixelMemory( bool zeroOut = true );
 
    /// Allocate memory for Mip-Map images.
    /// \param zeroOut Whether or not to clear the memory to zero on allocation.
    /// \return Whether or not allocation was successful.
    virtual GLS_EXPORT bool AllocateMipMapMemory( bool zeroOut = true );
 
    /// Calculate mip-map images from the main image.
    /// \param reCalc Whether or not to perform the calculation.
    virtual GLS_EXPORT void CalculateMipMapImages( bool reCalc = false );
 
    /** Helper routine used by constructor.  Allocates pixel memory and sets the
      * texture width, height and pixel size
      * \param width   Width of the image
      * \param height  Height of the image
      * \param pixelSize  The size in bytes of each pixel
      */
    virtual GLS_EXPORT void Initialize( int width, int height, int pixelSize );
 
public:
    /** \return  The state of any error found reading image file flag. */
    virtual GLS_EXPORT int ErrorFound();
 
    /** Sets the error message.
      * \param errorMessage  String containing error message.
      */
    virtual GLS_EXPORT void SetError( char* errorMessage );
 
    /// \return The error message found during reading image file
    virtual GLS_EXPORT char* GetError();
 
    /** Draws the image at the current raster position. */
    virtual GLS_EXPORT void Draw();
 
    /** Draws the image at the x,y raster position specified.
      * \param x  X position to draw the image
      * \param y  Y position to draw the image
      */
    virtual GLS_EXPORT void Draw( int x, int y );
 
    /** \return A new image that is a duplicate of this image or NULL if duplication is not possible.
      */
    virtual GLS_EXPORT Image* Clone();
 
    /** \return A pointer to the 2D image data */
    virtual GLS_EXPORT unsigned char* ImageData();
 
    /** \return the X position of the texture coordinate used for the image. */
    virtual GLS_EXPORT float TextureCoordX();
 
    /** \return the Y position of the texture coordinate used for the image. */
    virtual GLS_EXPORT float TextureCoordY();
 
    /** \return the texture width of the image file.  This is the power
      * of 2 size greater than or equal to the size of the image.
      */
    virtual GLS_EXPORT int TextureWidth();
 
    /** \return the texture height of the image file.  This is the power
      * of 2 size greater than or equal the size of the image.
      */
    virtual GLS_EXPORT int TextureHeight();
 
    /** \return the memory size of the image in bytes */
    virtual GLS_EXPORT int Size();
 
    /** \return the width of the image. */
    virtual GLS_EXPORT int Width();
 
    /** \return the height of the image. */
    virtual GLS_EXPORT int Height();
 
    /** \return true if the internal texture handle is valid */
    virtual GLS_EXPORT bool TextureHandleValid();
 
    /** \return the OpenGL texture handle of this texture instance */
    virtual GLS_EXPORT unsigned int TextureHandle() const { return _textureHandle; }
 
    /** Returns the pixel format for this image
      * \return The internal pixel format for this image
      */
    virtual GLS_EXPORT int PixelFormat();
 
    /** Sets the pixel format for this image and also the pixel size as
      * determined from the format. Eg. GL_RGBA has a pixel size of 4.
      * \param format The new internal pixel format for this image
      */
    virtual GLS_EXPORT void PixelFormat( int format );
 
    /** \return The OpenGL enumerator for the pixel format for this
      * image as a string.  Used for inline texture generation
      */
    virtual GLS_EXPORT char* PixelFormatString();
 
    /** \return The size of a pixel in this image in bytes */
    virtual GLS_EXPORT int PixelSize();
 
    /// \return A pointer to the memory location corresponding to the given X,Y position within the image.
    /// \param x The X raster position.
    /// \param y The Y raster position.
    virtual GLS_EXPORT unsigned char* GetRasterPosition( int x, int y );
 
    /** Set the value of a secific pixel in the rbg buffer.
      * \param x      X position of the pixel
      * \param y      Y position of the pixel
      * \param color  Color of the pixel
      */
    virtual GLS_EXPORT void SetPixel( int x, int y, float color[] );
 
    /** Takes the image and creates a 2D Decal texture map. (Not Implemented)*/
    virtual GLS_EXPORT void SetAsCurrentTexture();
 
    /** Create a new texture object using Image object data. */
    virtual GLS_EXPORT void AllocateTextureBinding();
 
    /** Deletes the OpenGL texture object for this Image. */
    virtual GLS_EXPORT void DeallocateTextureBinding();
 
    /** Make this Image object the active texture. */
    virtual GLS_EXPORT void BindTexture();
 
    /** Create an Image object with the specified image data and image size.
      * \param data    Pointer to the image data
      * \param width   Width of the image
      * \param height  Height of the image
      * \param pixelFormat  The format of each pixel, eg. GL_RGBA
      */
    GLS_EXPORT Image( const unsigned char* const data, int width, int height, int pixelFormat );
 
    /** Create an Image object with the specified image size.
      * \param width      Width of the image
      * \param height     Height of the image
      * \param pixelSize  The size in bytes of each pixel
      * \param allowNPOT  If the image is allowed to be non-power of two (NPOT)
      */
    GLS_EXPORT Image( int width, int height, int pixelSize, bool allowNPOT = false );
 
    /** Create an Image from an inline image (GL Studio 2.2 and later API)
      * \param image  Structure containing details of inline image
      */
    GLS_EXPORT Image( const glsInlineImage& image );
 
    /** Create an Image from a buffer of ZLIB compressed data
      * Image data must already be a power of two!
      * \param width       Width of the image
      * \param height      Height of the image
      * \param components  The size in bytes of each pixel
      * \param format      The OpenGL texture format to use
      * \param comprLen    The size of the compressed image
      * \param data        The buffer of compressed data
      * \param crcVal      The CRC value used to find duplicate textures
      * \param lineLength  The number of bytes in each inline image line
      */
    GLS_EXPORT Image( int width, int height, int components, int format, unsigned int comprLen, const unsigned char* const data[], unsigned long crcVal = 0, int lineLength = 320 );
 
    /** Create an Image from a buffer of uncompressed data
      * Image data must already be a power of two!
      * \param width       Width of the image
      * \param height      Height of the image
      * \param components  The size in bytes of each pixel
      * \param format      The OpenGL texture format to use
      * \param pix        The buffer of uncompressed data
      * \param crcVal      The CRC value used to find duplicate textures
      * \param lineLength  The number of bytes in each inline image line
      */
    GLS_EXPORT Image( int width, int height, int components, int format, const unsigned char* const pix[], unsigned long crcVal = 0, int lineLength = 320 );
 
    /// Copy constructor
    /// \param source The object to copy from.
    GLS_EXPORT Image( const Image& source );
 
    /** Constructor for an Image object. */
    GLS_EXPORT Image();
 
    /// Perform the upload process from the CPU to the GPU.
    GLS_EXPORT void DoTexSubImage();
 
    /** Unload RGB and mipmap data to save memory */
    GLS_EXPORT void UnloadRgbData();
 
protected:
    /** Destroy an Image object. Frees the memory for the RGB buffer. */
    virtual GLS_EXPORT ~Image();
 
public:
    /** Will delete the Image object if nobody is using it */
    virtual GLS_EXPORT void DeleteUsage();
 
    /** Lets this object know that another something is using this image */
    virtual GLS_EXPORT void AddUsage();
 
    /** \return the number of simultanious users of this image */
    virtual GLS_EXPORT int NumUsers();
 
    /// Assignment operator
    /// \param im The object to copy from.
    virtual GLS_EXPORT void operator=( Image& im );
 
    /** Scale the texture to the nearest power of two */
    virtual GLS_EXPORT void ScaleTexture();
 
    /** \return the CRC value for this image.  0 indicates an invalid value or that duplicate checking is disabled for the Image.
      */
    virtual GLS_EXPORT unsigned long CrcValue();
 
    /** Equality operator. Determines if two images are equal
      * \param im  Image to test
      * \return boolean result
      */
    virtual GLS_EXPORT int operator==( Image& im );
 
    /** Determines if an image #1 is the same a notional image based on the following criteria
      * \param image  Image #1
      * \param width       Width of notional image
      * \param height      Height of notional image
      * \param components  Number of components in the notional image
      * \param crcVal      32 bit CRC of notional image
      * \param glTexCompress GlTextureCompresssion setting for the image
      * \return True if they are equal
      */
    static GLS_EXPORT bool IsDuplicate( Image* image, int width, int height, int components, unsigned long crcVal, bool glTexCompress );
 
    /** Tries to find an image that is the same as this image
      * \return A pointer to the first image in the image instance list that matches or NULL if not found
      */
    virtual GLS_EXPORT Image* FindDuplicate();
 
    /** Tries to find an image that is the same as a notional image based on the following criteria
      * \param width       Width of notional image
      * \param height      Height of notional image
      * \param components  Number of components in the notional image
      * \param crcVal      32 bit CRC of notional image
      * \param glTexCompress GlTextureCompresssion setting for the image
      * \return A pointer to the first image in the image instance list that matches or NULL if not found
      */
    static GLS_EXPORT Image* FindDuplicate( int width, int height, int components, unsigned long crcVal, bool glTexCompress );
 
    /** Enable or disable mipmaps for this image
      * \param set  Whether or not mipmaps are enabled
      */
    virtual GLS_EXPORT void MipMap( bool set );
 
    /** \return Whether or not mipmaps are enabled */
    virtual GLS_EXPORT bool MipMap();
 
    /** Enable or disable Open GL texture compression for this image
      * \param set  Whether or not Open GL texture compression is enabled
      */
    virtual GLS_EXPORT void GlTextureCompression( bool set );
 
    /** \return Whether or not Open GL texture compression is enabled */
    virtual GLS_EXPORT bool GlTextureCompression();
 
    /** Scales the image up to the nearest power of two in each dimension */
    virtual GLS_EXPORT void ScaleToPowerOfTwo();
 
    /// Replaces the current image with the specified.
    /// The new image must be the same _texWidth, _texHeight, and _pixelSize as the current image.
    /// \param imageData The image data to replace with.
    virtual GLS_EXPORT void ReplaceImage( unsigned char* imageData );
 
    /** Replaces the current image with the specified.
      * \param imageData  buffer containing the new image data
      * \param width      new Width of the image.  Must be a power of two (2^n).
      * \param height     new Height of the image.  Must be a power of two (2^n).
      * \param pixelSize  The size in bytes of each pixel
      * \returns true if successful, false if the operation is unsupported or there was an error.
      */
    virtual GLS_EXPORT bool ReplaceImage( unsigned char* imageData, int width, int height, int pixelSize );
 
    /** Allocates the local rgb buffer from the glsInlineImage for this image.
      * \returns true if successful, false on failure (e.g. this image doesn't have a glsInlineImage associated with it.)
      */
    virtual GLS_EXPORT bool LoadInlineImageData();
 
    /** Frees the local rgb buffer if this image has a glsInlineImage associated with it.
      * \returns true if the buffer was freed, false if this Image does not have a glsInlineImage associated with it.
      */
    virtual GLS_EXPORT bool FreeInlineImageData();
 
    /** Removes the association between this Image and it's glsInlineImage data.
      * This will use more memory, but makes the Image independent of the static data.
      * This method will attempt to load the image before disconnecting from the glsInlineImage,
      * if the load fails, ImageData() will return NULL afterwards.
      * After calling this method, the Image will no longer have a glsInlineImage associated with it.
      *
      * \param loadImage If true, the _rgbBuf will be loaded from the inline image data before disconnecting
      *                  If false, the _rgbBuf will be allocated but not initialized.
      * \returns true if the Image had a glsInlineImage associated with it
      * \return false if the Image did not have a glsInlineImage associated with it.
      */
    virtual GLS_EXPORT bool DisconnectInlineImage( bool loadImage = true );
 
    /// If AllowImageSharing is true, this Image may be deleted by the texture palette if a duplicate texture is found.
    /// This also implies that the Image will not change and may be used in place of another texture
    /// with the same CrcValue(). If false this causes Image::CrcValue() to always return 0,
    /// disabling duplicate checking. (default: true)
    /// \note If this Image is already in a TexturePalette, you should call TexturePalette::DisableImageSharing() instead of this method.
    /// \param value The new sharing flag to set.
    virtual GLS_EXPORT void AllowImageSharing( bool value );
 
    /// \return Whether or not this image can be deleted if a duplicate texture is found.
    virtual GLS_EXPORT bool AllowImageSharing();
 
    /** Determine if non-power of two (NPOT) textures are allowed for this image.
      * \return true if non-power of two (NPOT) textures are allowed.
      */
    GLS_EXPORT bool IsAllowNPOTTextures() const;
}; // class Image
 
} // namespace disti
 
#endif