CUGL 2.0
Cornell University Game Library
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
cugl::TextureLoader Class Reference

#include <CUTextureLoader.h>

Inheritance diagram for cugl::TextureLoader:
cugl::Loader< Texture > cugl::BaseLoader

Public Member Functions

 TextureLoader ()
 
void dispose () override
 
GLuint getMinFilter () const
 
void setMinFilter (GLuint minFilter)
 
GLuint getMagFilter () const
 
void setMagFilter (GLuint magFilter)
 
GLuint getWrapS () const
 
void setWrapS (GLuint wrap)
 
GLuint getWrapT () const
 
void setWrapT (GLuint wrap)
 
bool hasMipMaps () const
 
void setMipMaps (bool flag)
 
- Public Member Functions inherited from cugl::Loader< Texture >
 Loader ()
 
std::shared_ptr< Textureget (const std::string &key) const
 
std::shared_ptr< Textureget (const char *key) const
 
std::shared_ptr< Textureoperator[] (const std::string &key) const
 
std::shared_ptr< Textureoperator[] (const char *key) const
 
size_t loadCount () const override
 
size_t waitCount () const override
 
void unloadAll () override
 
- Public Member Functions inherited from cugl::BaseLoader
 BaseLoader ()
 
 ~BaseLoader ()
 
virtual bool init ()
 
virtual bool init (const std::shared_ptr< ThreadPool > &threads)
 
std::shared_ptr< BaseLoadergetHook ()
 
std::shared_ptr< ThreadPoolgetThreadPool () const
 
void setThreadPool (const std::shared_ptr< ThreadPool > &threads)
 
void setManager (AssetManager *manager)
 
const AssetManagergetManager () const
 
bool load (const std::string &key, const std::string &source)
 
bool load (const char *key, const std::string &source)
 
bool load (const std::string &key, const char *source)
 
bool load (const char *key, const char *source)
 
bool load (const std::shared_ptr< JsonValue > &json)
 
void loadAsync (const std::string &key, const std::string &source, LoaderCallback callback)
 
void loadAsync (const char *key, const std::string &source, LoaderCallback callback)
 
void loadAsync (const std::string &key, const char *source, LoaderCallback callback)
 
void loadAsync (const char *key, const char *source, LoaderCallback callback)
 
void loadAsync (const std::shared_ptr< JsonValue > &json, LoaderCallback callback)
 
bool unload (const std::string &key)
 
bool unload (const char *key)
 
bool unload (const std::shared_ptr< JsonValue > &json)
 
bool contains (const std::string &key) const
 
bool contains (const char *key) const
 
bool complete () const
 
float progress () const
 

Static Public Member Functions

static std::shared_ptr< TextureLoaderalloc ()
 
static std::shared_ptr< TextureLoaderalloc (const std::shared_ptr< ThreadPool > &threads)
 

Protected Member Functions

void parseAtlas (const std::shared_ptr< JsonValue > &json, const std::shared_ptr< Texture > &texture)
 
SDL_Surface * preload (const std::string &source)
 
void materialize (const std::string &key, SDL_Surface *surface, LoaderCallback callback)
 
void materialize (const std::shared_ptr< JsonValue > &json, SDL_Surface *surface, LoaderCallback callback)
 
virtual bool read (const std::string &key, const std::string &source, LoaderCallback callback, bool async) override
 
virtual bool read (const std::shared_ptr< JsonValue > &json, LoaderCallback callback, bool async) override
 
virtual bool purge (const std::shared_ptr< JsonValue > &json) override
 
- Protected Member Functions inherited from cugl::Loader< Texture >
bool purge (const std::string &key) override
 
bool verify (const std::string &key) const override
 

Protected Attributes

GLuint _minfilter
 
GLuint _magfilter
 
GLuint _wraps
 
GLuint _wrapt
 
bool _mipmaps
 
- Protected Attributes inherited from cugl::Loader< Texture >
std::unordered_map< std::string, std::shared_ptr< Texture > > _assets
 
std::unordered_set< std::string > _queue
 
- Protected Attributes inherited from cugl::BaseLoader
std::shared_ptr< ThreadPool_loader
 
AssetManager_manager
 

Detailed Description

This class is a specific implementation of Loader<Texture>

This asset loader allows us to allocate texture objects from the associated image files. A texture asset is identified by both its source file and its texture parameters. Hence you may wish to load a texture asset multiple times, though this is potentially wasteful regarding memory. However, changing the parameters for a texture asset will change the asset parameters in this loader as well.

Note that this implementation uses a two phase loading system. First, it loads as much of the asset as possible without using OpenGL. This allows us to load the texture in a separate thread. It then finishes off the remainder of asset loading using Application#schedule. This is a good template for asset loaders in general.

As with all of our loaders, this loader is designed to be attached to an asset manager. Use the method getHook() to get the appropriate pointer for attaching the loader.

Constructor & Destructor Documentation

◆ TextureLoader()

cugl::TextureLoader::TextureLoader ( )

Creates a new, uninitialized texture loader

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate a loader on the heap, use one of the static constructors instead.

Member Function Documentation

◆ alloc() [1/2]

static std::shared_ptr<TextureLoader> cugl::TextureLoader::alloc ( )
inlinestatic

Returns a newly allocated texture loader.

This method bootstraps the loader with any initial resources that it needs to load assets. In particular, the OpenGL context must be active. Attempts to load an asset before this method is called will fail.

This loader will have no associated threads. That means any asynchronous loading will fail until a thread is provided via setThreadPool.

Returns
a newly allocated texture loader.

◆ alloc() [2/2]

static std::shared_ptr<TextureLoader> cugl::TextureLoader::alloc ( const std::shared_ptr< ThreadPool > &  threads)
inlinestatic

Returns a newly allocated texture loader.

This method bootstraps the loader with any initial resources that it needs to load assets. In particular, the OpenGL context must be active. Attempts to load an asset before this method is called will fail.

Parameters
threadsThe thread pool for asynchronous loading
Returns
a newly allocated texture loader.

◆ dispose()

void cugl::TextureLoader::dispose ( )
inlineoverridevirtual

Disposes all resources and assets of this loader

Any assets loaded by this object will be immediately released by the loader. However, a texture may still be available if it is referenced by another smart pointer. OpenGL will only release a texture asset once all smart pointer attached to the asset are null.

Once the loader is disposed, any attempts to load a new asset will fail. You must reinitialize the loader to begin loading assets again.

Reimplemented from cugl::BaseLoader.

◆ getMagFilter()

GLuint cugl::TextureLoader::getMagFilter ( ) const
inline

Returns the default mage filter for this loader.

The mag filter is the algorithm hint that OpenGL uses to make an image larger. The default is GL_LINEAR. Once this value is set, all future textures processed by this loader will have this mag filter.

Returns
the default mage filter for this loader

◆ getMinFilter()

GLuint cugl::TextureLoader::getMinFilter ( ) const
inline

Returns the default min filter for this loader.

The min filter is the algorithm hint that OpenGL uses to make an image smaller. The default is GL_NEAREST. Once this value is set, all future textures processed by this loader will have this min filter.

Returns
the default min filter for this loader.

◆ getWrapS()

GLuint cugl::TextureLoader::getWrapS ( ) const
inline

Returns the default horizontal wrap for this loader.

The default is GL_CLAMP_TO_EDGE. Once this value is set, all future textures processed by this loader will have this horizontal wrap.

Returns
the default horizontal wrap for this loader.

◆ getWrapT()

GLuint cugl::TextureLoader::getWrapT ( ) const
inline

Returns the default vertical wrap for this loader.

The default is GL_CLAMP_TO_EDGE. Once this value is set, all future textures processed by this loader will have this vertical wrap.

Returns
the default vertical wrap for this loader.

◆ hasMipMaps()

bool cugl::TextureLoader::hasMipMaps ( ) const
inline

Returns true if this loader generates mipmaps by default.

