OSDL::Data::ResourceManager Class Reference

This ResourceManager manages resources on behalf of the developer. More...

#include <OSDLResourceManager.h>

Collaboration diagram for OSDL::Data::ResourceManager:

Public Member Functions
	ResourceManager (const std::string &resourceMapFilename="OSDLResourceMap.xml")
	Creates a resource manager, which will manage resources listed in the resource map, whose filename is specified.
virtual	~ResourceManager () throw ()
	Virtual destructor.
virtual Audio::MusicCountedPtr	getMusic (Ceylan::ResourceID id)
	Returns a counter pointer referencing the specified music.
virtual Audio::MusicCountedPtr	getMusic (const std::string &musicPath)
	Returns a counter pointer referencing the specified music.
virtual Audio::SoundCountedPtr	getSound (Ceylan::ResourceID id)
	Returns a counter pointer referencing the specified sound.
virtual Audio::SoundCountedPtr	getSound (const std::string &soundPath)
	Returns a counter pointer referencing the specified sound.
virtual Video::TwoDimensional::ImageCountedPtr	getImage (Ceylan::ResourceID id)
	Returns a counter pointer referencing the specified image.
virtual Video::TwoDimensional::ImageCountedPtr	getImage (const std::string &imagePath)
	Returns a counter pointer referencing the specified image.
virtual Video::OpenGL::TextureCountedPtr	getTexture (Ceylan::ResourceID id, bool uploadWanted=true)
	Returns a counter pointer referencing the specified texture.
virtual Video::OpenGL::TextureCountedPtr	getTexture (const std::string &texturePath, bool uploadWanted=true)
	Returns a counter pointer referencing the specified texture.
virtual std::pair < Video::OpenGL::TextureCountedPtr, Ceylan::ResourceID >	getTextureFrom (Video::Surface &sourceSurface, Video::OpenGL::GLTexture::TextureFlavour flavour, bool uploadWanted=true)
	Returns a pair made of a counted pointer to a texture created from specified surface, and of the ID of the entry corresponding to that texture in this manager.
virtual Video::TwoDimensional::Text::TrueTypeFontCountedPtr	getTrueTypeFont (Ceylan::ResourceID id, Video::TwoDimensional::Text::PointSize pointSize)
	Returns a counter pointer referencing the specified TrueType font.
virtual Video::TwoDimensional::Text::TrueTypeFontCountedPtr	getTrueTypeFont (const std::string &fontPath, Video::TwoDimensional::Text::PointSize pointSize)
	Returns a counter pointer referencing the specified TrueType font.
virtual void	discardTexture (Ceylan::ResourceID textureId)
	Discards permanently the specified texture entry from this manager.
virtual void	purge ()
	Requests all resources only referenced by this manager to unload their content.
virtual void	displayLoadedResources ()
	Outputs the list of all currently loaded resources.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns an user-friendly description of the state of this object.
Static Public Member Functions
static ContentType	GetContentType (const std::string &stringifiedType, bool throwIfNotMatched=true)
	Returns the content type corresponding to the specified stringified version.
Protected Member Functions
void	registerResource (const Ceylan::XML::XMLParser::XMLTree &resourceXMLEntry)
	Registers a new resource, as specified by the XML resource entry.
Ceylan::ResourceID	getIDForPath (const std::string &resourcePath, bool emergencyStopInNotFound=true) const
	Returns the resource identifier corresponding to specified path, based on the reverse resource map.
Protected Attributes
std::map< Ceylan::ResourceID, Audio::MusicCountedPtr >	_musicMap
	Dictionary for music resources.
std::map< Ceylan::ResourceID, Audio::SoundCountedPtr >	_soundMap
	Dictionary for sound resources.
std::map< Ceylan::ResourceID, Video::TwoDimensional::ImageCountedPtr >	_imageMap
	Dictionary for image resources.
std::map< Ceylan::ResourceID, Video::OpenGL::TextureCountedPtr >	_textureMap
	Dictionary for texture resources (all kinds: 2D, 3D, etc.
std::map< Ceylan::ResourceID, Video::TwoDimensional::Text::TrueTypeFontCountedPtr >	_truetypeFontMap
	Dictionary for TrueType fonts.
std::map< std::string, Ceylan::ResourceID >	_reverseMap
	Reverse dictionary: allows to convert a specified resource path into a resource identifier.
Ceylan::ResourceID	_maxID
	Records the current highest resource identifier already allocated.
Private Member Functions
	ResourceManager (const ResourceManager &source)
	Copy constructor made private to ensure that it will never be called.
ResourceManager &	operator= (const ResourceManager &source)
	Assignment operator made private to ensure that it will never be called.

Detailed Description

This ResourceManager manages resources on behalf of the developer.

The manager is able to keep track of resources, to load them and to make them available to any number of clients.

To do so, the manager reads a resource map, usually from an XML file in an OSDL archive, and based on it maintains a set of dictionaries, each of them corresponding to a kind of resource, like images, sounds, etc.

A key of such a dictionary is a resource identifier, which is expected to correspond to a resource this dictionary manages.

Each associated value is a Ceylan::LoadableWithContent instance, which records the path of the resource file and, if loaded, the resource itself.

Note:: When the resource archive is modified (ex: a resource is added), the code loading from the archive must be recompiled, as resource identifiers are likely to change.

See also:: create-OSDL-archive.sh to understand how resources are indexed in an archive.

Definition at line 176 of file OSDLResourceManager.h.

Constructor & Destructor Documentation

Data::ResourceManager::ResourceManager ( const std::string & resourceMapFilename = "OSDLResourceMap.xml" ) [explicit]

Creates a resource manager, which will manage resources listed in the resource map, whose filename is specified.

Parameters:

resourceMapFilename

the filename of the XML resource map to use; typically "resource-map.xml" if using the create-OSDL-archive.sh script with default settings.

Definition at line 117 of file OSDLResourceManager.cc.

References registerResource(), and toString().

Data::ResourceManager::~ResourceManager ( ) throw () [virtual]

Virtual destructor.

Definition at line 154 of file OSDLResourceManager.cc.

References toString().

OSDL::Data::ResourceManager::ResourceManager ( const ResourceManager & source ) [explicit, private]

Copy constructor made private to ensure that it will never be called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Member Function Documentation

void Data::ResourceManager::discardTexture ( Ceylan::ResourceID textureId ) [virtual]

Discards permanently the specified texture entry from this manager.

Note:: Useful for resources like generated textures that cannot be unloaded (as they could not be then reloaded from file) and that we want nevertheless to be able to get rid of, when finished with them, so that their memory can be released.

Exceptions:

ResourceManagerException

if not such resource exists.

Definition at line 449 of file OSDLResourceManager.cc.

References _textureMap, and OSDL::Video::Pixels::toString().

void Data::ResourceManager::displayLoadedResources ( ) [virtual]

Outputs the list of all currently loaded resources.

Note:: Only for debugging purpose.

Definition at line 532 of file OSDLResourceManager.cc.

References _imageMap, _musicMap, _soundMap, _textureMap, _truetypeFontMap, toString(), and OSDL::Video::Pixels::toString().

ContentType Data::ResourceManager::GetContentType	(	const std::string &	stringifiedType,
		bool	throwIfNotMatched = `true`
	)			`[static]`

Returns the content type corresponding to the specified stringified version.

Parameters:

	stringifiedType	the string to interpret.
	throwIfNotMatched	if true, if the context type could not be determined, throws a ResourceManagerException rather than returning the 'unknown' content type.

Definition at line 1182 of file OSDLResourceManager.cc.

References OSDL::Data::data, OSDL::Data::image, OSDL::Data::music, OSDL::Data::sound, OSDL::Data::text, OSDL::Data::texture_2D, OSDL::Data::texture_3D, OSDL::Data::ttf_font, and OSDL::Data::unknown.

Referenced by registerResource().

Ceylan::ResourceID Data::ResourceManager::getIDForPath	(	const std::string &	resourcePath,
		bool	emergencyStopInNotFound = `true`
	)			const `[protected]`

Returns the resource identifier corresponding to specified path, based on the reverse resource map.

Parameters:

	resourcePath	the path of the specified resource in archive.
	emergencyStopInNotFound	performs an emergency stop in the look-up of the specified ID failed, as usually the raising of an exception here will make a view constructor fail, leading to a segmentation fault.

Exceptions:

ResourceManagerException

if the path could not be resolved.

Definition at line 1140 of file OSDLResourceManager.cc.

References _reverseMap.

Referenced by getImage(), getMusic(), getSound(), and getTexture().

Video::TwoDimensional::ImageCountedPtr Data::ResourceManager::getImage ( const std::string & imagePath ) [virtual]

Returns a counter pointer referencing the specified image.

Parameters:

imagePath

the image path that will be looked-up in the reverse resource map, resolved to a resource identifier which will be then used to return a corresponding counted image pointer.

Exceptions:

ResourceManagerException

if the image could not be found.

Definition at line 285 of file OSDLResourceManager.cc.

References _imageMap, and getIDForPath().

Video::TwoDimensional::ImageCountedPtr Data::ResourceManager::getImage ( Ceylan::ResourceID id ) [virtual]

Returns a counter pointer referencing the specified image.

Parameters:

id

the resource identifier for that image.

Exceptions:

ResourceManagerException

if the image could not be found.

Definition at line 262 of file OSDLResourceManager.cc.

References _imageMap, and OSDL::Video::Pixels::toString().

Audio::MusicCountedPtr Data::ResourceManager::getMusic ( const std::string & musicPath ) [virtual]

Returns a counter pointer referencing the specified music.

Parameters:

musicPath

the music path that will be looked-up in the reverse resource map, resolved to a resource identifier which will be then used to return a corresponding counted music pointer.

Exceptions:

ResourceManagerException

if the music could not be found.

Definition at line 192 of file OSDLResourceManager.cc.

References _musicMap, and getIDForPath().

Audio::MusicCountedPtr Data::ResourceManager::getMusic ( Ceylan::ResourceID id ) [virtual]

Returns a counter pointer referencing the specified music.

Parameters:

id

the resource identifier for that music.

Exceptions:

ResourceManagerException

if the music could not be found.

Definition at line 171 of file OSDLResourceManager.cc.

References _musicMap, and OSDL::Video::Pixels::toString().

Audio::SoundCountedPtr Data::ResourceManager::getSound ( const std::string & soundPath ) [virtual]

Returns a counter pointer referencing the specified sound.

Parameters:

soundPath

the sound path that will be looked-up in the reverse resource map, resolved to a resource identifier which will be then used to return a corresponding counted sound pointer.

Exceptions:

ResourceManagerException

if the sound could not be found.

Definition at line 238 of file OSDLResourceManager.cc.

References _soundMap, and getIDForPath().

Audio::SoundCountedPtr Data::ResourceManager::getSound ( Ceylan::ResourceID id ) [virtual]

Returns a counter pointer referencing the specified sound.

Parameters:

id

the resource identifier for that sound.

Exceptions:

ResourceManagerException

if the sound could not be found.

Definition at line 216 of file OSDLResourceManager.cc.

References _soundMap, and OSDL::Video::Pixels::toString().

Video::OpenGL::TextureCountedPtr Data::ResourceManager::getTexture	(	const std::string &	texturePath,
		bool	uploadWanted = `true`
	)			`[virtual]`

Returns a counter pointer referencing the specified texture.

Parameters:

	texturePath	the texture path that will be looked-up in the reverse resource map, resolved to a resource identifier which will be then used to return a corresponding counted texture pointer.
	uploadWanted	if true, the method will ensure that this texture is available in the video card before returning.

Exceptions:

ResourceManagerException

if the texture could not be found.

Note:: The returned texture has not been uploaded yet.

Definition at line 341 of file OSDLResourceManager.cc.

References _textureMap, and getIDForPath().

Video::OpenGL::TextureCountedPtr Data::ResourceManager::getTexture	(	Ceylan::ResourceID	id,
		bool	uploadWanted = `true`
	)			`[virtual]`

Returns a counter pointer referencing the specified texture.

Parameters:

	id	the resource identifier for that texture.
	uploadWanted	if true, the method will ensure that this texture is available in the video card before returning.

Exceptions:

ResourceManagerException

if the texture could not be found.

Note:: The returned texture has not been uploaded yet.

Definition at line 308 of file OSDLResourceManager.cc.

References _textureMap, and OSDL::Video::Pixels::toString().

std::pair< Video::OpenGL::TextureCountedPtr, Ceylan::ResourceID > Data::ResourceManager::getTextureFrom	(	Video::Surface &	sourceSurface,
		Video::OpenGL::GLTexture::TextureFlavour	flavour,
		bool	uploadWanted = `true`
	)			`[virtual]`

Returns a pair made of a counted pointer to a texture created from specified surface, and of the ID of the entry corresponding to that texture in this manager.

The texture can be used directly, whereas the ID is to be used later to discard it, once become useless.

See also:: discardTexture

Parameters:

	sourceSurface	the surface, whose ownership is taken, from which the texture will be made and referenced.
	flavour	the texture flavour that should be used.
	uploadWanted	if true, the method will ensure that this texture is available in the video card before returning.

Exceptions:

ResourceManagerException

if the operation failed.

Definition at line 376 of file OSDLResourceManager.cc.

References _maxID, and _textureMap.

virtual Video::TwoDimensional::Text::TrueTypeFontCountedPtr OSDL::Data::ResourceManager::getTrueTypeFont	(	const std::string &	fontPath,
		Video::TwoDimensional::Text::PointSize	pointSize
	)			`[virtual]`

Returns a counter pointer referencing the specified TrueType font.

Parameters:

	fontPath	the font path that will be looked-up in the reverse resource map, resolved to a resource identifier which will be then used to return a corresponding counted font pointer.
	pointSize	the targeted point size; it must be specified as otherwise, since a returned resource must always be loaded (due to conventions), it would be loaded with the default point size which is seldom the one wanted, thus it would have to be unloaded and then reloaded with the correct size, when wanting to use it for real.

Exceptions:

ResourceManagerException

if the font could not be found.

virtual Video::TwoDimensional::Text::TrueTypeFontCountedPtr OSDL::Data::ResourceManager::getTrueTypeFont	(	Ceylan::ResourceID	id,
		Video::TwoDimensional::Text::PointSize	pointSize
	)			`[virtual]`

Returns a counter pointer referencing the specified TrueType font.

Parameters:

	id	the resource identifier for that font.
	pointSize	the targeted point size; it must be specified as otherwise, since a returned resource must always be loaded (due to conventions), it would be loaded with the default point size which is seldom the one wanted, thus it would have to be unloaded and then reloaded with the correct size, when wanting to use it for real.

Exceptions:

ResourceManagerException

if the font could not be found.

ResourceManager& OSDL::Data::ResourceManager::operator= ( const ResourceManager & source ) [private]

Assignment operator made private to ensure that it will never be called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

void Data::ResourceManager::purge ( ) [virtual]

Requests all resources only referenced by this manager to unload their content.

Definition at line 467 of file OSDLResourceManager.cc.

References _imageMap, _musicMap, _soundMap, _textureMap, and _truetypeFontMap.

void Data::ResourceManager::registerResource ( const Ceylan::XML::XMLParser::XMLTree & resourceXMLEntry ) [protected]

Registers a new resource, as specified by the XML resource entry.

Definition at line 900 of file OSDLResourceManager.cc.

References _imageMap, _maxID, _musicMap, _reverseMap, _soundMap, _textureMap, _truetypeFontMap, OSDL::Video::OpenGL::GLTexture::For2D, OSDL::Video::OpenGL::GLTexture::For3D, GetContentType(), OSDL::Data::image, OSDL::Data::music, OSDL::Data::sound, OSDL::Data::texture_2D, OSDL::Data::texture_3D, OSDL::Data::ttf_font, and OSDL::Data::unknown.

Referenced by ResourceManager().

const string Data::ResourceManager::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const [virtual]

Returns an user-friendly description of the state of this object.

Parameters:

level

the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: Ceylan::TextDisplayable

Definition at line 627 of file OSDLResourceManager.cc.

References _imageMap, _maxID, _musicMap, _reverseMap, _soundMap, _textureMap, _truetypeFontMap, and OSDL::Video::Pixels::toString().

Referenced by displayLoadedResources(), ResourceManager(), and ~ResourceManager().

Member Data Documentation

std::map<Ceylan::ResourceID, Video::TwoDimensional::ImageCountedPtr> OSDL::Data::ResourceManager::_imageMap [protected]

Dictionary for image resources.

Each key of the map is a resource identifier, which is expected to correspond to a image resource.

Each associated value is a counted pointer on a Ceylan::LoadableWithContent instance (here, a image), which records the path of the resource file and, if loaded, the resource itself.

Definition at line 565 of file OSDLResourceManager.h.

Referenced by displayLoadedResources(), getImage(), purge(), registerResource(), and toString().

Ceylan::ResourceID OSDL::Data::ResourceManager::_maxID [protected]

Records the current highest resource identifier already allocated.

Useful, once having read the resource file, to know from which ID dynamically added resources can have their own ID.

Definition at line 634 of file OSDLResourceManager.h.

Referenced by getTextureFrom(), registerResource(), and toString().

std::map<Ceylan::ResourceID, Audio::MusicCountedPtr> OSDL::Data::ResourceManager::_musicMap [protected]

Dictionary for music resources.

Each key of the map is a resource identifier, which is expected to correspond to a music resource.

Each associated value is a counted pointer on a Ceylan::LoadableWithContent instance (here, a music), which records the path of the resource file and, if loaded, the resource itself.

Definition at line 534 of file OSDLResourceManager.h.

Referenced by displayLoadedResources(), getMusic(), purge(), registerResource(), and toString().

std::map<std::string,Ceylan::ResourceID> OSDL::Data::ResourceManager::_reverseMap [protected]

Reverse dictionary: allows to convert a specified resource path into a resource identifier.

This is useful when the resource path is to be established at runtime rather than at compile time (ex: if wanting to load a locale-dependent image, the simplest way is to forge the path at runtime based on the selected locale, rather than trying to determine and guess the corresponding identifier statically, for example with a 'switch (currentLocale) {...}'), and also to ensure that regardless of the resource package being used (ex: editor or game package), a shared resource (ex: a splash screen) will be referenced uniquely, by path name (whereas that image could be associated to different resource identifiers depending on the archive being read).

Each key of the map is a resource path, each value is a resource identifier which then can be given back to a get* method.

Definition at line 621 of file OSDLResourceManager.h.

Referenced by getIDForPath(), registerResource(), and toString().

std::map<Ceylan::ResourceID, Audio::SoundCountedPtr> OSDL::Data::ResourceManager::_soundMap [protected]

Dictionary for sound resources.

Each key of the map is a resource identifier, which is expected to correspond to a sound resource.

Each associated value is a counted pointer on a Ceylan::LoadableWithContent instance (here, a sound), which records the path of the resource file and, if loaded, the resource itself.

Definition at line 549 of file OSDLResourceManager.h.

Referenced by displayLoadedResources(), getSound(), purge(), registerResource(), and toString().

std::map<Ceylan::ResourceID, Video::OpenGL::TextureCountedPtr> OSDL::Data::ResourceManager::_textureMap [protected]

Dictionary for texture resources (all kinds: 2D, 3D, etc.

).

Each key of the map is a resource identifier, which is expected to correspond to a texture resource.

Each associated value is a counted pointer on a Ceylan::LoadableWithContent instance (here, a texture), which records the path of the resource file and, if loaded, the resource itself.

Definition at line 580 of file OSDLResourceManager.h.

Referenced by discardTexture(), displayLoadedResources(), getTexture(), getTextureFrom(), purge(), registerResource(), and toString().

std::map<Ceylan::ResourceID, Video::TwoDimensional::Text::TrueTypeFontCountedPtr> OSDL::Data::ResourceManager::_truetypeFontMap [protected]

Dictionary for TrueType fonts.

Each key of the map is a resource identifier, which is expected to correspond to a TrueType font.

Each associated value is a counted pointer on a Ceylan::LoadableWithContent instance (here, a TrueType font), which records the path of the resource file and, if loaded, the resource itself.

Definition at line 598 of file OSDLResourceManager.h.

Referenced by displayLoadedResources(), purge(), registerResource(), and toString().

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

OSDL::Data::ResourceManager Class Reference

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation