GL Studio C++ Runtime API
texture_palette.h
Go to the documentation of this file.
1 /*! \file
2  \brief The disti::TexturePalette class.
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 #ifndef _TEXTURE_PALETTE_H
41 #define _TEXTURE_PALETTE_H
42 
43 #include "disti_metadata.h"
44 #include "dynamic_array.h"
45 #include "gls_include.h"
47 #include "image.h"
48 #include <iostream>
49 
50 namespace disti
51 {
52 class FilePathClass;
53 
54 // Objects with no texture have a palette index of -1
55 // Valid texture indeces are zero through some positive number (no max)
56 const int NO_TEXTURE = -1;
57 
58 // When multiple textures are selected in the Texture Browser
59 // It is defined here, because it must be different than NO_TEXTURE
60 const int MULTIPLE_TEXTURES_SELECTED = -2;
61 
62 /** Current state of texture in the texture palette */
63 typedef enum
64 {
65  TEXTURE_UNUSED, /**< The texture slot is unused */
66  TEXTURE_IGNORED, /**< Texture slot does not contain a texture,
67  the user choose to ignore it. It appears UNUSED for most purposes.*/
68  TEXTURE_INVALID, /**< Texture slot contains a texture, but it isn't
69  bound to the GL context */
70  TEXTURE_VALID /**< Texture slot contains a texture, and it is
71  bound to the GL context */
72 
74 
75 /** Enumeration for an image compresion codec
76  */
78 {
79 public:
80  GLS_EXPORT DistiAttributeImageCodecEnum( CallbackMethodCallerBase* callback, const AttributeName& name, glsImageCodec* attribPtr );
81  virtual GLS_EXPORT ~DistiAttributeImageCodecEnum();
82 };
83 
84 /** A texture palette entry. Keeps track of which textures are assigned to
85  each entry in the texture palette */
87 {
88  DistiAttribDict _attribDict;
89 
90  TextureState_e status; /**< Status of the texture: UNUSED, INVALID, VALID, IGNORED */
91 
92  FilePathClass* _filePath; /**< Path to the texture file */
93  char* _returned_filename; /**< Holds a pointer to the buffer returned by Filename() */
94  bool _supportsNPOTValue;
95 
96  void SupportsAllowNPOT();
97 
98  void InitMetadata();
99 
100 public:
101  static GLS_EXPORT bool _defaultGenerateInline;
102 
103  bool generateInline; /**< True if the image is to be generated as inline code */
104  bool reverseAlpha; /**< True if the alpha channel should be reversed on load */
105  bool isLoadingDeferred; /**< True if loading should be deferred until first draw */
106  Image* texture; /**< Pointer to the texture object itself */
107  long compressedSize; /**< Size of image when compressed with currently set inline CODEC */
108  glsImageCodec codec; /**< CODEC that will be used to compress an inline image */
109  int compressionFactor; /**< Compression factor of the image, used only for JPEG */
110  int desiredLoadWidth; /**< The width that the image should load at. 0 indicates full size. (Editor only) */
111  int desiredLoadHeight; /**< The height that the image should load at. 0 indicates full size. (Editor only) */
112  int sourceImageWidth; /**< The width of the source image. (pixels) (Editor only) */
113  int sourceImageHeight; /**< The height of the source image. (pixels) (Editor only) */
114  int sourceImageMemSize; /**< The size of the source image im memory. (bytes) (Editor only) */
115  bool useGLTextureCompression; /**< True if the image should be generated to use hardware texture compression. (Editor only) */
116 
117  bool allowNPOT; /**< Allow Non-power of two texture (do not scale up) */
118 
119  GLS_EXPORT TexturePaletteEntry( void );
120  GLS_EXPORT TexturePaletteEntry( const TexturePaletteEntry& source );
121  GLS_EXPORT ~TexturePaletteEntry( void );
122  GLS_EXPORT void Initialize( void );
123 
124  GLS_EXPORT TexturePaletteEntry& operator=( const TexturePaletteEntry& source );
125 
126  GLS_EXPORT TextureState_e TextureStatus( void ) { return status; }
127  GLS_EXPORT const char* Filename( void ) const; // returns the filename relative to the current working directory
128  GLS_EXPORT void Filename( const char* name ); // set the filename relative to the current working directory
129  GLS_EXPORT void Invalidate( void );
130  GLS_EXPORT void Validate( void );
131  GLS_EXPORT void Ignore(); // Sets texture to NULL and status to IGNORED
132 
133  GLS_EXPORT bool IsEmpty() const; // true if there is no texture object (unused or ignored)
134  GLS_EXPORT bool IsIgnored() const; // true if ignored
135  GLS_EXPORT bool IsUsed() const; // true if invalid or valid (not unused or ignored)
136 
137  GLS_EXPORT std::ostream& WriteValue( std::ostream& outstr );
138  GLS_EXPORT std::istream& ReadValue( std::istream& instr );
139 };
140 
141 /** Texture Palette class. Stores a list of textures, each with its own
142  * texture handle. This the textures to be stored separately from the
143  * objects, which allows multiple objects to share the same textures.
144  */
146 {
147  /** A texture of a single magenta pixel used for displaying textures that are not valid */
148  Image* _defaultTexture;
149 
150  /** A callback that will get called when a texture in the palette has been update.
151  * \param bool True if it was added/update, false if it was removed
152  * \param int The index in the palette that was modified
153  * \param DisplayFrame The frame the palette belongs to
154  */
155  void ( *_paletteUpdateCallback )( bool, int, DisplayFrame* );
156 
157  DisplayFrame* _owningDisplayFrame;
158 
159  /** A dynamic array of TexturePaletteEntry */
161 
162 public:
163  /** \return true if the index \a i passed in is a valid texture index. Doesn't imply that a texture exists at that index,
164  * merely that the index is within the array bounds of the texture palette */
165  GLS_EXPORT bool IsValidIndex( int i );
166 
167  /** Create a new texture palette with the indicated number of entries
168  * \param size The number of entries in the palette
169  */
170  GLS_EXPORT explicit TexturePalette( int size = 0 );
171 
172  /** Resize texture palette with the indicated number of entries
173  * \param newSize The new number of entries in the palette
174  */
175  GLS_EXPORT void PaletteSize( int newSize );
176 
177  GLS_EXPORT ~TexturePalette( void );
178 
179  GLS_EXPORT void operator=( TexturePalette& source );
180 
181  /** Returns the texture palette entry at index i, expanding the palette to accomodate the index if needed. */
182  GLS_EXPORT TexturePaletteEntry* Entry( int i );
183 
184  /** Gets the number of textures (whether valid or not) in this texture palette.
185  * \deprecated Renamed to Count() to match DynamicArray.
186  */
187  DISTI_DEPRECATED( "Renamed to Count() to match DynamicArray." )
188  unsigned int size() const { return Count(); }
189 
190  /** The list of entries for this palette
191  * \deprecated Member data has been made private. Use accessor functions like Entry() and Count() instead.
192  */
193  DISTI_DEPRECATED( "Member data has been made private. Use accessor functions like Entry() and Count() instead." )
195 
196  /** Gets the number of textures (whether valid or not) in this texture palette */
197  GLS_EXPORT unsigned int Count() const;
198 
199  /** Invalidates all of the textures in the palette, forcing them to be
200  * rebound the next time they are referenced by an object.
201  */
202  GLS_EXPORT void InvalidateTextures( void );
203 
204  /** Finds an unused slot in the texture palette.
205  * \return The index of the first unused slot in the palette.
206  */
207  GLS_EXPORT int FindAvailableSlot( void );
208 
209  /** Returns the filename associated with the texture at the given index.
210  * \param i The index to get the filename from
211  * \return The filename of the texture at that index
212  */
213  GLS_EXPORT const char* TextureFilename( int i );
214 
215  /** Sets the filename associated with the texture at the given index.
216  * \param i The index to get the filename from
217  * \param filename The filename to set
218  */
219  GLS_EXPORT void TextureFilename( int i, const char* filename );
220 
221  /** Sets the texture at the given index.
222  * Attempts to load the texture from disk
223  * \param i The texture index to load the texture into
224  * \param filename The filename to set
225  * \param options Image load options (e.g. reverse alpha)
226  * \param glTexCompress The GlTextureCompression setting for the new Image.
227  * \param allowNPOT If the image is allowed to be non-power of two (NPOT)
228  * \param isLoadingDeferred If true, the image will not be loaded from disk until bound.
229  * \return TRUE if successful else FALSE
230  */
231  GLS_EXPORT bool SetTexture( int i, const char* filename, const Image::LoadOptions& options = Image::LoadOptions(), bool glTexCompress = false, bool allowNPOT = true, bool isLoadingDeferred = true );
232 
233  /** Sets the texture at the given index using a TexturePaletteEntry structure.
234  * This is generally only used in the Editor
235  * \param i
236  * \param entry Image generation options, NULL if not setting them
237  */
238  GLS_EXPORT bool SetTexture( int i, TexturePaletteEntry* entry );
239 
240  /** Sets the texture at the given index
241  * Does NOT attempt to load a file
242  * \param i The texture index to load the texture into
243  * \param image An image that will be the texture
244  * \return TRUE if successful else FALSE
245  */
246  GLS_EXPORT bool SetTexture( int i, Image* image );
247 
248  /** Sets the texture at the given index
249  * \param i The index to insert at
250  * \param image Structure containing the compressed image data
251  * \param isLoadingDeferred If true, the image will not be loaded from disk until bound.
252  */
253  GLS_EXPORT bool SetInlineTexture( int i, glsInlineImage& image, bool isLoadingDeferred = true );
254 
255  /** Disables image sharing for the Image at the given index and
256  * ensures that the index refers to a unique Image instance.
257  * Note: If you want to disable image sharing for an Image that is not
258  * yet in a palette, you should call AllowImageSharing(false) on the Image.
259  * \param index The index of the texture to disable image sharing. The Image must already be loaded in the palette.
260  * \returns true on success
261  * \returns false on failure (Invalid index or Image could not be guarenteed unique)
262  */
263  GLS_EXPORT bool DisableImageSharing( int index );
264 
265  /** Finds a texture based on its filename
266  * \param name The filename of the texture to find
267  * \return The index if found, -1 if not found
268  */
269  GLS_EXPORT int FindTextureByName( const char* name );
270 
271  /** Gets the texture state of the texture at the given index.
272  * \param i The index to get the texture state from
273  * \return The state (UNUSED,VALID,INVALID) of the texture
274  */
275  GLS_EXPORT TextureState_e TextureState( int i );
276 
277  /** Returns the width of the texture image in pixels
278  * \param i The index of the texture to get the width of
279  * \return The width of the texture image in pixels
280  */
281  GLS_EXPORT int Width( int i );
282 
283  /** Returns the height of the texture image in pixels
284  * \param i The index of the texture to get the height of
285  * \return The height of the texture image in pixels
286  */
287  GLS_EXPORT int Height( int i );
288 
289  /** Returns the power of two width of the texture image in pixels
290  * \param i The index of the texture to get the power of two width of
291  * \return The power of two width of the texture image in pixels
292  */
293  GLS_EXPORT int TextureWidth( int i );
294 
295  /** Returns the power of two height of the texture image in pixels
296  * \param i The index of the texture to get the power of two height of
297  * \return The power of two height of the texture image in pixels
298  */
299  GLS_EXPORT int TextureHeight( int i );
300 
301  /** Returns the Texture Coordinate of the upper right corner of the image
302  * computed as (Width/TextureWidth)
303  * \param i The index of the texture
304  * \return The Texture Coordinate of the upper right corner of the image
305  */
306  GLS_EXPORT float TextureCoordX( int i );
307 
308  /** Returns the Texture Coordinate of the upper right corner of the image
309  * computed as (Height/TextureHeight)
310  * \param i The index of the texture
311  * \return The Texture Coordinate of the upper right corner of the image
312  */
313  GLS_EXPORT float TextureCoordY( int i );
314 
315  /** Invalidate the texture at the given index, causing it to be rebound
316  * the next time it is referencd
317  * \param i The index of the texture
318  */
319  GLS_EXPORT void InvalidateTexture( int i );
320 
321 #ifdef GLES
322  /** Bind the texture at the given index, unless it is already bound. Set
323  * as the texture to be used for texturing polygons
324  * \param i The index of the texture
325  * \param stateManager
326  */
327  GLS_EXPORT void BindTexture( int i, IGlsStateManager* stateManager );
328 #else
329  /** Bind the texture at the given index, unless it is already bound. Set
330  * as the texture to be used for texturing polygons
331  * \param i The index of the texture
332  */
333  GLS_EXPORT void BindTexture( int i );
334 #endif
335 
336  /** Return whether or not texture is bound
337  * \param i The index of the texture
338  * \return boolean result of whether or not texture is bound
339  */
340  GLS_EXPORT int TextureValid( int i );
341 
342  /** Delete the texture at the given index. Mark the index as unused.
343  * \param i The index of the texture
344  */
345  GLS_EXPORT void DeleteTexture( int i );
346 
347  /** Get a pointer to the texture at the given index.
348  * \param i The index of the texture
349  * \return The texture at that index. NULL if there is none.
350  */
351  GLS_EXPORT Image* Texture( int i );
352 
353  /** \return True if the image is to be generated as inline code
354  * \param i The index of the texture
355  */
356  GLS_EXPORT bool GenerateInline( int i );
357 
358  /** \return True if the image is to be generated to use OpenGL texture compression
359  * \param i The index of the texture
360  */
361  GLS_EXPORT bool UseGLTextureCompression( int i );
362 
363  /** \return True if the image is allowed to be non power of two
364  * \param i The index of the texture
365  */
366  GLS_EXPORT bool AllowNPOT( int i );
367 
368  /** \return Size of image when compressed with currently set inline CODEC
369  * \param i The index of the texture
370  */
371  GLS_EXPORT long CompressedSize( int i );
372 
373  /** \return CODEC that will be used to compress an inline image
374  * \param i The index of the texture
375  */
376  GLS_EXPORT glsImageCodec Codec( int i );
377 
378  /** \return Compression factor of the image, used only for JPEG
379  * \param i The index of the texture
380  */
381  GLS_EXPORT int CompressionFactor( int i );
382 
383  /** Set True if the image is to be generated as inline code
384  * \param i The index of the texture
385  * \param val
386  */
387  GLS_EXPORT void GenerateInline( int i, bool val );
388 
389  /** Set True if the image is to be generated to use OpenGL texture compression
390  * \param i The index of the texture
391  * \param val
392  */
393  GLS_EXPORT void UseGLTextureCompression( int i, bool val );
394 
395  /** Set True if the image is allowed to be non power of two
396  * \param i The index of the texture
397  * \param val the value to set allowing non-power of two (NPOT) functionality
398  */
399  GLS_EXPORT void AllowNPOT( int i, bool val );
400 
401  /** Set Size of image when compressed with currently set inline CODEC
402  * \param i The index of the texture
403  * \param val
404  */
405  GLS_EXPORT void CompressedSize( int i, long val );
406 
407  /** Set CODEC that will be used to compress an inline image
408  * \param i The index of the texture
409  * \param val The codec to set
410  * \param reload Whether or not to reload the image
411  */
412  GLS_EXPORT void Codec( int i, glsImageCodec val, bool reload = true );
413 
414  /** Set Compression factor of the image, used only for JPEG
415  * \param i The index of the texture
416  * \param val
417  * \param reload
418  */
419  GLS_EXPORT void CompressionFactor( int i, int val, bool reload = true );
420 
421  /** Sets the desired load size for the image.
422  * If the loaded image is larger than the specified dimensions,
423  * it will be scaled down during the load.
424  * \param i The index of the texture
425  * \param width The desired width
426  * \param height The desired height
427  */
428  GLS_EXPORT void DesiredLoadSize( int i, int width, int height );
429 
430  /** Reload a texture from disk, then downsize and compress it using the current settings
431  * of the TexturePaletteEntry
432  * \param i The index of the texture to reload
433  */
434  GLS_EXPORT void Reload( int i );
435 
436  /** Set mip-mapping state for given texture
437  * \param i The index of the texture to set mipmapping for
438  * \param val The mipmapping state to set
439  */
440  GLS_EXPORT void SetMipMap( int i, bool val );
441 
442  /** Compress using the current compression settings for the texture
443  * and scale down to the DesiredLoadSize.
444  * \param i The index of the texture
445  */
446  GLS_EXPORT void PreviewGenerated( int i );
447 
448  /** Sets up for a callback to be used for reacting to the texture palette items and filenames to be updated.
449  * \param callback A function accepting whether the texture was added/modified(true) or removed(false), the index of it, and the frame this palette belongs to.
450  * \param owningFrame The display frame that this texture palette belongs to.
451  */
452  GLS_EXPORT void SetTexturePaletteCallback( void ( *callback )( bool, int, DisplayFrame* ), DisplayFrame* owningFrame );
453 
454  /** Scales down an image to the next power-of-two size where (width <= desiredWidth || height <= desiredHeight)
455  * Maintains aspect ratio.
456  * Note: This method may be removed from the TexturePalette in the future.
457  */
458  static GLS_EXPORT bool DownsizeImage( Image* image, int desiredWidth, int desiredHeight );
459 
460  /** The DistiAttributeTexturePalette class for version 2.1 and older (read only). Included for
461  * backwards compatibility with v 2.1
462  */
464  {
465  TexturePalette** _palette;
466 
467  public:
468  GLS_EXPORT DistiAttributeTexturePalette_V21( TexturePalette** palette );
469 
470  // This atttribute is never written
471  virtual bool OkToWrite() const { return false; }
472  virtual std::ostream& WriteValue( std::ostream& outstr ) { return outstr; }
473 
474  virtual GLS_EXPORT std::istream& ReadValue( std::istream& instr );
475  };
476 
477  /** The DistiAttributeTexturePalette class for version 3.0 and later
478  */
480  {
481  TexturePalette** _palette;
482 
483  public:
484  GLS_EXPORT DistiAttributeTexturePalette( TexturePalette** palette );
485  virtual GLS_EXPORT std::ostream& WriteValue( std::ostream& outstr );
486  virtual GLS_EXPORT std::istream& ReadValue( std::istream& instr );
487  virtual DISTI_EXPORT DistiAttributeBase& operator=( const DistiAttributeBase& oldClass );
488  };
489 };
490 
491 } // namespace disti
492 
493 #endif
Definition: image.h:79
glsImageCodec
Definition: image.h:62
glsImageCodec Codec(int i)
Definition: display_frame.h:85
virtual std::ostream & WriteValue(std::ostream &outstr)
const char * TextureFilename(int i)
Definition: image.h:162
bool useGLTextureCompression
Definition: texture_palette.h:115
The disti metadata.
#define DISTI_DEPRECATED(msg)
Defines whether this compiler supports the C++14 deprecated attribute.
Definition: gls_cpp_lang_support.h:436
virtual std::istream & ReadValue(std::istream &instr)
float TextureCoordX(int i)
int FindAvailableSlot(void)
TextureState_e
Definition: texture_palette.h:63
Definition: dynamic_array.h:66
static bool DownsizeImage(Image *image, int desiredWidth, int desiredHeight)
The disti::DynamicArray class. A templated array of objects capable of dynamically growing...
bool SetTexture(int i, const char *filename, const Image::LoadOptions &options=Image::LoadOptions(), bool glTexCompress=false, bool allowNPOT=true, bool isLoadingDeferred=true)
TexturePaletteEntry * Entry(int i)
Definition: texture_palette.h:86
bool UseGLTextureCompression(int i)
int desiredLoadWidth
Definition: texture_palette.h:110
long compressedSize
Definition: texture_palette.h:107
Definition: gls_metadata_attributes.h:1712
Definition: texture_palette.h:65
virtual bool OkToWrite() const
Definition: texture_palette.h:471
Image * Texture(int i)
Definition: gls_state_manager_interface.h:67
unsigned int Count() const
Definition: texture_palette.h:66
int compressionFactor
Definition: texture_palette.h:109
A file for all GL Studio files to include.
TexturePalette(int size=0)
Definition: texture_palette.h:70
The Image class. All textures are converted internally into Images.
void SetMipMap(int i, bool val)
void InvalidateTexture(int i)
Definition: texture_palette.h:68
int TextureHeight(int i)
bool allowNPOT
Definition: texture_palette.h:117
virtual DistiAttributeBase & operator=(const DistiAttributeBase &oldClass)
int sourceImageHeight
Definition: texture_palette.h:113
void InvalidateTextures(void)
float TextureCoordY(int i)
Definition: texture_palette.h:77
void BindTexture(int i)
int sourceImageWidth
Definition: texture_palette.h:112
int sourceImageMemSize
Definition: texture_palette.h:114
Definition: disti_metadata.h:186
bool reverseAlpha
Definition: texture_palette.h:104
Definition: file_path_class.h:61
void PaletteSize(int newSize)
Definition: disti_metadata.h:668
Image * texture
Definition: texture_palette.h:106
Definition: callback_caller_base.h:55
virtual std::istream & ReadValue(std::istream &instr)
bool SetInlineTexture(int i, glsInlineImage &image, bool isLoadingDeferred=true)
long CompressedSize(int i)
bool DisableImageSharing(int index)
Defines templated metadata classes for DisplayObjects and other uses.
bool generateInline
Definition: texture_palette.h:103
Definition: texture_palette.h:145
void PreviewGenerated(int i)
void SetTexturePaletteCallback(void(*callback)(bool, int, DisplayFrame *), DisplayFrame *owningFrame)
bool isLoadingDeferred
Definition: texture_palette.h:105
unsigned int size() const
Definition: texture_palette.h:188
int CompressionFactor(int i)
glsImageCodec codec
Definition: texture_palette.h:108
Definition: disti_metadata.h:85
bool IsValidIndex(int i)
void DesiredLoadSize(int i, int width, int height)
Definition: bmpimage.h:46
TextureState_e TextureState(int i)
void DeleteTexture(int i)
int desiredLoadHeight
Definition: texture_palette.h:111
virtual std::ostream & WriteValue(std::ostream &outstr)
Definition: texture_palette.h:472
DynamicArray< TexturePaletteEntry > & palette
Definition: texture_palette.h:194
int FindTextureByName(const char *name)
bool GenerateInline(int i)