OGRE  13.6
Object-Oriented Graphics Rendering Engine
Ogre::PixelUtil Class Reference

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

#include <OgrePixelFormat.h>

Static Public Member Functions

static void bulkPixelConversion (const PixelBox &src, const PixelBox &dst)
 Convert pixels from one format to another. More...
 
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 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 uint8 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 according 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 StringgetFormatName (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 uint8 getNumElemBits (PixelFormat format)
 Returns the size in bits of an element of the given pixel format. More...
 
static uint8 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 void packColour (const ColourValue &colour, 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)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. 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 unpackColour (ColourValue &colour, PixelFormat pf, const void *src)
 Unpack a colour value from memory. More...
 
static void unpackColour (ColourValue *colour, PixelFormat pf, const void *src)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 
static void unpackColour (float *r, float *g, float *b, float *a, 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)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...
 

Detailed Description

Some utility functions for packing and unpacking pixel data.

Member Function Documentation

◆ getNumElemBytes()

static uint8 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.

◆ getNumElemBits()

static uint8 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
widthThe width of the area
heightThe height of the area
depthThe depth of the area
formatThe 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.

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

Referenced by Ogre::to_string().

◆ 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 formats as they are special. It can only be true for formats with a fixed element size.

◆ 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 uint8 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
nameThe string of format name
accessibleOnlyIf true, non-accessible format will treat as invalid format, otherwise, all supported format are valid.
caseSensitiveShould be set true if string match should use case sensitivity.
Returns
The format match the format name, or PF_UNKNOWN if is invalid name.

◆ getFormatForBitDepths()

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

Returns the similar format but according with given bit depths.

Parameters
fmtThe original format.
integerBitsPreferred bit depth (pixel bits) for integer pixel format. Available values: 0, 16 and 32, where 0 (the default) means as it is.
floatBitsPreferred 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 
)
inlinestatic

Pack a colour value to memory.

Parameters
colourThe colour
pfPixelformat in which to write the colour
destDestination memory location

References Ogre::ColourValue::a, Ogre::ColourValue::b, Ogre::ColourValue::g, and Ogre::ColourValue::r.

◆ 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,aThe 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)
pfPixelformat in which to write the colour
destDestination 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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ unpackColour() [1/4]

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

Unpack a colour value from memory.

Parameters
colourThe colour is returned here
pfPixelformat in which to read the colour
srcSource memory location

References Ogre::ColourValue::a, Ogre::ColourValue::b, Ogre::ColourValue::g, and Ogre::ColourValue::r.

◆ unpackColour() [2/4]

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References Ogre::ColourValue::a, Ogre::ColourValue::b, Ogre::ColourValue::g, and Ogre::ColourValue::r.

◆ unpackColour() [3/4]

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,aThe four colour channels are returned here
pfPixelformat in which to read the colour
srcSource memory location

◆ unpackColour() [4/4]

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

◆ bulkPixelConversion() [1/2]

static void Ogre::PixelUtil::bulkPixelConversion ( void *  src,
PixelFormat  srcFormat,
void *  dst,
PixelFormat  dstFormat,
unsigned int  count 
)
inlinestatic

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
srcPointer to source region
srcFormatPixel format of source region
dstPointer to destination region
dstFormatPixel format of destination region
countThe number of pixels to convert

◆ 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
srcPixelBox containing the source pixels, pitches and format
dstPixelBox 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
boxPixelBox containing pixels, pitches and format
Remarks
Non consecutive pixel boxes are supported.

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