OSDL: OSDL::Video::Palette Class Reference

In these modes, the color of a pixel is defined by an index which points to a specific entry of the palette.

A palette is set thanks to color definitions, which describe a color 'as is', without taking into account a particular screen format.

To be used on a particular surface, color definitions need to be converted into PixelColor (actual colors), which are defined according to the surface pixel format. Therefore a Palette actually owns two palettes, a logical one (for color definitions) and a physical one (for pixel colors).

Definition at line 60 of file OSDLPalette.h.


Public Member Functions
	Palette (ColorCount numberOfColors, Pixels::ColorDefinition colors, Pixels::PixelFormat format=0) throw ( PaletteException )
	Constructs a palette from a specified array of color definitions.
	Palette (SDL_Palette &palette) throw ( PaletteException )
	Constructs a palette from an already existing SDL palette.
virtual	~Palette () throw ()
	Basic virtual destructor.
virtual void	load (ColorCount numberOfColors, Pixels::ColorDefinition *colors) throw ( PaletteException )
	Loads from memory a new palette.
virtual ColorCount	getNumberOfColors () const throw ()
	Returns the number of colors defined in the palette.
virtual const Pixels::PixelColor &	getPixelColorAt (ColorCount index) const throw ( PaletteException )
	Returns the pixel color of the palette which is located at specified index.
virtual Pixels::PixelColor *	getPixelColors () const throw ()
	Returns the palette's pointer to pixel colors.
virtual const Pixels::ColorDefinition &	getColorDefinitionAt (ColorCount index) const throw ( PaletteException )
	Returns the color definition of the palette which is located at specified index.
virtual Pixels::ColorDefinition *	getColorDefinitions () const throw ()
	Returns the palette's color definitions.
virtual void	updatePixelColorsFrom (Pixels::PixelFormat &format) throw ()
	Updates (recomputes) internal pixel colors from internal color definitions and specified pixel format.
virtual bool	draw (Surface &targetSurface, Pixels::ColorDefinition backgroundColor=Pixels::White) throw ()
	Draws in specified surface a series of horizontal lines taking its full width, each line being drawn with the color of the palette whose index corresponds to the line ordinate, with specified background underneath (useful to see that surface height and color number do not match).
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 Palette &	CreateGreyScalePalette (ColorCount numberOfColors=256) throw ()
	Palette factory, creating palettes with numberOfColors greyscale values, ranging uniformly from pure black to pure white.
static Palette &	CreateGradationPalette (Pixels::ColorDefinition colorStart, Pixels::ColorDefinition colorEnd, ColorCount numberOfColors=256) throw ()
	Palette factory, creating palettes with numberOfColors values, with continous tone interpolation from colorStart to colorEnd.
static Palette &	CreateLandscapePalette (ColorCount numberOfColors=256) throw ()
	Palette factory, creating palettes with numberOfColors corresponding to landscape colors.
Static Public Attributes
static const Ceylan::Flags	Logical
	The flag used to designate logical palette.
static const Ceylan::Flags	Physical
	The flag used to designate physical palette.
Protected Attributes
ColorCount	_numberOfColors
	The number of colors defined in this palette.
Pixels::ColorDefinition *	_colorDefs
	The logical palette, pointing to an array of _numberOfColors color definitions.
Pixels::PixelColor *	_pixelColors
	The physical palette, pointing to an array of _numberOfColors pixel colors.
bool	_converted
	Tells whether the physical colors (pixel colors) have already been computed from the stored pixel definitions.
Private Member Functions
	Palette (const Palette &source) throw ()
	Copy constructor made private to ensure that it will never be called.
Palette &	operator= (const Palette &source) throw ()
	Assignment operator made private to ensure that it will never be called.

Constructor & Destructor Documentation

Palette::Palette	(	ColorCount	numberOfColors,
		Pixels::ColorDefinition *	colors,
		Pixels::PixelFormat *	format = `0`
	)			throw ( PaletteException )

Constructs a palette from a specified array of color definitions.

Parameters:

format

if specified (non-null), pixel colors are computed thanks to it, otherwise they are still to be converted.

Note:: Takes ownership of the array of color definitions.

Definition at line 46 of file OSDLPalette.cc.

