OGRE: Ogre::PixelUtil Class Reference

| OGRE 2.2.4 Object-Oriented Graphics Rendering Engine

Static Public Member Functions | List of all members
Ogre::PixelUtil Class Reference
Core » Image

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. More...
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 size_t | calculateSizeBytes (uint32 width, uint32 height, uint32 depth, uint32 slices, PixelFormat format, uint8 numMipmaps)
| WARNING: numMipmaps includes the mip 0. More...
static void | convertForNormalMapping (const PixelBox &src, const PixelBox &dst)
| Converts the input source to either PF_R8G8_SNORM or PF_BYTE_LA. 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 uint32 | getCompressedBlockHeight (PixelFormat format, bool apiStrict=true)
| @See getCompressedBlockWidth More...
static uint32 | getCompressedBlockWidth (PixelFormat format, bool apiStrict=true)
| Returns the minimum width for block compressed schemes. 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 String | getFormatName (PixelFormat srcformat)
| Gets the name of an image format. More...
static uint8 | getMaxMipmapCount (uint32 maxResolution)
| Returns the maximum number of mipmaps given the resolution e.g. More...
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. 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 | isSigned (PixelFormat format)
| Shortcut method to determine if the format is signed. 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 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 | 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 (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)
| Unpack a colour value from memory. More...

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

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

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