#include <CULoader.h>

Inheritance diagram for cugl::BaseLoader:

Public Member Functions
	BaseLoader ()

	~BaseLoader ()

virtual void	dispose ()

virtual bool	init ()

virtual bool	init (const std::shared_ptr< ThreadPool > &threads)

std::shared_ptr< BaseLoader >	getHook ()

std::shared_ptr< ThreadPool >	getThreadPool () const

void	setThreadPool (const std::shared_ptr< ThreadPool > &threads)

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)

virtual void	unloadAll ()

bool	contains (const std::string &key) const

bool	contains (const char *key) const

virtual size_t	loadCount () const

virtual size_t	waitCount () const

bool	complete () const

float	progress () const

Protected Member Functions
virtual bool	read (const std::string &key, const std::string &source, LoaderCallback callback, bool async)

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

virtual bool	purge (const std::string &key)

virtual bool	verify (const std::string &key) const

Protected Attributes
std::shared_ptr< ThreadPool >	_loader

Detailed Description

This class provides a polymorphic base to the loader system.

This is effectively a Java-style interface. It identifies the methods that all loaders must have, and provides a type for the AssetManager to use in its underlying storage container.

IMPORTANT: This class is not even remotely thread-safe. Do not call any of these methods outside of the main CUGL thread.

Constructor & Destructor Documentation

cugl::BaseLoader::BaseLoader ( )

inline

Creates a degenerate asset loader with no resources

NEVER CALL THIS CONSTRUCTOR. As this is an abstract class, you should call one of the static constructors of the appropriate child class.

cugl::BaseLoader::~BaseLoader ( )

inline

Deletes this asset loader, disposing of all resources.

Member Function Documentation

bool cugl::BaseLoader::complete ( ) const

inline

Returns true if the loader has finished loading all assets.

It is not safe to use asynchronously loaded assets until all loading is complete. This method allows us to determine when asset loading is complete via polling.

Returns: true if the loader has finished loading all assets.

bool cugl::BaseLoader::contains ( const std::string & key ) const

inline

Returns true if the key maps to a loaded asset.

This method is useful in case the asset fails to load.

Parameters

key	the key associated with the asset

Returns: True if the key maps to a loaded asset.

bool cugl::BaseLoader::contains ( const char * key ) const

inline

Returns true if the key maps to a loaded asset.

This method is useful in case the asset fails to load.

Parameters

key	the key associated with the asset

Returns: True if the key maps to a loaded asset.

virtual void cugl::BaseLoader::dispose ( )

inlinevirtual

Disposes all resources and assets of this loader

Any assets loaded by this object will be immediately released by the loader. However, an asset may still be available if it is referenced by another smart pointer. See the description of the specific implementation for how assets are released.

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

This method is abstract and should be overridden in the specific implementation for each asset.

Reimplemented in cugl::TextureLoader, cugl::GenericLoader< T >, cugl::FontLoader, cugl::SoundLoader, cugl::MusicLoader, and cugl::JsonLoader.

std::shared_ptr<BaseLoader> cugl::BaseLoader::getHook ( )

inline

Returns a pointer for attaching this loader to an AssetManager.

Smart pointers are great, and all asset loaders should be referenced by one. However, polymorphism and smart pointers really do not mix and type casting can be quite tricky. This method provides a simple interface for handling this type case.

Returns: a pointer for attaching this loader to an AssetManager.

std::shared_ptr<ThreadPool> cugl::BaseLoader::getThreadPool ( ) const

inline

Returns the thread pool attached to this loader

The thread pool is used for asynchronous loading. Multiple asset loaders can share the same thread pool. This keeps the system from being overloaded by a large number of threads.

Returns: the thread pool attached to this loader

virtual bool cugl::BaseLoader::init ( )

inlinevirtual

Initializes a new asset loader.

This method bootstraps the loader with any initial resources that it needs to load assets. 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.

This method is abstract and should be overridden in the specific implementation for each asset.

