OSDL::Video::Palette Class Reference

Describes a palette, for example for color-indexed modes. More...

#include <OSDLPalette.h>

Public Member Functions
	Palette (ColorCount numberOfColors, Pixels::ColorDefinition colors=0, Pixels::PixelFormat format=0)
	Constructs a palette from a specified array of color definitions.
	Palette (const std::string &paletteFilename)
	Creates a new palette from specified file, whose format is expected to be the .osdl.palette, which implies an OSDL palette header followed by the palette itself, with 24 bits per color (8 bits per color component), in RGB order.
	Palette (const LowLevelPalette &palette)
	Constructs a palette from an already existing SDL palette.
virtual	~Palette () throw ()
	Basic virtual destructor.
virtual void	load (ColorCount numberOfColors, Pixels::ColorDefinition *colors)
	Loads new color definitions from memory .
virtual ColorCount	getNumberOfColors () const
	Returns the number of colors defined in the palette (including any colorkey).
virtual const Pixels::PixelColor &	getPixelColorAt (ColorCount index) const
	Returns the pixel color of the palette which is located at specified index.
virtual Pixels::PixelColor *	getPixelColors () const
	Returns the palette's pointer to pixel colors.
virtual const Pixels::ColorDefinition &	getColorDefinitionAt (ColorCount index) const
	Returns the color definition of the palette which is located at specified index.
virtual void	setColorDefinitionAt (ColorCount targetIndex, const Pixels::ColorDefinition &newColorDefinition)
	Sets the specified color definition at specified index of the palette (overwrites prior definition).
virtual void	setColorDefinitionAt (ColorCount targetIndex, Pixels::ColorElement red, Pixels::ColorElement green, Pixels::ColorElement blue, Pixels::ColorElement alpha=Pixels::AlphaOpaque)
	Sets the specified color definition at specified index of the palette (overwrites prior definition).
virtual Pixels::ColorDefinition *	getColorDefinitions () const
	Returns the palette's color definitions.
virtual bool	hasColorKey () const
	Returns whether this palette has a colorkey registered.
virtual ColorCount	getColorKeyIndex () const
	Returns the index of the colorkey.
virtual void	setColorKeyIndex (ColorCount colorkeyIndex)
	Sets the specified index as a colorkey.
virtual void	updatePixelColorsFrom (const Pixels::PixelFormat &format)
	Updates (recomputes) internal pixel colors from internal color definitions and specified pixel format.
virtual void	quantize (Pixels::ColorElement quantizeMaxCoordinate, bool scaleUp=false)
virtual void	correctGamma (Pixels::GammaFactor gamma)
virtual ColorCount	getClosestColorIndexTo (const Pixels::ColorDefinition &color) const
	Returns the index of the color definition in the palette that matches the most closely to specified color.
virtual bool	draw (Surface &targetSurface, const Pixels::ColorDefinition &backgroundColor=Pixels::White)
	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 bool	hasDuplicates (bool useAlpha=false) const
	Tells whether the current palette has strictly identical color definitions.
virtual void	save (const std::string &filename, bool encoded=false) const
	Saves current palette to specified file.
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 Palette &	CreateGreyScalePalette (ColorCount numberOfColors=256)
	Palette factory, creating palettes with numberOfColors greyscale values, ranging uniformly from pure black to pure white.
static Palette &	CreateGradationPalette (const Pixels::ColorDefinition &colorStart, const Pixels::ColorDefinition &colorEnd, ColorCount numberOfColors=256)
	Palette factory, creating palettes with numberOfColors values, with continous tone interpolation from colorStart to colorEnd.
static Palette &	CreateMasterPalette (bool addColorkey=true)
	Palette factory, creating a colorkey-less 255 or colorkey-enabled 256 color master palette suitable for best-fit color-reduction of all kinds of images, notably animation frames.
Static Public Attributes
static const Ceylan::Flags	Logical = 0x01
	The flag used to designate logical palette.
static const Ceylan::Flags	Physical = 0x02
	The flag used to designate physical palette.
Protected Member Functions
virtual void	invalidatePixelColors ()
	Invalidates any already computed pixel colors.
Static Protected Member Functions
static Pixels::ColorElement	QuantizeComponent (Pixels::ColorElement component, Pixels::ColorElement newMaxCoordinate=31)
static Pixels::ColorElement	CorrectGammaComponent (Pixels::ColorElement component, Pixels::GammaFactor gamma)
	Corrects gamma-wise an individual color component.
static ColorDistance	GetDistance (const Pixels::ColorDefinition &firstColor, const Pixels::ColorDefinition &secondColor)
	Returns the perceived distance of the human eye between the two specified color definitions.
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.
bool	_ownsColorDefinition
	Tells whether this palette owns any color definitions it uses.
Private Member Functions
	Palette (const Palette &source)
	Copy constructor made private to ensure that it will never be called.
Palette &	operator= (const Palette &source)
	Assignment operator made private to ensure that it will never be called.
Private Attributes
bool	_hasColorkey
	Tells whether this palette has a registered color key.
ColorCount	_colorKeyIndex
	Index in palette of the used colorkey (if any), usually #0.

Detailed Description

Describes a palette, for example for color-indexed modes.

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

Palettes can be used too for special effects, even in true color modes.

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 uses two palettes, a logical one (for color definitions) and a physical one (for pixel colors).

A palette has getNumberOfColors() colors, ranging from 0 to getNumberOfColors()-1.

A color index can be set as being the colorkey.

Definition at line 164 of file OSDLPalette.h.

Constructor & Destructor Documentation

OSDL::Video::Palette::Palette	(	ColorCount	numberOfColors,
		Pixels::ColorDefinition *	colors = `0`,
		Pixels::PixelFormat *	format = `0`
	)			`[explicit]`

Constructs a palette from a specified array of color definitions.

No colorkey is set.

Parameters:

	numberOfColors	the number of color for this palette.
	colors	pointer to an array of numberOfColors color definitions. This palette takes ownership of the array. If a null pointer is specified, then the palette will create its own array of numberOfColors and set all colors to full black, i.e. (0,0,0,255) in the RGBA colorspace.
	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.

Referenced by CreateMasterPalette().

Palette::Palette ( const std::string & paletteFilename ) [explicit]

Creates a new palette from specified file, whose format is expected to be the .osdl.palette, which implies an OSDL palette header followed by the palette itself, with 24 bits per color (8 bits per color component), in RGB order.

A colorkey index may be specified in the file.

Parameters:

paletteFilename

the name of the file containing the palette in '.osdl.palette' format.

See also:: the Palette::save for the corresponding '.osdl.palette' file format.

Note:: No alpha information is stored on file, and loaded colors will all be set to fully opaque (AlphaOpaque).

Exceptions:

PaletteException

if the operation failed.

Definition at line 155 of file OSDLPalette.cc.

References OSDL::Video::Pixels::AlphaOpaque, OSDL::DescribeFileTag(), load(), OSDL::PaletteTag, setColorKeyIndex(), and OSDL::Video::Pixels::toString().

Palette::Palette ( const LowLevelPalette & palette ) [explicit]

Constructs a palette from an already existing SDL palette.

No colorkey is set.

Note:: Does not take ownership of the LowLevelPalette's color buffer.

Definition at line 128 of file OSDLPalette.cc.

References load().

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

Basic virtual destructor.

Definition at line 249 of file OSDLPalette.cc.

References _colorDefs, _ownsColorDefinition, and invalidatePixelColors().

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

virtual void OSDL::Video::Palette::correctGamma ( Pixels::GammaFactor gamma ) [virtual]

static Pixels::ColorElement OSDL::Video::Palette::CorrectGammaComponent	(	Pixels::ColorElement	component,
		Pixels::GammaFactor	gamma
	)			`[static, protected]`

Corrects gamma-wise an individual color component.

Parameters:

	component	the component to gamma-correct.
	gamma	the gamma correction factor to apply.

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

Palette factory, creating palettes with numberOfColors values, with continous tone interpolation from colorStart to colorEnd.

Note:: Alpha coordinates are interpolated as well.

Referenced by CreateGreyScalePalette().

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

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

Definition at line 816 of file OSDLPalette.cc.

References OSDL::Video::Pixels::Black, CreateGradationPalette(), and OSDL::Video::Pixels::White.

Palette & Palette::CreateMasterPalette ( bool addColorkey = true ) [static]

Palette factory, creating a colorkey-less 255 or colorkey-enabled 256 color master palette suitable for best-fit color-reduction of all kinds of images, notably animation frames.

Parameters:

addColorkey

if true, the default colorkey will be inserted at palette index #0, and registered as such. There will be then 256 colors in the palette. Otherwise, if false, only 255 colors (not 256) will be defined here, to leave one index for a future colorkey.

See also:: http://en.wikipedia.org/wiki/: List_of_software_palettes#6-8-5_levels_RGB for the base colors of this palette.

Definition at line 887 of file OSDLPalette.cc.

References OSDL::Video::Pixels::AlphaOpaque, OSDL::Video::Pixels::DefaultColorkey, Palette(), setColorDefinitionAt(), and setColorKeyIndex().

