OGRE  2.2.4
Object-Oriented Graphics Rendering Engine
Ogre::Image Class Reference

Class representing an image file. More...

#include <OgreImage.h>

+ Inheritance diagram for Ogre::Image:

Public Types

typedef Ogre::Box Box
 
enum  Filter {
  FILTER_NEAREST, FILTER_LINEAR, FILTER_BILINEAR, FILTER_BOX,
  FILTER_TRIANGLE, FILTER_BICUBIC, FILTER_GAUSSIAN, FILTER_GAUSSIAN_HIGH
}
 
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...
 
ImagecombineTwoImagesAsRGBA (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...
 
ImageflipAroundX ()
 Flips (mirrors) the image around the X-axis. More...
 
ImageflipAroundY ()
 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...
 
bool generateMipmaps (bool gammaCorrected, Filter filter=FILTER_BILINEAR)
 Generates the mipmaps for this image. 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...
 
uchargetData (void)
 Returns a pointer to the internal image buffer. More...
 
const uchargetData () 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...
 
uint8 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...
 
Imageload (const String &filename, const String &groupName)
 Loads an image file. More...
 
Imageload (DataStreamPtr &stream, const String &type=BLANKSTRING)
 Loads an image file from a stream. More...
 
ImageloadDynamicImage (uchar *data, uint32 width, uint32 height, uint32 depth, PixelFormat format, bool autoDelete=false, size_t numFaces=1, uint8 numMipMaps=0)
 Stores a pointer to raw data in memory. More...
 
ImageloadDynamicImage (uchar *data, uint32 width, uint32 height, PixelFormat format)
 Stores a pointer to raw data in memory. More...
 
ImageloadRawData (DataStreamPtr &stream, uint32 width, uint32 height, uint32 depth, PixelFormat format, size_t numFaces=1, size_t numMipMaps=0)
 Loads raw data from a stream. More...
 
ImageloadRawData (DataStreamPtr &stream, uint32 width, uint32 height, PixelFormat format)
 Loads raw data from a stream. More...
 
ImageloadTwoImagesAsRGBA (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...
 
ImageloadTwoImagesAsRGBA (DataStreamPtr &rgbStream, 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...
 
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)
 
Imageoperator= (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 Typedef Documentation

◆ Box

◆ Rect

Member Enumeration Documentation

◆ Filter

Enumerator
FILTER_NEAREST 
FILTER_LINEAR 
FILTER_BILINEAR 
FILTER_BOX 
FILTER_TRIANGLE 
FILTER_BICUBIC 
FILTER_GAUSSIAN 

Applies gaussian filter over the image, then a point sampling reduction This is done at the same time (i.e.

we don't blur pixels we ignore).

FILTER_GAUSSIAN_HIGH 

Applies gaussian filter over the image, then bilinear downsamples.

This prevents certain artifacts for some images when using FILTER_GAUSSIAN, like biasing towards certain direction. Not supported by cubemaps.

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

virtual Ogre::Image::~Image ( )
virtual

Standard destructor.

Member Function Documentation

◆ 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

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

◆ 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
rgbImage supplying the RGB channels (any alpha is ignored)
alphaImage 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.
formatThe destination format

◆ encode()

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

Encode the image and return a stream to the data.

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

◆ 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
    

◆ 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
    

◆ freeMemory()

void Ogre::Image::freeMemory ( )

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

◆ generateMipmaps()

bool Ogre::Image::generateMipmaps ( bool  gammaCorrected,
Filter  filter = FILTER_BILINEAR 
)

Generates the mipmaps for this image.

For Cubemaps, the filtering is seamless; and a gaussian filter is recommended although it's slow.

Remarks
Cannot handle compressed formats. Gaussian filter is implemented with a generic 1-pass convolution matrix, which in turn means it is O( N^N ) instead of a 2-pass filter which is O( 2^N ); where N is the number of taps. The Gaussian filter is 5x5
Parameters
gammaCorrectedTrue if the filter should be applied in linear space.
filterThe type of filter to use.
Returns
False if failed to generate and mipmaps properties won't be changed. True on success.

◆ getBPP()

uchar Ogre::Image::getBPP ( ) const

Returns the number of bits per pixel.

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

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

◆ getDepth()

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

Gets the depth of the image.

◆ getFileExtFromMagic()

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

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

◆ getFormat()

PixelFormat Ogre::Image::getFormat ( ) const

Returns the image format.

◆ getHasAlpha()

bool Ogre::Image::getHasAlpha ( ) const

Returns true if the image has an alpha component.

◆ getHeight()

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

Gets the height of the image in pixels.

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

◆ getNumMipmaps()

uint8 Ogre::Image::getNumMipmaps ( ) const

Returns the number of mipmaps contained in the image.

◆ getPixelBox()

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

Get a PixelBox encapsulating the image data of a mipmap.

◆ getRowSpan()

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

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

◆ getSize()

size_t Ogre::Image::getSize ( ) const

Returns the size of the data buffer.

◆ getWidth()

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

Gets the width of the image in pixels.

◆ hasFlag()

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

Returns true if the image has the appropriate flag set.

◆ 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
filenameName of an image file to load.
groupNameName 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 ( 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
streamThe source data.
typeThe 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 )

◆ loadDynamicImage() [1/2]

Image& Ogre::Image::loadDynamicImage ( uchar data,
uint32  width,
uint32  height,
uint32  depth,
PixelFormat  format,
bool  autoDelete = false,
size_t  numFaces = 1,
uint8  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
dataThe data pointer
widthWidth of image
heightHeight of image
depthImage Depth (in 3d images, numbers of layers, otherwise 1)
formatPixel Format
autoDeleteIf 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.
numFacesThe number of faces the image data has inside (6 for cubemaps, 1 otherwise)
numMipMapsThe 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

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
dataThe data pointer
widthWidth of image
heightHeight of image
formatPixel 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.

◆ loadRawData() [1/2]

Image& Ogre::Image::loadRawData ( DataStreamPtr stream,
uint32  width,
uint32  height,
uint32  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.

◆ loadRawData() [2/2]

Image& Ogre::Image::loadRawData ( DataStreamPtr stream,
uint32  width,
uint32  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.

References Ogre::BLANKSTRING, and Ogre::PF_BYTE_RGBA.

◆ 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
rgbFilenameFilename of image supplying the RGB channels (any alpha is ignored)
alphaFilenameFilename 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.
groupNameThe resource group from which to load the images
formatThe destination format

◆ loadTwoImagesAsRGBA() [2/2]

Image& Ogre::Image::loadTwoImagesAsRGBA ( DataStreamPtr rgbStream,
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
rgbStreamStream of image supplying the RGB channels (any alpha is ignored)
alphaStreamStream 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.
formatThe destination format
rgbTypeThe 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.
alphaTypeThe 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.

◆ operator delete() [1/3]

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

◆ operator delete() [2/3]

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

◆ operator delete() [3/3]

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

◆ operator delete[]() [1/2]

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

◆ operator delete[]() [2/2]

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

◆ operator new() [1/3]

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

◆ operator new() [2/3]

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

◆ operator new() [3/3]

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

placement operator new

◆ operator new[]() [1/2]

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

◆ operator new[]() [2/2]

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

◆ operator=()

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

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

◆ resize()

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

Resize a 2D image, applying the appropriate filter.

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

◆ 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
srcPixelBox containing the source pointer, dimensions and format
dstPixelBox containing the destination pointer, dimensions and format
filterWhich 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

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


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