Returns: true if the asset loader was initialized successfully

virtual bool cugl::BaseLoader::init ( const std::shared_ptr< ThreadPool > & threads )

inlinevirtual

Initializes a new asset loader.

This method bootstraps the loader with any initial resources that it needs to load assets. Attempts to load an asset before this method is called will fail.

This method is abstract and should be overridden in the specific implementation for each asset.

Parameters

threads The thread pool for asynchronous loading support

Returns: true if the asset loader was initialized successfully

bool cugl::BaseLoader::load	(	const std::string &	key,
		const std::string &	source
	)

inline

Synchronously loads the given asset with the specified key.

The asset will be loaded synchronously, which means the main CUGL thread will block until loading is complete. When it is finished loading, the asset will be added to the contents loader, and accessible under the given key.

This method is abstract and should be overridden in child classes to support the appropriate asset type.

Parameters

key	The key to access the asset after loading
source	The pathname to the asset

Returns: true if the asset was successfully loaded

bool cugl::BaseLoader::load	(	const char *	key,
		const std::string &	source
	)

inline

Synchronously loads the given asset with the specified key.

The asset will be loaded synchronously, which means the main CUGL thread will block until loading is complete. When it is finished loading, the asset will be added to the contents loader, and accessible under the given key.

This method is abstract and should be overridden in child classes to support the appropriate asset type.

Parameters

key	The key to access the asset after loading
source	The pathname to the asset

Returns: true if the asset was successfully loaded

bool cugl::BaseLoader::load	(	const std::string &	key,
		const char *	source
	)

inline

Synchronously loads the given asset with the specified key.

The asset will be loaded synchronously, which means the main CUGL thread will block until loading is complete. When it is finished loading, the asset will be added to the contents loader, and accessible under the given key.

This method is abstract and should be overridden in child classes to support the appropriate asset type.

Parameters

key	The key to access the asset after loading
source	The pathname to the asset

Returns: true if the asset was successfully loaded

bool cugl::BaseLoader::load	(	const char *	key,
		const char *	source
	)

inline

Synchronously loads the given asset with the specified key.

The asset will be loaded synchronously, which means the main CUGL thread will block until loading is complete. When it is finished loading, the asset will be added to the contents loader, and accessible under the given key.

This method is abstract and should be overridden in child classes to support the appropriate asset type.

Parameters

key	The key to access the asset after loading
source	The pathname to the asset

Returns: true if the asset was successfully loaded

bool cugl::BaseLoader::load ( const std::shared_ptr< JsonValue > & json )

inline

Synchronously loads the given asset with the specified key.

The asset will be loaded synchronously, which means the main CUGL thread will block until loading is complete. When it is finished loading, the asset will be added to the contents loader, and accessible under the given key.

This version of load provides support for JSON directories. The exact format of the directory entry is up to you. However, unless the asset is one of the five basic types, it will not be supported by AssetManager. You will need to load the directory manually in that case.

This method is abstract and should be overridden in child classes to support the appropriate asset type.

Parameters

json	The directory entry for the asset

Returns: true if the asset was successfully loaded

void cugl::BaseLoader::loadAsync	(	const std::string &	key,
		const std::string &	source,
		LoaderCallback	callback
	)

inline

Asynchronously loads the given asset with the specified key.

The asset will be loaded asynchronously. When it is finished loading, the asset will be added to this loader, and accessible under the given key. This method will mark the loading process as not complete, even if it was completed previously. It is not safe to access the loaded asset until it is complete again.

The optional callback function will be called with the asset status when it either finishes loading or fails to load.

This method is abstract and should be overridden in child classes to support the appropriate asset type.

Parameters

key	The key to access the asset after loading
source	The pathname to the asset
callback	An optional callback for asynchronous loading

void cugl::BaseLoader::loadAsync	(	const char *	key,
		const std::string &	source,
		LoaderCallback	callback
	)

inline

Asynchronously loads the given asset with the specified key.

The asset will be loaded asynchronously. When it is finished loading, the asset will be added to this loader, and accessible under the given key. This method will mark the loading process as not complete, even if it was completed previously. It is not safe to access the loaded asset until it is complete again.

The optional callback function will be called with the asset status when it either finishes loading or fails to load.

This method is abstract and should be overridden in child classes to support the appropriate asset type.

Parameters

key	The key to access the asset after loading
source	The pathname to the asset
callback	An optional callback for asynchronous loading

void cugl::BaseLoader::loadAsync	(	const std::string &	key,
		const char *	source,
		LoaderCallback	callback
	)

inline

Asynchronously loads the given asset with the specified key.

The asset will be loaded asynchronously. When it is finished loading, the asset will be added to this loader, and accessible under the given key. This method will mark the loading process as not complete, even if it was completed previously. It is not safe to access the loaded asset until it is complete again.

The optional callback function will be called with the asset status when it either finishes loading or fails to load.

This method is abstract and should be overridden in child classes to support the appropriate asset type.

Parameters

key	The key to access the asset after loading
source	The pathname to the asset
callback	An optional callback for asynchronous loading

void cugl::BaseLoader::loadAsync	(	const char *	key,
		const char *	source,
		LoaderCallback	callback
	)

inline

Asynchronously loads the given asset with the specified key.

The asset will be loaded asynchronously. When it is finished loading, the asset will be added to this loader, and accessible under the given key. This method will mark the loading process as not complete, even if it was completed previously. It is not safe to access the loaded asset until it is complete again.

The optional callback function will be called with the asset status when it either finishes loading or fails to load.

This method is abstract and should be overridden in child classes to support the appropriate asset type.

Parameters

key	The key to access the asset after loading
source	The pathname to the asset
callback	An optional callback for asynchronous loading

void cugl::BaseLoader::loadAsync	(	const std::shared_ptr< JsonValue > &	json,
		LoaderCallback	callback
	)

inline

Asynchronously loads the given asset with the specified key.

The asset will be loaded asynchronously. When it is finished loading, the asset will be added to this loader, and accessible under the given key. This method will mark the loading process as not complete, even if it was completed previously. It is not safe to access the loaded asset until it is complete again.

This version of loadAsync provides support for JSON directories. The exact format of the directory entry is up to you. However, unless the asset is one of the five basic types, it will not be supported by AssetManager. You will need to load the directory manually in that case.

The optional callback function will be called with the asset status when it either finishes loading or fails to load.

This method is abstract and should be overridden in child classes to support the appropriate asset type.

Parameters

key	The key to access the asset after loading
source	The pathname to the asset
callback	An optional callback for asynchronous loading

virtual size_t cugl::BaseLoader::loadCount ( ) const

inlinevirtual

Returns the number of assets currently loaded.

This is a rough way to determine how many assets have been loaded so far. This method counts each asset equally regardless of the memory requirements of each asset.

This method is abstract and should be overridden in child classes to support the appropriate asset type.

Returns: the number of assets currently loaded.

Reimplemented in cugl::Loader< T >, cugl::Loader< Texture >, cugl::Loader< Music >, cugl::Loader< Sound >, cugl::Loader< JsonValue >, and cugl::Loader.

float cugl::BaseLoader::progress ( ) const

inline

Returns the loader progress as a percentage.

This method returns a value between 0 and 1. A value of 0 means no assets have been loaded. A value of 1 means that all assets have been loaded.

Anything in-between indicates that there are assets which have been loaded asynchronously and have not completed loading. It is not safe to use asynchronously loaded assets until all loading is complete.

Returns: the loader progress as a percentage.

virtual bool cugl::BaseLoader::purge ( const std::string & key )

inlineprotectedvirtual

Unloads the asset for the given key

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.

Returns: true if the asset was successfully unloaded

Reimplemented in cugl::Loader< T >, cugl::Loader< Texture >, cugl::Loader< Music >, cugl::Loader< Sound >, cugl::Loader< JsonValue >, and cugl::Loader.

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

inlineprotectedvirtual

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 is abstract and should be overridden in child classes to support the appropriate asset type.

Parameters

key	The key to access the asset after loading
source	The pathname to the asset
callback	An optional callback for asynchronous loading
async	Whether the asset was loaded asynchronously

Returns: true if the asset was successfully loaded

Reimplemented in cugl::TextureLoader, cugl::FontLoader, cugl::GenericLoader< T >, cugl::SoundLoader, cugl::MusicLoader, and cugl::JsonLoader.

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

inlineprotectedvirtual

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 is abstract and should be overridden in child classes to support the appropriate asset type.

This version of read provides support for JSON directories. The exact exact format of the directory entry is up to you. However, unless the asset is one of the four basic types, it will not be supported by AssetManager. You will need to load the directory manually in that case.

Parameters

json	The directory entry for the asset
callback	An optional callback for asynchronous loading
async	Whether the asset was loaded asynchronously

Returns: true if the asset was successfully loaded

Reimplemented in cugl::TextureLoader, cugl::FontLoader, cugl::GenericLoader< T >, cugl::SoundLoader, cugl::MusicLoader, and cugl::JsonLoader.

void cugl::BaseLoader::setThreadPool ( const std::shared_ptr< ThreadPool > & threads )

inline

Sets the thread pool attached to this loader

If there was a previously attached thread pool, it will be deleted and the threads will be shutdown. Assets not yet loaded by that thread pool will fail to load. Hence it is unsafe to call this method if the loader is actively loading assets.

The thread pool is used for asynchronous loading. Multiple asset loaders can share the same thread pool. This keeps the system from being overloaded by a large number of threads.

Parameters

threads The thread pool attached to this loader

bool cugl::BaseLoader::unload ( const std::string & key )

inline

Unloads the asset for the given key

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.

Returns: true if the asset was successfully unloaded

bool cugl::BaseLoader::unload ( const char * key )

inline

Unloads the asset for the given key

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 the child classes.

Returns: true if the asset was successfully unloaded

virtual void cugl::BaseLoader::unloadAll ( )

inlinevirtual

Unloads all assets present in this loader.

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 the child classes.

Reimplemented in cugl::Loader< T >, cugl::Loader< Texture >, cugl::Loader< Music >, cugl::Loader< Sound >, cugl::Loader< JsonValue >, and cugl::Loader.

virtual bool cugl::BaseLoader::verify ( const std::string & key ) const

inlineprotectedvirtual

Returns true if the key maps to a loaded asset.

This method is useful in case the asset fails to load. You will notice that this method is essentially identical to contains. We separated the methods because overloading and virtual methods do not place nice.

Parameters

key	The key associated with the asset

Returns: true if the key maps to a loaded asset.

Reimplemented in cugl::Loader< T >, cugl::Loader< Texture >, cugl::Loader< Music >, cugl::Loader< Sound >, cugl::Loader< JsonValue >, and cugl::Loader.

virtual size_t cugl::BaseLoader::waitCount ( ) const

inlinevirtual

Returns the number of assets waiting to load.

This is a rough way to determine how many assets are still pending. An asset is pending if it has been loaded asychronously, and the loading process has not yet finished. This method counts each asset equally regardless of the memory requirements of each asset.

This method is abstract and should be overridden in child classes to support the appropriate asset type.

Returns: the number of assets waiting to load.

Reimplemented in cugl::Loader< T >, cugl::Loader< Texture >, cugl::Loader< Music >, cugl::Loader< Sound >, cugl::Loader< JsonValue >, and cugl::Loader.

Member Data Documentation

std::shared_ptr<ThreadPool> cugl::BaseLoader::_loader

protected

The associated thread for asynchronous loading

If this value is nullptr, only synchronous loading is supported

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

assets/CULoader.h

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation