irr::video::IImage Class Reference

Interface for software image data. More...

#include <IImage.h>

Inheritance diagram for irr::video::IImage:

Public Member Functions
	IImage (ECOLOR_FORMAT format, const core::dimension2d< u32 > &size, bool deleteMemory)
	constructor More...
virtual	~IImage ()
	destructor More...
ECOLOR_FORMAT	getColorFormat () const
	Returns the color format. More...
const core::dimension2d< u32 > &	getDimension () const
	Returns width and height of image data. More...
u32	getBitsPerPixel () const
	Returns bits per pixel. More...
u32	getBytesPerPixel () const
	Returns bytes per pixel. More...
u32	getImageDataSizeInBytes () const
	Returns image data size in bytes. More...
u32	getImageDataSizeInPixels () const
	Returns image data size in pixels. More...
u32	getPitch () const
	Returns pitch of image. More...
u32	getRedMask () const
	Returns mask for red value of a pixel. More...
u32	getGreenMask () const
	Returns mask for green value of a pixel. More...
u32	getBlueMask () const
	Returns mask for blue value of a pixel. More...
u32	getAlphaMask () const
	Returns mask for alpha value of a pixel. More...
void *	getData () const
	Use this to get a pointer to the image data. More...
_IRR_DEPRECATED_ void *	lock ()
	Lock function. Use this to get a pointer to the image data. More...
_IRR_DEPRECATED_ void	unlock ()
	Unlock function. More...
core::dimension2du	getMipMapsSize (u32 mipmapLevel) const
	Get the mipmap size for this image for a certain mipmap level. More...
void *	getMipMapsData (irr::u32 mipLevel=1) const
	Get mipmaps data. More...
void	setMipMapsData (void *data, bool ownForeignMemory, bool deleteMemory)
	Set mipmaps data. More...
virtual SColor	getPixel (u32 x, u32 y) const =0
	Returns a pixel. More...
virtual void	setPixel (u32 x, u32 y, const SColor &color, bool blend=false)=0
	Sets a pixel. More...
virtual void	copyToScaling (void *target, u32 width, u32 height, ECOLOR_FORMAT format=ECF_A8R8G8B8, u32 pitch=0)=0
	Copies the image into the target, scaling the image to fit. More...
virtual void	copyToScaling (IImage *target)=0
	Copies the image into the target, scaling the image to fit. More...
virtual void	copyTo (IImage *target, const core::position2d< s32 > &pos=core::position2d< s32 >(0, 0))=0
	copies this surface into another More...
virtual void	copyTo (IImage *target, const core::position2d< s32 > &pos, const core::rect< s32 > &sourceRect, const core::rect< s32 > *clipRect=0)=0
	copies this surface into another More...
virtual void	copyToWithAlpha (IImage *target, const core::position2d< s32 > &pos, const core::rect< s32 > &sourceRect, const SColor &color, const core::rect< s32 > *clipRect=0, bool combineAlpha=false)=0
	copies this surface into another, using the alpha mask and cliprect and a color to add with More...
virtual void	copyToScalingBoxFilter (IImage *target, s32 bias=0, bool blend=false)=0
	copies this surface into another, scaling it to fit, applying a box filter More...
virtual void	fill (const SColor &color)=0
	fills the surface with given color More...
_IRR_DEPRECATED_ bool	isCompressed () const
	Inform whether the image is compressed. More...
_IRR_DEPRECATED_ bool	hasMipMaps () const
	Check whether the image has MipMaps. More...
Public Member Functions inherited from irr::IReferenceCounted
	IReferenceCounted ()
	Constructor. More...
virtual	~IReferenceCounted ()
	Destructor. More...
void	grab () const
	Grabs the object. Increments the reference counter by one. More...
bool	drop () const
	Drops the object. Decrements the reference counter by one. More...
s32	getReferenceCount () const
	Get the reference count. More...
const c8 *	getDebugName () const
	Returns the debug name of the object. More...

Static Public Member Functions
static core::dimension2du	getMipMapsSize (const core::dimension2du &sizeLevel0, u32 mipmapLevel)
	Calculate mipmap size for a certain level. More...
static u32	getBitsPerPixelFromFormat (const ECOLOR_FORMAT format)
	get the amount of Bits per Pixel of the given color format More...
static u32	getDataSizeFromFormat (ECOLOR_FORMAT format, u32 width, u32 height)
	calculate image data size in bytes for selected format, width and height. More...
static bool	isCompressedFormat (const ECOLOR_FORMAT format)
	check if this is compressed color format More...
static bool	isDepthFormat (const ECOLOR_FORMAT format)
	check if the color format is only viable for depth/stencil textures More...
static bool	isFloatingPointFormat (const ECOLOR_FORMAT format)
	Check if the color format uses floating point values for pixels. More...

Protected Attributes
ECOLOR_FORMAT	Format
core::dimension2d< u32 >	Size
u8 *	Data
u8 *	MipMapsData
u32	BytesPerPixel
u32	Pitch
bool	DeleteMemory
bool	DeleteMipMapsMemory
core::irrAllocator< u8 >	Allocator

Additional Inherited Members
Protected Member Functions inherited from irr::IReferenceCounted
void	setDebugName (const c8 *newName)
	Sets the debug name of the object. More...

Detailed Description

Interface for software image data.

Image loaders create these images from files. IVideoDrivers convert these images into their (hardware) textures. NOTE: Floating point formats are not well supported yet. Basically only getData() works for them.

Definition at line 25 of file IImage.h.

Constructor & Destructor Documentation

IImage()

irr::video::IImage::IImage ( ECOLOR_FORMAT  format, const core::dimension2d< u32 > &  size, bool  deleteMemory  )

inline

constructor

Definition at line 30 of file IImage.h.

                                                                                          :
                Format(format), Size(size), Data(0), MipMapsData(0), BytesPerPixel(0), Pitch(0), DeleteMemory(deleteMemory), DeleteMipMapsMemory(false)
        {
                BytesPerPixel = getBitsPerPixelFromFormat(Format) / 8;
                Pitch = BytesPerPixel * Size.Width;
        }

~IImage()

virtual irr::video::IImage::~IImage ( )

inlinevirtual

destructor

Definition at line 38 of file IImage.h.

        {
                if (DeleteMemory)
                        delete[] Data;

                if (DeleteMipMapsMemory)
                        Allocator.deallocate(MipMapsData);
        }

Member Function Documentation

copyTo() [1/2]

virtual void irr::video::IImage::copyTo ( IImage *  target, const core::position2d< s32 > &  pos = core::position2d< s32 >(0, 0)  )

pure virtual

copies this surface into another

NOTE: mipmaps are ignored

copyTo() [2/2]

virtual void irr::video::IImage::copyTo ( IImage *  target, const core::position2d< s32 > &  pos, const core::rect< s32 > &  sourceRect, const core::rect< s32 > *  clipRect = 0  )

pure virtual

copies this surface into another

NOTE: mipmaps are ignored

copyToScaling() [1/2]

virtual void irr::video::IImage::copyToScaling ( void *  target, u32  width, u32  height, ECOLOR_FORMAT  format = ECF_A8R8G8B8, u32  pitch = 0  )

pure virtual

Copies the image into the target, scaling the image to fit.

NOTE: mipmaps are ignored

copyToScaling() [2/2]

virtual void irr::video::IImage::copyToScaling ( IImage *  target )

pure virtual

Copies the image into the target, scaling the image to fit.

NOTE: mipmaps are ignored

copyToScalingBoxFilter()

virtual void irr::video::IImage::copyToScalingBoxFilter ( IImage *  target, s32  bias = 0, bool  blend = false  )

pure virtual

copies this surface into another, scaling it to fit, applying a box filter

NOTE: mipmaps are ignored

copyToWithAlpha()

virtual void irr::video::IImage::copyToWithAlpha ( IImage *  target, const core::position2d< s32 > &  pos, const core::rect< s32 > &  sourceRect, const SColor &  color, const core::rect< s32 > *  clipRect = 0, bool  combineAlpha = false  )

pure virtual

copies this surface into another, using the alpha mask and cliprect and a color to add with

