OGRE-Next: Ogre::Image2 Class Reference

| OGRE-Next 3.0.0 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | List of all members
Ogre::Image2 Class Reference
Core » Image

Class representing an image file. More...

`#include <OgreImage2.h>`

Inheritance diagram for Ogre::Image2:
[legend]

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

## Public Member Functions
| Image2 ()
| Image2 (const Image2 &img)
| Copy-constructor - copies all the data from the target image.
virtual | ~Image2 ()
void | _setAutoDelete (bool autoDelete)
void | convertFromTexture (TextureGpu *texture, uint8 minMip, uint8 maxMip, bool automaticResolve=true)
| Synchronously downloads the selected mips from a TextureGpu into this Image.
void | createEmptyImage (uint32 width, uint32 height, uint32 depthOrSlices, TextureTypes::TextureTypes textureType, PixelFormatGpu format, uint8 numMipmaps=1u)
| Convenience function.
void | createEmptyImageLike (const TextureGpu *texture)
| Same as createEmptyImage, but retrieves all metadata parameters from the input texture.
DataStreamPtr | encode (const String &formatextension, uint8 mipLevel, uint8 numMipmaps)
| Encode the image and return a stream to the data.
void | flipAroundX ()
| Flips (mirrors) the image around the X-axis.
void | flipAroundY ()
| Flips (mirrors) the image around the Y-axis.
void | freeMemory ()
| Delete all the memory held by this image, if owned by this image (not dynamic)
bool | generateMipmaps (bool gammaCorrected, Filter filter=FILTER_BILINEAR)
| Generates the mipmaps for this image.
bool | getAutoDelete () const
size_t | getBytesPerImage (uint8 mipLevel) const
uint32 | getBytesPerRow (uint8 mipLevel) const
ColourValue | getColourAt (size_t x, size_t y, size_t z, uint8 mipLevel=0) const
| Get colour value from a certain location in the image.
TextureBox | getData (uint8 mipLevel) const
| Returns a pointer to the internal image buffer.
uint32 | getDepth () const
| For TypeCube & TypeCubeArray, this value returns 1.
uint32 | getDepthOrSlices () const
uint32 | getHeight () const
uint8 | getNumMipmaps () const
uint32 | getNumSlices () const
| For TypeCube this value returns 6.
PixelFormatGpu | getPixelFormat () const
void * | getRawBuffer ()
size_t | getSizeBytes () const
| Returns total size in bytes used in GPU by this texture including mipmaps.
TextureTypes::TextureTypes | getTextureType () const
uint32 | getWidth () const
void | load (const String &filename, const String &groupName)
| Loads an image file.
void | load (DataStreamPtr &stream, const String &type=BLANKSTRING)
| Loads an image file from a stream.
void | load2 (DataStreamPtr &stream, const String &filename)
| Same as load() as but we will try to find the codec by both magic numbers and extension The original load() only allows to either use magic number OR name extension This version tries both.
void | loadDynamicImage (void *pData, bool autoDelete, const Image2 *image)
void | loadDynamicImage (void *pData, bool autoDelete, const TextureGpu *texture)
| Convenience function.
void | loadDynamicImage (void *pData, uint32 width, uint32 height, uint32 depthOrSlices, TextureTypes::TextureTypes textureType, PixelFormatGpu format, bool autoDelete, uint8 numMipmaps=1u)
| Stores a pointer to raw data in memory.
Image2 & | operator= (const Image2 &img)
| Assignment operator - copies all the data from the target image.
void | resize (uint32 width, uint32 height, Filter filter=FILTER_BILINEAR)
| Resize a 2D image, applying the appropriate filter.
void | save (const String &filename, uint8 mipLevel, uint8 numMipmaps)
| Save the image as a file.
void | setColourAt (const ColourValue &cv, size_t x, size_t y, size_t z, uint8 mipLevel=0)
| Set colour value at a certain location in the image.
void | uploadTo (TextureGpu *texture, uint8 minMip, uint8 maxMip, uint32 dstZorSliceStart=0u, uint32 srcDepthOrSlices=0u)
| Synchronously uploads the selected mips from this Image into a TextureGpu.

## Static Public Member Functions
static void | copyContentsToMemory (TextureGpu *srcTexture, TextureBox srcBox, TextureBox dstBox, PixelFormatGpu dstFormat, bool automaticResolve=true)
| Synchronously downloads the mip 0 from a TextureGpu into the TextureBox.
static bool | getDownsamplerFunctions (PixelFormatGpu format, void **imageDownsampler2D, void **imageDownsampler3D, void **imageDownsamplerCube, void **imageBlur2D, bool gammaCorrected, uint32 depthOrSlices, TextureTypes::TextureTypes textureType, Filter filter)
| Sets the proper downsampler functions to generate mipmaps.
static String | getFileExtFromMagic (DataStreamPtr &stream)
| Static function to get an image type string from a stream via magic numbers.
static void | scale (const TextureBox &src, PixelFormatGpu srcFormat, TextureBox &dst, PixelFormatGpu dstFormat, Filter filter=FILTER_BILINEAR)
| Scale a 1D, 2D or 3D image volume.
static bool | supportsSwMipmaps (PixelFormatGpu format, uint32 depthOrSlices, TextureTypes::TextureTypes textureType, Filter filter)

## 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::Image2::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

## ◆ Image2() [1/2]

Ogre::Image2::Image2 | ( |  | ) |

Referenced by Image2(), loadDynamicImage(), and operator=().

## ◆ Image2() [2/2]

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

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

References Image2().

## ◆ ~Image2()

virtual Ogre::Image2::~Image2 | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ _setAutoDelete()

void Ogre::Image2::_setAutoDelete | ( | bool | autoDelete | ) |

## ◆ convertFromTexture()

void Ogre::Image2::convertFromTexture | ( | TextureGpu * | texture,
|  | uint8 | minMip,
|  | uint8 | maxMip,
|  | bool | automaticResolve = true )

Synchronously downloads the selected mips from a TextureGpu into this Image.

This function is for convenience for when going async is not important.

Parameters

  minMip | First mipmap to download, inclusive.
  maxMip | Last mipmap to download, inclusive.
  automaticResolve | When true, we will take care of resolving explicit MSAA textures if necessary, so that the download from GPU works fine.

## ◆ copyContentsToMemory()

static void Ogre::Image2::copyContentsToMemory | ( | TextureGpu * | srcTexture,
|  | TextureBox | srcBox,
|  | TextureBox | dstBox,
|  | PixelFormatGpu | dstFormat,
|  | bool | automaticResolve = true )
| static

Synchronously downloads the mip 0 from a TextureGpu into the TextureBox.

This function is for convenience for when going async is not important.

Parameters

  srcBox | Source region of source texture to download. Only x, y, z, sliceStart, width, height, depth, numSlices fields are used.
  dstBox | Together with dstFormat describes the destination memory region. It is explicitly allowed for this region to be non-contiguous.
  dstFormat | Together with dstBox describes the destination memory region. This format is not required to be the same as the format of the source texture, it could be any supported by bulkPixelConversion, including 24bpp formats.
  automaticResolve | When true, we will take care of resolving explicit MSAA textures if necessary, so that the download from GPU works fine.

## ◆ createEmptyImage()

void Ogre::Image2::createEmptyImage | ( | uint32 | width,
|  | uint32 | height,
|  | uint32 | depthOrSlices,
|  | TextureTypes::TextureTypes | textureType,
|  | PixelFormatGpu | format,
|  | uint8 | numMipmaps = 1u )

Convenience function.

Same as Image2::loadDynamicImage, but allocates an uninitialized pointer to store all data and call loadDynamicImage with it

## ◆ createEmptyImageLike()

void Ogre::Image2::createEmptyImageLike | ( | const TextureGpu * | texture | ) |

Same as createEmptyImage, but retrieves all metadata parameters from the input texture.

## ◆ encode()

DataStreamPtr Ogre::Image2::encode | ( | const String & | formatextension,
|  | uint8 | mipLevel,
|  | uint8 | numMipmaps )

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"

## ◆ flipAroundX()

void Ogre::Image2::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()

void Ogre::Image2::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::Image2::freeMemory | ( |  | ) |

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

## ◆ generateMipmaps()

bool Ogre::Image2::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

  gammaCorrected | True if the filter should be applied in linear space.
  filter | The type of filter to use.

Returns
  False if failed to generate and mipmaps properties won't be changed. True on success.

References FILTER_BILINEAR.

## ◆ getAutoDelete()

bool Ogre::Image2::getAutoDelete | ( |  | ) | const

## ◆ getBytesPerImage()

size_t Ogre::Image2::getBytesPerImage | ( | uint8 | mipLevel | ) | const

## ◆ getBytesPerRow()

uint32 Ogre::Image2::getBytesPerRow | ( | uint8 | mipLevel | ) | const

## ◆ getColourAt()

ColourValue Ogre::Image2::getColourAt | ( | size_t | x,
|  | size_t | y,
|  | size_t | z,
|  | uint8 | mipLevel = 0 ) const

Get colour value from a certain location in the image.

Remarks
  This function is slow as we need to calculate the mipmap offset every time. If you need to call it often, prefer using Image2::getData and then call TextureBox::getColourAt instead.

## ◆ getData()

TextureBox Ogre::Image2::getData | ( | uint8 | mipLevel | ) | const

Returns a pointer to the internal image buffer.

## ◆ getDepth()

uint32 Ogre::Image2::getDepth | ( |  | ) | const

For TypeCube & TypeCubeArray, this value returns 1.

## ◆ getDepthOrSlices()

uint32 Ogre::Image2::getDepthOrSlices | ( |  | ) | const

## ◆ getDownsamplerFunctions()

static bool Ogre::Image2::getDownsamplerFunctions | ( | PixelFormatGpu | format,
|  | void ** | imageDownsampler2D,
|  | void ** | imageDownsampler3D,
|  | void ** | imageDownsamplerCube,
|  | void ** | imageBlur2D,
|  | bool | gammaCorrected,
|  | uint32 | depthOrSlices,
|  | TextureTypes::TextureTypes | textureType,
|  | Filter | filter )
| static

Sets the proper downsampler functions to generate mipmaps.

Parameters

  format |
  imageDownsampler2D | [out]
  imageDownsampler3D | [out]
  imageDownsamplerCube | [out]
  imageBlur2D | [out]
  gammaCorrected | When true, force gamma correction on. If this value is false but format is of the sRGB family, gamma correction will still be used.
  depthOrSlices | Required to properly calculate the return value
  textureType | Required to properly calculate the return value
  filter |

Returns
  True if mipmaps can be generated. False if mipmaps cannot be generated.

## ◆ getFileExtFromMagic()

static String Ogre::Image2::getFileExtFromMagic | ( | DataStreamPtr & | stream | ) |
| static

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

## ◆ getHeight()

uint32 Ogre::Image2::getHeight | ( |  | ) | const

## ◆ getNumMipmaps()

uint8 Ogre::Image2::getNumMipmaps | ( |  | ) | const

## ◆ getNumSlices()

uint32 Ogre::Image2::getNumSlices | ( |  | ) | const

For TypeCube this value returns 6.

For TypeCubeArray, value returns numSlices * 6u.

## ◆ getPixelFormat()

PixelFormatGpu Ogre::Image2::getPixelFormat | ( |  | ) | const

## ◆ getRawBuffer()

void * Ogre::Image2::getRawBuffer | ( |  | ) |
| inline

## ◆ getSizeBytes()

size_t Ogre::Image2::getSizeBytes | ( |  | ) | const

Returns total size in bytes used in GPU by this texture including mipmaps.

## ◆ getTextureType()

TextureTypes::TextureTypes Ogre::Image2::getTextureType | ( |  | ) | const

## ◆ getWidth()

uint32 Ogre::Image2::getWidth | ( |  | ) | const

## ◆ load() [1/2]

void Ogre::Image2::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.

Referenced by load2().

## ◆ load() [2/2]

void Ogre::Image2::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

  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 )

References Ogre::BLANKSTRING.

## ◆ load2()

void Ogre::Image2::load2 | ( | DataStreamPtr & | stream,
|  | const String & | filename )

Same as load() as but we will try to find the codec by both magic numbers and extension The original load() only allows to either use magic number OR name extension This version tries both.

References load().

## ◆ loadDynamicImage() [1/3]

void Ogre::Image2::loadDynamicImage | ( | void * | pData,
|  | bool | autoDelete,
|  | const Image2 * | image )

References Image2().

## ◆ loadDynamicImage() [2/3]

void Ogre::Image2::loadDynamicImage | ( | void * | pData,
|  | bool | autoDelete,
|  | const TextureGpu * | texture )

Convenience function.

Same as Image2::loadDynamicImage, but retrieves all metadata parameters from the input texture

## ◆ loadDynamicImage() [3/3]

void Ogre::Image2::loadDynamicImage | ( | void * | pData,
|  | uint32 | width,
|  | uint32 | height,
|  | uint32 | depthOrSlices,
|  | TextureTypes::TextureTypes | textureType,
|  | PixelFormatGpu | format,
|  | bool | autoDelete,
|  | uint8 | numMipmaps = 1u )

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.

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)
  - .. remaining mips for face 0 ..
  - face 1, mip 0 (top), width x height (x depth)
  - .. and so on.

Parameters

  pData | The data pointer. Must've been allocated with OGRE_MALLOC_SIMD( sizeBytes, MEMCATEGORY_RESOURCE ); and sizeBytes assumes a pitch with row alignment = 4u; Use PixelFormatGpuUtils::getSizeBytes( width, 1u, 1u, 1u, pixelFormat, 4u ); to get the pitch.
  width | Width of image
  height | Height of image
  depthOrSlices | Image Depth. For 3D images, it's the depth. For cubemaps it must be 6. For cubemap arrays it must be 6 x num_arrays. For the rest it must be 1.
  textureType | The type of the texture.
  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_MALLOC_SIMD with a category of MEMCATEGORY_RESOURCE to ensure the freeing of memory matches up.
  numMipmaps | The number of mipmaps the image data has inside. A value of 0 is invalid.

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

## ◆ operator=()

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

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

References Image2().

## ◆ resize()

void Ogre::Image2::resize | ( | uint32 | width,
|  | uint32 | height,
|  | Filter | filter = FILTER_BILINEAR )

Resize a 2D image, applying the appropriate filter.

References FILTER_BILINEAR.

## ◆ save()

void Ogre::Image2::save | ( | const String & | filename,
|  | uint8 | mipLevel,
|  | uint8 | numMipmaps )

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::Image2::scale | ( | const TextureBox & | src,
|  | PixelFormatGpu | srcFormat,
|  | TextureBox & | dst,
|  | PixelFormatGpu | dstFormat,
|  | 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

References FILTER_BILINEAR.

## ◆ setColourAt()

void Ogre::Image2::setColourAt | ( | const ColourValue & | cv,
|  | size_t | x,
|  | size_t | y,
|  | size_t | z,
|  | uint8 | mipLevel = 0 )

Set colour value at a certain location in the image.

Remarks
  This function is slow as we need to calculate the mipmap offset every time. If you need to call it often, prefer using Image2::getData and then call TextureBox::setColourAt instead.

## ◆ supportsSwMipmaps()

static bool Ogre::Image2::supportsSwMipmaps | ( | PixelFormatGpu | format,
|  | uint32 | depthOrSlices,
|  | TextureTypes::TextureTypes | textureType,
|  | Filter | filter )
| static

## ◆ uploadTo()

void Ogre::Image2::uploadTo | ( | TextureGpu * | texture,
|  | uint8 | minMip,
|  | uint8 | maxMip,
|  | uint32 | dstZorSliceStart = 0u,
|  | uint32 | srcDepthOrSlices = 0u )

Synchronously uploads the selected mips from this Image into a TextureGpu.

This function is for convenience for when going async is not important.

Parameters

  texture | Texture to upload to. Must have the same resolution and same pixel format family as this Image. For simplicity, you can't upload mip 0 of this image into mip 1.
  minMip | First mipmap to upload, inclusive.
  maxMip | Last mipmap to upload, inclusive.
  dstZorSliceStart | Destination offset in the texture (e.g. when dstZorSliceStart = 5, it uploads N slices between [5; 5+N) )
  srcDepthOrSlices | How many slices from this Image2 to upload. Zero to upload all of them.

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

- OgreImage2.h