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