texture_loader.h

Go to the documentation of this file.

/*! \file
  \brief  The TextureLoader and TextureLoaderList classes.

  \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 INCLUDED_TEXTURE_LOADER_H
#define INCLUDED_TEXTURE_LOADER_H

#include "gls_include.h"
#include "image.h"
#include "list.h"
#include "plugin.h"

namespace disti
{
class TextureLoader;

/**
  A list of (pointers to) texture loader objects.  
*/
class TextureLoaderList : public List_c
{
    static GLS_EXPORT TextureLoaderList* _instance; /** A singleton interface */

public:
    GLS_EXPORT TextureLoaderList();

    /** A singleton interface 
      * \return A pointer to the one and only instance 
      */
    static GLS_EXPORT TextureLoaderList* Instance();

    /** enable / disable texture loading optimization (defaults to enabled)
      * \param enable true to enable else false
      */
    static GLS_EXPORT void SetOptimizeTextureLoading( const bool enable );

    /** determine if texture loading optimization is enabled
      * \return true if enabled else false
      */
    static GLS_EXPORT bool IsOptimizeTextureLoading();

    /** Insert the loader into the list at the specified location
      * \param importer
      */
    GLS_EXPORT void InsertObject( TextureLoader* importer );

    /** Creates and returns a file filter string for all of the file types that have been
      * registered by Texture Loaders
      * \return Filter string */
    GLS_EXPORT char* FilterString();

    /** Load the specified texture file.  Try all loaders to see if any of them support 
      * the given file type.  
      * \param filename   The file to load the image from
      * \param options    Options to load the image with
      * \param allowNPOT  If the image is allowed to be non-power of two (NPOT)
      * \return NULL if the file type isn't supported or if loading fails 
      */
    GLS_EXPORT Image* LoadTexture( const char* filename, const Image::LoadOptions& options, bool allowNPOT = true );

    /** Load the specified texture file optionally attempting to optimize the load by looking at
      * previously loaded images.  Try all loaders to see if any of them support 
      * the given file type.  
      * \param filename   The file to load the image from
      * \param options    Options to load the image with
      * \param optimizeTextureLoad true to attempt loading optimization else false to force a load
      * \param allowNPOT  If the image is allowed to be non-power of two (NPOT)
      * \return NULL if the file type isn't supported or if loading fails 
      */
    GLS_EXPORT Image* LoadTextureWithOptimization( const char* filename, const Image::LoadOptions& options, const bool optimizeTextureLoad, bool allowNPOT = true );

#ifdef __APPLE__
    /** Load the specified texture file optionally attempting to optimize the load by looking at
     * previously loaded images.
     *
     * This method uses the iOS image loader classes to load the textures and thus supports whatever platform native loaders
     * are supported by the iOS SDK.
     *
     * NOTE:  This code will also give preference to texture files compressed using PowerVR Texture compression.
     *        The way that works is that if this code is asked to load 'xyz.png' and 'xyz.pvr' is found, then the .pvr 
     *        file will be loaded instead.
     *
     * \return NULL if the file type isn't supported or if loading fails */
    GLS_EXPORT Image* LoadTextureIOS( const char* filename, const Image::LoadOptions& options, const bool optimizeTextureLoad );
#endif

    /** Finds the registered texture loader, if any, that supports the given file
      * extension.  
      * \param ext The (case insensitive) file extension
      * \return A pointer to the registered loader, or NULL if no loader exists
      */
    GLS_EXPORT TextureLoader* SupportsExtension( const char* ext );
};

/** The TextureLoader class
  */
class TextureLoader : public Plugin
{
protected:
    GLS_EXPORT TextureLoader();

public:
    /** \return A filter string that is used by the windows FileBrowser to build the list of files to 
      * display in the browser
      */
    virtual const char* FilterString() = 0;

    /** \return A filter string description that is used by the windows FileBrowser to build the list
      * of files to display in the browser
      */
    virtual const char* FilterDescription() = 0;

    /** \return The name of the header file to include when generating code
      * for this plugin
      */
    virtual const char* GenerateHeader() = 0;

    /** \return The string to be generated to generate an instance of this object
      */
    virtual const char* GenerateDeclaration() = 0;

    /** \return The type of plugin
      */
    virtual GLS_EXPORT const char* PluginType();

    /** \returns TRUE if the file pointer appears to contain an image that can be loaded by this class.  
      * This method must close the file if it returns TRUE.  It must rewind the file if it returns 
      * FALSE */
    virtual bool IsFileType( const char* filename ) = 0;

    /** \return TRUE if the class can load files with the given extension. */
    virtual bool SupportsExtension( const char* ext ) = 0;

    /** Load the specified texture file.  Try all loaders to see if any of them support 
      * the given file type.  
      * \param filename   The file to load the image from
      * \param options    Options to load the image with
      * \param allowNPOT  If the image is allowed to be non-power of two (NPOT)
      * \return NULL if the file type isn't supported or if loading fails 
      */
    virtual Image* LoadTexture( const char* filename, const Image::LoadOptions& options, bool allowNPOT = true ) = 0;

    /** Adds this file importer to a texture loader list
      * \param list  The texture loader list to add to
      */
    void GLS_EXPORT AddToList( TextureLoaderList* list = TextureLoaderList::Instance() );
};

} // namespace disti

#endif