This documents an old version of bs::framework. Click here to see the latest release.
PixelUtil Class Reference

Description

Utility methods for converting and managing pixel data and formats.

Static methods

static UINT32 getNumElemBytes (PixelFormat format)
 Returns the size of a single pixel of the provided pixel format, in bytes. More...
 
static UINT32 getNumElemBits (PixelFormat format)
 Returns the size of a single pixel of the provided pixel format, in bits. More...
 
static UINT32 getMemorySize (UINT32 width, UINT32 height, UINT32 depth, PixelFormat format)
 Returns the size of the memory region required to hold pixels of the provided size ana format. More...
 
static void getSizeForMipLevel (UINT32 width, UINT32 height, UINT32 depth, UINT32 mipLevel, UINT32 &mipWidth, UINT32 &mipHeight, UINT32 &mipDepth)
 Calculates the size of a mip level of a texture with the provided size. More...
 
static void getPitch (UINT32 width, UINT32 height, UINT32 depth, PixelFormat format, UINT32 &rowPitch, UINT32 &depthPitch)
 Calculates row and depth pitch for a texture surface of the specified size and format. More...
 
static UINT32 getFlags (PixelFormat format)
 Returns property flags for this pixel format. More...
 
static bool hasAlpha (PixelFormat format)
 Checks if the provided pixel format has an alpha channel. More...
 
static bool isFloatingPoint (PixelFormat format)
 Checks is the provided pixel format a floating point format. More...
 
static bool isCompressed (PixelFormat format)
 Checks is the provided pixel format compressed. More...
 
static bool isDepth (PixelFormat format)
 Checks is the provided pixel format a depth/stencil buffer format. More...
 
static bool isNormalized (PixelFormat format)
 Checks does the provided format store data in normalized range. More...
 
static bool checkFormat (PixelFormat &format, TextureType texType, int usage)
 Checks is the provided format valid for the texture type and usage. More...
 
static bool isValidExtent (UINT32 width, UINT32 height, UINT32 depth, PixelFormat format)
 Checks are the provided dimensions valid for the specified pixel format. More...
 
static void getBitDepths (PixelFormat format, int(&rgba)[4])
 Returns the number of bits per each element in the provided pixel format. More...
 
static void getBitMasks (PixelFormat format, UINT32(&rgba)[4])
 Returns bit masks that determine in what bit range is each channel stored. More...
 
static void getBitShifts (PixelFormat format, UINT8(&rgba)[4])
 Returns number of bits you need to shift a pixel element in order to move it to the start of the data type. More...
 
static String getFormatName (PixelFormat srcformat)
 Returns the name of the pixel format. More...
 
static bool isAccessible (PixelFormat srcformat)
 Returns true if the pixel data in the format can be directly accessed and read. More...
 
static PixelComponentType getElementType (PixelFormat format)
 Returns the type of an individual pixel element in the provided format. More...
 
static UINT32 getNumElements (PixelFormat format)
 Returns the number of pixel elements in the provided format. More...
 
static UINT32 getMaxMipmaps (UINT32 width, UINT32 height, UINT32 depth, PixelFormat format)
 Returns the maximum number of mip maps that can be generated until we reach the minimum size possible. More...
 
static void packColor (const Color &color, PixelFormat format, void *dest)
 Writes the color to the provided memory location. More...
 
static void packColor (UINT8 r, UINT8 g, UINT8 b, UINT8 a, PixelFormat format, void *dest)
 Writes the color to the provided memory location. More...
 
static void packColor (float r, float g, float b, float a, const PixelFormat format, void *dest)
 Writes the color to the provided memory location. More...
 
static void unpackColor (Color *color, PixelFormat format, const void *src)
 Reads the color from the provided memory location and stores it into the provided color object. More...
 
static void unpackColor (UINT8 *r, UINT8 *g, UINT8 *b, UINT8 *a, PixelFormat format, const void *src)
 Reads the color from the provided memory location and stores it into the provided color elements, as bytes clamped to [0, 255] range.
 
static void unpackColor (float *r, float *g, float *b, float *a, PixelFormat format, const void *src)
 Reads the color from the provided memory location and stores it into the provided color elements. More...
 
static void packDepth (float depth, const PixelFormat format, void *dest)
 Writes a depth value to the provided memory location. More...
 
static float unpackDepth (PixelFormat format, void *src)
 Reads the depth from the provided memory location. More...
 
static void bulkPixelConversion (const PixelData &src, PixelData &dst)
 Converts pixels from one format to another. More...
 
static void flipComponentOrder (PixelData &data)
 Flips the order of components in each individual pixel. More...
 
static void compress (const PixelData &src, PixelData &dst, const CompressionOptions &options)
 Compresses the provided data using the specified compression options. More...
 
static Vector< SPtr< PixelData > > genMipmaps (const PixelData &src, const MipMapGenOptions &options)
 Generates mip-maps from the provided source data using the specified compression options. More...
 
static void scale (const PixelData &src, PixelData &dst, Filter filter=FILTER_LINEAR)
 Scales pixel data in the source buffer and stores the scaled data in the destination buffer. More...
 
static void mirror (PixelData &pixelData, MirrorMode mode)
 Mirrors the contents of the provided object along the X, Y and/or Z axes. More...
 
static void copy (const PixelData &src, PixelData &dst, UINT32 offsetX=0, UINT32 offsetY=0, UINT32 offsetZ=0)
 Copies the contents of the src buffer into the dst buffer. More...
 
static Color linearToSRGB (const Color &color)
 Converts a color in linear space to a color in sRGB space. More...
 
static Color SRGBToLinear (const Color &color)
 Converts a color in sRGB space to a color in linear space. More...
 
static void linearToSRGB (PixelData &pixelData)
 Converts pixel data in linear space to one in sRGB space. More...
 
static void SRGBToLinear (PixelData &pixelData)
 Converts pixel data in sRGB space to one in linear space. More...
 

Public Types

enum  Filter { FILTER_NEAREST, FILTER_LINEAR }
 Filtering types to use when scaling images. More...
 

Method documentation

◆ bulkPixelConversion()

static void bulkPixelConversion ( const PixelData src,
PixelData dst 
)
static

Converts pixels from one format to another.

Provided pixel data objects must have previously allocated buffers of adequate size and their sizes must match.

◆ checkFormat()

static bool checkFormat ( PixelFormat format,
TextureType  texType,
int  usage 
)
static

Checks is the provided format valid for the texture type and usage.

Parameters
[in,out]formatFormat to check. If format is not valid the method will update this with the closest relevant format.
[in]texTypeType of the texture the format will be used for.
[in]usageA set of TextureUsage flags that define how will a texture be used.
Returns
True if the format is valid, false if not.
Note
This method checks only for obvious format mismatches:
  • Using depth format for anything but a depth-stencil buffer
  • Using anything but a depth format for a depth-stencil-buffer
  • Using compressed format for anything but normal textures
  • Using compressed format for 1D textures

Caller should still check for platform-specific unsupported formats.

◆ compress()

static void compress ( const PixelData src,
PixelData dst,
const CompressionOptions options 
)
static

Compresses the provided data using the specified compression options.

◆ copy()

static void copy ( const PixelData src,
PixelData dst,
UINT32  offsetX = 0,
UINT32  offsetY = 0,
UINT32  offsetZ = 0 
)
static

Copies the contents of the src buffer into the dst buffer.

The size of the copied contents is determined by the size of the dst buffer. First pixel copied from src is determined by offset provided in offsetX, offsetY and offsetZ parameters.

◆ flipComponentOrder()

static void flipComponentOrder ( PixelData data)
static

Flips the order of components in each individual pixel.

For example RGBA -> ABGR.

◆ genMipmaps()

static Vector<SPtr<PixelData> > genMipmaps ( const PixelData src,
const MipMapGenOptions options 
)
static

Generates mip-maps from the provided source data using the specified compression options.

Returned list includes the base level.

Returns
A list of calculated mip-map data. First entry is the largest mip and other follow in order from largest to smallest.

◆ getBitDepths()

static void getBitDepths ( PixelFormat  format,
int(&)  rgba[4] 
)
static

Returns the number of bits per each element in the provided pixel format.

This will return all zero for compressed and depth/stencil formats.

◆ getBitMasks()

static void getBitMasks ( PixelFormat  format,
UINT32(&)  rgba[4] 
)
static

Returns bit masks that determine in what bit range is each channel stored.

Note

For example if your color is stored in an UINT32 and you want to extract the red channel you should AND the color UINT32 with the bit-mask for the red channel and then right shift it by the red channel bit shift amount.

◆ getBitShifts()

static void getBitShifts ( PixelFormat  format,
UINT8(&)  rgba[4] 
)
static

Returns number of bits you need to shift a pixel element in order to move it to the start of the data type.

Note

For example if your color is stored in an UINT32 and you want to extract the red channel you should AND the color UINT32 with the bit-mask for the red channel and then right shift it by the red channel bit shift amount.

◆ getElementType()

static PixelComponentType getElementType ( PixelFormat  format)
static

Returns the type of an individual pixel element in the provided format.

◆ getFlags()

static UINT32 getFlags ( PixelFormat  format)
static

Returns property flags for this pixel format.

See also
PixelFormatFlags

◆ getFormatName()

static String getFormatName ( PixelFormat  srcformat)
static

Returns the name of the pixel format.

◆ getMaxMipmaps()

static UINT32 getMaxMipmaps ( UINT32  width,
UINT32  height,
UINT32  depth,
PixelFormat  format 
)
static

Returns the maximum number of mip maps that can be generated until we reach the minimum size possible.

This does not count the base level.

◆ getMemorySize()

static UINT32 getMemorySize ( UINT32  width,
UINT32  height,
UINT32  depth,
PixelFormat  format 
)
static

Returns the size of the memory region required to hold pixels of the provided size ana format.

◆ getNumElemBits()

static UINT32 getNumElemBits ( PixelFormat  format)
static

Returns the size of a single pixel of the provided pixel format, in bits.

◆ getNumElemBytes()

static UINT32 getNumElemBytes ( PixelFormat  format)
static

Returns the size of a single pixel of the provided pixel format, in bytes.

◆ getNumElements()

static UINT32 getNumElements ( PixelFormat  format)
static

Returns the number of pixel elements in the provided format.

◆ getPitch()

static void getPitch ( UINT32  width,
UINT32  height,
UINT32  depth,
PixelFormat  format,
UINT32 &  rowPitch,
UINT32 &  depthPitch 
)
static

Calculates row and depth pitch for a texture surface of the specified size and format.

For most this will be equal to their width & height, respectively. But some texture formats (especially compressed ones) might require extra padding.

◆ getSizeForMipLevel()

static void getSizeForMipLevel ( UINT32  width,
UINT32  height,
UINT32  depth,
UINT32  mipLevel,
UINT32 &  mipWidth,
UINT32 &  mipHeight,
UINT32 &  mipDepth 
)
static

Calculates the size of a mip level of a texture with the provided size.

◆ hasAlpha()

static bool hasAlpha ( PixelFormat  format)
static

Checks if the provided pixel format has an alpha channel.

◆ isAccessible()

static bool isAccessible ( PixelFormat  srcformat)
static

Returns true if the pixel data in the format can be directly accessed and read.

This is generally not true for compressed formats.

◆ isCompressed()

static bool isCompressed ( PixelFormat  format)
static

Checks is the provided pixel format compressed.

◆ isDepth()

static bool isDepth ( PixelFormat  format)
static

Checks is the provided pixel format a depth/stencil buffer format.

◆ isFloatingPoint()

static bool isFloatingPoint ( PixelFormat  format)
static

Checks is the provided pixel format a floating point format.

◆ isNormalized()

static bool isNormalized ( PixelFormat  format)
static

Checks does the provided format store data in normalized range.

◆ isValidExtent()

static bool isValidExtent ( UINT32  width,
UINT32  height,
UINT32  depth,
PixelFormat  format 
)
static

Checks are the provided dimensions valid for the specified pixel format.

Some formats (like BC) require width/height to be multiples of four and some formats dont allow depth larger than 1.

◆ linearToSRGB() [1/2]

static Color linearToSRGB ( const Color color)
static

Converts a color in linear space to a color in sRGB space.

Only converts the RGB components.

◆ linearToSRGB() [2/2]

static void linearToSRGB ( PixelData pixelData)
static

Converts pixel data in linear space to one in sRGB space.

Only converts the RGB components.

◆ mirror()

static void mirror ( PixelData pixelData,
MirrorMode  mode 
)
static

Mirrors the contents of the provided object along the X, Y and/or Z axes.

◆ packColor() [1/3]

static void packColor ( const Color color,
PixelFormat  format,
void *  dest 
)
static

Writes the color to the provided memory location.

◆ packColor() [2/3]

static void packColor ( UINT8  r,
UINT8  g,
UINT8  b,
UINT8  a,
PixelFormat  format,
void *  dest 
)
static

Writes the color to the provided memory location.

If the destination format is floating point, the byte values will be converted into [0.0, 1.0] range.

◆ packColor() [3/3]

static void packColor ( float  r,
float  g,
float  b,
float  a,
const PixelFormat  format,
void *  dest 
)
static

Writes the color to the provided memory location.

If the destination format in non-floating point, the float values will be assumed to be in [0.0, 1.0] which will be converted to integer range. ([0, 255] in the case of bytes)

◆ packDepth()

static void packDepth ( float  depth,
const PixelFormat  format,
void *  dest 
)
static

Writes a depth value to the provided memory location.

Depth should be in range [0, 1].

◆ scale()

static void scale ( const PixelData src,
PixelData dst,
Filter  filter = FILTER_LINEAR 
)
static

Scales pixel data in the source buffer and stores the scaled data in the destination buffer.

Provided pixel data objects must have previously allocated buffers of adequate size. You may also provided a filtering method to use when scaling.

◆ SRGBToLinear() [1/2]

static Color SRGBToLinear ( const Color color)
static

Converts a color in sRGB space to a color in linear space.

Only converts the RGB components.

◆ SRGBToLinear() [2/2]

static void SRGBToLinear ( PixelData pixelData)
static

Converts pixel data in sRGB space to one in linear space.

Only converts the RGB components.

◆ unpackColor() [1/2]

static void unpackColor ( Color color,
PixelFormat  format,
const void *  src 
)
static

Reads the color from the provided memory location and stores it into the provided color object.

◆ unpackColor() [2/2]

static void unpackColor ( float *  r,
float *  g,
float *  b,
float *  a,
PixelFormat  format,
const void *  src 
)
static

Reads the color from the provided memory location and stores it into the provided color elements.

If the format is not natively floating point a conversion is done in such a way that returned values range [0.0, 1.0].

◆ unpackDepth()

static float unpackDepth ( PixelFormat  format,
void *  src 
)
static

Reads the depth from the provided memory location.

Value ranges in [0, 1].

Member Enumeration Documentation

◆ Filter

enum Filter

Filtering types to use when scaling images.