OSDL: OSDL::Video::TwoDimensional::Image Class Reference

The Image interface is mostly a set of related functions (static methods), including factories.

Our belief is however that the fewer formats you use, the simpler it will be for everyone.

We therefore recommend using two of them, which moreover are patent-less standards and should cover most if not all needs :

Definition at line 72 of file OSDLImage.h.


Public Member Functions
	Image (const std::string &filename) throw ( ImageException )
	This Image constructor uses given filename to load the picture from the corresponding file .
virtual	~Image () throw ()
	Basic overridable destructor, so that it remains virtual.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const throw ()
	Returns an user-friendly description of the state of this object.
Static Public Member Functions
static Surface &	LoadIcon (const std::string &filename, Pixels::ColorElement **mask) throw ( ImageException )
	Loads specified icon, and returns the corresponding surface, while updating specified mask so that it selects only icon pixels that should remain visible.
static void	Load (Surface &targetSurface, const std::string &filename, bool blitOnly=false, bool convertToDisplay=true, bool convertWithAlpha=true) throw ( ImageException )
	Loads an image, whose format will be auto-detected, from specified file into target surface.
static void	LoadJPG (Surface &targetSurface, const std::string &filename, bool blitOnly=false, bool convertToDisplay=true, bool convertWithAlpha=true) throw ( ImageException )
	Loads a JPEG image from specified file into target surface.
static void	LoadPNG (Surface &targetSurface, const std::string &filename, bool blitOnly=false, bool convertToDisplay=true, bool convertWithAlpha=true) throw ( ImageException )
	Loads a PNG image from specified file into target surface.
static void	LoadBMP (Surface &targetSurface, const std::string &filename, bool blitOnly=false, bool convertToDisplay=true, bool convertWithAlpha=true) throw ( ImageException )
	Loads a BMP image from specified file into target surface.
static void	LoadGIF (Surface &targetSurface, const std::string &filename, bool blitOnly=false, bool convertToDisplay=true, bool convertWithAlpha=true) throw ( ImageException )
	Loads a GIF image from specified file into target surface.
static void	LoadLBM (Surface &targetSurface, const std::string &filename, bool blitOnly=false, bool convertToDisplay=true, bool convertWithAlpha=true) throw ( ImageException )
	Loads a LBM image from specified file into target surface.
static void	LoadPCX (Surface &targetSurface, const std::string &filename, bool blitOnly=false, bool convertToDisplay=true, bool convertWithAlpha=true) throw ( ImageException )
	Loads a PCX image from specified file into target surface.
static void	LoadPNM (Surface &targetSurface, const std::string &filename, bool blitOnly=false, bool convertToDisplay=true, bool convertWithAlpha=true) throw ( ImageException )
	Loads a PNM image from specified file into target surface.
static void	LoadTGA (Surface &targetSurface, const std::string &filename, bool blitOnly=false, bool convertToDisplay=true, bool convertWithAlpha=true) throw ( ImageException )
	Loads a TGA image from specified file into target surface.
static void	LoadXPM (Surface &targetSurface, const std::string &filename, bool blitOnly=false, bool convertToDisplay=true, bool convertWithAlpha=true) throw ( ImageException )
	Loads a XPM image from specified file into target surface.
static void	SavePNG (Surface &targetSurface, const std::string &filename, bool overwrite=true) throw ( ImageException )
	Saves specified surface on file, with specified filename, in PNG format.
static void	SaveBMP (Surface &targetSurface, const std::string &filename, bool overwrite=true) throw ( ImageException )
	Saves specified surface on file, with specified filename, in BMP format.
Protected Attributes
std::string	_filename
	The filename corresponding to the internal image.
Private Member Functions
	Image (const Image &source) throw ()
	Copy constructor made private to ensure that it will never be called.
Image &	operator= (const Image &source) throw ()
	Assignment operator made private to ensure that it will never be called.
Static Private Attributes
static const std::string	JPGTag
	Tag for JPG images, one of the recommended formats.
static const std::string	PNGTag
	Tag for PNG images, one of the recommended formats.
static const std::string	BMPTag
	Tag for BMP images, a supported but not recommended format.
static const std::string	GIFTag
	Tag for GIF images, a supported but not recommended format.
static const std::string	LBMTag
	Tag for LBM images, a supported but not recommended format.
static const std::string	PCXTag
	Tag for PCX images, a supported but not recommended format.
static const std::string	PNMTag
	Tag for PNM images, a supported but not recommended format.
static const std::string	TGATag
	Tag for TGA images, a supported but not recommended format.
static const std::string	XPMTag
	Tag for XPM images, a supported but not recommended format.

Constructor & Destructor Documentation

OSDL::Video::TwoDimensional::Image::Image ( const std::string & filename ) throw ( ImageException ) [explicit]

This Image constructor uses given filename to load the picture from the corresponding file .

Actual picture format is guessed.

Image::~Image ( ) throw () [virtual]

Basic overridable destructor, so that it remains virtual.

Definition at line 71 of file OSDLImage.cc.

OSDL::Video::TwoDimensional::Image::Image ( const Image & source ) throw () [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

static Surface& OSDL::Video::TwoDimensional::Image::LoadIcon	(	const std::string &	filename,
		Pixels::ColorElement **	mask
	)			throw ( ImageException ) `[static]`

Loads specified icon, and returns the corresponding surface, while updating specified mask so that it selects only icon pixels that should remain visible.

Note:

Ownership of the surface and the mask is transferred to the caller, which has to deallocate them when necessary.

The icon must have a palette, and its size should be 32 * 32 pixels.

Icon format, if supported, will be auto-detected.

See also:: VideoModule::setWindowIcon

Referenced by OSDL::Video::VideoModule::setWindowIcon().

void Image::Load	(	Surface &	targetSurface,
		const std::string &	filename,
		bool	blitOnly = `false`,
		bool	convertToDisplay = `true`,
		bool	convertWithAlpha = `true`
	)			throw ( ImageException ) `[static]`

Loads an image, whose format will be auto-detected, from specified file into target surface.

Parameters:

	targetSurface	the surface that should contain eventually the loaded image.
	filename	the name of the image file.
	blitOnly	tells whether the loaded image surface should only be blitted into the supposed already existing internal surface and then be deallocated (if flag is true, notably useful to load an image into the screen surface), or if this loaded surface should simply replace the former one (if flag is false, usual case for shadow surfaces).
	convertToDisplay	tells whether this loaded image should have its pixel format converted to the screen's format, in order to allow for faster blits if ever that surface was to be blitted multiple times to the screen (one-time-for-all conversion). Beware : setMode must have been called before convertToDisplay is chosen.
	convertWithAlpha	if the conversion to screen format is selected (convertToDisplay is true), tells whether the converted surface should also have an alpha channel.

Note:: The auto-detected format must be of course a supported image format.
Specifying a blitOnly option set to true is especially convenient when specifying the screen's surface as target surface, since this surface is special and should not be deallocated as the others may be.

Definition at line 194 of file OSDLImage.cc.

References OSDL::Utils::getBackendLastError(), and OSDL::Video::VideoModule::IsDisplayInitialized().

void Image::LoadJPG	(	Surface &	targetSurface,
		const std::string &	filename,
		bool	blitOnly = `false`,
		bool	convertToDisplay = `true`,
		bool	convertWithAlpha = `true`
	)			throw ( ImageException ) `[static]`

Loads a JPEG image from specified file into target surface.

Parameters:

	targetSurface	the surface that should contain the loaded image.
	filename	the name of the JPEG file.
	blitOnly	tells whether the loaded image surface should only be blitted into the supposed already existing internal surface and then be deallocated (if flag is true, notably useful to load an image into the screen surface), or if this loaded surface should simply replace the former one (if flag is false, usual case for shadow surfaces).
	convertToDisplay	tells whether this loaded image should have its pixel format converted to the screen's format, in order to allow for faster blits if ever that surface was to be blitted multiple times to the screen (one-time-for-all conversion). Beware : setMode must have been called before convertToDisplay is chosen.
	convertWithAlpha	if the conversion to screen format is selected (convertToDisplay is true), tells whether the converted surface should also have an alpha channel.

Note:: The auto-detected format must be of course a supported image format.
Specifying a blitOnly option set to true is especially convenient when specifying the screen's surface as target surface, since this surface is special and should not be deallocated as the others may be.

See also:: Surface::loadJPG

Definition at line 366 of file OSDLImage.cc.

References OSDL::Utils::getBackendLastError(), and OSDL::Video::VideoModule::IsDisplayInitialized().

void Image::LoadPNG	(	Surface &	targetSurface,
		const std::string &	filename,
		bool	blitOnly = `false`,
		bool	convertToDisplay = `true`,
		bool	convertWithAlpha = `true`
	)			throw ( ImageException ) `[static]`

Loads a PNG image from specified file into target surface.

Parameters:

	targetSurface	the surface that should contain the loaded image.
	filename	the name of the PNG file.
	blitOnly	tells whether the loaded image surface should only be blitted into the supposed already existing internal surface and then be deallocated (if flag is true, notably useful to load an image into the screen surface), or if this loaded surface should simply replace the former one (if flag is false, usual case for shadow surfaces).
	convertToDisplay	tells whether this loaded image should have its pixel format converted to the screen's format, in order to allow for faster blits if ever that surface was to be blitted multiple times to the screen (one-time-for-all conversion). Beware : setMode must have been called before convertToDisplay is chosen.
	convertWithAlpha	if the conversion to screen format is selected (convertToDisplay is true), tells whether the converted surface should also have an alpha channel.

Note:: The auto-detected format must be of course a supported image format.
Specifying a blitOnly option set to true is especially convenient when specifying the screen's surface as target surface, since this surface is special and should not be deallocated as the others may be.

See also:: Surface::loadPNG

Definition at line 509 of file OSDLImage.cc.

References OSDL::Utils::getBackendLastError(), and OSDL::Video::VideoModule::IsDisplayInitialized().

void Image::LoadBMP	(	Surface &	targetSurface,
		const std::string &	filename,
		bool	blitOnly = `false`,
		bool	convertToDisplay = `true`,
		bool	convertWithAlpha = `true`
	)			throw ( ImageException ) `[static]`

Loads a BMP image from specified file into target surface.

Parameters:

	targetSurface	the surface that should contain the loaded image.
	filename	the name of the BMP file.
	blitOnly	tells whether the loaded image surface should only be blitted into the supposed already existing internal surface and then be deallocated (if flag is true, notably useful to load an image into the screen surface), or if this loaded surface should simply replace the former one (if flag is false, usual case for shadow surfaces).
	convertToDisplay	tells whether this loaded image should have its pixel format converted to the screen's format, in order to allow for faster blits if ever that surface was to be blitted multiple times to the screen (one-time-for-all conversion). Beware : setMode must have been called before convertToDisplay is chosen.
	convertWithAlpha	if the conversion to screen format is selected (convertToDisplay is true), tells whether the converted surface should also have an alpha channel.

Note:: The auto-detected format must be of course a supported image format.
Specifying a blitOnly option set to true is especially convenient when specifying the screen's surface as target surface, since this surface is special and should not be deallocated as the others may be.

See also:: Surface::loadBMP

Definition at line 649 of file OSDLImage.cc.

References OSDL::Utils::getBackendLastError(), and OSDL::Video::VideoModule::IsDisplayInitialized().

void Image::LoadGIF	(	Surface &	targetSurface,
		const std::string &	filename,
		bool	blitOnly = `false`,
		bool	convertToDisplay = `true`,
		bool	convertWithAlpha = `true`
	)			throw ( ImageException ) `[static]`

Loads a GIF image from specified file into target surface.

Parameters:

	targetSurface	the surface that should contain the loaded image.
	filename	the name of the GIF file.
	blitOnly	tells whether the loaded image surface should only be blitted into the supposed already existing internal surface and then be deallocated (if flag is true, notably useful to load an image into the screen surface), or if this loaded surface should simply replace the former one (if flag is false, usual case for shadow surfaces).
	convertToDisplay	tells whether this loaded image should have its pixel format converted to the screen's format, in order to allow for faster blits if ever that surface was to be blitted multiple times to the screen (one-time-for-all conversion). Beware : setMode must have been called before convertToDisplay is chosen.
	convertWithAlpha	if the conversion to screen format is selected (convertToDisplay is true), tells whether the converted surface should also have an alpha channel.

Note:: The auto-detected format must be of course a supported image format.
Specifying a blitOnly option set to true is especially convenient when specifying the screen's surface as target surface, since this surface is special and should not be deallocated as the others may be.

See also:: Surface::loadGIF

Definition at line 791 of file OSDLImage.cc.

References OSDL::Utils::getBackendLastError(), and OSDL::Video::VideoModule::IsDisplayInitialized().

void Image::LoadLBM	(	Surface &	targetSurface,
		const std::string &	filename,
		bool	blitOnly = `false`,
		bool	convertToDisplay = `true`,
		bool	convertWithAlpha = `true`
	)			throw ( ImageException ) `[static]`

Loads a LBM image from specified file into target surface.

Parameters:

	targetSurface	the surface that should contain the loaded image.
	filename	the name of the LBM file.
	blitOnly	tells whether the loaded image surface should only be blitted into the supposed already existing internal surface and then be deallocated (if flag is true, notably useful to load an image into the screen surface), or if this loaded surface should simply replace the former one (if flag is false, usual case for shadow surfaces).
	convertToDisplay	tells whether this loaded image should have its pixel format converted to the screen's format, in order to allow for faster blits if ever that surface was to be blitted multiple times to the screen (one-time-for-all conversion). Beware : setMode must have been called before convertToDisplay is chosen.
	convertWithAlpha	if the conversion to screen format is selected (convertToDisplay is true), tells whether the converted surface should also have an alpha channel.

Note:: The auto-detected format must be of course a supported image format.
Specifying a blitOnly option set to true is especially convenient when specifying the screen's surface as target surface, since this surface is special and should not be deallocated as the others may be.

See also:: Surface::loadLBM

Definition at line 931 of file OSDLImage.cc.

References OSDL::Utils::getBackendLastError(), and OSDL::Video::VideoModule::IsDisplayInitialized().

void Image::LoadPCX	(	Surface &	targetSurface,
		const std::string &	filename,
		bool	blitOnly = `false`,
		bool	convertToDisplay = `true`,
		bool	convertWithAlpha = `true`
	)			throw ( ImageException ) `[static]`

Loads a PCX image from specified file into target surface.

Parameters:

	targetSurface	the surface that should contain the loaded image.
	filename	the name of the PCX file.
	blitOnly	tells whether the loaded image surface should only be blitted into the supposed already existing internal surface and then be deallocated (if flag is true, notably useful to load an image into the screen surface), or if this loaded surface should simply replace the former one (if flag is false, usual case for shadow surfaces).
	convertToDisplay	tells whether this loaded image should have its pixel format converted to the screen's format, in order to allow for faster blits if ever that surface was to be blitted multiple times to the screen (one-time-for-all conversion). Beware : setMode must have been called before convertToDisplay is chosen.
	convertWithAlpha	if the conversion to screen format is selected (convertToDisplay is true), tells whether the converted surface should also have an alpha channel.

Note:: The auto-detected format must be of course a supported image format.
Specifying a blitOnly option set to true is especially convenient when specifying the screen's surface as target surface, since this surface is special and should not be deallocated as the others may be.

See also:: Surface::loadPCX

Definition at line 1073 of file OSDLImage.cc.

References OSDL::Utils::getBackendLastError(), and OSDL::Video::VideoModule::IsDisplayInitialized().

void Image::LoadPNM	(	Surface &	targetSurface,
		const std::string &	filename,
		bool	blitOnly = `false`,
		bool	convertToDisplay = `true`,
		bool	convertWithAlpha = `true`
	)			throw ( ImageException ) `[static]`

Loads a PNM image from specified file into target surface.

Parameters:

	targetSurface	the surface that should contain the loaded image.
	filename	the name of the PNM file.
	blitOnly	tells whether the loaded image surface should only be blitted into the supposed already existing internal surface and then be deallocated (if flag is true, notably useful to load an image into the screen surface), or if this loaded surface should simply replace the former one (if flag is false, usual case for shadow surfaces).
	convertToDisplay	tells whether this loaded image should have its pixel format converted to the screen's format, in order to allow for faster blits if ever that surface was to be blitted multiple times to the screen (one-time-for-all conversion). Beware : setMode must have been called before convertToDisplay is chosen.
	convertWithAlpha	if the conversion to screen format is selected (convertToDisplay is true), tells whether the converted surface should also have an alpha channel.

Note:: The auto-detected format must be of course a supported image format.
Specifying a blitOnly option set to true is especially convenient when specifying the screen's surface as target surface, since this surface is special and should not be deallocated as the others may be.

See also:: Surface::loadPNM

Definition at line 1215 of file OSDLImage.cc.

References OSDL::Utils::getBackendLastError(), and OSDL::Video::VideoModule::IsDisplayInitialized().

void Image::LoadTGA	(	Surface &	targetSurface,
		const std::string &	filename,
		bool	blitOnly = `false`,
		bool	convertToDisplay = `true`,
		bool	convertWithAlpha = `true`
	)			throw ( ImageException ) `[static]`

Loads a TGA image from specified file into target surface.

Parameters:

	targetSurface	the surface that should contain the loaded image.
	filename	the name of the TGA file.
	blitOnly	tells whether the loaded image surface should only be blitted into the supposed already existing internal surface and then be deallocated (if flag is true, notably useful to load an image into the screen surface), or if this loaded surface should simply replace the former one (if flag is false, usual case for shadow surfaces).
	convertToDisplay	tells whether this loaded image should have its pixel format converted to the screen's format, in order to allow for faster blits if ever that surface was to be blitted multiple times to the screen (one-time-for-all conversion). Beware : setMode must have been called before convertToDisplay is chosen.
	convertWithAlpha	if the conversion to screen format is selected (convertToDisplay is true), tells whether the converted surface should also have an alpha channel.

Note:: The auto-detected format must be of course a supported image format.
Specifying a blitOnly option set to true is especially convenient when specifying the screen's surface as target surface, since this surface is special and should not be deallocated as the others may be.

See also:: Surface::loadTGA

Definition at line 1354 of file OSDLImage.cc.

References OSDL::Utils::getBackendLastError(), and OSDL::Video::VideoModule::IsDisplayInitialized().

void Image::LoadXPM	(	Surface &	targetSurface,
		const std::string &	filename,
		bool	blitOnly = `false`,
		bool	convertToDisplay = `true`,
		bool	convertWithAlpha = `true`
	)			throw ( ImageException ) `[static]`

Loads a XPM image from specified file into target surface.

Parameters:

	targetSurface	the surface that should contain the loaded image.
	filename	the name of the XPM file.
	blitOnly	tells whether the loaded image surface should only be blitted into the supposed already existing internal surface and then be deallocated (if flag is true, notably useful to load an image into the screen surface), or if this loaded surface should simply replace the former one (if flag is false, usual case for shadow surfaces).
	convertToDisplay	tells whether this loaded image should have its pixel format converted to the screen's format, in order to allow for faster blits if ever that surface was to be blitted multiple times to the screen (one-time-for-all conversion). Beware : setMode must have been called before convertToDisplay is chosen.
	convertWithAlpha	if the conversion to screen format is selected (convertToDisplay is true), tells whether the converted surface should also have an alpha channel.

Note:: The auto-detected format must be of course a supported image format.
Specifying a blitOnly option set to true is especially convenient when specifying the screen's surface as target surface, since this surface is special and should not be deallocated as the others may be.

See also:: Surface::loadXPM

Definition at line 1495 of file OSDLImage.cc.

References OSDL::Utils::getBackendLastError(), and OSDL::Video::VideoModule::IsDisplayInitialized().

void Image::SavePNG	(	Surface &	targetSurface,
		const std::string &	filename,
		bool	overwrite = `true`
	)			throw ( ImageException ) `[static]`

Saves specified surface on file, with specified filename, in PNG format.

Parameters:

	targetSurface	the surface that should be saved on file. This parameter cannot be 'const' since the surface may have to be locked to read its pixels, so that they can be stored in the image file.
	filename	the name of the PNG file.
	overwrite	tells whether any already existing file should be overwritten. The default is true, if false an exception will be raised should a corresponding file be found.

Note:: This method is especially convenient for screenshots.

Transparency is managed.

Note:: The PNG format is to be preferred to the BMP one.

See also:: Surface::savePNG

Definition at line 1638 of file OSDLImage.cc.

Referenced by OSDL::Video::Surface::savePNG().

void Image::SaveBMP	(	Surface &	targetSurface,
		const std::string &	filename,
		bool	overwrite = `true`
	)			throw ( ImageException ) `[static]`

Saves specified surface on file, with specified filename, in BMP format.

Parameters:

	targetSurface	the surface that should be saved on file. This parameter cannot be 'const' since the surface may have to be locked to read its pixels, so that they can be stored in the image file.
	filename	the name of the BMP file.
	overwrite	tells whether an already existing file should be overwritten. The default is true, if false an exception will be raised should a corresponding file be found.

Note:: This method is especially convenient for screenshots.
The PNG format is to be preferred to the BMP one.

See also:: Surface::saveBMP

Definition at line 1833 of file OSDLImage.cc.

References OSDL::Utils::getBackendLastError().

const string Image::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const throw () [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 1851 of file OSDLImage.cc.

OSDL::Video::TwoDimensional::Image Class Reference

Detailed Description

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Member Functions

Static Private Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation