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