The default is false. If this value is set to true, all future textures processed by this loader will build mipmaps by default. Similarly, setting it to false suppresses mipmaps in all future textures.

Returns
true if this loader generates mipmaps by default.

◆ materialize() [1/2]

void cugl::TextureLoader::materialize ( const std::shared_ptr< JsonValue > &  json,
SDL_Surface *  surface,
LoaderCallback  callback 
)
protected

Creates an OpenGL texture from the SDL_Surface accoring to the directory entry.

This method finishes the asset loading started in preload. This step is not safe to be done in a separate thread. Instead, it takes place in the main CUGL thread via Application#schedule.

This version of read provides support for JSON directories. A texture directory entry has the following values

 "file":         The path to the asset
 "mipmaps":      Whether to generate mipmaps (bool)
 "minfilter":    The name of the min filter ("nearest", "linear";
                 with mipmaps, "nearest-nearest", "linear-nearest",
                 "nearest-linear", or "linear-linear")
 "magfilter":    The name of the min filter ("nearest" or "linear")
 "wrapS":        The s-coord wrap rule ("clamp", "repeat", or "mirrored")
 "wrapT":        The t-coord wrap rule ("clamp", "repeat", or "mirrored")

The asset key is the key for the JSON directory entry

This method supports an optional callback function which reports whether the asset was successfully materialized.

Parameters
jsonThe asset directory entry
surfaceThe SDL_Surface to convert
callbackAn optional callback for asynchronous loading

◆ materialize() [2/2]

void cugl::TextureLoader::materialize ( const std::string &  key,
SDL_Surface *  surface,
LoaderCallback  callback 
)
protected

Creates an OpenGL texture from the SDL_Surface, and assigns it the given key.

This method finishes the asset loading started in preload. This step is not safe to be done in a separate thread. Instead, it takes place in the main CUGL thread via Application#schedule.

The loaded texture will have default parameters for scaling and wrap. It will only have a mipmap if that is the default.

This method supports an optional callback function which reports whether the asset was successfully materialized.

Parameters
keyThe key to access the asset after loading
surfaceThe SDL_Surface to convert
callbackAn optional callback for asynchronous loading

◆ parseAtlas()

void cugl::TextureLoader::parseAtlas ( const std::shared_ptr< JsonValue > &  json,
const std::shared_ptr< Texture > &  texture 
)
protected

Extracts any subtextures specified in an atlas

An atlas is specified as a list of named, four-element integer arrays. Each integer array specifies the left, top, right, and bottom pixels of the subtexture, respectively. Each subtexture will have the key of the main texture as the prefix (together with an underscore _) of its key.

Parameters
jsonThe asset directory entry
textureThe texture loaded for this asset

◆ preload()

SDL_Surface* cugl::TextureLoader::preload ( const std::string &  source)
protected

Loads the portion of this asset that is safe to load outside the main thread.

It is not safe to create an OpenGL texture in a separate thread. However, it is safe to create an SDL_surface, which contains all of the data that we need to create an OpenGL texture. Hence this method does the maximum amount of work that can be done in asynchronous texture loading.

Parameters
sourceThe pathname to the asset
Returns
the SDL_Surface with the texture information

◆ purge()

virtual bool cugl::TextureLoader::purge ( const std::shared_ptr< JsonValue > &  json)
overrideprotectedvirtual

Unloads the asset for the given directory entry

An asset may still be available if it is referenced by a smart pointer. See the description of the specific implementation for how assets are released.

This method is abstract and should be overridden in child classes. You will notice that this method is essentially identical to unload. We separated the methods because overloading and virtual methods do not place nice.

Parameters
jsonThe directory entry for the asset
Returns
true if the asset was successfully unloaded

Reimplemented from cugl::BaseLoader.

◆ read() [1/2]

virtual bool cugl::TextureLoader::read ( const std::shared_ptr< JsonValue > &  json,
LoaderCallback  callback,
bool  async 
)
overrideprotectedvirtual

Internal method to support asset loading.

This method supports either synchronous or asynchronous loading, as specified by the given parameter. If the loading is asynchronous, the user may specify an optional callback function.

This method will split the loading across the preload and materialize methods. This ensures that asynchronous loading is safe.

This version of read provides support for JSON directories. A texture directory entry has the following values

 "file":         The path to the asset
 "mipmaps":      Whether to generate mipmaps (bool)
 "minfilter":    The name of the min filter ("nearest", "linear";
                 with mipmaps, "nearest-nearest", "linear-nearest",
                 "nearest-linear", or "linear-linear")
 "magfilter":    The name of the min filter ("nearest" or "linear")
 "wrapS":        The s-coord wrap rule ("clamp", "repeat", or "mirrored")
 "wrapT":        The t-coord wrap rule ("clamp", "repeat", or "mirrored")
Parameters
jsonThe directory entry for the asset
callbackAn optional callback for asynchronous loading
asyncWhether the asset was loaded asynchronously
Returns
true if the asset was successfully loaded

Reimplemented from cugl::BaseLoader.

◆ read() [2/2]

virtual bool cugl::TextureLoader::read ( const std::string &  key,
const std::string &  source,
LoaderCallback  callback,
bool  async 
)
overrideprotectedvirtual

Internal method to support asset loading.

This method supports either synchronous or asynchronous loading, as specified by the given parameter. If the loading is asynchronous, the user may specify an optional callback function.

This method will split the loading across the preload and materialize methods. This ensures that asynchronous loading is safe.

Parameters
keyThe key to access the asset after loading
sourceThe pathname to the asset
callbackAn optional callback for asynchronous loading
asyncWhether the asset was loaded asynchronously
Returns
true if the asset was successfully loaded

Reimplemented from cugl::BaseLoader.

◆ setMagFilter()

void cugl::TextureLoader::setMagFilter ( GLuint  magFilter)
inline

Sets the default mage filter for this loader.

The mag filter is the algorithm hint that OpenGL uses to make an image larger. The default is GL_LINEAR. Once this value is set, all future textures processed by this loader will have this mag filter.

Parameters
magFilterThe default mage filter for this loader.

◆ setMinFilter()

void cugl::TextureLoader::setMinFilter ( GLuint  minFilter)
inline

Sets the default min filter for this loader.

The min filter is the algorithm hint that OpenGL uses to make an image smaller. The default is GL_NEAREST. Once this value is set, all future textures processed by this loader will have this min filter.

Parameters
minFilterThe default min filter for this loader.

◆ setMipMaps()

void cugl::TextureLoader::setMipMaps ( bool  flag)
inline

Sets whether this loader generates mipmaps by default.

The default is false. If this value is set to true, all future textures processed by this loader will build mipmaps by default. Similarly, setting it to false suppresses mipmaps in all future textures.

Parameters
flagWhether this loader generates mipmaps by default.

◆ setWrapS()

void cugl::TextureLoader::setWrapS ( GLuint  wrap)
inline

Sets the default horizontal wrap for this loader.

The default is GL_CLAMP_TO_EDGE. Once this value is set, all future textures processed by this loader will have this horizontal wrap.

Parameters
wrapThe default horizontal wrap for this loader.

◆ setWrapT()

void cugl::TextureLoader::setWrapT ( GLuint  wrap)
inline

Sets the default vertical wrap for this loader.

The default is GL_CLAMP_TO_EDGE. Once this value is set, all future textures processed by this loader will have this vertical wrap.

Parameters
wrapThe default vertical wrap for this loader.

Member Data Documentation

◆ _magfilter

GLuint cugl::TextureLoader::_magfilter
protected

The default mag filter

◆ _minfilter

GLuint cugl::TextureLoader::_minfilter
protected

The default min filter

◆ _mipmaps

bool cugl::TextureLoader::_mipmaps
protected

The default support for mipmaps

◆ _wraps

GLuint cugl::TextureLoader::_wraps
protected

The default s-coordinate wrap

◆ _wrapt

GLuint cugl::TextureLoader::_wrapt
protected

The default t-coordinate wrap


The documentation for this class was generated from the following file: