An AssetLoader coordinates asset loading operations on one or more cubes. More...

#include <sifteo/asset/loader.h>

Public Member Functions
unsigned	averageProgress (unsigned max) const
	Measures total progress on all cubes, as an integer. More...

float	averageProgress () const
	Measures total progress on all cubes, as a floating point value. More...

_SYSCubeIDVector	busyCubes () const
	Which cubes are still busy loading?

void	cancel (_SYSCubeIDVector cubes=-1)
	End any in-progress asset loading operations without finishing them. More...

unsigned	cubeProgress (_SYSCubeID cubeID, unsigned max) const
	Measures progress on a single cube, as an integer. More...

float	cubeProgress (_SYSCubeID cubeID) const
	Measures progress on a single cube, as a floating point value. More...

void	finish ()
	Ensure that the system is no longer using this AssetLoader object. More...

void	init ()
	Initialize this object. More...

bool	isComplete (_SYSCubeIDVector vec) const
	Is the asset install finished for all cubes in the specified vector? More...

bool	isComplete (_SYSCubeID cubeID) const
	Is the asset install for "cubeID" finished? More...

bool	isComplete () const
	Are all asset installations from this asset loading session complete?

	operator const _SYSAssetLoader & () const
	Implicit conversion to system object.

template<typename T >
void	start (T &configuration, _SYSCubeIDVector cubes=-1)
	Start installing an AssetConfiguration. More...

Detailed Description

An AssetLoader coordinates asset loading operations on one or more cubes.

An AssetLoader may be a transient object; it only needs to exist when an asset loading operation is taking place, and can be deleted or recycled afterwards. AssetLoaders can be allocated on the stack, or as part of a union.

A single AssetLoader can load any combination of AssetConfiguration objects concurrently to any number of cubes, up to the defined CUBE_ALLOCATION. Each AssetConfiguration operates on its own CubeSet, such that a different AssetConfiguration may be loaded on each cube, or any combination of cubes.

Single AssetConfiguration Example

#include "assets.gen.h"
using namespace Sifteo;
// allocate a slot into which our assets will be loaded
static AssetSlot MenuSlot = AssetSlot::allocate();
// assume assets.gen.h provides a Sifteo::AssetGroup called MenuGroup
AssetConfiguration<1> config;
config.append(MenuSlot, MenuGroup);
// load a single configuration to the set of all connected cubes
AssetLoader loader;
loader.init();
loader.start(config, CubeSet::connected());
// and wait until the load is complete
// NOTE - it is also possible to poll for completion using AssetLoader::isComplete()
loader.finish();

Multiple AssetConfiguration Example

#include "assets.gen.h"
using namespace Sifteo;
static AssetSlot MenuSlot = AssetSlot::allocate();
static AssetSlot AnimationSlot = AssetSlot::allocate();
// assume assets.gen.h provides two Sifteo::AssetGroup objects
// called MenuGroup and AnimationGroup
AssetConfiguration<1> menuConfig;
menuConfig.append(MenuSlot, MenuGroup);
AssetConfiguration<1> animationConfig;
animationConfig.append(AnimationSlot, AnimationGroup);
AssetLoader loader;
loader.init();
// load menuConfig to cubes 0 and 1
CubeSet cubeset01(0, 2);
loader.start(menuConfig, cubeset01);
// load animationConfig to cubes 2 and 3
CubeSet cubeset23(2, 4);
loader.start(animationConfig, cubeset23);
loader.finish();

Member Function Documentation

unsigned Sifteo::AssetLoader::averageProgress ( unsigned max ) const

inline

Measures total progress on all cubes, as an integer.

This measures loading progress for all cubes, returning a number between 0 and 'max'. If all cubes are done loading, this returns 'max'. If the loading has not yet made any progress or no loading was necessary, returns zero.

This calculates using 32-bit integer math, and 'max' multiplied by the number of bytes of uncompressed asset data must not overflow the 32-bit type.

float Sifteo::AssetLoader::averageProgress ( ) const

inline

Measures total progress on all cubes, as a floating point value.

This measures loading progress for all cubes, returning a number between 0.0f and 1.0f. If all cubes are done loading, this returns 1.0f. If the loading has not yet made any progress, returns 0.0f. If no loading was necessary, returns NaN.

