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

#include <OgrePixelFormat.h>

Static Public Member Functions
static void	bulkCompressedSubregion (const PixelBox &src, const PixelBox &dst, const Box &dstRegion)
	Emplaces the binary compressed data from src into a subregion of dst.

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

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

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

static size_t	calculateSizeBytes (uint32 width, uint32 height, uint32 depth, uint32 slices, PixelFormat format, uint8 numMipmaps)
	WARNING: numMipmaps includes the mip 0.

static void	convertForNormalMapping (const PixelBox &src, const PixelBox &dst)
	Converts the input source to either PF_R8G8_SNORM or PF_BYTE_LA.

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

static void	getBitMasks (PixelFormat format, uint64 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	getBNFExpressionOfPixelFormats (bool accessibleOnly=false)
	Gets the BNF expression of the pixel-formats.

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

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

static uint32	getCompressedBlockHeight (PixelFormat format, bool apiStrict=true)
	@See getCompressedBlockWidth

static uint32	getCompressedBlockWidth (PixelFormat format, bool apiStrict=true)
	Returns the minimum width for block compressed schemes.

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

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

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

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

static uint8	getMaxMipmapCount (uint32 maxResolution)
	Returns the maximum number of mipmaps given the resolution e.g.

static uint8	getMaxMipmapCount (uint32 width, uint32 height)

static uint8	getMaxMipmapCount (uint32 width, uint32 height, uint32 depth)

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.

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

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

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

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

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	isFloatingPoint (PixelFormat format)
	Shortcut method to determine if the format is floating point.

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

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

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

static bool	isSigned (PixelFormat format)
	Shortcut method to determine if the format is signed.

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.

static void	packColour (const ColourValue &colour, 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	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	unpackColour (ColourValue colour, 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	unpackColour (uint8 r, uint8 g, uint8 b, uint8 a, PixelFormat pf, const void *src)
	Unpack a colour value from memory.

Detailed Description

Some utility functions for packing and unpacking pixel data.

Member Function Documentation

◆ bulkCompressedSubregion()

static void Ogre::PixelUtil::bulkCompressedSubregion	(	const PixelBox &	src,
		const PixelBox &	dst,
		const Box &	dstRegion
	)

static

Emplaces the binary compressed data from src into a subregion of dst.

Parameters

src	PixelBox containing the source pixels, pitches and format. Data must be consecutive
dst	PixelBox containing the destination pixels, pitches and format. Data must be consecutive
dstRegion	The region on dst where src will be emplaced. dstRegion's resolution must match that of src. dstRegion must be within dst's bounds.

Remarks: The source and destination must have the same the same format.

: Each compression format may enforce different requirements. Most notably the subregions' bounds must be aligned to a certain boundary (usually to multiples of 4). If these requirements aren't met, an exception will be thrown.

: Some formats (i.e. PVRTC) don't support subregions at all, and thus an exception will be thrown.

: @See getCompressedBlockWidth

◆ bulkPixelConversion() [1/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.

◆ bulkPixelConversion() [2/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

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

◆ calculateSizeBytes()

static size_t Ogre::PixelUtil::calculateSizeBytes	(	uint32	width,
		uint32	height,
		uint32	depth,
		uint32	slices,
		PixelFormat	format,
		uint8	numMipmaps
	)

static

WARNING: numMipmaps includes the mip 0.

That means numMipmaps > 0, and that you should use texture->getNumMipmaps + 1u

◆ convertForNormalMapping()

static void Ogre::PixelUtil::convertForNormalMapping	(	const PixelBox &	src,
		const PixelBox &	dst
	)

static

Converts the input source to either PF_R8G8_SNORM or PF_BYTE_LA.

dst must be one of either formats.

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.

◆ 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

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

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

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

◆ getCompressedBlockHeight()

static uint32 Ogre::PixelUtil::getCompressedBlockHeight	(	PixelFormat	format,
		bool	apiStrict = `true`
	)

static

@See getCompressedBlockWidth

◆ getCompressedBlockWidth()

static uint32 Ogre::PixelUtil::getCompressedBlockWidth	(	PixelFormat	format,
		bool	apiStrict = `true`
	)

static

Returns the minimum width for block compressed schemes.

ie. DXT1 compresses in blocks of 4x4 pixels. A texture with a width of 2 is just padded to 4. When building UV atlases composed of already compressed data being stitched together, the block size is very important to know as the resolution of the individual textures must be a multiple of this size.

Remarks: If the format is not compressed, returns 1.

: The function can return a value of 0 (as happens with PVRTC & ETC1 compression); this is because although they may compress in blocks (i.e. PVRTC uses a 4x4 or 8x4 block), this information is useless as the compression scheme doesn't have isolated blocks (modifying a single pixel can change the binary data of the entire stream) making it useless for subimage sampling or creating UV atlas.

Parameters

format	The format to query for. Can be compressed or not.
apiStrict	When true, obeys the rules of most APIs (i.e. ETC1 can't update subregions according to GLES specs). When false, becomes more practical if manipulating by hand (i.e. ETC1's subregions can be updated just fine by @bulkCompressedSubregion)

Returns: The width of compression block, in pixels. Can be 0 (see remarks). If format is not compressed, returns 1.

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

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

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

◆ getFormatName()

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

static

Gets the name of an image format.

◆ getMaxMipmapCount() [1/3]

static uint8 Ogre::PixelUtil::getMaxMipmapCount ( uint32 maxResolution )

static

Returns the maximum number of mipmaps given the resolution e.g.

at 4x4 there's 2 mipmaps. At 1x1 there's 0 mipmaps.

Returns: Mip count.

◆ getMaxMipmapCount() [2/3]

static uint8 Ogre::PixelUtil::getMaxMipmapCount	(	uint32	width,
		uint32	height
	)

static

◆ getMaxMipmapCount() [3/3]

static uint8 Ogre::PixelUtil::getMaxMipmapCount	(	uint32	width,
		uint32	height,
		uint32	depth
	)

static

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

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

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

◆ hasAlpha()

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

static

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

◆ 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

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

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

◆ isLuminance()

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

static

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

◆ isNativeEndian()

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

static

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

◆ isSigned()

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

static

Shortcut method to determine if the format is signed.

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

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

◆ packColour() [3/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

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

◆ unpackColour() [3/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.

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

OgrePixelFormat.h

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ bulkCompressedSubregion()

◆ bulkPixelConversion() [1/2]

◆ bulkPixelConversion() [2/2]

◆ bulkPixelVerticalFlip()

◆ calculateSizeBytes()

◆ convertForNormalMapping()

◆ getBitDepths()

◆ getBitMasks()

◆ getBitShifts()

◆ getBNFExpressionOfPixelFormats()

◆ getComponentCount()

◆ getComponentType()

◆ getCompressedBlockHeight()

◆ getCompressedBlockWidth()

◆ getFlags()

◆ getFormatForBitDepths()

◆ getFormatFromName()

◆ getFormatName()

◆ getMaxMipmapCount() [1/3]

◆ getMaxMipmapCount() [2/3]

◆ getMaxMipmapCount() [3/3]

◆ getMemorySize()

◆ getNumElemBits()

◆ getNumElemBytes()

◆ hasAlpha()

◆ isAccessible()

◆ isCompressed()

◆ isDepth()

◆ isFloatingPoint()

◆ isInteger()

◆ isLuminance()

◆ isNativeEndian()

◆ isSigned()

◆ isValidExtent()

◆ packColour() [1/3]

◆ packColour() [2/3]

◆ packColour() [3/3]

◆ unpackColour() [1/3]

◆ unpackColour() [2/3]

◆ unpackColour() [3/3]