Palette::Palette ( SDL_Palette & palette ) throw ( PaletteException ) [explicit]

Constructs a palette from an already existing SDL palette.

Note:: Takes ownership of the SDL_Palette's color buffer. The SDL_Palette object itself is still to be deallocated by the caller, as if it had no color buffer.

Definition at line 62 of file OSDLPalette.cc.

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

Basic virtual destructor.

Definition at line 70 of file OSDLPalette.cc.

References _colorDefs, and _pixelColors.

OSDL::Video::Palette::Palette ( const Palette & 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

void Palette::load	(	ColorCount	numberOfColors,
		Pixels::ColorDefinition *	colors
	)			throw ( PaletteException ) `[virtual]`

Loads from memory a new palette.

Parameters:

colors

the color array, which should have been allocated like : 'PixelsColorDefinition * colors = new Pixels::ColorDefinition[ numberOfColors ] ;'

Note:: If a palette was already registered, it is deallocated first.
The palette takes ownership of the specified array of colors, and will deallocate them when necessary.

Definition at line 86 of file OSDLPalette.cc.

ColorCount Palette::getNumberOfColors ( ) const throw () [virtual]

Returns the number of colors defined in the palette.

Definition at line 121 of file OSDLPalette.cc.

References _numberOfColors.

const Pixels::PixelColor & Palette::getPixelColorAt ( ColorCount index ) const throw ( PaletteException ) [virtual]

Returns the pixel color of the palette which is located at specified index.

Note:: The pixel color is returned as a 'const' reference.

Exceptions:

PaletteException

if index is out of bounds (superior or equal to getNumberOfColors).

Definition at line 129 of file OSDLPalette.cc.

References OSDL::Video::Pixels::toString().

Pixels::PixelColor * Palette::getPixelColors ( ) const throw () [virtual]

Returns the palette's pointer to pixel colors.

Note:: This method should generally not be used.

Definition at line 144 of file OSDLPalette.cc.

References _pixelColors.

const Pixels::ColorDefinition & Palette::getColorDefinitionAt ( ColorCount index ) const throw ( PaletteException ) [virtual]

Returns the color definition of the palette which is located at specified index.

Note:: The color definition is returned as a 'const' reference.

Exceptions:

PaletteException

if index is out of bounds (superior or equal to getNumberOfColors).

Definition at line 152 of file OSDLPalette.cc.

References OSDL::Video::Pixels::toString().

Pixels::ColorDefinition * Palette::getColorDefinitions ( ) const throw () [virtual]

Returns the palette's color definitions.

Note:: This method should generally not be used.

Definition at line 168 of file OSDLPalette.cc.

References _colorDefs.

void Palette::updatePixelColorsFrom ( Pixels::PixelFormat & format ) throw () [virtual]

Updates (recomputes) internal pixel colors from internal color definitions and specified pixel format.

Note:: The pixel format cannot be 'const' because of SDL back-end.

Definition at line 176 of file OSDLPalette.cc.

References OSDL::Video::Pixels::convertColorDefinitionToPixelColor().

bool Palette::draw	(	Surface &	targetSurface,
		Pixels::ColorDefinition	backgroundColor = `Pixels::White`
	)			throw () `[virtual]`

Draws in specified surface a series of horizontal lines taking its full width, each line being drawn with the color of the palette whose index corresponds to the line ordinate, with specified background underneath (useful to see that surface height and color number do not match).

Returns:: false if and only if surface height was too small to draw lines with all the palette colors.

Note:: Cannot be 'const' since pixel color physical color may have to be recomputed.

Definition at line 205 of file OSDLPalette.cc.

const string Palette::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 237 of file OSDLPalette.cc.

References OSDL::Video::Pixels::toString().

Palette & Palette::CreateGreyScalePalette ( ColorCount numberOfColors = 256 ) throw () [static]

Palette factory, creating palettes with numberOfColors greyscale values, ranging uniformly from pure black to pure white.

Definition at line 282 of file OSDLPalette.cc.

References OSDL::Video::Pixels::Black, and OSDL::Video::Pixels::White.

Palette & Palette::CreateGradationPalette	(	Pixels::ColorDefinition	colorStart,
		Pixels::ColorDefinition	colorEnd,
		ColorCount	numberOfColors = `256`
	)			throw () `[static]`