#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)

void	setManager (AssetManager *manager)

const AssetManager *	getManager () const

void	setJsonKey (const std::string key)

const std::string	getJsonKey () const

void	setPriority (Uint32 priority)

const Uint32	getPriority () const

bool	load (const std::string key, const std::string source)

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

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

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

bool	unload (const std::string key)

bool	unload (const std::shared_ptr< JsonValue > &json)

virtual void	unloadAll ()

virtual std::vector< std::string >	keys ()

bool	contains (const std::string 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	purge (const std::shared_ptr< JsonValue > &json)

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

Protected Attributes
std::string	_jsonKey

Uint32	_priority

std::shared_ptr< ThreadPool >	_loader

AssetManager *	_manager

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

◆ BaseLoader()

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.

◆ ~BaseLoader()

cugl::BaseLoader::~BaseLoader ( )

inline

Deletes this asset loader, disposing of all resources.

Member Function Documentation

◆ complete()

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.

◆ contains()

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.

◆ dispose()

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::FontLoader, cugl::GenericLoader< T >, cugl::JsonLoader, cugl::Scene2Loader, cugl::SoundLoader, cugl::TextureLoader, and cugl::WidgetLoader.

◆ getHook()

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.

◆ getJsonKey()

const std::string cugl::BaseLoader::getJsonKey ( ) const

inline

Returns the asset directory JSON key

Asset directories are JSON files specifying which assets to load. Each type of asset is grouped together in a top-level JSON object with a key defining the asset. The JSON key is the key that this loader responds to. This allows us to have highly flexible asset directories.

Returns: the asset directory JSON key

◆ getManager()

const AssetManager * cugl::BaseLoader::getManager ( ) const

inline

Returns the asset manager for this loader.

The asset manager allows this loader to access previously loaded assets. This allows materialization of complex, dependent assets.

Returns: the asset manager for this loader

◆ getPriority()

const Uint32 cugl::BaseLoader::getPriority ( ) const

inline

Returns the priority for this loader.

Loaders are executed according to their priority. Loaders of the same priority may be run simulatenously, in multiple threads. However, we guarantee that all loaders of a higher priority have completed before running a loader of lower priority.

Priority is determined with lower numbers representing higher priority. So 0 is the highest possible priority.

Returns: the priority for this loader.

◆ getThreadPool()

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

◆ init() [1/2]

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

Reimplemented in cugl::GenericLoader< T >, and cugl::Scene2Loader.

◆ init() [2/2]

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

Reimplemented in cugl::GenericLoader< T >, and cugl::Scene2Loader.

◆ keys()

virtual std::vector< std::string > cugl::BaseLoader::keys ( )

inlinevirtual

Returns the set of active keys in this loader.

Returns: the set of active keys in this loader.

Reimplemented in cugl::Loader< T >, cugl::Loader, cugl::Loader< JsonValue >, cugl::Loader< scene2::SceneNode >, cugl::Loader< Sound >, cugl::Loader< Texture >, and cugl::Loader< WidgetValue >.

◆ load() [1/2]

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

◆ load() [2/2]

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

◆ loadAsync() [1/2]

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

json	The JSON entry (and key) associated with the asset
callback	An optional callback for asynchronous loading

◆ loadAsync() [2/2]

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

◆ loadCount()

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, cugl::Loader< JsonValue >, cugl::Loader< scene2::SceneNode >, cugl::Loader< Sound >, cugl::Loader< Texture >, and cugl::Loader< WidgetValue >.

◆ progress()

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.

◆ purge() [1/2]

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

inlineprotectedvirtual

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

json	The directory entry for the asset

Returns: true if the asset was successfully unloaded

Reimplemented in cugl::Scene2Loader, and cugl::TextureLoader.

◆ purge() [2/2]

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, cugl::Loader< JsonValue >, cugl::Loader< scene2::SceneNode >, cugl::Loader< Sound >, cugl::Loader< Texture >, and cugl::Loader< WidgetValue >.

◆ read() [1/2]

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::FontLoader, cugl::GenericLoader< T >, cugl::JsonLoader, cugl::Scene2Loader, cugl::SoundLoader, cugl::TextureLoader, and cugl::WidgetLoader.

◆ read() [2/2]

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::FontLoader, cugl::GenericLoader< T >, cugl::JsonLoader, cugl::Scene2Loader, cugl::SoundLoader, cugl::TextureLoader, and cugl::WidgetLoader.

◆ setJsonKey()

void cugl::BaseLoader::setJsonKey ( const std::string key )

inline

Sets the asset directory JSON key

Asset directories are JSON files specifying which assets to load. Each type of asset is grouped together in a top-level JSON object with a key defining the asset. The JSON key is the key that this loader responds to. This allows us to have highly flexible asset directories.

NOTE: Changing this value after the loader is attached to an AssetManager is unsafe.

Parameters

key	The asset directory JSON key

◆ setManager()

void cugl::BaseLoader::setManager ( AssetManager * manager )

inline

Sets the asset manager for this loader.

The asset manager allows this loader to access previously loaded assets. This allows materialization of complex, dependent assets.

Parameters

manager The asset manager

◆ setPriority()

void cugl::BaseLoader::setPriority ( Uint32 priority )

inline

Sets the priority for this loader.

Loaders are executed according to their priority. Loaders of the same priority may be run simulatenously, in multiple threads. However, we guarantee that all loaders of a higher priority have completed before running a loader of lower priority.

Priority is determined with lower numbers representing higher priority. So 0 is the highest possible priority.

Parameters

priority The priority for this loader.

◆ setThreadPool()

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

◆ unload() [1/2]

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

inline

Unloads the asset for the given JSON 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 the child classes.

Parameters

json	the JSON entry (and key) associated with the asset

Returns: true if the asset was successfully unloaded

◆ unload() [2/2]

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.

Parameters

key	the key associated with the asset

Returns: true if the asset was successfully unloaded

◆ unloadAll()

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, cugl::Loader< JsonValue >, cugl::Loader< scene2::SceneNode >, cugl::Loader< Sound >, cugl::Loader< Texture >, and cugl::Loader< WidgetValue >.

◆ verify()

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, cugl::Loader< JsonValue >, cugl::Loader< scene2::SceneNode >, cugl::Loader< Sound >, cugl::Loader< Texture >, and cugl::Loader< WidgetValue >.

◆ waitCount()

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, cugl::Loader< JsonValue >, cugl::Loader< scene2::SceneNode >, cugl::Loader< Sound >, cugl::Loader< Texture >, and cugl::Loader< WidgetValue >.

Member Data Documentation

◆ _jsonKey

std::string cugl::BaseLoader::_jsonKey

protected

The JSON key this loader responds to

◆ _loader

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

protected

The associated thread for asynchronous loading

If this value is nullptr, only synchronous loading is supported

◆ _manager

AssetManager* cugl::BaseLoader::_manager

protected

The parent asset manager for this loader (may be null)

This is a weak reference to avoid cycles.

◆ _priority

Uint32 cugl::BaseLoader::_priority

protected

The loader priority (all higher priority loaders finish first)

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

cugl/include/cugl/assets/CULoader.h

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BaseLoader()

◆ ~BaseLoader()

Member Function Documentation

◆ complete()

◆ contains()

◆ dispose()

◆ getHook()

◆ getJsonKey()

◆ getManager()

◆ getPriority()

◆ getThreadPool()

◆ init() [1/2]

◆ init() [2/2]

◆ keys()

◆ load() [1/2]

◆ load() [2/2]

◆ loadAsync() [1/2]

◆ loadAsync() [2/2]

◆ loadCount()

◆ progress()

◆ purge() [1/2]

◆ purge() [2/2]

◆ read() [1/2]

◆ read() [2/2]

◆ setJsonKey()

◆ setManager()

◆ setPriority()

◆ setThreadPool()

◆ unload() [1/2]

◆ unload() [2/2]

◆ unloadAll()

◆ verify()

◆ waitCount()

Member Data Documentation

◆ _jsonKey

◆ _loader

◆ _manager

◆ _priority