texture_palette.h

Go to the documentation of this file.

/*! \file
  \brief  The disti::TexturePalette class.

  \par Copyright Information

  Copyright (c) 2017 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/
#ifndef _TEXTURE_PALETTE_H
#define _TEXTURE_PALETTE_H

#include "disti_metadata.h"
#include "dynamic_array.h"
#include "gls_include.h"
#include "gls_metadata_attributes.h"
#include "image.h"
#include <iostream>

namespace disti
{
class FilePathClass;

// Objects with no texture have a palette index of -1
// Valid texture indeces are zero through some positive number (no max)
const int NO_TEXTURE = -1;

// When multiple textures are selected in the Texture Browser
// It is defined here, because it must be different than NO_TEXTURE
const int MULTIPLE_TEXTURES_SELECTED = -2;

/** Current state of texture in the texture palette */
typedef enum
{
    TEXTURE_UNUSED,  /**< The texture slot is unused */
    TEXTURE_IGNORED, /**< Texture slot does not contain a texture,
                             the user choose to ignore it. It appears UNUSED for most purposes.*/
    TEXTURE_INVALID, /**< Texture slot contains a texture, but it isn't
                             bound to the GL context */
    TEXTURE_VALID    /**< Texture slot contains a texture, and it is
                             bound to the GL context */

} TextureState_e;

/** Enumeration for an image compresion codec
  */
class DistiAttributeImageCodecEnum : public DistiAttributeEnumDirect<glsImageCodec>
{
public:
    GLS_EXPORT DistiAttributeImageCodecEnum( CallbackMethodCallerBase* callback, const AttributeName& name, glsImageCodec* attribPtr );
    virtual GLS_EXPORT ~DistiAttributeImageCodecEnum();
};

/** A texture palette entry.  Keeps track of which textures are assigned to
    each entry in the texture palette */
class TexturePaletteEntry
{
    DistiAttribDict _attribDict;

    TextureState_e status; /**< Status of the texture: UNUSED, INVALID, VALID, IGNORED */

    FilePathClass* _filePath;          /**< Path to the texture file */
    char*          _returned_filename; /**< Holds a pointer to the buffer returned by Filename() */
    bool           _supportsNPOTValue;

    void SupportsAllowNPOT();

    void InitMetadata();

public:
    static GLS_EXPORT bool _defaultGenerateInline;

    bool          generateInline;          /**< True if the image is to be generated as inline code */
    bool          reverseAlpha;            /**< True if the alpha channel should be reversed on load */
    bool          isLoadingDeferred;       /**< True if loading should be deferred until first draw */
    Image*        texture;                 /**< Pointer to the texture object itself  */
    long          compressedSize;          /**< Size of image when compressed with currently set inline CODEC */
    glsImageCodec codec;                   /**< CODEC that will be used to compress an inline image */
    int           compressionFactor;       /**< Compression factor of the image, used only for JPEG */
    int           desiredLoadWidth;        /**< The width that the image should load at. 0 indicates full size. (Editor only) */
    int           desiredLoadHeight;       /**< The height that the image should load at. 0 indicates full size. (Editor only) */
    int           sourceImageWidth;        /**< The width of the source image. (pixels) (Editor only) */
    int           sourceImageHeight;       /**< The height of the source image. (pixels) (Editor only) */
    int           sourceImageMemSize;      /**< The size of the source image im memory. (bytes) (Editor only) */
    bool          useGLTextureCompression; /**< True if the image should be generated to use hardware texture compression. (Editor only) */

    bool allowNPOT; /**< Allow Non-power of two texture (do not scale up) */

    GLS_EXPORT TexturePaletteEntry( void );
    GLS_EXPORT TexturePaletteEntry( const TexturePaletteEntry& source );
    GLS_EXPORT ~TexturePaletteEntry( void );
    GLS_EXPORT void Initialize( void );

    GLS_EXPORT TexturePaletteEntry& operator=( const TexturePaletteEntry& source );

    GLS_EXPORT TextureState_e TextureStatus( void ) { return status; }
    GLS_EXPORT const char*    Filename( void ) const;       // returns the filename relative to the current working directory
    GLS_EXPORT void           Filename( const char* name ); // set the filename relative to the current working directory
    GLS_EXPORT void           Invalidate( void );
    GLS_EXPORT void           Validate( void );
    GLS_EXPORT void           Ignore(); // Sets texture to NULL and status to IGNORED

    GLS_EXPORT bool IsEmpty() const;   // true if there is no texture object (unused or ignored)
    GLS_EXPORT bool IsIgnored() const; // true if ignored
    GLS_EXPORT bool IsUsed() const;    // true if invalid or valid (not unused or ignored)

    GLS_EXPORT std::ostream& WriteValue( std::ostream& outstr );
    GLS_EXPORT std::istream& ReadValue( std::istream& instr );
};

/** Texture Palette class.  Stores a list of textures, each with its own
  * texture handle.  This the textures to be stored separately from the
  * objects, which allows multiple objects to share the same textures.
  */
class TexturePalette
{
    /** A texture of a single magenta pixel used for displaying textures that are not valid */
    Image* _defaultTexture;

    /** A callback that will get called when a texture in the palette has been update.
      * \param bool True if it was added/update, false if it was removed
      * \param int The index in the palette that was modified
      * \param DisplayFrame The frame the palette belongs to
    */
    void ( *_paletteUpdateCallback )( bool, int, DisplayFrame* );

    DisplayFrame* _owningDisplayFrame;

    /** A dynamic array of TexturePaletteEntry */
    DynamicArray<TexturePaletteEntry> _palette;

public:
    /** \return true if the index \a i passed in is a valid texture index.  Doesn't imply that a texture exists at that index, 
      * merely that the index is within the array bounds of the texture palette */
    GLS_EXPORT bool IsValidIndex( int i );

    /** Create a new texture palette with the indicated number of entries
      * \param size  The number of entries in the palette
      */
    GLS_EXPORT explicit TexturePalette( int size = 0 );

    /** Resize texture palette with the indicated number of entries
      * \param newSize  The new number of entries in the palette
      */
    GLS_EXPORT void PaletteSize( int newSize );

    GLS_EXPORT ~TexturePalette( void );

    GLS_EXPORT void operator=( TexturePalette& source );

    /** Returns the texture palette entry at index i, expanding the palette to accomodate the index if needed. */
    GLS_EXPORT TexturePaletteEntry* Entry( int i );

    /** Gets the number of textures (whether valid or not) in this texture palette.
      * \deprecated Renamed to Count() to match DynamicArray.
      */
    DISTI_DEPRECATED( "Renamed to Count() to match DynamicArray." )
    unsigned int size() const { return Count(); }

    /** The list of entries for this palette
      * \deprecated Member data has been made private. Use accessor functions like Entry() and Count() instead.
      */
    DISTI_DEPRECATED( "Member data has been made private. Use accessor functions like Entry() and Count() instead." )
    DynamicArray<TexturePaletteEntry>& palette;

    /** Gets the number of textures (whether valid or not) in this texture palette */
    GLS_EXPORT unsigned int Count() const;

    /** Invalidates all of the textures in the palette, forcing them to be
      * rebound the next time they are referenced by an object.
      */
    GLS_EXPORT void InvalidateTextures( void );

    /** Finds an unused slot in the texture palette.
      * \return  The index of the first unused slot in the palette.
      */
    GLS_EXPORT int FindAvailableSlot( void );

    /** Returns the filename associated with the texture at the given index.
      * \param i   The index to get the filename from
      * \return  The filename of the texture at that index
      */
    GLS_EXPORT const char* TextureFilename( int i );

    /** Sets the filename associated with the texture at the given index.
      * \param i   The index to get the filename from
      * \param filename The filename to set
      */
    GLS_EXPORT void TextureFilename( int i, const char* filename );

    /** Sets the texture at the given index.
      * Attempts to load the texture from disk
      * \param i   The texture index to load the texture into
      * \param filename  The filename to set
      * \param options Image load options (e.g. reverse alpha)
      * \param glTexCompress The GlTextureCompression setting for the new Image.
      * \param allowNPOT  If the image is allowed to be non-power of two (NPOT)
      * \param isLoadingDeferred If true, the image will not be loaded from disk until bound.
      * \return TRUE if successful else FALSE
      */
    GLS_EXPORT bool SetTexture( int i, const char* filename, const Image::LoadOptions& options = Image::LoadOptions(), bool glTexCompress = false, bool allowNPOT = true, bool isLoadingDeferred = true );

    /** Sets the texture at the given index using a TexturePaletteEntry structure.
      * This is generally only used in the Editor
      * \param i
      * \param entry Image generation options, NULL if not setting them
      */
    GLS_EXPORT bool SetTexture( int i, TexturePaletteEntry* entry );

