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