NOTE: mipmaps are ignored

Parameters

combineAlpha

- When true then combine alpha channels. When false replace target image alpha with source image alpha.

fill()

virtual void irr::video::IImage::fill ( const SColor &  color )

pure virtual

fills the surface with given color

getAlphaMask()

u32 irr::video::IImage::getAlphaMask ( ) const

inline

Returns mask for alpha value of a pixel.

Definition at line 145 of file IImage.h.

        {
                switch (Format)
                {
                case ECF_A1R5G5B5:
                        return 0x1 << 15;
                case ECF_R5G6B5:
                        return 0x0;
                case ECF_R8G8B8:
                        return 0x0;
                case ECF_A8R8G8B8:
                        return 0xFF000000;
                default:
                        return 0x0;
                }
        }

getBitsPerPixel()

u32 irr::video::IImage::getBitsPerPixel ( ) const

inline

Returns bits per pixel.

Definition at line 60 of file IImage.h.

        {

                return getBitsPerPixelFromFormat(Format);
        }

getBitsPerPixelFromFormat()

static u32 irr::video::IImage::getBitsPerPixelFromFormat ( const ECOLOR_FORMAT  format )

inlinestatic

get the amount of Bits per Pixel of the given color format

Definition at line 364 of file IImage.h.

        {
                switch(format)
                {
                case ECF_A1R5G5B5:
                        return 16;
                case ECF_R5G6B5:
                        return 16;
                case ECF_R8G8B8:
                        return 24;
                case ECF_A8R8G8B8:
                        return 32;
                case ECF_DXT1:
                        return 16;
                case ECF_DXT2:
                case ECF_DXT3:
                case ECF_DXT4:
                case ECF_DXT5:
                        return 32;
                case ECF_PVRTC_RGB2:
                        return 12;
                case ECF_PVRTC_ARGB2:
                case ECF_PVRTC2_ARGB2:
                        return 16;
                case ECF_PVRTC_RGB4:
                        return 24;
                case ECF_PVRTC_ARGB4:
                case ECF_PVRTC2_ARGB4:
                        return 32;
                case ECF_ETC1:
                case ECF_ETC2_RGB:
                        return 24;
                case ECF_ETC2_ARGB:
                        return 32;
                case ECF_D16:
                        return 16;
                case ECF_D32:
                        return 32;
                case ECF_D24S8:
                        return 32;
                case ECF_R8:
                        return 8;
                case ECF_R8G8:
                        return 16;
                case ECF_R16:
                        return 16;
                case ECF_R16G16:
                        return 32;
                case ECF_R16F:
                        return 16;
                case ECF_G16R16F:
                        return 32;
                case ECF_A16B16G16R16F:
                        return 64;
                case ECF_R32F:
                        return 32;
                case ECF_G32R32F:
                        return 64;
                case ECF_A32B32G32R32F:
                        return 128;
                default:
                        return 0;
                }
        }

getBlueMask()

u32 irr::video::IImage::getBlueMask ( ) const

inline

Returns mask for blue value of a pixel.

Definition at line 127 of file IImage.h.

        {
                switch (Format)
                {
                case ECF_A1R5G5B5:
                        return 0x1F;
                case ECF_R5G6B5:
                        return 0x1F;
                case ECF_R8G8B8:
                        return 0x000000FF;
                case ECF_A8R8G8B8:
                        return 0x000000FF;
                default:
                        return 0x0;
                }
        }

getBytesPerPixel()

u32 irr::video::IImage::getBytesPerPixel ( ) const

inline

Returns bytes per pixel.

Definition at line 67 of file IImage.h.

        {
                return BytesPerPixel;
        }

getColorFormat()

ECOLOR_FORMAT irr::video::IImage::getColorFormat ( ) const

inline

Returns the color format.

Definition at line 48 of file IImage.h.

        {
                return Format;
        }

getData()

void* irr::video::IImage::getData ( ) const

inline

Use this to get a pointer to the image data.

Returns

Pointer to the image data. What type of data is pointed to depends on the color format of the image. For example if the color format is ECF_A8R8G8B8, it is of u32.