void Sifteo::AssetLoader::cancel ( _SYSCubeIDVector cubes = -1 )

inline

End any in-progress asset loading operations without finishing them.

This function is similar to finish(), except that any in-progress asset loading operations do not finish. Instead, any asset slots written to since the last finish() will be in an indeterminate state, and the slot must be erased before any further loading may be attempted.

By default, this cancels all in-progress load operations. A CubeSet may be specified, to cancel only the indicated cubes.

If a load is cancelled, the group that was being loaded will not be available, but pre-existing groups will still be usable. However, further load operations on that AssetSlot will not be possible until the slot is erased. It is said that a slot in this post-cancellation state is indeterminate until it is erased.

unsigned Sifteo::AssetLoader::cubeProgress	(	_SYSCubeID	cubeID,
		unsigned	max
	)		const

inline

Measures progress on a single cube, as an integer.

This measures just the loading progress for a single cube, returning a number between 0 and 'max'. If the cube is done loading, this returns 'max'. If the cube hasn't started loading or has no need to load assets, returns zero.

This calculates using 32-bit integer math, and 'max' multiplied by the number of bytes of uncompressed asset data must not overflow the 32-bit type.

float Sifteo::AssetLoader::cubeProgress ( _SYSCubeID cubeID ) const

inline

Measures progress on a single cube, as a floating point value.

This measures just the loading progress for a single cube, returning a number between 0.0f and 1.0f. If the cube is done loading, this returns 1.0f. If the cube hasn't started loading or has no need to load assets, returns 0.0f.

void Sifteo::AssetLoader::finish ( )

inline

Ensure that the system is no longer using this AssetLoader object.

If any loads are still in progress, this function blocks until they complete. This must be called after an asset load is done, before the AssetLoader object itself is deallocated or recycled.

If finish() has already been called, has no effect.

void Sifteo::AssetLoader::init ( )

inline

Initialize this object.

This is made explicit, rather than using a constructor, so that games can keep AssetLoader in a union if necessary to save memory.

Must be called once, prior to any calls to start().

bool Sifteo::AssetLoader::isComplete ( _SYSCubeIDVector vec ) const

inline

Is the asset install finished for all cubes in the specified vector?

This only returns 'true' when the install is completely done on all of these cubes.

Note that this is more efficient than calling AssetGroup::isInstalled. Whereas isInstalled() needs to look for the AssetGroup in the system's cache, this function is simply checking whether the current installation session has completed.

bool Sifteo::AssetLoader::isComplete ( _SYSCubeID cubeID ) const

inline

Is the asset install for "cubeID" finished?

Returns true only when the install is completely done on this cube.

template<typename T >

void Sifteo::AssetLoader::start	(	T &	configuration,
		_SYSCubeIDVector	cubes = `-1`
	)

inline

Start installing an AssetConfiguration.

This uses an AssetConfiguration object to describe a set of AssetGroups which should be made available, and the slots to install each into. The AssetLoader object will automatically erase any slots that need to be erased before starting, and it will calculate progress.

By default, the AssetConfiguration is installed on to all cubes that are currently connected, and any cubes which connect prior to the other cubes completing their loads. This will load the same AssetConfiguration on all cubes.

A CubeSet can be specified to restrict this load to only some of the available cubes. This can also be used to load different AssetConfigurations on different subsets of the available cubes.

The provided AssetConfiguration must be valid, in that it must be possible to load all indicated AssetGroups in the indicated slots. If space is exhausted due to groups not mentioned in the AssetConfiguration, the AssetLoader will automatically erase the slot and reload only necessary groups. However, if space is exhausted solely due to groups mentioned in the AssetConfiguration, this indicates that the AssetConfiguration is invalid.

An AssetConfiguration which is invalid or which does not match the corresponding AssetGroup header will cause a fault.

The system does not copy the AssetConfiguration, it refers to it by address. As a consequence, it is vital that your AssetConfiguration instance stays in scope until you call AssetLoader::finish(), or until after your ScopedAssetLoader goes out of scope.

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

loader.h

Public Member Functions

Detailed Description

Member Function Documentation