# Ogre::PixelUtil Class Reference
[Image]

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

`#include <OgrePixelFormat.h>`

List of all members.

## 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 287 of file OgrePixelFormat.h.

## Member Function Documentation

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::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::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 intented to use 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 seperate 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 convertion occuring.

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

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.

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

- OgrePixelFormat.h

Copyright © 2008 Torus Knot Software Ltd
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Last modified Wed Nov 3 2010 19:24:58