virtual bool OSDL::Video::Palette::draw	(	Surface &	targetSurface,
		const Pixels::ColorDefinition &	backgroundColor = `Pixels::White`
	)			`[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.; The colorkey will be drawn as other colors.

virtual ColorCount OSDL::Video::Palette::getClosestColorIndexTo ( const Pixels::ColorDefinition & color ) const [virtual]

Returns the index of the color definition in the palette that matches the most closely to specified color.

Exceptions:

PaletteException

if the palette does not have at least one color.

Note:: Uses GetDistance as a metric.; If a colorkey is defined, it will not be taken into account as a possible color match.

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

const Pixels::ColorDefinition & Palette::getColorDefinitionAt ( ColorCount index ) const [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 347 of file OSDLPalette.cc.

References _colorDefs, _numberOfColors, and OSDL::Video::Pixels::toString().

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

Returns the palette's color definitions.

Note:: This method should generally not be used, and is "pseudo-const".

Definition at line 404 of file OSDLPalette.cc.

References _colorDefs.

ColorCount Palette::getColorKeyIndex ( ) const [virtual]

Returns the index of the colorkey.

Exceptions:

PaletteException

if no colorkey is registered.

See also:: hasColorKey

Definition at line 422 of file OSDLPalette.cc.

References _colorKeyIndex, and _hasColorkey.

Referenced by OSDL::Video::Surface::createColorReducedSurfaceFor(), and save().

ColorDistance Palette::GetDistance	(	const Pixels::ColorDefinition &	firstColor,
		const Pixels::ColorDefinition &	secondColor
	)			`[static, protected]`

Returns the perceived distance of the human eye between the two specified color definitions.

An advanced weighted Euclidean distance is used, see the lost-cost approximation in http://www.compuphase.com/cmetric.htm.

Note:: The alpha coordinate is ignored for the distance computation.

Definition at line 1053 of file OSDLPalette.cc.

ColorCount Palette::getNumberOfColors ( ) const [virtual]

Returns the number of colors defined in the palette (including any colorkey).

Definition at line 314 of file OSDLPalette.cc.

References _numberOfColors.

const Pixels::PixelColor & Palette::getPixelColorAt ( ColorCount index ) const [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 323 of file OSDLPalette.cc.

References _numberOfColors, _pixelColors, and OSDL::Video::Pixels::toString().

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

Returns the palette's pointer to pixel colors.

Note:: This method should generally not be used, and is "pseudo-const".

Definition at line 338 of file OSDLPalette.cc.

References _pixelColors.

bool Palette::hasColorKey ( ) const [virtual]

Returns whether this palette has a colorkey registered.

Definition at line 413 of file OSDLPalette.cc.

References _hasColorkey.

Referenced by save().

bool Palette::hasDuplicates ( bool useAlpha = false ) const [virtual]

Tells whether the current palette has strictly identical color definitions.

Parameters:

useAlpha

tells whether the alpha coordinate is tested too for equality.

Returns:: true iff there is at least a duplicated color.

Note:: If a colorkey is defined, it will not be taken into account for a possible color collision.

Definition at line 638 of file OSDLPalette.cc.

References _colorDefs, _colorKeyIndex, _hasColorkey, OSDL::Video::Pixels::areEqual(), and OSDL::Video::Pixels::toString().

void Palette::invalidatePixelColors ( ) [protected, virtual]

Invalidates any already computed pixel colors.

Definition at line 1007 of file OSDLPalette.cc.

References _pixelColors.

Referenced by quantize(), and ~Palette().

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

Loads new color definitions from memory .

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.; This palette takes ownership of the specified array of colors, and will deallocate them when necessary.

Referenced by Palette().

Palette& OSDL::Video::Palette::operator= ( const Palette & 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 Palette::quantize	(	Pixels::ColorElement	quantizeMaxCoordinate,
		bool	scaleUp = `false`
	)			`[virtual]`

Definition at line 480 of file OSDLPalette.cc.

References _colorDefs, invalidatePixelColors(), and QuantizeComponent().

static Pixels::ColorElement OSDL::Video::Palette::QuantizeComponent	(	Pixels::ColorElement	component,
		Pixels::ColorElement	newMaxCoordinate = `31`
	)			`[static, protected]`

Referenced by quantize(), and save().

void Palette::save	(	const std::string &	filename,
		bool	encoded = `false`
	)			const `[virtual]`

Saves current palette to specified file.

All color definitions will be saved in palette order.

Alpha coordinates will be ignored (not taken into account, not saved).

A palette can be saved in the osdl.palette format (a.k.a unencoded format), or in .pal format (a.k.a. encoded format.

With the osdl.palette format, a palette is made of a header, storing:

the OSDL tag for palette
in next byte: 1 if a colorkey is defined, 0 otherwise
if there is a color key, in next sizeof(ColorCount) bytes the index of the color key is specified (otherwise the header contains only the first byte). After the header, the content of the palette itself is stored, with 8 bits per color component, in RGB order (thus 24 bits per color, and no alpha coordinate stored). The extension of files respecting this format is preferably '.osdl.palette'.

With the encoded format, quantized colors will be written, i.e. each color definition will be packed into 16 bits only (first bit set to 1, then 5 bits per quantized color component, in BGR order). The fact that a given index corresponds to a colorkey will not be stored in this encoded format. The encoded format is suitable for the Nintendo GBA and DS consoles. The extension of files respecting this format is preferably '.pal'.

Parameters:

	filename	the name of the palette file to create (respecting recommended extensions is encouraged).
	encoded	tells whether the palette will be written in encoded format (if true), or in .osdl.palette format (if false).

Exceptions:

PaletteException

if the operation failed.

Definition at line 677 of file OSDLPalette.cc.

References _colorDefs, getColorKeyIndex(), hasColorKey(), OSDL::PaletteTag, and QuantizeComponent().

virtual void OSDL::Video::Palette::setColorDefinitionAt	(	ColorCount	targetIndex,
		Pixels::ColorElement	red,
		Pixels::ColorElement	green,
		Pixels::ColorElement	blue,
		Pixels::ColorElement	alpha = `Pixels::AlphaOpaque`
	)			`[virtual]`