    /** Sets the texture at the given index
      * Does NOT attempt to load a file
      * \param i   The texture index to load the texture into
      * \param image  An image that will be the texture
      * \return TRUE if successful else FALSE
      */
    GLS_EXPORT bool SetTexture( int i, Image* image );

    /** Sets the texture at the given index 
      * \param i      The index to insert at   
      * \param image  Structure containing the compressed image data
      * \param isLoadingDeferred If true, the image will not be loaded from disk until bound.
      */
    GLS_EXPORT bool SetInlineTexture( int i, glsInlineImage& image, bool isLoadingDeferred = true );

    /** Disables image sharing for the Image at the given index and
      * ensures that the index refers to a unique Image instance.
      * Note: If you want to disable image sharing for an Image that is not
      * yet in a palette, you should call AllowImageSharing(false) on the Image.
      * \param index The index of the texture to disable image sharing.  The Image must already be loaded in the palette.
      * \returns true on success
      * \returns false on failure (Invalid index or Image could not be guarenteed unique)
      */
    GLS_EXPORT bool DisableImageSharing( int index );

    /** Finds a texture based on its filename
      * \param name   The filename of the texture to find
      * \return  The index if found, -1 if not found
      */
    GLS_EXPORT int FindTextureByName( const char* name );

    /** Gets the texture state of the texture at the given index.
      * \param i  The index to get the texture state from
      * \return   The state (UNUSED,VALID,INVALID) of the texture
      */
    GLS_EXPORT TextureState_e TextureState( int i );

    /** Returns the width of the texture image in pixels
      * \param i  The index of the texture to get the width of
      * \return The width of the texture image in pixels
      */
    GLS_EXPORT int Width( int i );

    /** Returns the height of the texture image in pixels
      * \param i  The index of the texture to get the height of
      * \return The height of the texture image in pixels
      */
    GLS_EXPORT int Height( int i );

    /** Returns the power of two width of the texture image in pixels
      * \param i  The index of the texture to get the power of two width of
      * \return The power of two width of the texture image in pixels
      */
    GLS_EXPORT int TextureWidth( int i );

    /** Returns the power of two height of the texture image in pixels
      * \param i  The index of the texture to get the power of two height of
      * \return The power of two height of the texture image in pixels
      */
    GLS_EXPORT int TextureHeight( int i );

    /** Returns the Texture Coordinate of the upper right corner of the image
      * computed as (Width/TextureWidth)
      * \param i  The index of the texture
      * \return The Texture Coordinate of the upper right corner of the image
      */
    GLS_EXPORT float TextureCoordX( int i );

    /** Returns the Texture Coordinate of the upper right corner of the image
      * computed as (Height/TextureHeight)
      * \param i  The index of the texture
      * \return The Texture Coordinate of the upper right corner of the image
      */
    GLS_EXPORT float TextureCoordY( int i );

    /** Invalidate the texture at the given index, causing it to be rebound
      * the next time it is referencd
      * \param i  The index of the texture
      */
    GLS_EXPORT void InvalidateTexture( int i );

#ifdef GLES
    /** Bind the texture at the given index, unless it is already bound.  Set
      * as the texture to be used for texturing polygons
      * \param i  The index of the texture
      * \param stateManager  
      */
    GLS_EXPORT void BindTexture( int i, IGlsStateManager* stateManager );
#else
    /** Bind the texture at the given index, unless it is already bound.  Set
      * as the texture to be used for texturing polygons
      * \param i  The index of the texture
      */
    GLS_EXPORT void BindTexture( int i );
#endif

    /** Return whether or not texture is bound
      * \param i  The index of the texture
      * \return boolean result of whether or not texture is bound
      */
    GLS_EXPORT int TextureValid( int i );

    /** Delete the texture at the given index.  Mark the index as unused.
      * \param i  The index of the texture
      */
    GLS_EXPORT void DeleteTexture( int i );

    /** Get a pointer to the texture at the given index.
      * \param i  The index of the texture
      * \return  The texture at that index.  NULL if there is none.
      */
    GLS_EXPORT Image* Texture( int i );

    /** \return True if the image is to be generated as inline code 
      * \param i The index of the texture
      */
    GLS_EXPORT bool GenerateInline( int i );

    /** \return True if the image is to be generated to use OpenGL texture compression
      * \param i The index of the texture
      */
    GLS_EXPORT bool UseGLTextureCompression( int i );

    /** \return True if the image is allowed to be non power of two
      * \param i The index of the texture
      */
    GLS_EXPORT bool AllowNPOT( int i );

    /** \return Size of image when compressed with currently set inline CODEC
      * \param i The index of the texture
      */
    GLS_EXPORT long CompressedSize( int i );

    /** \return CODEC that will be used to compress an inline image 
      * \param i The index of the texture
      */
    GLS_EXPORT glsImageCodec Codec( int i );

    /** \return Compression factor of the image, used only for JPEG
      * \param i The index of the texture
      */
    GLS_EXPORT int CompressionFactor( int i );

    /** Set True if the image is to be generated as inline code 
      * \param i The index of the texture
      * \param val
      */
    GLS_EXPORT void GenerateInline( int i, bool val );

    /** Set True if the image is to be generated to use OpenGL texture compression
      * \param i The index of the texture
      * \param val
      */
    GLS_EXPORT void UseGLTextureCompression( int i, bool val );

    /** Set True if the image is allowed to be non power of two
      * \param i The index of the texture
      * \param val the value to set allowing non-power of two (NPOT) functionality
      */
    GLS_EXPORT void AllowNPOT( int i, bool val );

    /** Set Size of image when compressed with currently set inline CODEC
      * \param i The index of the texture
      * \param val
      */
    GLS_EXPORT void CompressedSize( int i, long val );

    /** Set CODEC that will be used to compress an inline image 
      * \param i       The index of the texture
      * \param val     The codec to set
      * \param reload  Whether or not to reload the image
      */
    GLS_EXPORT void Codec( int i, glsImageCodec val, bool reload = true );

    /** Set Compression factor of the image, used only for JPEG
      * \param i The index of the texture
      * \param val
      * \param reload
      */
    GLS_EXPORT void CompressionFactor( int i, int val, bool reload = true );

    /** Sets the desired load size for the image.
      * If the loaded image is larger than the specified dimensions,
      * it will be scaled down during the load.
      * \param i The index of the texture
      * \param width The desired width
      * \param height The desired height
      */
    GLS_EXPORT void DesiredLoadSize( int i, int width, int height );

    /** Reload a texture from disk, then downsize and compress it using the current settings
      * of the TexturePaletteEntry
      * \param i The index of the texture to reload
      */
    GLS_EXPORT void Reload( int i );

    /** Set mip-mapping state for given texture
      * \param i    The index of the texture to set mipmapping for
      * \param val  The mipmapping state to set
      */
    GLS_EXPORT void SetMipMap( int i, bool val );

    /** Compress using the current compression settings for the texture
      * and scale down to the DesiredLoadSize.
      * \param i The index of the texture
      */
    GLS_EXPORT void PreviewGenerated( int i );

    /** Sets up for a callback to be used for reacting to the texture palette items and filenames to be updated.
      * \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.
      * \param owningFrame The display frame that this texture palette belongs to.
      */
    GLS_EXPORT void SetTexturePaletteCallback( void ( *callback )( bool, int, DisplayFrame* ), DisplayFrame* owningFrame );

    /** Scales down an image to the next power-of-two size where (width <= desiredWidth || height <= desiredHeight)
      * Maintains aspect ratio.
      * Note: This method may be removed from the TexturePalette in the future.
      */
    static GLS_EXPORT bool DownsizeImage( Image* image, int desiredWidth, int desiredHeight );

    /** The DistiAttributeTexturePalette class for version 2.1 and older (read only). Included for
      * backwards compatibility with v 2.1
      */
    class DistiAttributeTexturePalette_V21 : public DistiAttributeBase
    {
        TexturePalette** _palette;

    public:
        GLS_EXPORT DistiAttributeTexturePalette_V21( TexturePalette** palette );

        // This atttribute is never written
        virtual bool          OkToWrite() const { return false; }
        virtual std::ostream& WriteValue( std::ostream& outstr ) { return outstr; }

        virtual GLS_EXPORT std::istream& ReadValue( std::istream& instr );
    };

    /** The DistiAttributeTexturePalette class for version 3.0 and later
      */
    class DistiAttributeTexturePalette : public DistiAttributeBase
    {
        TexturePalette** _palette;

    public:
        GLS_EXPORT         DistiAttributeTexturePalette( TexturePalette** palette );
        virtual GLS_EXPORT std::ostream& WriteValue( std::ostream& outstr );
        virtual GLS_EXPORT std::istream& ReadValue( std::istream& instr );
        virtual DISTI_EXPORT DistiAttributeBase& operator=( const DistiAttributeBase& oldClass );
    };
};

} // namespace disti

#endif