Ogre::Image Class Reference

Class representing an image file. More...

#include <OgreImage.h>

Inheritance diagram for Ogre::Image:

Inheritance graph
[legend]

List of all members.

Public Types

enum  Filter {
  FILTER_NEAREST, FILTER_LINEAR, FILTER_BILINEAR, FILTER_BOX,
  FILTER_TRIANGLE, FILTER_BICUBIC
}
typedef Ogre::Box Box
typedef Ogre::Rect Rect

Public Member Functions

 Image ()
 Standard constructor.
 Image (const Image &img)
 Copy-constructor - copies all the data from the target image.
virtual ~Image ()
 Standard destructor.
Imageoperator= (const Image &img)
 Assignment operator - copies all the data from the target image.
ImageflipAroundY ()
 Flips (mirrors) the image around the Y-axis.
ImageflipAroundX ()
 Flips (mirrors) the image around the X-axis.
ImageloadDynamicImage (uchar *pData, size_t uWidth, size_t uHeight, size_t depth, PixelFormat eFormat, bool autoDelete=false, size_t numFaces=1, size_t numMipMaps=0)
 Stores a pointer to raw data in memory.
ImageloadDynamicImage (uchar *pData, size_t uWidth, size_t uHeight, PixelFormat eFormat)
 Stores a pointer to raw data in memory.
ImageloadRawData (DataStreamPtr &stream, size_t uWidth, size_t uHeight, size_t uDepth, PixelFormat eFormat, size_t numFaces=1, size_t numMipMaps=0)
 Loads raw data from a stream.
ImageloadRawData (DataStreamPtr &stream, size_t uWidth, size_t uHeight, PixelFormat eFormat)
 Loads raw data from a stream.
Imageload (const String &strFileName, const String &groupName)
 Loads an image file.
Imageload (DataStreamPtr &stream, const String &type=StringUtil::BLANK)
 Loads an image file from a stream.
void save (const String &filename)
 Save the image as a file.
DataStreamPtr encode (const String &formatextension)
 Encode the image and return a stream to the data.
uchargetData (void)
 Returns a pointer to the internal image buffer.
const uchargetData () const
 Returns a const pointer to the internal image buffer.
size_t getSize () const
 Returns the size of the data buffer.
size_t getNumMipmaps () const
 Returns the number of mipmaps contained in the image.
bool hasFlag (const ImageFlags imgFlag) const
 Returns true if the image has the appropriate flag set.
size_t getWidth (void) const
 Gets the width of the image in pixels.
size_t getHeight (void) const
 Gets the height of the image in pixels.
size_t getDepth (void) const
 Gets the depth of the image.
size_t getNumFaces (void) const
 Get the number of faces of the image.
size_t getRowSpan (void) const
 Gets the physical width in bytes of each row of pixels.
PixelFormat getFormat () const
 Returns the image format.
uchar getBPP () const
 Returns the number of bits per pixel.
bool getHasAlpha () const
 Returns true if the image has an alpha component.
ColourValue getColourAt (int x, int y, int z) const
 Get colour value from a certain location in the image.
PixelBox getPixelBox (size_t face=0, size_t mipmap=0) const
 Get a PixelBox encapsulating the image data of a mipmap.
void resize (ushort width, ushort height, Filter filter=FILTER_BILINEAR)
 Resize a 2D image, applying the appropriate filter.
void * operator new (size_t sz, const char *file, int line, const char *func)
 operator new, with debug line info
void * operator new (size_t sz)
void * operator new (size_t sz, void *ptr)
 placement operator new
void * operator new[] (size_t sz, const char *file, int line, const char *func)
 array operator new, with debug line info
void * operator new[] (size_t sz)
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 *)

Static Public Member Functions

static void applyGamma (uchar *buffer, Real gamma, size_t size, uchar bpp)
 Does gamma adjustment.
static void scale (const PixelBox &src, const PixelBox &dst, Filter filter=FILTER_BILINEAR)
 Scale a 1D, 2D or 3D image volume.
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.

Protected Attributes

size_t m_uWidth
size_t m_uHeight
size_t m_uDepth
size_t m_uSize
size_t m_uNumMipmaps
int m_uFlags
PixelFormat m_eFormat
uchar m_ucPixelSize
ucharm_pBuffer
bool m_bAutoDelete


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 56 of file OgreImage.h.


Member Typedef Documentation

Definition at line 59 of file OgreImage.h.

Definition at line 60 of file OgreImage.h.


Member Enumeration Documentation

Enumerator:
FILTER_NEAREST 
FILTER_LINEAR 
FILTER_BILINEAR 
FILTER_BOX 
FILTER_TRIANGLE 
FILTER_BICUBIC 

Definition at line 384 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

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

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

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
                

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::loadDynamicImage ( uchar pData,
size_t  uWidth,
size_t  uHeight,
size_t  depth,
PixelFormat  eFormat,
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, otherwhise 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 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*PixelUtilgetMemorySize(width, height, depth, format)

Image& Ogre::Image::loadDynamicImage ( uchar pData,
size_t  uWidth,
size_t  uHeight,
PixelFormat  eFormat 
)

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(pData, width, height, depth, format, ...) to be compatible with future Ogre versions.

Definition at line 200 of file OgreImage.h.

Image& Ogre::Image::loadRawData ( DataStreamPtr stream,
size_t  uWidth,
size_t  uHeight,
size_t  uDepth,
PixelFormat  eFormat,
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*PixelUtilgetMemorySize(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  uWidth,
size_t  uHeight,
PixelFormat  eFormat 
)

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 248 of file OgreImage.h.

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

Loads an image file.

Remarks:
This method loads an image into memory. Any format for which and 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:
strFileName Name of a file 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 and 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& strFileName )

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

Save the image as a file.

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"

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::getSize (  )  const

Returns the size of the data buffer.

size_t Ogre::Image::getNumMipmaps (  )  const

Returns the number of mipmaps contained in the image.

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

Returns true if the image has the appropriate flag set.

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

Gets the width of the image in pixels.

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

Gets the height of the image in pixels.

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

Gets the depth of the image.

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::getRowSpan ( void   )  const

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

PixelFormat Ogre::Image::getFormat (  )  const

Returns the image format.

uchar Ogre::Image::getBPP (  )  const

Returns the number of bits per pixel.

bool Ogre::Image::getHasAlpha (  )  const

Returns true if the image has an alpha component.

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

ColourValue Ogre::Image::getColourAt ( int  x,
int  y,
int  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.

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

Get a PixelBox encapsulating the image data of a mipmap.

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::resize ( ushort  width,
ushort  height,
Filter  filter = FILTER_BILINEAR 
)

Resize a 2D image, applying the appropriate filter.

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

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

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

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

operator new, with debug line info

Definition at line 62 of file OgreMemoryAllocatedObject.h.

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

Definition at line 67 of file OgreMemoryAllocatedObject.h.

template<class Alloc>
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
void *  ptr 
) [inherited]

placement operator new

Definition at line 73 of file OgreMemoryAllocatedObject.h.

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

array operator new, with debug line info

Definition at line 79 of file OgreMemoryAllocatedObject.h.

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

Definition at line 84 of file OgreMemoryAllocatedObject.h.

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

Definition at line 89 of file OgreMemoryAllocatedObject.h.

template<class Alloc>
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
void *   
) [inherited]

Definition at line 95 of file OgreMemoryAllocatedObject.h.

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

Definition at line 101 of file OgreMemoryAllocatedObject.h.

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

Definition at line 106 of file OgreMemoryAllocatedObject.h.

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

Definition at line 112 of file OgreMemoryAllocatedObject.h.


Member Data Documentation

size_t Ogre::Image::m_uWidth [protected]

Definition at line 413 of file OgreImage.h.

size_t Ogre::Image::m_uHeight [protected]

Definition at line 415 of file OgreImage.h.

size_t Ogre::Image::m_uDepth [protected]

Definition at line 417 of file OgreImage.h.

size_t Ogre::Image::m_uSize [protected]

Definition at line 419 of file OgreImage.h.

size_t Ogre::Image::m_uNumMipmaps [protected]

Definition at line 421 of file OgreImage.h.

int Ogre::Image::m_uFlags [protected]

Definition at line 423 of file OgreImage.h.

Definition at line 426 of file OgreImage.h.

Definition at line 429 of file OgreImage.h.

Definition at line 430 of file OgreImage.h.

bool Ogre::Image::m_bAutoDelete [protected]

Definition at line 433 of file OgreImage.h.


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

Copyright © 2008 Torus Knot Software Ltd
Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 License.
Last modified Sun Sep 27 22:03:43 2009