Ogre::PixelUtil Class Reference
[Image]

Some utility functions for packing and unpacking pixel data. More...

#include <OgrePixelFormat.h>

Static Public Member Functions
static size_t	getNumElemBytes (PixelFormat format)
	Returns the size in bytes of an element of the given pixel format.
static size_t	getNumElemBits (PixelFormat format)
	Returns the size in bits of an element of the given pixel format.
static size_t	getMemorySize (size_t width, size_t height, size_t depth, PixelFormat format)
	Returns the size in memory of a region with the given extents and pixel format with consecutive memory layout.
static unsigned int	getFlags (PixelFormat format)
	Returns the property flags for this pixel format.
static bool	hasAlpha (PixelFormat format)
	Shortcut method to determine if the format has an alpha component.
static bool	isFloatingPoint (PixelFormat format)
	Shortcut method to determine if the format is floating point.
static bool	isCompressed (PixelFormat format)
	Shortcut method to determine if the format is compressed.
static bool	isDepth (PixelFormat format)
	Shortcut method to determine if the format is a depth format.
static bool	isNativeEndian (PixelFormat format)
	Shortcut method to determine if the format is in native endian format.
static bool	isLuminance (PixelFormat format)
	Shortcut method to determine if the format is a luminance format.
static bool	isValidExtent (size_t width, size_t height, size_t depth, PixelFormat format)
	Return wether a certain image extent is valid for this image format.
static void	getBitDepths (PixelFormat format, int rgba[4])
	Gives the number of bits (RGBA) for a format.
static void	getBitMasks (PixelFormat format, uint32 rgba[4])
	Gives the masks for the R, G, B and A component.
static void	getBitShifts (PixelFormat format, unsigned char rgba[4])
	Gives the bit shifts for R, G, B and A component.
static String	getFormatName (PixelFormat srcformat)
	Gets the name of an image format.
static bool	isAccessible (PixelFormat srcformat)
	Returns wether the format can be packed or unpacked with the packColour() and unpackColour() functions.
static PixelComponentType	getComponentType (PixelFormat fmt)
	Returns the component type for a certain pixel format.
static size_t	getComponentCount (PixelFormat fmt)
	Returns the component count for a certain pixel format.
static PixelFormat	getFormatFromName (const String &name, bool accessibleOnly=false, bool caseSensitive=false)
	Gets the format from given name.
static String	getBNFExpressionOfPixelFormats (bool accessibleOnly=false)
	Gets the BNF expression of the pixel-formats.
static PixelFormat	getFormatForBitDepths (PixelFormat fmt, ushort integerBits, ushort floatBits)
	Returns the similar format but acoording with given bit depths.
static void	packColour (const ColourValue &colour, const PixelFormat pf, void *dest)
	Pack a colour value to memory.
static void	packColour (const uint8 r, const uint8 g, const uint8 b, const uint8 a, const PixelFormat pf, void *dest)
	Pack a colour value to memory.
static void	packColour (const float r, const float g, const float b, const float a, const PixelFormat pf, void *dest)
	Pack a colour value to memory.
static void	unpackColour (ColourValue colour, PixelFormat pf, const void src)
	Unpack a colour value from memory.
static void	unpackColour (uint8 r, uint8 g, uint8 b, uint8 a, PixelFormat pf, const void *src)
	Unpack a colour value from memory.
static void	unpackColour (float r, float g, float b, float a, PixelFormat pf, const void *src)
	Unpack a colour value from memory.
static void	bulkPixelConversion (void src, PixelFormat srcFormat, void dest, PixelFormat dstFormat, unsigned int count)
	Convert consecutive pixels from one format to another.
static void	bulkPixelConversion (const PixelBox &src, const PixelBox &dst)
	Convert pixels from one format to another.

Detailed Description

Some utility functions for packing and unpacking pixel data.

Definition at line 305 of file OgrePixelFormat.h.

Member Function Documentation

static void Ogre::PixelUtil::bulkPixelConversion	(	const PixelBox &	src,
		const PixelBox &	dst
	)			`[static]`

Convert pixels from one format to another.

No dithering or filtering is being done. Converting from RGB to luminance takes the R channel.

Parameters:

	src	PixelBox containing the source pixels, pitches and format
	dst	PixelBox containing the destination pixels, pitches and format

Remarks:: The source and destination boxes must have the same dimensions. In case the source and destination format match, a plain copy is done.

static void Ogre::PixelUtil::bulkPixelConversion	(	void *	src,
		PixelFormat	srcFormat,
		void *	dest,
		PixelFormat	dstFormat,
		unsigned int	count
	)			`[static]`

Convert consecutive pixels from one format to another.

No dithering or filtering is being done. Converting from RGB to luminance takes the R channel. In case the source and destination format match, just a copy is done.

Parameters:

	src	Pointer to source region
	srcFormat	Pixel format of source region
	dst	Pointer to destination region
	dstFormat	Pixel format of destination region

static void Ogre::PixelUtil::getBitDepths	(	PixelFormat	format,
		int	rgba[4]
	)			`[static]`

Gives the number of bits (RGBA) for a format.

See remarks.

Remarks:: For non-colour formats (dxt, depth) this returns [0,0,0,0].

static void Ogre::PixelUtil::getBitMasks	(	PixelFormat	format,
		uint32	rgba[4]
	)			`[static]`

Gives the masks for the R, G, B and A component.

Note:: Only valid for native endian formats

static void Ogre::PixelUtil::getBitShifts	(	PixelFormat	format,
		unsigned char	rgba[4]
	)			`[static]`

Gives the bit shifts for R, G, B and A component.

Note:: Only valid for native endian formats

static String Ogre::PixelUtil::getBNFExpressionOfPixelFormats ( bool accessibleOnly = false ) [static]

Gets the BNF expression of the pixel-formats.

Note:: The string returned by this function is intended to be used as a BNF expression to work with Compiler2Pass.

Parameters:

accessibleOnly

If true, only accessible pixel format will take into account, otherwise all pixel formats list in PixelFormat enumeration will being returned.

Returns:: A string contains the BNF expression.

static size_t Ogre::PixelUtil::getComponentCount ( PixelFormat fmt ) [static]

Returns the component count for a certain pixel format.

Returns 3(no alpha) or 4 (has alpha) in case there is no clear component type like with compressed formats.

static PixelComponentType Ogre::PixelUtil::getComponentType ( PixelFormat fmt ) [static]

Returns the component type for a certain pixel format.

Returns PCT_BYTE in case there is no clear component type like with compressed formats. This is one of PCT_BYTE, PCT_SHORT, PCT_FLOAT16, PCT_FLOAT32.

static unsigned int Ogre::PixelUtil::getFlags ( PixelFormat format ) [static]

Returns the property flags for this pixel format.

Returns:: A bitfield combination of PFF_HASALPHA, PFF_ISCOMPRESSED, PFF_FLOAT, PFF_DEPTH, PFF_NATIVEENDIAN, PFF_LUMINANCE

Remarks:: This replaces the separate functions for formatHasAlpha, formatIsFloat, ...

static PixelFormat Ogre::PixelUtil::getFormatForBitDepths	(	PixelFormat	fmt,
		ushort	integerBits,
		ushort	floatBits
	)			`[static]`

Returns the similar format but acoording with given bit depths.

Parameters:

	fmt	The original foamt.
	integerBits	Preferred bit depth (pixel bits) for integer pixel format. Available values: 0, 16 and 32, where 0 (the default) means as it is.
	floatBits	Preferred bit depth (channel bits) for float pixel format. Available values: 0, 16 and 32, where 0 (the default) means as it is.

Returns:: The format that similar original format with bit depth according with preferred bit depth, or original format if no conversion occurring.

static PixelFormat Ogre::PixelUtil::getFormatFromName	(	const String &	name,
		bool	accessibleOnly = `false`,
		bool	caseSensitive = `false`
	)			`[static]`

Gets the format from given name.

Parameters:

	name	The string of format name
	accessibleOnly	If true, non-accessible format will treat as invalid format, otherwise, all supported format are valid.
	caseSensitive	Should be set true if string match should use case sensitivity.

Returns:: The format match the format name, or PF_UNKNOWN if is invalid name.

static String Ogre::PixelUtil::getFormatName ( PixelFormat srcformat ) [static]

Gets the name of an image format.

static size_t Ogre::PixelUtil::getMemorySize	(	size_t	width,
		size_t	height,
		size_t	depth,
		PixelFormat	format
	)			`[static]`

Returns the size in memory of a region with the given extents and pixel format with consecutive memory layout.

Parameters:

	width	The width of the area
	height	The height of the area
	depth	The depth of the area
	format	The format of the area

Returns:: The size in bytes

Remarks:: In case that the format is non-compressed, this simply returns width*height*depth*PixelUtilgetNumElemBytes(format). In the compressed case, this does serious magic.

static size_t Ogre::PixelUtil::getNumElemBits ( PixelFormat format ) [static]

Returns the size in bits of an element of the given pixel format.

Returns:: The size in bits of an element. See Remarks.

Remarks:: Passing PF_UNKNOWN will result in returning a size of 0 bits.

static size_t Ogre::PixelUtil::getNumElemBytes ( PixelFormat format ) [static]

Returns the size in bytes of an element of the given pixel format.

Returns:: The size in bytes of an element. See Remarks.

Remarks:: Passing PF_UNKNOWN will result in returning a size of 0 bytes.

Referenced by Ogre::LinearResampler_Float32::scale(), and Ogre::LinearResampler::scale().

static bool Ogre::PixelUtil::hasAlpha ( PixelFormat format ) [static]

Shortcut method to determine if the format has an alpha component.

static bool Ogre::PixelUtil::isAccessible ( PixelFormat srcformat ) [static]

Returns wether the format can be packed or unpacked with the packColour() and unpackColour() functions.

This is generally not true for compressed and depth formats as they are special. It can only be true for formats with a fixed element size.

Returns:: true if yes, otherwise false

static bool Ogre::PixelUtil::isCompressed ( PixelFormat format ) [static]

Shortcut method to determine if the format is compressed.

static bool Ogre::PixelUtil::isDepth ( PixelFormat format ) [static]

Shortcut method to determine if the format is a depth format.

static bool Ogre::PixelUtil::isFloatingPoint ( PixelFormat format ) [static]

Shortcut method to determine if the format is floating point.

static bool Ogre::PixelUtil::isLuminance ( PixelFormat format ) [static]

Shortcut method to determine if the format is a luminance format.

static bool Ogre::PixelUtil::isNativeEndian ( PixelFormat format ) [static]

Shortcut method to determine if the format is in native endian format.

static bool Ogre::PixelUtil::isValidExtent	(	size_t	width,
		size_t	height,
		size_t	depth,
		PixelFormat	format
	)			`[static]`

Return wether a certain image extent is valid for this image format.

Parameters:

	width	The width of the area
	height	The height of the area
	depth	The depth of the area
	format	The format of the area

Remarks:: For non-compressed formats, this is always true. For DXT formats, only sizes with a width and height multiple of 4 and depth 1 are allowed.

static void Ogre::PixelUtil::packColour	(	const float	r,
		const float	g,
		const float	b,
		const float	a,
		const PixelFormat	pf,
		void *	dest
	)			`[static]`

Pack a colour value to memory.

Parameters:

	r,g,b,a	The four colour components, range 0.0f to 1.0f (an exception to this case exists for floating point pixel formats, which don't clamp to 0.0f..1.0f)
	pf	Pixelformat in which to write the colour
	dest	Destination memory location

static void Ogre::PixelUtil::packColour	(	const uint8	r,
		const uint8	g,
		const uint8	b,
		const uint8	a,
		const PixelFormat	pf,
		void *	dest
	)			`[static]`

Pack a colour value to memory.

Parameters:

	r,g,b,a	The four colour components, range 0x00 to 0xFF
	pf	Pixelformat in which to write the colour
	dest	Destination memory location

static void Ogre::PixelUtil::packColour	(	const ColourValue &	colour,
		const PixelFormat	pf,
		void *	dest
	)			`[static]`

Pack a colour value to memory.

Parameters:

	colour	The colour
	pf	Pixelformat in which to write the colour
	dest	Destination memory location

Referenced by Ogre::LinearResampler::scale().

static void Ogre::PixelUtil::unpackColour	(	float *	r,
		float *	g,
		float *	b,
		float *	a,
		PixelFormat	pf,
		const void *	src
	)			`[static]`

Unpack a colour value from memory.

Parameters:

	r,g,b,a	The colour is returned here (as float)
	pf	Pixelformat in which to read the colour
	src	Source memory location

static void Ogre::PixelUtil::unpackColour	(	uint8 *	r,
		uint8 *	g,
		uint8 *	b,
		uint8 *	a,
		PixelFormat	pf,
		const void *	src
	)			`[static]`

Unpack a colour value from memory.

Parameters:

	r,g,b,a	The colour is returned here (as byte)
	pf	Pixelformat in which to read the colour
	src	Source memory location

Remarks:: This function returns the colour components in 8 bit precision, this will lose precision when coming from PF_A2R10G10B10 or floating point formats.

static void Ogre::PixelUtil::unpackColour	(	ColourValue *	colour,
		PixelFormat	pf,
		const void *	src
	)			`[static]`

Unpack a colour value from memory.

Parameters:

	colour	The colour is returned here
	pf	Pixelformat in which to read the colour
	src	Source memory location

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

OgrePixelFormat.h

Ogre::PixelUtil Class Reference [Image]

Static Public Member Functions

Detailed Description

Member Function Documentation

Ogre::PixelUtil Class Reference
[Image]