CUGL 2.3
Cornell University Game Library
Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
cugl::BaseLoader Class Reference

#include <CULoader.h>

Inheritance diagram for cugl::BaseLoader:
cugl::Loader< Font > cugl::Loader< JsonValue > cugl::Loader< scene2::SceneNode > cugl::Loader< Sound > cugl::Loader< Texture > cugl::Loader< WidgetValue > cugl::Loader< T > cugl::FontLoader cugl::JsonLoader cugl::Scene2Loader cugl::SoundLoader cugl::TextureLoader cugl::WidgetLoader cugl::GenericLoader< T >

Public Member Functions

 BaseLoader ()
 
 ~BaseLoader ()
 
virtual void dispose ()
 
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
 
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
keythe 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
threadsThe 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< Font >, 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
jsonThe 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
keyThe key to access the asset after loading
sourceThe 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
jsonThe JSON entry (and key) associated with the asset
callbackAn 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
keyThe key to access the asset after loading
sourceThe pathname to the asset
callbackAn 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< Font >, 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
jsonThe 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< Font >, 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
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 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
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 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
keyThe 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
managerThe 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
priorityThe 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
threadsThe 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
jsonthe 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
keythe 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< Font >, 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
keyThe key associated with the asset
Returns
true if the key maps to a loaded asset.

Reimplemented in cugl::Loader< T >, cugl::Loader< Font >, 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< Font >, 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: