OGRE: Ogre::Image Class Reference - OGRE Documentation

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

# Ogre::Image Class Reference

Class representing an image file. More...

`#include <OgreImage.h>`

List of all members.

## Public Types

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

## Public Member Functions

| Image ()
| Standard constructor.
| Image (const Image &img)
| Copy-constructor - copies all the data from the target image.
virtual | ~Image ()
| Standard destructor.
Image & | operator= (const Image &img)
| Assignment operator - copies all the data from the target image.
Image & | flipAroundY ()
| Flips (mirrors) the image around the Y-axis.
Image & | flipAroundX ()
| Flips (mirrors) the image around the X-axis.
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.
Image & | loadDynamicImage (uchar *pData, size_t uWidth, size_t uHeight, PixelFormat eFormat)
| Stores a pointer to raw data in memory.
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.
Image & | loadRawData (DataStreamPtr &stream, size_t uWidth, size_t uHeight, PixelFormat eFormat)
| Loads raw data from a stream.
Image & | load (const String &strFileName, const String &groupName)
| Loads an image file.
Image & | load (DataStreamPtr &stream, const String &type)
| Loads an image file from a stream.
void | save (const String &filename)
| Save the image as a file.
uchar * | getData (void)
| Returns a pointer to the internal image buffer.
const uchar * | getData () 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 numer 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)
| 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.

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

## Private 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
uchar * | m_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

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

| Definition at line 59 of file OgreImage.h.

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

| Definition at line 60 of file OgreImage.h.

## Member Enumeration Documentation

enum Ogre::Image::Filter

Enumeration values:

  FILTER_NEAREST |
  FILTER_LINEAR |
  FILTER_BILINEAR |
  FILTER_BOX |
  FILTER_TRIANGLE |
  FILTER_BICUBIC |

Definition at line 374 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::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

uchar Ogre::Image::getBPP | ( |  | ) | const

| Returns the number of bits per pixel.

ColourValue Ogre::Image::getColourAt | ( | int | x,
|  | int | y,
|  | int | z
| ) |

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

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.

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.

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

| Gets the depth of the image.

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 numer 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 | ( | DataStreamPtr & | stream,
|  | const String & | type
| ) |

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.

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

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

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.
  | 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::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 245 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*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::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.

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

## Member Data Documentation

bool Ogre::Image::m_bAutoDelete`[private]`

| Definition at line 419 of file OgreImage.h.

PixelFormat Ogre::Image::m_eFormat`[private]`

| Definition at line 412 of file OgreImage.h.

uchar* Ogre::Image::m_pBuffer`[private]`

| Definition at line 416 of file OgreImage.h.

uchar Ogre::Image::m_ucPixelSize`[private]`

| Definition at line 415 of file OgreImage.h.

size_t Ogre::Image::m_uDepth`[private]`

| Definition at line 403 of file OgreImage.h.

int Ogre::Image::m_uFlags`[private]`

| Definition at line 409 of file OgreImage.h.

size_t Ogre::Image::m_uHeight`[private]`

| Definition at line 401 of file OgreImage.h.

size_t Ogre::Image::m_uNumMipmaps`[private]`

| Definition at line 407 of file OgreImage.h.

size_t Ogre::Image::m_uSize`[private]`

| Definition at line 405 of file OgreImage.h.

size_t Ogre::Image::m_uWidth`[private]`

| Definition at line 399 of file OgreImage.h.

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

- OgreImage.h

Copyright © 2000-2005 by The OGRE Team
This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 License.
Last modified Thu Mar 6 09:46:54 2008