| OGRE 1.11.1 Object-Oriented Graphics Rendering Engine

Public Types | Public Member Functions | Static Public Member Functions | List of all members
Ogre::Image Class Reference
Core » Image

Class representing an image file. More...

`#include <OgreImage.h>`

Inheritance diagram for Ogre::Image:
[legend]

## Public Types
enum | Filter { FILTER_NEAREST, FILTER_LINEAR, FILTER_BILINEAR, FILTER_BOX, FILTER_TRIANGLE, FILTER_BICUBIC }

## Public Member Functions
| Image ()
| Standard constructor. More...
| Image (const Image &img)
| Copy-constructor - copies all the data from the target image. More...
| ~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...
uint32 | 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...
uint32 | 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...
uint32 | 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...
uint32 | 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 (const DataStreamPtr &stream, const String &type=BLANKSTRING)
| Loads an image file from a stream. More...
Image & | loadDynamicImage (uchar *data, uint32 width, uint32 height, uint32 depth, PixelFormat format, bool autoDelete=false, size_t numFaces=1, uint32 numMipMaps=0)
| Stores a pointer to raw data in memory. More...
Image & | loadDynamicImage (uchar *data, uint32 width, uint32 height, PixelFormat format)
Image & | loadRawData (const DataStreamPtr &stream, uint32 width, uint32 height, uint32 depth, PixelFormat format, size_t numFaces=1, uint32 numMipMaps=0)
| Loads raw data from a stream. More...
Image & | loadRawData (const DataStreamPtr &stream, uint32 width, uint32 height, PixelFormat format)
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 (const DataStreamPtr &rgbStream, const DataStreamPtr &alphaStream, PixelFormat format=PF_BYTE_RGBA, const String &rgbType=BLANKSTRING, const String &alphaType=BLANKSTRING)
| 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 & | 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, uint32 width, uint32 height, uint32 depth, PixelFormat format)
| Static function to calculate size in bytes from the number of mipmaps, faces and the dimensions. More...
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...

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

## Member Enumeration Documentation

## ◆ Filter

enum Ogre::Image::Filter

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

## Constructor & Destructor Documentation

## ◆ Image() [1/2]

Ogre::Image::Image | ( |  | ) |

Standard constructor.

## ◆ Image() [2/2]

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

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

## ◆ ~Image()

Ogre::Image::~Image | ( |  | ) |

Standard destructor.

## Member Function Documentation

## ◆ operator=()

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

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

## ◆ flipAroundY()

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

## ◆ flipAroundX()

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

## ◆ loadDynamicImage() [1/2]

Image& Ogre::Image::loadDynamicImage | ( | uchar * | data,
|  | uint32 | width,
|  | uint32 | height,
|  | uint32 | depth,
|  | PixelFormat | format,
|  | bool | autoDelete = `false`,
|  | size_t | numFaces = `1`,
|  | uint32 | 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

  data | The data pointer
  width | Width of image
  height | Height of image
  depth | Image Depth (in 3d images, numbers of layers, otherwise 1)
  format | Pixel Format
  autoDelete | 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.
  numFaces | The number of faces the image data has inside (6 for cubemaps, 1 otherwise)
  numMipMaps | 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)

## ◆ loadDynamicImage() [2/2]

Image& Ogre::Image::loadDynamicImage | ( | uchar * | data,
|  | uint32 | width,
|  | uint32 | height,
|  | PixelFormat | format
| ) |  |
| inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ loadRawData() [1/2]

Image& Ogre::Image::loadRawData | ( | const DataStreamPtr & | stream,
|  | uint32 | width,
|  | uint32 | height,
|  | uint32 | depth,
|  | PixelFormat | format,
|  | size_t | numFaces = `1`,
|  | uint32 | 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.

## ◆ loadRawData() [2/2]

Image& Ogre::Image::loadRawData | ( | const DataStreamPtr & | stream,
|  | uint32 | width,
|  | uint32 | height,
|  | PixelFormat | format
| ) |  |
| inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ load() [1/2]

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.

## ◆ load() [2/2]

Image& Ogre::Image::load | ( | const DataStreamPtr & | stream,
|  | const String & | type = `BLANKSTRING`
| ) |  |

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 )

## ◆ loadTwoImagesAsRGBA() [1/2]

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

## ◆ loadTwoImagesAsRGBA() [2/2]

Image& Ogre::Image::loadTwoImagesAsRGBA | ( | const DataStreamPtr & | rgbStream,
|  | const DataStreamPtr & | alphaStream,
|  | PixelFormat | format = `PF_BYTE_RGBA`,
|  | const String & | rgbType = `BLANKSTRING`,
|  | const String & | alphaType = `BLANKSTRING`
| ) |  |

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.

## ◆ combineTwoImagesAsRGBA()

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

## ◆ save()

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.

## ◆ encode()

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"

## ◆ getData() [1/2]

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.

## ◆ getData() [2/2]

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.

## ◆ getSize()

size_t Ogre::Image::getSize | ( |  | ) | const

Returns the size of the data buffer.

## ◆ getNumMipmaps()

uint32 Ogre::Image::getNumMipmaps | ( |  | ) | const

Returns the number of mipmaps contained in the image.

## ◆ hasFlag()

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

Returns true if the image has the appropriate flag set.

## ◆ getWidth()

uint32 Ogre::Image::getWidth | ( | void |  | ) | const

Gets the width of the image in pixels.

## ◆ getHeight()

uint32 Ogre::Image::getHeight | ( | void |  | ) | const

Gets the height of the image in pixels.

## ◆ getDepth()

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

Gets the depth of the image.

## ◆ getNumFaces()

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.

## ◆ getRowSpan()

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

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

## ◆ getFormat()

PixelFormat Ogre::Image::getFormat | ( |  | ) | const

Returns the image format.

## ◆ getBPP()

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

Returns the number of bits per pixel.

## ◆ getHasAlpha()

bool Ogre::Image::getHasAlpha | ( |  | ) | const

Returns true if the image has an alpha component.

## ◆ applyGamma()

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

## ◆ getColourAt()

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.

## ◆ setColourAt()

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.

## ◆ getPixelBox()

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

Get a PixelBox encapsulating the image data of a mipmap.

## ◆ freeMemory()

void Ogre::Image::freeMemory | ( |  | ) |

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

## ◆ scale()

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

## ◆ resize()

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

Resize a 2D image, applying the appropriate filter.

## ◆ calculateSize()

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

Static function to calculate size in bytes from the number of mipmaps, faces and the dimensions.

## ◆ getFileExtFromMagic()

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

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

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

- OgreImage.h