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

#include <OgrePixelFormat.h>

Static Public Member Functions
static void	bulkPixelConversion (void src, PixelFormat srcFormat, void dst, PixelFormat dstFormat, unsigned int count)
	Convert consecutive pixels from one format to another. More...

static void	bulkPixelConversion (const PixelBox &src, const PixelBox &dst)
	Convert pixels from one format to another. More...

static void	bulkPixelVerticalFlip (const PixelBox &box)
	Flips pixels inplace in vertical direction. More...

static void	getBitDepths (PixelFormat format, int rgba[4])
	Gives the number of bits (RGBA) for a format. More...

static void	getBitMasks (PixelFormat format, uint64 rgba[4])
	Gives the masks for the R, G, B and A component. More...

static void	getBitShifts (PixelFormat format, unsigned char rgba[4])
	Gives the bit shifts for R, G, B and A component. More...

static String	getBNFExpressionOfPixelFormats (bool accessibleOnly=false)
	Gets the BNF expression of the pixel-formats. More...

static size_t	getComponentCount (PixelFormat fmt)
	Returns the component count for a certain pixel format. More...

static PixelComponentType	getComponentType (PixelFormat fmt)
	Returns the component type for a certain pixel format. More...

static unsigned int	getFlags (PixelFormat format)
	Returns the property flags for this pixel format. More...

static PixelFormat	getFormatForBitDepths (PixelFormat fmt, ushort integerBits, ushort floatBits)
	Returns the similar format but acoording with given bit depths. More...

static PixelFormat	getFormatFromName (const String &name, bool accessibleOnly=false, bool caseSensitive=false)
	Gets the format from given name. More...

static const String &	getFormatName (PixelFormat srcformat)
	Gets the name of an image format. More...

static size_t	getMemorySize (uint32 width, uint32 height, uint32 depth, PixelFormat format)
	Returns the size in memory of a region with the given extents and pixel format with consecutive memory layout. More...

static size_t	getNumElemBits (PixelFormat format)
	Returns the size in bits of an element of the given pixel format. More...

static size_t	getNumElemBytes (PixelFormat format)
	Returns the size in bytes of an element of the given pixel format. More...

static bool	hasAlpha (PixelFormat format)
	Shortcut method to determine if the format has an alpha component. More...

static bool	isAccessible (PixelFormat srcformat)
	Returns whether the format can be packed or unpacked with the packColour() and unpackColour() functions. More...

static bool	isCompressed (PixelFormat format)
	Shortcut method to determine if the format is compressed. More...

static bool	isDepth (PixelFormat format)
	Shortcut method to determine if the format is a depth format. More...

static bool	isFloatingPoint (PixelFormat format)
	Shortcut method to determine if the format is floating point. More...

static bool	isInteger (PixelFormat format)
	Shortcut method to determine if the format is integer. More...

static bool	isLuminance (PixelFormat format)
	Shortcut method to determine if the format is a luminance format. More...

static bool	isNativeEndian (PixelFormat format)
	Shortcut method to determine if the format is in native endian format. More...

static bool	isValidExtent (size_t width, size_t height, size_t depth, PixelFormat format)
	Return whether a certain image extent is valid for this image format. More...

static void	packColour (const ColourValue &colour, const PixelFormat pf, void *dest)
	Pack a colour value to memory. More...

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. More...

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. More...

static void	unpackColour (ColourValue colour, PixelFormat pf, const void src)
	Unpack a colour value from memory. More...

static void	unpackColour (uint8 r, uint8 g, uint8 b, uint8 a, PixelFormat pf, const void *src)
	Unpack a colour value from memory. More...

static void	unpackColour (float r, float g, float b, float a, PixelFormat pf, const void *src)
	Unpack a colour value from memory. More...

Detailed Description

Some utility functions for packing and unpacking pixel data.

Member Function Documentation

◆ getNumElemBytes()

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::scale(), and Ogre::LinearResampler_Float32::scale().

◆ getNumElemBits()

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.

◆ getMemorySize()

static size_t Ogre::PixelUtil::getMemorySize	(	uint32	width,
		uint32	height,
		uint32	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 * PixelUtil::getNumElemBytes(format). In the compressed case, this does serious magic.

◆ getFlags()

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, ...

◆ hasAlpha()

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

static

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

◆ isFloatingPoint()

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

static

Shortcut method to determine if the format is floating point.

◆ isInteger()

static bool Ogre::PixelUtil::isInteger ( PixelFormat format )

static

Shortcut method to determine if the format is integer.

◆ isCompressed()

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

static

Shortcut method to determine if the format is compressed.

◆ isDepth()

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

static

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

◆ isNativeEndian()

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

static

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

◆ isLuminance()

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

static

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

◆ isValidExtent()

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

static

Return whether 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.

Deprecated:: do not use

◆ getBitDepths()

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].

◆ getBitMasks()

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

static

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

Note: Only valid for native endian formats

◆ getBitShifts()

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

◆ getFormatName()

static const String& Ogre::PixelUtil::getFormatName ( PixelFormat srcformat )

static

Gets the name of an image format.

◆ isAccessible()

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

static

Returns whether 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

◆ getComponentType()

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.

◆ getComponentCount()

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.

◆ getFormatFromName()

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.

◆ getBNFExpressionOfPixelFormats()

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.

◆ getFormatForBitDepths()

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.

◆ packColour() [1/3]

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().

◆ packColour() [2/3]

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 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

◆ packColour() [3/3]

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

◆ unpackColour() [1/3]

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

◆ unpackColour() [2/3]

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	The red channel is returned here (as byte)
g	The blue channel is returned here (as byte)
b	The green channel is returned here (as byte)
a	The alpha channel 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.

◆ unpackColour() [3/3]

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	The red channel is returned here (as float)
g	The blue channel is returned here (as float)
b	The green channel is returned here (as float)
a	The alpha channel is returned here (as float)
pf	Pixelformat in which to read the colour
src	Source memory location

◆ bulkPixelConversion() [1/2]

static void Ogre::PixelUtil::bulkPixelConversion	(	void *	src,
		PixelFormat	srcFormat,
		void *	dst,
		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

◆ bulkPixelConversion() [2/2]

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.

◆ bulkPixelVerticalFlip()

static void Ogre::PixelUtil::bulkPixelVerticalFlip ( const PixelBox & box )

static

Flips pixels inplace in vertical direction.

Parameters

box	PixelBox containing pixels, pitches and format

Remarks: Non consecutive pixel boxes are supported.

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

OgrePixelFormat.h

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ getNumElemBytes()

◆ getNumElemBits()

◆ getMemorySize()

◆ getFlags()

◆ hasAlpha()

◆ isFloatingPoint()

◆ isInteger()

◆ isCompressed()

◆ isDepth()

◆ isNativeEndian()

◆ isLuminance()

◆ isValidExtent()

◆ getBitDepths()

◆ getBitMasks()

◆ getBitShifts()

◆ getFormatName()

◆ isAccessible()

◆ getComponentType()

◆ getComponentCount()

◆ getFormatFromName()

◆ getBNFExpressionOfPixelFormats()

◆ getFormatForBitDepths()

◆ packColour() [1/3]

◆ packColour() [2/3]

◆ packColour() [3/3]

◆ unpackColour() [1/3]

◆ unpackColour() [2/3]

◆ unpackColour() [3/3]

◆ bulkPixelConversion() [1/2]

◆ bulkPixelConversion() [2/2]

◆ bulkPixelVerticalFlip()