Class representing an image file. More...

#include <OgreImage.h>

Inheritance diagram for Ogre::Image:

Collaboration diagram for Ogre::Image:

Public Types
typedef Ogre::Box	Box

enum	Filter { FILTER_NEAREST, FILTER_LINEAR, FILTER_BILINEAR, FILTER_BOX, FILTER_TRIANGLE, FILTER_BICUBIC }

typedef Ogre::Rect	Rect

Public Member Functions
	Image ()
	Standard constructor. More...

	Image (const Image &img)
	Copy-constructor - copies all the data from the target image. More...

virtual	~Image ()
	Standard destructor. More...

Image &	combineTwoImagesAsRGBA (const Image &rgb, const Image &alpha, PixelFormat format=PF_BYTE_RGBA)
	Utility method to combine 2 separate images into this one, with the first image source supplying the RGB channels, and the second image supplying the alpha channel (as luminance or separate alpha). More...

DataStreamPtr	encode (const String &formatextension)
	Encode the image and return a stream to the data. More...

Image &	flipAroundX ()
	Flips (mirrors) the image around the X-axis. More...

Image &	flipAroundY ()
	Flips (mirrors) the image around the Y-axis. More...

void	freeMemory ()
	Delete all the memory held by this image, if owned by this image (not dynamic) More...

uchar	getBPP () const
	Returns the number of bits per pixel. More...

ColourValue	getColourAt (size_t x, size_t y, size_t z) const
	Get colour value from a certain location in the image. More...

uchar *	getData (void)
	Returns a pointer to the internal image buffer. More...

const uchar *	getData () const
	Returns a const pointer to the internal image buffer. More...

size_t	getDepth (void) const
	Gets the depth of the image. More...

PixelFormat	getFormat () const
	Returns the image format. More...

bool	getHasAlpha () const
	Returns true if the image has an alpha component. More...

size_t	getHeight (void) const
	Gets the height of the image in pixels. More...

size_t	getNumFaces (void) const
	Get the number of faces of the image. More...

size_t	getNumMipmaps () const
	Returns the number of mipmaps contained in the image. More...

PixelBox	getPixelBox (size_t face=0, size_t mipmap=0) const
	Get a PixelBox encapsulating the image data of a mipmap. More...

size_t	getRowSpan (void) const
	Gets the physical width in bytes of each row of pixels. More...

size_t	getSize () const
	Returns the size of the data buffer. More...

size_t	getWidth (void) const
	Gets the width of the image in pixels. More...

bool	hasFlag (const ImageFlags imgFlag) const
	Returns true if the image has the appropriate flag set. More...

Image &	load (const String &filename, const String &groupName)
	Loads an image file. More...

Image &	load (DataStreamPtr &stream, const String &type=StringUtil::BLANK)
	Loads an image file from a stream. More...

Image &	loadDynamicImage (uchar *data, size_t width, size_t height, size_t depth, PixelFormat format, bool autoDelete=false, size_t numFaces=1, size_t numMipMaps=0)
	Stores a pointer to raw data in memory. More...

Image &	loadDynamicImage (uchar *data, size_t width, size_t height, PixelFormat format)
	Stores a pointer to raw data in memory. More...

Image &	loadRawData (DataStreamPtr &stream, size_t width, size_t height, size_t depth, PixelFormat format, size_t numFaces=1, size_t numMipMaps=0)
	Loads raw data from a stream. More...

Image &	loadRawData (DataStreamPtr &stream, size_t width, size_t height, PixelFormat format)
	Loads raw data from a stream. More...

Image &	loadTwoImagesAsRGBA (const String &rgbFilename, const String &alphaFilename, const String &groupName, PixelFormat format=PF_BYTE_RGBA)
	Utility method to combine 2 separate images into this one, with the first image source supplying the RGB channels, and the second image supplying the alpha channel (as luminance or separate alpha). More...

Image &	loadTwoImagesAsRGBA (DataStreamPtr &rgbStream, DataStreamPtr &alphaStream, PixelFormat=PF_BYTE_RGBA, const String &rgbType=StringUtil::BLANK, const String &alphaType=StringUtil::BLANK)
	Utility method to combine 2 separate images into this one, with the first image source supplying the RGB channels, and the second image supplying the alpha channel (as luminance or separate alpha). More...

void	operator delete (void *ptr)

void	operator delete (void ptr, void )

void	operator delete (void ptr, const char , int, const char *)

void	operator delete[] (void *ptr)

void	operator delete[] (void ptr, const char , int, const char *)

void *	operator new (size_t sz, const char file, int line, const char func)
	operator new, with debug line info More...

void *	operator new (size_t sz)

void *	operator new (size_t sz, void *ptr)
	placement operator new More...

void *	operator new[] (size_t sz, const char file, int line, const char func)
	array operator new, with debug line info More...

void *	operator new[] (size_t sz)

Image &	operator= (const Image &img)
	Assignment operator - copies all the data from the target image. More...

void	resize (ushort width, ushort height, Filter filter=FILTER_BILINEAR)
	Resize a 2D image, applying the appropriate filter. More...

void	save (const String &filename)
	Save the image as a file. More...

void	setColourAt (ColourValue const &cv, size_t x, size_t y, size_t z)
	Set colour value at a certain location in the image. More...

Static Public Member Functions
static void	applyGamma (uchar *buffer, Real gamma, size_t size, uchar bpp)
	Does gamma adjustment. More...

static size_t	calculateSize (size_t mipmaps, size_t faces, size_t width, size_t height, size_t depth, PixelFormat format)

static String	getFileExtFromMagic (DataStreamPtr stream)
	Static function to get an image type string from a stream via magic numbers. More...

static void	scale (const PixelBox &src, const PixelBox &dst, Filter filter=FILTER_BILINEAR)
	Scale a 1D, 2D or 3D image volume. More...

Protected Attributes
bool	mAutoDelete

uchar *	mBuffer

size_t	mBufSize

size_t	mDepth

int	mFlags

PixelFormat	mFormat

size_t	mHeight

size_t	mNumMipmaps

uchar	mPixelSize

size_t	mWidth

Detailed Description

Class representing an image file.

Remarks: The Image class usually holds uncompressed image data and is the only object that can be loaded in a texture. Image objects handle image data decoding themselves by the means of locating the correct Codec object for each data type.

: Typically, you would want to use an Image object to load a texture when extra processing needs to be done on an image before it is loaded or when you want to blit to an existing texture.

Definition at line 61 of file OgreImage.h.

Member Typedef Documentation

typedef Ogre::Box Ogre::Image::Box

Definition at line 64 of file OgreImage.h.

typedef Ogre::Rect Ogre::Image::Rect

Definition at line 65 of file OgreImage.h.

Member Enumeration Documentation

enum Ogre::Image::Filter

Enumerator
FILTER_NEAREST
FILTER_LINEAR
FILTER_BILINEAR
FILTER_BOX
FILTER_TRIANGLE
FILTER_BICUBIC

Definition at line 450 of file OgreImage.h.

Constructor & Destructor Documentation

Ogre::Image::Image ( )

Standard constructor.

Ogre::Image::Image ( const Image & img )

Copy-constructor - copies all the data from the target image.

virtual Ogre::Image::~Image ( )

virtual

Standard destructor.

Member Function Documentation

static void Ogre::Image::applyGamma	(	uchar *	buffer,
		Real	gamma,
		size_t	size,
		uchar	bpp
	)

static

Does gamma adjustment.

Note: Basic algo taken from Titan Engine, copyright (c) 2000 Ignacio Castano Iguado

static size_t Ogre::Image::calculateSize	(	size_t	mipmaps,
		size_t	faces,
		size_t	width,
		size_t	height,
		size_t	depth,
		PixelFormat	format
	)

static

Image& Ogre::Image::combineTwoImagesAsRGBA	(	const Image &	rgb,
		const Image &	alpha,
		PixelFormat	format = `PF_BYTE_RGBA`
	)

Utility method to combine 2 separate images into this one, with the first image source supplying the RGB channels, and the second image supplying the alpha channel (as luminance or separate alpha).

Parameters

rgb	Image supplying the RGB channels (any alpha is ignored)
alpha	Image supplying the alpha channel. If a luminance image the single channel is used directly, if an RGB image then the values are converted to greyscale.
format	The destination format

DataStreamPtr Ogre::Image::encode ( const String & formatextension )

Encode the image and return a stream to the data.

Parameters

formatextension An extension to identify the image format to encode into, e.g. "jpg" or "png"

Image& Ogre::Image::flipAroundX ( )

Flips (mirrors) the image around the X-axis.

Remarks

An example of an original and flipped image:

            flip axis
                |
    originalimg|gmilanigiro
    00000000000|00000000000
    00000000000|00000000000
    00000000000|00000000000
    00000000000|00000000000
    00000000000|00000000000

Image& Ogre::Image::flipAroundY ( )

Flips (mirrors) the image around the Y-axis.

