GL Studio C++ Runtime API
image.h
Go to the documentation of this file.
1 /*! \file
2  \brief The Image class. All textures are converted internally into Images.
3 
4  \par Copyright Information
5 
6  Copyright (c) 2017 by The DiSTI Corporation.<br>
7  11301 Corporate Blvd; Suite 100<br>
8  Orlando, Florida 32817<br>
9  USA<br>
10  <br>
11  All rights reserved.<br>
12 
13  This Software contains proprietary trade secrets of DiSTI and may not be
14 reproduced, in whole or part, in any form, or by any means of electronic,
15 mechanical, or otherwise, without the written permission of DiSTI. Said
16 permission may be derived through the purchase of applicable DiSTI product
17 licenses which detail the distribution rights of this content and any
18 Derivative Works based on this or other copyrighted DiSTI Software.
19 
20  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
21 AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
22 PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
23 AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
24 IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
25 PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
26 
27  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
28 IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
29 INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
30 DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
31 INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
32 INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
33 OF SUCH DAMAGES. DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
34 EXCEED FIVE DOLLARS (US$5.00).
35 
36  The aforementioned terms and restrictions are governed by the laws of the
37 State of Florida and the United States of America.
38 
39 */
40 
41 #ifndef _IMAGE_LIB_H
42 #define _IMAGE_LIB_H
43 
44 #include "IFontImage.h"
45 #include "file_path_class.h"
46 #include "gls_include.h"
47 #include "list.h"
48 #include "util.h"
49 #include <stdio.h>
50 
51 #ifdef QNX
52 # include <time.h>
53 #endif
54 
55 namespace disti
56 {
57 class Mutex;
58 const int IMG_TRANSPARENT = 0; /**< Alpha value for a transparent pixel */
59 const int IMG_NON_TRANSPARENT = 255; /**< Alpha value for a non-transparent pixel */
60 const int MAX_MIP_MAP_IMAGES = 16; /**< Maximum number of mipmapping levels */
61 
62 typedef enum
63 {
64  GLS_CODEC_RAW, /**< Image data is not compressed */
65  GLS_CODEC_LZ77, /**< Image data is compressed with LZ77 (Z-Lib) */
66  GLS_CODEC_JPEG /**< Image data is compressed with lossy JPEG */
68 
69 typedef enum
70 {
71  GLS_NPOT_AUTO, /**< Allow Non Power Of Two textures if able */
72  GLS_NPOT_ENABLED, /**< Always allow Non Power Of Two textures */
73  GLS_NPOT_DISABLED /**< Never allow Non Power Of Two textures */
75 
76 /** The glsInlineImage structure. This structure is generated and contains information needed to
77  * create reconstruct an inline generated image.
78  */
80 {
81  typedef const unsigned char* const _BufferType;
82  unsigned int _width; /**< Width of image in pixels */
83  unsigned int _height; /**< Height of image in pixels */
84  unsigned int _components; /**< Number of components in image */
85  unsigned int _pixel_format; /**< GL_RGB, GL_RGBA ... */
86  glsImageCodec _codec; /**< CODEC used to compress image */
87  unsigned long _crc; /**< CRC of image data (compressed or uncompressed?) */
88  bool _gl_texture_compression; /**< Value of GlTextureCompression */
89  unsigned long _image_data_size; /**< Size of RGB data (compressed) */
90  unsigned long _alpha_data_size; /**< Size of Alpha data (compressed). Zero if no alpha channel present */
91  unsigned int _line_length; /**< Length of each line of inline data, in bytes */
92  _BufferType* _rgb_buffer; /**< Pointer to the static compressed rgb buffer for the image */
93  _BufferType* _alpha_buffer; /**< Pointer to the static compressed alpha layer for the image */
94 
95  glsInlineImage( unsigned int width,
96  unsigned int height,
97  unsigned int components,
98  unsigned int pixel_format,
99  glsImageCodec codec,
100  unsigned long crc,
101  bool gl_tex_compress,
102  unsigned long image_data_size,
103  unsigned long alpha_data_size,
104  unsigned int line_length,
105  const unsigned char* const* rgb_buffer,
106  const unsigned char* const* alpha_buffer )
107  : _width( width )
108  , _height( height )
109  , _components( components )
110  , _pixel_format( pixel_format )
111  , _codec( codec )
112  , _crc( crc )
113  , _gl_texture_compression( gl_tex_compress )
114  , _image_data_size( image_data_size )
115  , _alpha_data_size( alpha_data_size )
116  , _line_length( line_length )
117  , _rgb_buffer( rgb_buffer )
118  , _alpha_buffer( alpha_buffer )
119  {
120  }
121 };
122 
123 /** Enable/Disable global Non Power Of Two capability. This will override the
124  * texture's setting from the editor.
125  * \note NPOT detection is not currently supported. (GLS-5940)
126  * \param state The state to set it to. Will enable, disable, or apply auto detection
127  for if NPOT support is available.
128  */
129 GLS_EXPORT void SetNPOTState( ImageNPOTMode state );
130 
131 /** Determines if Non Power Of Two textures are supported.
132  * \return GLS_NPOT_ENABLED if NPOT textures are supported, GLS_NPOT_DISABLED otherwise.
133  */
135 
136 /** By default, Image instances release their texture data in main memory after loading it to the GPU.
137  * This flag controls that default behavior for new Image instances. Set to false if you want all
138  * Images to keep a copy of their texture data loaded in main memory. (Note: This can dramatically
139  * increase memory usage.)
140  *
141  * \note The default applies only to Image instances created after this flag is set. To set or get
142  * the value behavior for a particular Image instance, call Image::SetReleaseImageDataEnabled()
143  * or Image::IsReleaseImageDataEnabled(), respectively.
144  *
145  * \note Default value: true
146  *
147  * \param enable The new default value
148  *
149  * \sa disti::Image::SetReleaseImageDataEnabled(), disti::Image::IsReleaseImageDataEnabled()
150  */
151 GLS_EXPORT void SetReleaseImageDataDefault( bool enable );
152 
153 /** Returns the current value for the flag controlling the default behavior for new Image instances.
154  * See SetReleaseImageDataDefault() for more details.
155  * \sa disti::SetReleaseImageDataDefault( bool )
156  */
157 GLS_EXPORT bool GetReleaseImageDataDefault( void );
158 
159 /**
160  The Image class. Implements loading 2D image files.
161 */
162 class Image
163  : virtual public IFontImage
164 {
165 protected:
166  unsigned int _textureHandle; /**< The texture handle of the image. */
167  int _pixelFormat; /**< Pixel format for the image */
168  int _pixelSize; /**< Size of a pixel in bytes */
169  int _errorFound; /**< Error found reading image file flag. */
170  char* _errorMessage; /**< Error message in string format. */
171  int _width; /**< Actual width of image in pixels. */
172  int _height; /**< Actual height of image in pixels. */
173  int _texWidth; /**< Texture width (power of 2) of the image in pixels. */
174  int _texHeight; /**< Texture height (power of 2) of the image in pixels. */
175 
176  float _texCoord[ 2 ]; /**< Texture coordinates of upper right corner
177  * of image. This will be (1.0,1.0) for a
178  * square power of two image */
179 
180  unsigned char* _rgbBuf; /**< Pointer to the image data for this image. */
181 
182  bool _mipMap; /**< True if this image should use mip mapping */
183  unsigned char* _mmBuf[ MAX_MIP_MAP_IMAGES ]; /**< Pointers to the smaller versions of _rgbBuf */
184 
185  unsigned long _crcValue; /**< CRC value used to determine if two images are the same */
186 
187  int _numUsers; /**< Count of number of objects that reference this one */
188 
189  bool _replaceImageFlag; /**< Indicates the images has been changed and needs to be re-bound */
190 
191  bool _releaseImageData; /**< true to allow image data for image to be unloaded from main memory else false */
192 
193  static bool _glTextureCompressionSupported; /**< Indicates if GL Texture compression is supported on the
194  Machine that this program is running on. */
195 
196  bool _glTextureCompression; /**< Indicates if GL Texture compression is enabled for this image */
197 
198  glsInlineImage* _staticInlineImage; /**< Inline image data for this image, if applicable. */
199 
200  bool _allowImageSharing; /**< If false, causes Image::CrcValue() to always return 0, disabling duplicate checking. */
201 
202  bool _allowNPOT; /**< If true, this texture is not scaled to power of two. */
203 
204 #ifdef GLES
205  unsigned int _stateManagerHandle; /**< Handle used by the OpenGL ES state manager to quickly find this texture */
206 #endif
207 
208  /** Convert Luminance Alpha texture to Alpha texture.
209  * Used on OpenGL ES target to speedup texturing for fonts
210  */
212 
213 public:
214  static GLS_EXPORT bool _globalMipMapEnabled; /**< Determines the default value for _mipMap, and does not
215  * do mip mapping if false */
216 
217  /** All images get added to the InstanceList */
218  static GLS_EXPORT List_c& InstanceList();
219 
220  /** Use this Mutex when accessing the InstanceList */
221  static GLS_EXPORT disti::Mutex& InstanceListMutex();
222 
223  /** Empties the InstanceList
224  * This is done when loading objects which will be drawn in different
225  * OpenGL contexts.
226  */
227  static GLS_EXPORT void EmptyInstanceList();
228 
229  /** Determines whether this image will release its image data from main memory when it is not needed.
230  *
231  * When enabled (true), the the Image will release the main memory copy of the data when it is not
232  * needed in order to save memory. This flag is enabled by default and should be disabled in situations
233  * such as when the ImageData for this Image cannot be re-created from permanent storage.
234  *
235  * \note The default value is determined by disti::GetReleaseImageDataDefault().
236  *
237  * \param enable Whether release of image data is enabled.
238  *
239  * \sa IsReleaseImageDataEnabled()
240  * \sa disti::SetReleaseImageDataDefault()
241  *
242  * \note The static methods SetUnloadImageDataEnabled() and IsUnloadImageDataEnabled() from Image and Image::InstanceListEntry
243  * were removed to disambiguate between the per-instance setting and the global setting. Code that was calling
244  * Image::SetUnloadImageDataEnabled() to set the default flag for all instances should now call disti::SetReleaseImageDataDefault().
245  * Code that was calling Image::InstanceListEntry::SetUnloadImageDataEnabled() to set the flag for only one instance
246  * should call this method.
247  */
248  GLS_EXPORT void SetReleaseImageDataEnabled( bool enable );
249 
250  /** Returnswhether release of image data is enabled.
251  *
252  * \sa SetReleaseImageDataEnabled()
253  * \sa disti::GetReleaseImageDataDefault()
254  *
255  * \note The static methods SetUnloadImageDataEnabled() and IsUnloadImageDataEnabled() from Image and Image::InstanceListEntry
256  * were removed to disambiguate between the per-instance setting and the global setting. Code that was calling
257  * Image::IsUnloadImageDataEnabled() to get the default flag for all instances should now call disti::GetReleaseImageDataDefault().
258  * Code that was calling Image::InstanceListEntry::IsUnloadImageDataEnabled() to get the flag for only one instance
259  * should call this method.
260  */
261  GLS_EXPORT bool IsReleaseImageDataEnabled();
262 
263 #ifdef GLES
264  /** see IFontImage */
265  virtual unsigned int StateManagerHandle() const { return _stateManagerHandle; }
266 
267  /** see IFontImage */
268  virtual void StateManagerHandle( unsigned int handle ) { _stateManagerHandle = handle; }
269 #endif
270 
271  /** These are options that are possibly used during loading of the image. */
273  {
274  public:
275  LoadOptions()
276  : _reverseAlpha( FALSE )
277  {
278  }
279 
280  bool _reverseAlpha; /** For compatibility with images with the alpha channel reversed */
281 
282  bool operator==( const LoadOptions& rhs ) const
283  {
284  return ( _reverseAlpha == rhs._reverseAlpha );
285  }
286  }; // class LoadOptions
287 
288  /** an entry in the Image::InstanceList */
290  {
291  public:
292  /** holds absolute file path, file size, mod time and image load options */
293  class FileID
294  {
295  public:
296  /** default ctor - no file */
297  GLS_EXPORT FileID( void );
298 
299  /** ctor
300  * \param path path for file ( can be relative or absolute, will ultimately be stored in the FileID as an absolute path )
301  * \param loadOptions image loading options for file
302  */
303  GLS_EXPORT FileID( const FilePathClass& path, const LoadOptions& loadOptions );
304 
305  /** copy ctor
306  * \param src FileID to copy
307  */
308  GLS_EXPORT FileID( const FileID& src );
309 
310  /** get the absolute path for the file
311  * \return the absolute path for the file
312  */
313  GLS_EXPORT const FilePathClass& GetPath( void ) const;
314 
315  /** get the image load options for the file
316  * \return the image load options for the file
317  */
318  GLS_EXPORT const LoadOptions& GetLoadOptions( void ) const;
319 
320  /** get the file size for the file
321  * \return the file size for the file
322  */
323  GLS_EXPORT off_t GetFileSize( void ) const;
324 
325  /** get the modification time for the file
326  * \return the modification time for the file
327  */
328  GLS_EXPORT time_t GetModTime( void ) const;
329 
330  /** compare two FileID's checking for same absolute path and load options
331  * \note file size and mod time are not compared here, just absolute path and load options
332  * \param rhs FileID to compare
333  * \return true if equal absolute paths and load options
334  */
335  GLS_EXPORT bool operator==( const FileID& rhs ) const;
336 
337  /** assigment operator
338  * \param rhs
339  */
340  GLS_EXPORT FileID& operator=( const FileID& rhs );
341 
342  /** get the absolute path for the given path
343  * \param imgPath path in question
344  * \return the absolute path for the given path
345  */
346  static FilePathClass GetAbsoluteFilePath( const FilePathClass& imgPath );
347 
348  protected:
349  FilePathClass _path; /**< absolute path for image file */
350  LoadOptions _loadOptions; /**< load options associated with image */
351  off_t _fileSize; /**< size in bytes of image file */
352  time_t _modTime; /**< file mod time for image file */
353  }; // class FileID
354 
355  /** array of FileID */
357 
358  /** ctor
359  * \param img image for list entry
360  * \param imgPath [optional, defaults to ""] optional path to image file associated with image
361  * \param imgLoadOptions [optional] optional load options associated with image
362  */
363  GLS_EXPORT InstanceListEntry( Image* img, const FilePathClass& imgPath = FilePathClass(), const LoadOptions& imgLoadOptions = LoadOptions() );
364 
365  /** dtor -- NOTE: image associated with entry is not destroyed */
366  GLS_EXPORT ~InstanceListEntry();
367 
368  /** get the image associated with the entry
369  * \return the image associated with the entry
370  */
371  GLS_EXPORT Image* GetImage( void );
372 
373  /** get the image files associated with the entry
374  * \return the image files associated with the entry
375  */
376  GLS_EXPORT FileIDArray& GetAssociatedFiles( void );
377 
378  /** determine if the given fileID is associated with this entry
379  * \param fileID file ID in question
380  * \param foundFileID [out] receives associated file ID if the given fileID is associated with this entry
381  * \return true if the given fileID is associated with this entry else false
382  */
383  GLS_EXPORT bool FileIsAssociatedWithImage( const FileID& fileID, FileID& foundFileID );
384 
385  /** associate the given fileID with the image in this entry
386  * \param fileID file ID in question
387  */
388  GLS_EXPORT void AssociateFileWithImage( const FileID& fileID );
389 
390  /** disassociate the given fileID with the image in this entry
391  * \param fileID file ID in question
392  */
393  GLS_EXPORT void DisassociateFileWithImage( const FileID& fileID );
394 
395  /** Attempt to reload the associated image from an associated image file. Associated image will
396  * be marked as no longer being a candidate for unloading.
397  * NOTE: Image::InstanceListMutex() cannot be locked when calling this method
398  * \return true if reload succeeded else false
399  * \pre Image::InstanceListMutex() is not locked
400  */
401  GLS_EXPORT bool ReloadImageFromFile( void );
402 
403  protected:
404  Image* _img; /**< image associated with entry */
405  FileIDArray _associatedFiles; /**< files associated with image else empty array */
406 
407  private:
408  // disallow
409  InstanceListEntry( const InstanceListEntry& src );
410  InstanceListEntry operator=( const InstanceListEntry& rhs );
411  }; // class InstanceListEntry
412 
413 protected:
414  /** Add this image to the Image Sharing Instance List */
415  GLS_EXPORT void AddSelfToInstanceList();
416 
417  /** Set the Image _texWidth, _texHeight, _texWidth, _texCoord[0],
418  * and _texCoord[1]. Width and height must be set before calling
419  * this function. */
420  virtual GLS_EXPORT void SetTexWidthHeight( void );
421 
422  /** Allocate and initialize the pixel buffer memory for this image
423  * _texWidth, _textHeight and _pixelSize must be initialized prior to
424  * calling! _rgbBuf is set to the initialized memory.
425  * \param zeroOut Whether or not to clear the memory to zero on allocation.
426  * \return True if allocated. false on failure.
427  */
428  virtual GLS_EXPORT bool AllocatePixelMemory( bool zeroOut = true );
429 
430  /** Allocate memory for Mip-Map images
431  * \param zeroOut Whether or not to clear the memory to zero on allocation.
432  */
433  virtual GLS_EXPORT bool AllocateMipMapMemory( bool zeroOut = true );
434 
435  /** Calculate mip-map images from the main image */
436  virtual GLS_EXPORT void CalculateMipMapImages( bool reCalc = false );
437 
438  /** Helper routine used by constructor. Allocates pixel memory and sets the
439  * texture width, height and pixel size
440  * \param width Width of the image
441  * \param height Height of the image
442  * \param pixelSize The size in bytes of each pixel
443  */
444  virtual GLS_EXPORT void Initialize( int width, int height, int pixelSize );
445 
446 public:
447  /** \return The state of any error found reading image file flag. */
448  virtual GLS_EXPORT int ErrorFound( void );
449 
450  /** Sets the error message.
451  * \param errorMessage String containing error message.
452  */
453  virtual GLS_EXPORT void SetError( char* errorMessage );
454 
455  /** Returns the error message found during reading image file. */
456  virtual GLS_EXPORT char* GetError( void );
457 
458  /** Draws the image at the current raster position. */
459  virtual GLS_EXPORT void Draw( void );
460 
461  /** Draws the image at the x,y raster position specified.
462  * \param x X position to draw the image
463  * \param y Y position to draw the image
464  */
465  virtual GLS_EXPORT void Draw( int x, int y );
466 
467  /** \return A new image that is a duplicate of this image or NULL if duplication is not possible.
468  */
469  virtual GLS_EXPORT Image* Clone();
470 
471  /** \return A pointer to the 2D image data */
472  virtual GLS_EXPORT unsigned char* ImageData( void );
473 
474  /** \return the X position of the texture coordinate used for the image. */
475  virtual GLS_EXPORT float TextureCoordX( void );
476 
477  /** \return the Y position of the texture coordinate used for the image. */
478  virtual GLS_EXPORT float TextureCoordY( void );
479 
480  /** \return the texture width of the image file. This is the power
481  * of 2 size greater than or equal to the size of the image.
482  */
483  virtual GLS_EXPORT int TextureWidth( void );
484 
485  /** \return the texture height of the image file. This is the power
486  * of 2 size greater than or equal the size of the image.
487  */
488  virtual GLS_EXPORT int TextureHeight( void );
489 
490  /** \return the memory size of the image in bytes */
491  virtual GLS_EXPORT int Size( void );
492 
493  /** \return the width of the image. */
494  virtual GLS_EXPORT int Width( void );
495 
496  /** \return the height of the image. */
497  virtual GLS_EXPORT int Height( void );
498 
499  /** \return true if the internal texture handle is valid */
500  virtual GLS_EXPORT bool TextureHandleValid();
501 
502  /** \return the OpenGL texture handle of this texture instance */
503  virtual GLS_EXPORT unsigned int TextureHandle() const { return _textureHandle; }
504 
505  /** Returns the pixel format for this image
506  * \return The internal pixel format for this image
507  */
508  virtual GLS_EXPORT int PixelFormat( void );
509 
510  /** Sets the pixel format for this image and also the pixel size as
511  * determined from the format. Eg. GL_RGBA has a pixel size of 4.
512  * \param format The new internal pixel format for this image
513  */
514  virtual GLS_EXPORT void PixelFormat( int format );
515 
516  /** \return The OpenGL enumerator for the pixel format for this
517  * image as a string. Used for inline texture generation
518  */
519  virtual GLS_EXPORT char* PixelFormatString( void );
520 
521  /** \return The size of a pixel in this image in bytes */
522  virtual GLS_EXPORT int PixelSize( void );
523 
524  /** Returns a pointer to the memory location corresponding to the given X,Y
525  * position within the image
526  * \param x X raster position
527  * \param y Y raster position
528  */
529  virtual GLS_EXPORT unsigned char* GetRasterPosition( int x, int y );
530 
531  /** Set the value of a secific pixel in the rbg buffer.
532  * \param x X position of the pixel
533  * \param y Y position of the pixel
534  * \param color Color of the pixel
535  */
536  virtual GLS_EXPORT void SetPixel( int x, int y, float color[] );
537 
538  /** Takes the image and creates a 2D Decal texture map. (Not Implemented)*/
539  virtual GLS_EXPORT void SetAsCurrentTexture( void );
540 
541  /** Create a new texture object using Image object data. */
542  virtual GLS_EXPORT void AllocateTextureBinding( void );
543 
544  /** Deletes the OpenGL texture object for this Image. */
545  virtual GLS_EXPORT void DeallocateTextureBinding( void );
546 
547  /** Make this Image object the active texture. */
548  virtual GLS_EXPORT void BindTexture( void );
549 
550  /** Create an Image object with the specified image data and image size.
551  * \param data Pointer to the image data
552  * \param width Width of the image
553  * \param height Height of the image
554  * \param pixelFormat The format of each pixel, eg. GL_RGBA
555  */
556  GLS_EXPORT Image( const unsigned char* const data, int width, int height, int pixelFormat );
557 
558  /** Create an Image object with the specified image size.
559  * \param width Width of the image
560  * \param height Height of the image
561  * \param pixelSize The size in bytes of each pixel
562  * \param allowNPOT If the image is allowed to be non-power of two (NPOT)
563  */
564  GLS_EXPORT Image( int width, int height, int pixelSize, bool allowNPOT = false );
565 
566  /** Create an Image from an inline image (GL Studio 2.2 and later API)
567  * \param image Structure containing details of inline image
568  */
569  GLS_EXPORT Image( const glsInlineImage& image );
570 
571  /** Create an Image from a buffer of ZLIB compressed data
572  * Image data must already be a power of two!
573  * \param width Width of the image
574  * \param height Height of the image
575  * \param components The size in bytes of each pixel
576  * \param format The OpenGL texture format to use
577  * \param comprLen The size of the compressed image
578  * \param data The buffer of compressed data
579  * \param crcVal The CRC value used to find duplicate textures
580  * \param lineLength The number of bytes in each inline image line
581  */
582  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 );
583 
584  /** Create an Image from a buffer of uncompressed data
585  * Image data must already be a power of two!
586  * \param width Width of the image
587  * \param height Height of the image
588  * \param components The size in bytes of each pixel
589  * \param format The OpenGL texture format to use
590  * \param pix The buffer of uncompressed data
591  * \param crcVal The CRC value used to find duplicate textures
592  * \param lineLength The number of bytes in each inline image line
593  */
594  GLS_EXPORT Image( int width, int height, int components, int format, const unsigned char* const pix[], unsigned long crcVal = 0, int lineLength = 320 );
595 
596  /** Create an Image from another Image instance.
597  */
598  GLS_EXPORT Image( const Image& source );
599 
600  /** Constructor for an Image object. */
601  GLS_EXPORT Image( void );
602 
603  GLS_EXPORT void DoTexSubImage();
604 
605  /** Unload RGB and mipmap data to save memory */
606  GLS_EXPORT void UnloadRgbData();
607 
608 protected:
609  /** Destroy an Image object. Frees the memory for the RGB buffer. */
610  virtual GLS_EXPORT ~Image( void );
611 
612 public:
613  /** Will delete the Image object if nobody is using it */
614  virtual GLS_EXPORT void DeleteUsage();
615 
616  /** Lets this object know that another something is using this image */
617  virtual GLS_EXPORT void AddUsage();
618 
619  /** \return the number of simultanious users of this image */
620  virtual GLS_EXPORT int NumUsers();
621 
622  /** Overloaded operator for copying Image objects. */
623  virtual GLS_EXPORT void operator=( Image& im );
624 
625  /** Scale the texture to the nearest power of two */
626  virtual GLS_EXPORT void ScaleTexture( void );
627 
628  /** \return the CRC value for this image. 0 indicates an invalid value or that duplicate checking is disabled for the Image.
629  */
630  virtual GLS_EXPORT unsigned long CrcValue();
631 
632  /** Equality operator. Determines if two images are equal
633  * \param im Image to test
634  * \return boolean result
635  */
636  virtual GLS_EXPORT int operator==( Image& im );
637 
638  /** Determines if an image #1 is the same a notional image based on the following criteria
639  * \param image Image #1
640  * \param width Width of notional image
641  * \param height Height of notional image
642  * \param components Number of components in the notional image
643  * \param crcVal 32 bit CRC of notional image
644  * \param glTexCompress GlTextureCompresssion setting for the image
645  * \return True if they are equal
646  */
647  static GLS_EXPORT bool IsDuplicate( Image* image, int width, int height, int components, unsigned long crcVal, bool glTexCompress );
648 
649  /** Tries to find an image that is the same as this image
650  * \return A pointer to the first image in the image instance list that matches or NULL if not found
651  */
652  virtual GLS_EXPORT Image* FindDuplicate();
653 
654  /** Tries to find an image that is the same as a notional image based on the following criteria
655  * \param width Width of notional image
656  * \param height Height of notional image
657  * \param components Number of components in the notional image
658  * \param crcVal 32 bit CRC of notional image
659  * \param glTexCompress GlTextureCompresssion setting for the image
660  * \return A pointer to the first image in the image instance list that matches or NULL if not found
661  */
662  static GLS_EXPORT Image* FindDuplicate( int width, int height, int components, unsigned long crcVal, bool glTexCompress );
663 
664  /** Enable or disable mipmaps for this image
665  * \param set Whether or not mipmaps are enabled
666  */
667  virtual GLS_EXPORT void MipMap( bool set );
668 
669  /** \return Whether or not mipmaps are enabled */
670  virtual GLS_EXPORT bool MipMap();
671 
672  /** Enable or disable Open GL texture compression for this image
673  * \param set Whether or not Open GL texture compression is enabled
674  */
675  virtual GLS_EXPORT void GlTextureCompression( bool set );
676 
677  /** \return Whether or not Open GL texture compression is enabled */
678  virtual GLS_EXPORT bool GlTextureCompression();
679 
680  /** Scales the image up to the nearest power of two in each dimension */
681  virtual GLS_EXPORT void ScaleToPowerOfTwo( void );
682 
683  /** Replaces the current image with the specified.
684  * The new image must be the same _texWidth, _texHeight, and _pixelSize
685  * as the current image */
686  virtual GLS_EXPORT void ReplaceImage( unsigned char* imageData );
687 
688  /** Replaces the current image with the specified.
689  * \param imageData buffer containing the new image data
690  * \param width new Width of the image. Must be a power of two (2^n).
691  * \param height new Height of the image. Must be a power of two (2^n).
692  * \param pixelSize The size in bytes of each pixel
693  * \returns true if successful, false if the operation is unsupported or there was an error.
694  */
695  virtual GLS_EXPORT bool ReplaceImage( unsigned char* imageData, int width, int height, int pixelSize );
696 
697  /** Allocates the local rgb buffer from the glsInlineImage for this image.
698  * \returns true if successful, false on failure (e.g. this image doesn't have a glsInlineImage associated with it.)
699  */
700  virtual GLS_EXPORT bool LoadInlineImageData();
701 
702  /** Frees the local rgb buffer if this image has a glsInlineImage associated with it.
703  * \returns true if the buffer was freed, false if this Image does not have a glsInlineImage associated with it.
704  */
705  virtual GLS_EXPORT bool FreeInlineImageData();
706 
707  /** Removes the association between this Image and it's glsInlineImage data.
708  * This will use more memory, but makes the Image independent of the static data.
709  * This method will attempt to load the image before disconnecting from the glsInlineImage,
710  * if the load fails, ImageData() will return NULL afterwards.
711  * After calling this method, the Image will no longer have a glsInlineImage associated with it.
712  *
713  * \param loadImage If true, the _rgbBuf will be loaded from the inline image data before disconnecting
714  * If false, the _rgbBuf will be allocated but not initialized.
715  * \returns true if the Image had a glsInlineImage associated with it
716  * \return false if the Image did not have a glsInlineImage associated with it.
717  */
718  virtual GLS_EXPORT bool DisconnectInlineImage( bool loadImage = true );
719 
720  /** If AllowImageSharing is true, this Image may be deleted by the texture palette if a duplicate texture is found.
721  * This also implies that the Image will not change and may be used in place of another texture
722  * with the same CrcValue(). If false this causes Image::CrcValue() to always return 0,
723  * disabling duplicate checking. (default: true)
724  * Note: If this Image is already in a TexturePalette, you should call TexturePalette::DisableImageSharing()
725  * instead of this method.
726  */
727  virtual GLS_EXPORT void AllowImageSharing( bool value );
728  virtual GLS_EXPORT bool AllowImageSharing();
729 
730  /** Determine if non-power of two (NPOT) textures are allowed for this image.
731  * \return true if non-power of two (NPOT) textures are allowed.
732  */
733  GLS_EXPORT bool IsAllowNPOTTextures( void ) const;
734 }; // class Image
735 
736 } // namespace disti
737 
738 #endif
Definition: image.h:79
unsigned long _image_data_size
Definition: image.h:89
virtual bool MipMap()
glsImageCodec
Definition: image.h:62
const int IMG_NON_TRANSPARENT
Definition: image.h:59
A class to handle file paths.
virtual void ScaleTexture(void)
Definition: image.h:162
unsigned long _crc
Definition: image.h:87
static bool _globalMipMapEnabled
Definition: image.h:214
virtual int operator==(Image &im)
virtual void BindTexture(void)
Definition: IFontImage.h:53
virtual void DeallocateTextureBinding(void)
bool _glTextureCompression
Definition: image.h:196
unsigned int _textureHandle
Definition: image.h:166
virtual int Height(void)
bool operator==(const FileID &rhs) const
glsImageCodec _codec
Definition: image.h:86
void ConvertLuminanceAlphaToAlpha()
off_t _fileSize
Definition: image.h:351
time_t _modTime
Definition: image.h:352
void UnloadRgbData()
const int MAX_MIP_MAP_IMAGES
Definition: image.h:60
virtual float TextureCoordX(void)
bool _gl_texture_compression
Definition: image.h:88
unsigned int _components
Definition: image.h:84
Definition: image.h:72
unsigned char * _mmBuf[MAX_MIP_MAP_IMAGES]
Definition: image.h:183
virtual unsigned long CrcValue()
virtual void SetError(char *errorMessage)
virtual void SetPixel(int x, int y, float color[])
bool _mipMap
Definition: image.h:182
DynamicArray< FileID > FileIDArray
Definition: image.h:356
virtual ~Image(void)
virtual char * GetError(void)
virtual unsigned char * GetRasterPosition(int x, int y)
virtual unsigned int TextureHandle() const
Definition: image.h:503
virtual Image * FindDuplicate()
Definition: image.h:272
virtual void ReplaceImage(unsigned char *imageData)
void SetNPOTState(ImageNPOTMode state)
int _height
Definition: image.h:172
virtual void ScaleToPowerOfTwo(void)
virtual bool TextureHandleValid()
virtual float TextureCoordY(void)
A file for all GL Studio files to include.
Image * _img
Definition: image.h:404
virtual bool DisconnectInlineImage(bool loadImage=true)
void DisassociateFileWithImage(const FileID &fileID)
unsigned int _pixel_format
Definition: image.h:85
int _pixelSize
Definition: image.h:168
bool GetReleaseImageDataDefault(void)
virtual int Size(void)
virtual int PixelSize(void)
int _errorFound
Definition: image.h:169
Definition: image.h:65
Definition: image.h:71
FilePathClass _path
Definition: image.h:349
virtual void Draw(void)
bool _allowImageSharing
Definition: image.h:200
Definition: image.h:289
_BufferType * _alpha_buffer
Definition: image.h:93
virtual void Initialize(int width, int height, int pixelSize)
_BufferType * _rgb_buffer
Definition: image.h:92
float _texCoord[2]
Definition: image.h:176
virtual bool AllocatePixelMemory(bool zeroOut=true)
The List_c class. Generic linked list.
unsigned long _crcValue
Definition: image.h:185
virtual Image * Clone()
static List_c & InstanceList()
virtual void CalculateMipMapImages(bool reCalc=false)
virtual bool GlTextureCompression()
Definition: gls_mutex.h:52
int _texWidth
Definition: image.h:173
Generally useful defines, macros, enumerations and function prototypes.
const FilePathClass & GetPath(void) const
Definition: image.h:64
static disti::Mutex & InstanceListMutex()
virtual bool LoadInlineImageData()
bool IsAllowNPOTTextures(void) const
unsigned int _height
Definition: image.h:83
Definition: image.h:66
virtual void SetTexWidthHeight(void)
Definition: file_path_class.h:61
FileIDArray _associatedFiles
Definition: image.h:405
unsigned int _line_length
Definition: image.h:91
FileID & operator=(const FileID &rhs)
unsigned long _alpha_data_size
Definition: image.h:90
virtual int ErrorFound(void)
glsInlineImage * _staticInlineImage
Definition: image.h:198
virtual void operator=(Image &im)
FileIDArray & GetAssociatedFiles(void)
int _width
Definition: image.h:171
int _pixelFormat
Definition: image.h:167
const int IMG_TRANSPARENT
Definition: image.h:58
void SetReleaseImageDataDefault(bool enable)
int _texHeight
Definition: image.h:174
char * _errorMessage
Definition: image.h:170
virtual char * PixelFormatString(void)
LoadOptions _loadOptions
Definition: image.h:350
bool _replaceImageFlag
Definition: image.h:189
bool _releaseImageData
Definition: image.h:191
int _numUsers
Definition: image.h:187
bool FileIsAssociatedWithImage(const FileID &fileID, FileID &foundFileID)
ImageNPOTMode
Definition: image.h:69
virtual int Width(void)
static bool IsDuplicate(Image *image, int width, int height, int components, unsigned long crcVal, bool glTexCompress)
virtual bool FreeInlineImageData()
InstanceListEntry(Image *img, const FilePathClass &imgPath=FilePathClass(), const LoadOptions &imgLoadOptions=LoadOptions())
virtual bool AllocateMipMapMemory(bool zeroOut=true)
bool IsReleaseImageDataEnabled()
virtual unsigned char * ImageData(void)
Definition: image.h:73
unsigned char * _rgbBuf
Definition: image.h:180
static FilePathClass GetAbsoluteFilePath(const FilePathClass &imgPath)
virtual void DeleteUsage()
virtual void SetAsCurrentTexture(void)
virtual void AllocateTextureBinding(void)
void AssociateFileWithImage(const FileID &fileID)
virtual int TextureHeight(void)
ImageNPOTMode DoesSystemSupportNPOT()
void AddSelfToInstanceList()
virtual int NumUsers()
virtual void AddUsage()
bool operator==(const LoadOptions &rhs) const
Definition: image.h:282
void SetReleaseImageDataEnabled(bool enable)
Definition: bmpimage.h:46
bool _allowNPOT
Definition: image.h:202
Definition: list.h:134
static bool _glTextureCompressionSupported
Definition: image.h:193
static void EmptyInstanceList()
virtual int TextureWidth(void)
unsigned int _width
Definition: image.h:82
virtual int PixelFormat(void)
IFontImage.
const LoadOptions & GetLoadOptions(void) const