Definition at line 167 of file IImage.h.

        {
                return Data;
        }

getDataSizeFromFormat()

static u32 irr::video::IImage::getDataSizeFromFormat ( ECOLOR_FORMAT  format, u32  width, u32  height  )

inlinestatic

calculate image data size in bytes for selected format, width and height.

Definition at line 430 of file IImage.h.

        {
                u32 imageSize = 0;

                switch (format)
                {
                case ECF_DXT1:
                        imageSize = ((width + 3) / 4) * ((height + 3) / 4) * 8;
                        break;
                case ECF_DXT2:
                case ECF_DXT3:
                case ECF_DXT4:
                case ECF_DXT5:
                        imageSize = ((width + 3) / 4) * ((height + 3) / 4) * 16;
                        break;
                case ECF_PVRTC_RGB2:
                case ECF_PVRTC_ARGB2:
                        imageSize = (core::max_<u32>(width, 16) * core::max_<u32>(height, 8) * 2 + 7) / 8;
                        break;
                case ECF_PVRTC_RGB4:
                case ECF_PVRTC_ARGB4:
                        imageSize = (core::max_<u32>(width, 8) * core::max_<u32>(height, 8) * 4 + 7) / 8;
                        break;
                case ECF_PVRTC2_ARGB2:
                        imageSize = core::ceil32(width / 8.0f) * core::ceil32(height / 4.0f) * 8;
                        break;
                case ECF_PVRTC2_ARGB4:
                case ECF_ETC1:
                case ECF_ETC2_RGB:
                        imageSize = core::ceil32(width / 4.0f) * core::ceil32(height / 4.0f) * 8;
                        break;
                case ECF_ETC2_ARGB:
                        imageSize = core::ceil32(width / 4.0f) * core::ceil32(height / 4.0f) * 16;
                        break;
                default: // uncompressed formats
                        imageSize = getBitsPerPixelFromFormat(format) / 8 * width;
                        imageSize *= height;
                        break;
                }

                return imageSize;
        }

getDimension()

const core::dimension2d<u32>& irr::video::IImage::getDimension ( ) const

inline

Returns width and height of image data.

Definition at line 54 of file IImage.h.

        {
                return Size;
        }

getGreenMask()

u32 irr::video::IImage::getGreenMask ( ) const

inline

Returns mask for green value of a pixel.

Definition at line 109 of file IImage.h.

        {
                switch (Format)
                {
                case ECF_A1R5G5B5:
                        return 0x1F << 5;
                case ECF_R5G6B5:
                        return 0x3F << 5;
                case ECF_R8G8B8:
                        return 0x0000FF00;
                case ECF_A8R8G8B8:
                        return 0x0000FF00;
                default:
                        return 0x0;
                }
        }

getImageDataSizeInBytes()

u32 irr::video::IImage::getImageDataSizeInBytes ( ) const

inline

Returns image data size in bytes.

Definition at line 73 of file IImage.h.

        {
                return getDataSizeFromFormat(Format, Size.Width, Size.Height);
        }

getImageDataSizeInPixels()

u32 irr::video::IImage::getImageDataSizeInPixels ( ) const

inline

Returns image data size in pixels.

Definition at line 79 of file IImage.h.

        {
                return Size.Width * Size.Height;
        }

getMipMapsData()

void* irr::video::IImage::getMipMapsData ( irr::u32  mipLevel = 1 ) const

inline

Get mipmaps data.

Note that different mip levels are just behind each other in memory block. So if you just get level 1 you also have the data for all other levels. There is no level 0 - use getData to get the original image data.

Definition at line 225 of file IImage.h.

        {
                if ( MipMapsData && mipLevel > 0)
                {
                        size_t dataSize = 0;
                        core::dimension2du mipSize(Size);
                        u32 i = 1;      // We want the start of data for this level, not end.

                        while (i != mipLevel)
                        {
                                if (mipSize.Width > 1)
                                        mipSize.Width >>= 1;

                                if (mipSize.Height > 1)
                                        mipSize.Height >>= 1;

                                dataSize += getDataSizeFromFormat(Format, mipSize.Width, mipSize.Height);

                                ++i;
                                if ( mipSize.Width == 1 && mipSize.Height == 1 && i < mipLevel)
                                        return 0;
                        } 

                        return MipMapsData + dataSize;
                }
        
                return 0;
        }

getMipMapsSize() [1/2]

core::dimension2du irr::video::IImage::getMipMapsSize ( u32  mipmapLevel ) const

inline

Get the mipmap size for this image for a certain mipmap level.

level 0 will be full image size. Every further level is half the size. Doesn't care if the image actually has mipmaps, just which size would be needed.

Definition at line 193 of file IImage.h.

        {
                return getMipMapsSize(Size, mipmapLevel);
        }

getMipMapsSize() [2/2]

static core::dimension2du irr::video::IImage::getMipMapsSize ( const core::dimension2du &  sizeLevel0, u32  mipmapLevel  )

inlinestatic

Calculate mipmap size for a certain level.

level 0 will be full image size. Every further level is half the size.

Definition at line 201 of file IImage.h.

        {
                core::dimension2du result(sizeLevel0);
                u32 i=0;
                while (i != mipmapLevel)
                {
                        if (result.Width>1)
                                result.Width >>= 1;
                        if (result.Height>1)
                                result.Height>>=1;
                        ++i;

                        if ( result.Width == 1 && result.Height == 1 && i < mipmapLevel )
                                return core::dimension2du(0,0);
                }
                return result;
        }

getPitch()

u32 irr::video::IImage::getPitch ( ) const

inline

Returns pitch of image.

Definition at line 85 of file IImage.h.

        {
                return Pitch;
        }

getPixel()

virtual SColor irr::video::IImage::getPixel ( u32  x, u32  y  ) const

pure virtual

Returns a pixel.

getRedMask()

u32 irr::video::IImage::getRedMask ( ) const

inline

Returns mask for red value of a pixel.

Definition at line 91 of file IImage.h.

        {
                switch (Format)
                {
                case ECF_A1R5G5B5:
                        return 0x1F << 10;
                case ECF_R5G6B5:
                        return 0x1F << 11;
                case ECF_R8G8B8:
                        return 0x00FF0000;
                case ECF_A8R8G8B8:
                        return 0x00FF0000;
                default:
                        return 0x0;
                }
        }

hasMipMaps()

_IRR_DEPRECATED_ bool irr::video::IImage::hasMipMaps ( ) const

inline

Check whether the image has MipMaps.

Returns

True if image has MipMaps, else false.

Definition at line 358 of file IImage.h.

        {
                return (getMipMapsData() != 0);
        }

isCompressed()

_IRR_DEPRECATED_ bool irr::video::IImage::isCompressed ( ) const

inline

Inform whether the image is compressed.

Definition at line 351 of file IImage.h.

        {
                return IImage::isCompressedFormat(Format);
        }

isCompressedFormat()

static bool irr::video::IImage::isCompressedFormat ( const ECOLOR_FORMAT  format )

inlinestatic

check if this is compressed color format

Definition at line 474 of file IImage.h.

        {
                switch(format)
                {
                        case ECF_DXT1:
                        case ECF_DXT2:
                        case ECF_DXT3:
                        case ECF_DXT4:
                        case ECF_DXT5:
                        case ECF_PVRTC_RGB2:
                        case ECF_PVRTC_ARGB2:
                        case ECF_PVRTC2_ARGB2:
                        case ECF_PVRTC_RGB4:
                        case ECF_PVRTC_ARGB4:
                        case ECF_PVRTC2_ARGB4:
                        case ECF_ETC1:
                        case ECF_ETC2_RGB:
                        case ECF_ETC2_ARGB:
                                return true;
                        default:
                                return false;
                }
        }

isDepthFormat()

static bool irr::video::IImage::isDepthFormat ( const ECOLOR_FORMAT  format )

inlinestatic

check if the color format is only viable for depth/stencil textures

Definition at line 499 of file IImage.h.

        {
                switch(format)
                {
                        case ECF_D16:
                        case ECF_D32:
                        case ECF_D24S8:
                                return true;
                        default:
                                return false;
                }
        }

isFloatingPointFormat()

static bool irr::video::IImage::isFloatingPointFormat ( const ECOLOR_FORMAT  format )

inlinestatic

Check if the color format uses floating point values for pixels.

Definition at line 513 of file IImage.h.

        {
                if (isCompressedFormat(format))
                        return false;

                switch(format)
                {
                case ECF_R16F:
                case ECF_G16R16F:
                case ECF_A16B16G16R16F:
                case ECF_R32F:
                case ECF_G32R32F:
                case ECF_A32B32G32R32F:
                        return true;
                default:
                        break;
                }
                return false;
        }

lock()

_IRR_DEPRECATED_ void* irr::video::IImage::lock ( )

inline

Lock function. Use this to get a pointer to the image data.

Use getData instead.

Returns

Pointer to the image data. What type of data is pointed to depends on the color format of the image. For example if the color format is ECF_A8R8G8B8, it is of u32. Be sure to call unlock() after you don't need the pointer any more.

Definition at line 178 of file IImage.h.

        {
                return getData();
        }

setMipMapsData()

void irr::video::IImage::setMipMapsData ( void *  data, bool  ownForeignMemory, bool  deleteMemory  )

inline

Set mipmaps data.

This method allows you to put custom mipmaps data for image.

Parameters

data	A byte array with pixel color information
ownForeignMemory	If true, the image will use the data pointer directly and own it afterward. If false, the memory will by copied internally.
deleteMemory	Whether the memory is deallocated upon destruction.

Definition at line 263 of file IImage.h.

        {
                if (data != MipMapsData)
                {
                        if (DeleteMipMapsMemory)
                        {
                                Allocator.deallocate(MipMapsData);

                                DeleteMipMapsMemory = false;
                        }

                        if (data)
                        {
                                if (ownForeignMemory)
                                {
                                        MipMapsData = static_cast<u8*>(data);

                                        DeleteMipMapsMemory = deleteMemory;
                                }
                                else
                                {
                                        u32 dataSize = 0;
                                        u32 width = Size.Width;
                                        u32 height = Size.Height;

                                        do
                                        {
                                                if (width > 1)
                                                        width >>= 1;

                                                if (height > 1)
                                                        height >>= 1;

                                                dataSize += getDataSizeFromFormat(Format, width, height);
                                        } while (width != 1 || height != 1);

                                        MipMapsData = Allocator.allocate(dataSize);
                                        memcpy(MipMapsData, data, dataSize);

                                        DeleteMipMapsMemory = true;
                                }
                        }
                        else
                        {
                                MipMapsData = 0;
                        }
                }
        }

setPixel()

virtual void irr::video::IImage::setPixel ( u32  x, u32  y, const SColor &  color, bool  blend = false  )

pure virtual

Sets a pixel.

unlock()

_IRR_DEPRECATED_ void irr::video::IImage::unlock ( )

inline

Unlock function.

Should be called after the pointer received by lock() is not needed anymore.

Definition at line 186 of file IImage.h.

        {
        }

Member Data Documentation

Allocator

core::irrAllocator<u8> irr::video::IImage::Allocator

protected

Definition at line 546 of file IImage.h.

BytesPerPixel

u32 irr::video::IImage::BytesPerPixel

protected

Definition at line 540 of file IImage.h.

Data

u8* irr::video::IImage::Data

protected

Definition at line 537 of file IImage.h.

DeleteMemory

bool irr::video::IImage::DeleteMemory

protected

Definition at line 543 of file IImage.h.

DeleteMipMapsMemory

bool irr::video::IImage::DeleteMipMapsMemory

protected

Definition at line 544 of file IImage.h.

Format

ECOLOR_FORMAT irr::video::IImage::Format

protected

Definition at line 534 of file IImage.h.

MipMapsData

u8* irr::video::IImage::MipMapsData

protected

Definition at line 538 of file IImage.h.

Pitch

u32 irr::video::IImage::Pitch

protected

Definition at line 541 of file IImage.h.

Size

core::dimension2d<u32> irr::video::IImage::Size

protected

Definition at line 535 of file IImage.h.

---

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

• include/irrlicht/IImage.h