Remarks

An example of an original and flipped image:

                
    originalimg
    00000000000
    00000000000
    00000000000
    00000000000
    00000000000
    ---------—> flip axis
    00000000000
    00000000000
    00000000000
    00000000000
    00000000000
    originalimg

void Ogre::Image::freeMemory ( )

Delete all the memory held by this image, if owned by this image (not dynamic)

uchar Ogre::Image::getBPP ( ) const

Returns the number of bits per pixel.

ColourValue Ogre::Image::getColourAt	(	size_t	x,
		size_t	y,
		size_t	z
	)		const

Get colour value from a certain location in the image.

The z coordinate is only valid for cubemaps and volume textures. This uses the first (largest) mipmap.

uchar* Ogre::Image::getData ( void )

Returns a pointer to the internal image buffer.

Remarks: Be careful with this method. You will almost certainly prefer to use getPixelBox, especially with complex images which include many faces or custom mipmaps.

const uchar* Ogre::Image::getData ( ) const

Returns a const pointer to the internal image buffer.

Remarks: Be careful with this method. You will almost certainly prefer to use getPixelBox, especially with complex images which include many faces or custom mipmaps.

size_t Ogre::Image::getDepth ( void ) const

Gets the depth of the image.

static String Ogre::Image::getFileExtFromMagic ( DataStreamPtr stream )

static

Static function to get an image type string from a stream via magic numbers.

PixelFormat Ogre::Image::getFormat ( ) const

Returns the image format.

bool Ogre::Image::getHasAlpha ( ) const

Returns true if the image has an alpha component.

size_t Ogre::Image::getHeight ( void ) const

Gets the height of the image in pixels.

size_t Ogre::Image::getNumFaces ( void ) const

Get the number of faces of the image.

This is usually 6 for a cubemap, and 1 for a normal image.

size_t Ogre::Image::getNumMipmaps ( ) const

Returns the number of mipmaps contained in the image.

PixelBox Ogre::Image::getPixelBox	(	size_t	face = `0`,
		size_t	mipmap = `0`
	)		const

Get a PixelBox encapsulating the image data of a mipmap.

size_t Ogre::Image::getRowSpan ( void ) const

Gets the physical width in bytes of each row of pixels.

size_t Ogre::Image::getSize ( ) const

Returns the size of the data buffer.

size_t Ogre::Image::getWidth ( void ) const

Gets the width of the image in pixels.

bool Ogre::Image::hasFlag ( const ImageFlags imgFlag ) const

Returns true if the image has the appropriate flag set.

Image& Ogre::Image::load	(	const String &	filename,
		const String &	groupName
	)

Loads an image file.

Remarks: This method loads an image into memory. Any format for which an associated ImageCodec is registered can be loaded. This can include complex formats like DDS with embedded custom mipmaps, cube faces and volume textures. The type can be determined by calling getFormat().

Parameters

filename	Name of an image file to load.
groupName	Name of the resource group to search for the image

Note: The memory associated with this buffer is destroyed with the Image object.

Image& Ogre::Image::load	(	DataStreamPtr &	stream,
		const String &	type = `StringUtil::BLANK`
	)

Loads an image file from a stream.

Remarks: This method works in the same way as the filename-based load method except it loads the image from a DataStream object. This DataStream is expected to contain the encoded data as it would be held in a file. Any format for which an associated ImageCodec is registered can be loaded. This can include complex formats like DDS with embedded custom mipmaps, cube faces and volume textures. The type can be determined by calling getFormat().

Parameters

stream	The source data.
type	The type of the image. Used to decide what decompression codec to use. Can be left blank if the stream data includes a header to identify the data.

See also: Image::load( const String& filename )

Image& Ogre::Image::loadDynamicImage	(	uchar *	data,
		size_t	width,
		size_t	height,
		size_t	depth,
		PixelFormat	format,
		bool	autoDelete = `false`,
		size_t	numFaces = `1`,
		size_t	numMipMaps = `0`
	)

Stores a pointer to raw data in memory.

The pixel format has to be specified.

Remarks: This method loads an image into memory held in the object. The pixel format will be either greyscale or RGB with an optional Alpha component. The type can be determined by calling getFormat().

Note

Whilst typically your image is likely to be a simple 2D image, you can define complex images including cube maps, volume maps, and images including custom mip levels. The layout of the internal memory should be:

face 0, mip 0 (top), width x height (x depth)
face 0, mip 1, width/2 x height/2 (x depth/2)
face 0, mip 2, width/4 x height/4 (x depth/4)
.. remaining mips for face 0 ..
face 1, mip 0 (top), width x height (x depth)</li
.. and so on.

Of course, you will never have multiple faces (cube map) and depth too.

Parameters

The	data pointer
Width	of image
Height	of image
Image	Depth (in 3d images, numbers of layers, otherwise 1)
Pixel	Format
if	memory associated with this buffer is to be destroyed with the Image object. Note: it's important that if you set this option to true, that you allocated the memory using OGRE_ALLOC_T with a category of MEMCATEGORY_GENERAL to ensure the freeing of memory matches up.
the	number of faces the image data has inside (6 for cubemaps, 1 otherwise)
the	number of mipmaps the image data has inside

Note: The memory associated with this buffer is NOT destroyed with the Image object, unless autoDelete is set to true.

Remarks: The size of the buffer must be numFaces*PixelUtil::getMemorySize(width, height, depth, format)

Image& Ogre::Image::loadDynamicImage	(	uchar *	data,
		size_t	width,
		size_t	height,
		PixelFormat	format
	)

inline

Stores a pointer to raw data in memory.

The pixel format has to be specified.

Remarks: This method loads an image into memory held in the object. The pixel format will be either greyscale or RGB with an optional Alpha component. The type can be determined by calling getFormat().

Note

Whilst typically your image is likely to be a simple 2D image, you can define complex images including cube maps and images including custom mip levels. The layout of the internal memory should be:

face 0, mip 0 (top), width x height
face 0, mip 1, width/2 x height/2
face 0, mip 2, width/4 x height/4
.. remaining mips for face 0 ..
face 1, mip 0 (top), width x height (x depth)</li
.. and so on.

Of course, you will never have multiple faces (cube map) and depth too.

Parameters

The	data pointer
Width	of image
Height	of image
Pixel	Format

Note: The memory associated with this buffer is NOT destroyed with the Image object.

Remarks: This function is deprecated; one should really use the Image::loadDynamicImage(data, width, height, depth, format, ...) to be compatible with future Ogre versions.

Definition at line 205 of file OgreImage.h.

Image& Ogre::Image::loadRawData	(	DataStreamPtr &	stream,
		size_t	width,
		size_t	height,
		size_t	depth,
		PixelFormat	format,
		size_t	numFaces = `1`,
		size_t	numMipMaps = `0`
	)

Loads raw data from a stream.

See the function loadDynamicImage for a description of the parameters.

Remarks: The size of the buffer must be numFaces*PixelUtil::getMemorySize(width, height, depth, format)

Note

Whilst typically your image is likely to be a simple 2D image, you can define complex images including cube maps and images including custom mip levels. The layout of the internal memory should be:

face 0, mip 0 (top), width x height (x depth)
face 0, mip 1, width/2 x height/2 (x depth/2)
face 0, mip 2, width/4 x height/4 (x depth/4)
.. remaining mips for face 0 ..
face 1, mip 0 (top), width x height (x depth)</li
.. and so on.

Of course, you will never have multiple faces (cube map) and depth too.

Image& Ogre::Image::loadRawData	(	DataStreamPtr &	stream,
		size_t	width,
		size_t	height,
		PixelFormat	format
	)

inline

Loads raw data from a stream.

The pixel format has to be specified.

Remarks: This function is deprecated; one should really use the Image::loadRawData(stream, width, height, depth, format, ...) to be compatible with future Ogre versions.

Note

Whilst typically your image is likely to be a simple 2D image, you can define complex images including cube maps and images including custom mip levels. The layout of the internal memory should be:

face 0, mip 0 (top), width x height
face 0, mip 1, width/2 x height/2
face 0, mip 2, width/4 x height/4
.. remaining mips for face 0 ..
face 1, mip 0 (top), width x height (x depth)</li
.. and so on.

Of course, you will never have multiple faces (cube map) and depth too.

Definition at line 253 of file OgreImage.h.

Image& Ogre::Image::loadTwoImagesAsRGBA	(	const String &	rgbFilename,
		const String &	alphaFilename,
		const String &	groupName,
		PixelFormat	format = `PF_BYTE_RGBA`
	)

Utility method to combine 2 separate images into this one, with the first image source supplying the RGB channels, and the second image supplying the alpha channel (as luminance or separate alpha).

Parameters

rgbFilename	Filename of image supplying the RGB channels (any alpha is ignored)
alphaFilename	Filename of image supplying the alpha channel. If a luminance image the single channel is used directly, if an RGB image then the values are converted to greyscale.
groupName	The resource group from which to load the images
format	The destination format

Image& Ogre::Image::loadTwoImagesAsRGBA	(	DataStreamPtr &	rgbStream,
		DataStreamPtr &	alphaStream,
		PixelFormat	= `PF_BYTE_RGBA`,
		const String &	rgbType = `StringUtil::BLANK`,
		const String &	alphaType = `StringUtil::BLANK`
	)

Utility method to combine 2 separate images into this one, with the first image source supplying the RGB channels, and the second image supplying the alpha channel (as luminance or separate alpha).

Parameters

rgbStream	Stream of image supplying the RGB channels (any alpha is ignored)
alphaStream	Stream of image supplying the alpha channel. If a luminance image the single channel is used directly, if an RGB image then the values are converted to greyscale.
format	The destination format
rgbType	The type of the RGB image. Used to decide what decompression codec to use. Can be left blank if the stream data includes a header to identify the data.
alphaType	The type of the alpha image. Used to decide what decompression codec to use. Can be left blank if the stream data includes a header to identify the data.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete ( void * ptr )

inlineinherited

Definition at line 95 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete	(	void *	ptr,
		void *
	)

inlineinherited

Definition at line 101 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete	(	void *	ptr,
		const char *	,
		int	,
		const char *
	)

inlineinherited

Definition at line 107 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] ( void * ptr )

inlineinherited

Definition at line 112 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[]	(	void *	ptr,
		const char *	,
		int	,
		const char *
	)

inlineinherited

Definition at line 118 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new	(	size_t	sz,
		const char *	file,
		int	line,
		const char *	func
	)

inlineinherited

operator new, with debug line info

Definition at line 67 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new ( size_t sz )

inlineinherited

Definition at line 72 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new	(	size_t	sz,
		void *	ptr
	)

inlineinherited

placement operator new

Definition at line 78 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[]	(	size_t	sz,
		const char *	file,
		int	line,
		const char *	func
	)

inlineinherited

array operator new, with debug line info

Definition at line 85 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t sz )

inlineinherited

Definition at line 90 of file OgreMemoryAllocatedObject.h.

Image& Ogre::Image::operator= ( const Image & img )

Assignment operator - copies all the data from the target image.

void Ogre::Image::resize	(	ushort	width,
		ushort	height,
		Filter	filter = `FILTER_BILINEAR`
	)

Resize a 2D image, applying the appropriate filter.

void Ogre::Image::save ( const String & filename )

Save the image as a file.

Remarks: Saving and loading are implemented by back end (sometimes third party) codecs. Implemented saving functionality is more limited than loading in some cases. Particularly DDS file format support is currently limited to true colour or single channel float32, square, power of two textures with no mipmaps. Volumetric support is currently limited to DDS files.

static void Ogre::Image::scale	(	const PixelBox &	src,
		const PixelBox &	dst,
		Filter	filter = `FILTER_BILINEAR`
	)

static

Scale a 1D, 2D or 3D image volume.

Parameters

src	PixelBox containing the source pointer, dimensions and format
dst	PixelBox containing the destination pointer, dimensions and format
filter	Which filter to use

Remarks: This function can do pixel format conversion in the process.

Note: dst and src can point to the same PixelBox object without any problem

void Ogre::Image::setColourAt	(	ColourValue const &	cv,
		size_t	x,
		size_t	y,
		size_t	z
	)

Set colour value at a certain location in the image.

The z coordinate is only valid for cubemaps and volume textures. This uses the first (largest) mipmap.

Member Data Documentation

bool Ogre::Image::mAutoDelete

protected

Definition at line 499 of file OgreImage.h.

uchar* Ogre::Image::mBuffer

protected

Definition at line 496 of file OgreImage.h.

size_t Ogre::Image::mBufSize

protected

Definition at line 485 of file OgreImage.h.

size_t Ogre::Image::mDepth

protected

Definition at line 483 of file OgreImage.h.

int Ogre::Image::mFlags

protected

Definition at line 489 of file OgreImage.h.

PixelFormat Ogre::Image::mFormat

protected

Definition at line 492 of file OgreImage.h.

size_t Ogre::Image::mHeight

protected

Definition at line 481 of file OgreImage.h.

size_t Ogre::Image::mNumMipmaps

protected

Definition at line 487 of file OgreImage.h.

uchar Ogre::Image::mPixelSize

protected

Definition at line 495 of file OgreImage.h.

size_t Ogre::Image::mWidth

protected

Definition at line 479 of file OgreImage.h.

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

OgreImage.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation