A Volume that has been mapped into the secondary flash memory region. More...

#include <sifteo/filesystem.h>

Public Types
typedef AssetConfiguration < MAX_BOOTSTRAP_GROUPS >	BootstrapAssetConfiguration
	An AssetConfiguration large enough to hold all bootstrap groups.

typedef Array< AssetGroup, MAX_BOOTSTRAP_GROUPS >	BootstrapAssetGroups
	An array large enough to hold all bototstrap AssetGroups.

Public Member Functions
void	attach (Volume vol)
	Attach this MappedVolume to a new volume. More...

void	getBootstrap (BootstrapAssetGroups &groups, BootstrapAssetConfiguration &config)
	Get the bootstrap assets for this Volume, returning the result in the provided BootstrapAssetConfiguration array.

	MappedVolume ()
	Construct a detached MappedVolume. More...

	MappedVolume (Volume vol)
	Map a view of the provided Volume. More...

void *	metadata (unsigned key, unsigned minSize, unsigned *actualSize) const
	Look up a metadata value from the mapped Volume. More...

template<typename T >
const T *	metadata (unsigned key, unsigned *actualSize=NULL) const
	Look up a metadata value from the mapped Volume. The result is cast to a constant pointer of the indicated type, and we require that the metadata value is at least as large as sizeof(T). More...

const char *	package (const char *placeholder="(none)") const
	Retrieve a mapped, NUL-terminated string with the volume's package string. More...

const char *	title (const char *placeholder="(untitled)") const
	Retrieve a mapped, NUL-terminated string with the volume's title. More...

template<typename T >
T *	translate (T *va) const
	Translate a virtual address in this ELF volume's read-only data segment, into a virtual address in the mapped view of the same program. More...

uint32_t	translate (uint32_t va) const
	A variant of translate() for pointers that have already been cast to uint32_t, such as pointers that are found in system asset objects.

void	translate (const _SYSMetadataBootAsset &meta, AssetGroup &group)
	Translate a bootstrap asset metadata record to an AssetGroup. More...

void	translate (const _SYSMetadataImage *meta, AssetImage &image, AssetGroup &group)
	Translate an image metadata record to an AssetImage. More...

const UUID *	uuid () const
	Retrieve the volume's UUID. More...

const char *	version (const char *placeholder="(none)") const
	Retrieve a mapped, NUL-terminated string with the volume's version string. More...

Volume	volume () const
	Returns the Volume associated with this mapping.

Detailed Description

A Volume that has been mapped into the secondary flash memory region.

This object can be used to access the mapped data.

For Volumes containing a valid ELF binary only.

Only one thing may be mapped into the secondary flash memory region at a time. This means that any time you create a MappedVolume, any previously existing MappedVolume becomes no longer valid.

Since only one Volume can be mapped at a time, it's important to copy data out of the volume into RAM if you need to collect data from multiple volumes. For example, a title can be copied to a Sifteo::String, or an AssetImage can be copied to a Sifteo::TileBuffer.

Constructor & Destructor Documentation

Sifteo::MappedVolume::MappedVolume ( )

inline

Construct a detached MappedVolume.

You must call attach() to connect this to a Volume.

Sifteo::MappedVolume::MappedVolume ( Volume vol )

inlineexplicit

Map a view of the provided Volume.

The volume must contain an ELF binary. No other MappedVolume instances may exist at this time.

Member Function Documentation

void Sifteo::MappedVolume::attach ( Volume vol )

inline

Attach this MappedVolume to a new volume.

Pointers obtained prior to this reattachment, if any, will no longer be valid.

void* Sifteo::MappedVolume::metadata	(	unsigned	key,
		unsigned	minSize,
		unsigned *	actualSize
	)		const

inline

Look up a metadata value from the mapped Volume.

On success, returns a pointer to the value, and (if actualSize is not NULL) writes the actual size of the metadata value to *actualSize.

If the metadata value is not found, or it's smaller than minSize, returns NULL.

Note that the 'actualSize' parameter here is required, in order to reliably differentiate this from the 1- or 2-argument form of metadata().

template<typename T >

const T* Sifteo::MappedVolume::metadata	(	unsigned	key,
		unsigned *	actualSize = `NULL`
	)		const

inline

Look up a metadata value from the mapped Volume. The result is cast to a constant pointer of the indicated type, and we require that the metadata value is at least as large as sizeof(T).

On success, returns a pointer to the value, and (if actualSize is not NULL) writes the actual size of the metadata value to *actualSize.

If the metadata value is not found, or it's smaller than sizeof(T), returns NULL.

Use this form of metadata() in the common case when minSize equals the size of the object you're retrieving a pointer to.

const char* Sifteo::MappedVolume::package ( const char * placeholder = "(none)" ) const

inline

Retrieve a mapped, NUL-terminated string with the volume's package string.

Always returns a valid pointer. If the game has no package, returns a placeholder string.

const char* Sifteo::MappedVolume::title ( const char * placeholder = "(untitled)" ) const

inline

Retrieve a mapped, NUL-terminated string with the volume's title.

Always returns a valid pointer. If the game has no title, returns a placeholder string.

template<typename T >

T* Sifteo::MappedVolume::translate ( T * va ) const

inline

Translate a virtual address in this ELF volume's read-only data segment, into a virtual address in the mapped view of the same program.

This accounts for the difference between the primary and secondary flash address spaces, as well as the offset between the RODATA segment and the beginning of the ELF file.

void Sifteo::MappedVolume::translate	(	const _SYSMetadataBootAsset &	meta,
		AssetGroup &	group
	)

inline

Translate a bootstrap asset metadata record to an AssetGroup.

Using this object's memory mapping, convert a _SYSMetadataBootAsset record into an AssetGroup which can be used to load the corresponding assets.

This is only useful for programs which must bootstrap another program's assets.

void Sifteo::MappedVolume::translate	(	const _SYSMetadataImage *	meta,
		AssetImage &	image,
		AssetGroup &	group
	)

inline

Translate an image metadata record to an AssetImage.

Using this object's memory mapping, convert a _SYSMetadataImage record into an AssetImage which references the image data mapped in from another volume.

Since the _SYSMetadataImage only stores information about the read-only data associated with an AssetGroup, you must also supply an AssetGroup object to be used for the read-write storage of state, such as load addresses for the group on each cube

This function can be used to load graphics assets from another game or other Volume on the system, as long as those assets have been annotated in their game's metadata.

const UUID* Sifteo::MappedVolume::uuid ( ) const

inline

Retrieve the volume's UUID.

Always returns a valid pointer. If there is no UUID, returns an all-zero dummy UUID.

const char* Sifteo::MappedVolume::version ( const char * placeholder = "(none)" ) const

inline

Retrieve a mapped, NUL-terminated string with the volume's version string.

Always returns a valid pointer. If the game has no package, returns a placeholder string.

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

filesystem.h

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation