Kanzi  3.9.7
Kanzi Engine API
kanzi::BitmapImage Class Reference

Image is the basic runtime primitive to load, hold, and convert image data in memory. More...

#include <kanzi/core.ui/bitmap/bitmap_image.hpp>

Public Member Functions

void convert (GraphicsFormat newFormat)
 Converts the graphics format of the image data. More...
 
void flip (ImageFlipAxis axis)
 Flip data over an axis. More...
 
void flipHorizontally ()
 Flips an image horizontally. More...
 
void flipVertically ()
 Flips an image vertically. More...
 
void generateMipmaps ()
 Generates mipmap images for an image. The size of the smallest mipmap image is 1x1 pixels. More...
 
bytegetData ()
 Returns a pointer to the raw image data in memory. More...
 
bytegetData (size_t mipmapLevel)
 Returns a pointer to the raw image data at a specific mipmap level. More...
 
const bytegetData () const
 Returns a const pointer to the raw image data in memory. More...
 
const bytegetData (size_t mipmapLevel) const
 Returns a const pointer to the raw image data at a specific mipmap level. More...
 
GraphicsFormat getDataFormat () const
 Returns the pixel data format of an image. More...
 
GraphicsFormat getDataFormat (size_t mipmapLevel) const
 Returns the pixel data format at specified mipmap level. More...
 
size_t getDataSize () const
 Returns the size of image data in bytes. More...
 
size_t getDataSize (size_t mipmapLevel) const
 Returns the size of image data at a specific mipmap level in bytes. More...
 
unsigned int getHeight () const
 Returns the height of an image in pixels. More...
 
unsigned int getHeight (size_t mipmapLevel) const
 Returns the height of a an image in pixels at specific mipmap level. More...
 
size_t getMipmapLevelCount () const
 Returns the count of mipmap levels held by this image. More...
 
string_view getName () const
 Gets the name of an image. More...
 
unsigned int getWidth () const
 Returns the width of an image in pixels. More...
 
unsigned int getWidth (size_t mipmapLevel) const
 Returns the width of a an image in pixels at specific mipmap level. More...
 
bool isCompressedFormat () const
 Returns whether an image uses a compressed format. More...
 
void premultiplyAlpha ()
 Premultiplies the color and luminance channels by the alpha channel. More...
 
void resetData (unsigned int newWidth, unsigned int newHeight, GraphicsFormat newFormat)
 Resets an image with a new width, height, and data format. More...
 
void resize (unsigned int newWidth, unsigned int newHeight, ImageResizeFilter resizeFilter)
 Resizes the image and discards any existing mipmap images. More...
 
void setName (string_view name)
 Sets the name for an image. More...
 

Static Public Member Functions

static BitmapImageUniquePtr createCopy (const BitmapImage &image)
 Creates a copy of an image. More...
 
static BitmapImageUniquePtr createEmpty (unsigned int width, unsigned int height, GraphicsFormat format, string_view name="")
 Creates an empty image, initializes all pixel data to zero. More...
 
static BitmapImageUniquePtr createEmptyMipmapped (unsigned int width, unsigned int height, GraphicsFormat format, string_view name="")
 Creates an empty image with empty mipmaps, initializes all pixel data to zero. More...
 
static BitmapImageUniquePtr createFromMemory (unsigned int width, unsigned int height, GraphicsFormat format, const byte *data, string_view name="")
 Creates an image by copying the pixel data from memory. More...
 
static BitmapImageUniquePtr createFromMemoryFlipped (unsigned int width, unsigned int height, GraphicsFormat format, const byte *data, ImageFlipAxis axis, string_view name="")
 Creates an image by copying the pixel data from memory. More...
 
static BitmapImageUniquePtr createMipmapped (BitmapImageVector mipmapImages)
 Creates a mipmapped image from a vector of mipmap level images. More...
 

Protected Member Functions

 BitmapImage ()
 Constructs an image with all members set to zero. More...
 
 BitmapImage (unsigned int width, unsigned int height, GraphicsFormat format, bool mipmaps, string_view name="")
 Constructs an image with data set to all zeroes. More...
 
void setMipmapLevels (BitmapImageVector images)
 Replaces the mipmap level images for an image. More...
 

Static Protected Member Functions

static BitmapImageUniquePtr createCopyMoveData (BitmapImage *other)
 Kanzi internally uses this function to create a copy of an image by moving over the image data. More...
 

Detailed Description

Image is the basic runtime primitive to load, hold, and convert image data in memory.

Each image has width, height, pixel format, image data in memory, and can contain mipmap images.

To display an image, you must create a texture instance from that image. When you do so, you must transfer the ownership of the image to the texture instance using Texture::CreateInfo2D.

See also
Texture

Examples

To load an image from a file and make a texture out of it:

// Load an image file and create a texture out of it.
TextureSharedPtr texture = domain->getResourceManager()->acquireResource<Texture>(string("file://") + filePath);

To create an image from pixel data in memory:

// Fill image data with opaque red.
unique_ptr<uint8_t[]> sourceData(new uint8_t[512 * 512 * 4]);
for (unsigned it = 0; it < 512 * 512 * 4; it += 4)
{
sourceData[it + 0] = 255u;
sourceData[it + 1] = 0u;
sourceData[it + 2] = 0u;
sourceData[it + 3] = 255u;
}
// Create an image.
BitmapImage* imagePtr = image.get();
// Create a texture from the image. This texture keeps the ownership of the image.
// This means that the image is also automatically destroyed when the texture is destroyed.
Texture::CreateInfo2D createInfo(kanzi::move(image));
createInfo.memoryType = GPUResource::GpuAndRam;
TextureSharedPtr texture = Texture::create(domain, createInfo, "Texture");
// Get the host copy of the image you created. In this case the getHostCopyImage() returns a
// pointer that is identical to the variable imagePtr you created above.
BitmapImageSharedPtr hostCopyImage = texture->getHostCopyImage();

Constructor & Destructor Documentation

kanzi::BitmapImage::BitmapImage ( )
explicitprotected

Constructs an image with all members set to zero.

kanzi::BitmapImage::BitmapImage ( unsigned int  width,
unsigned int  height,
GraphicsFormat  format,
bool  mipmaps,
string_view  name = "" 
)
explicitprotected

Constructs an image with data set to all zeroes.

Parameters
widthWidth of the image in pixels.
heightHeight of the image in pixels.
formatGraphics format to use.
mipmapsIndicates whether to allocate data for mipmaps.
name(Optional) A name for the image.

Member Function Documentation

unsigned int kanzi::BitmapImage::getWidth ( ) const

Returns the width of an image in pixels.

Returns
The width of the image in pixels.
unsigned int kanzi::BitmapImage::getWidth ( size_t  mipmapLevel) const

Returns the width of a an image in pixels at specific mipmap level.

Parameters
mipmapLevelThe wanted mipmap level, 0 being base level.
Returns
The width of the specified mipmap image in pixels.
unsigned int kanzi::BitmapImage::getHeight ( ) const

Returns the height of an image in pixels.

Returns
The height of the image in pixels.
unsigned int kanzi::BitmapImage::getHeight ( size_t  mipmapLevel) const

Returns the height of a an image in pixels at specific mipmap level.

Parameters
mipmapLevelThe wanted mipmap level, 0 being base level.
Returns
The height of the specified mipmap image in pixels.
void kanzi::BitmapImage::resetData ( unsigned int  newWidth,
unsigned int  newHeight,
GraphicsFormat  newFormat 
)

Resets an image with a new width, height, and data format.

This function discards the current image data.

See also
To reformat an image, use the convert function.
To resize an image, use the resize function.
Parameters
newWidthNew width of the image in pixels.
newHeightNew height of the image in pixels.
newFormatNew pixel format for the image.
GraphicsFormat kanzi::BitmapImage::getDataFormat ( ) const

Returns the pixel data format of an image.

Returns
The pixel data format of the image.
GraphicsFormat kanzi::BitmapImage::getDataFormat ( size_t  mipmapLevel) const

Returns the pixel data format at specified mipmap level.

Parameters
mipmapLevelThe wanted mipmap level, 0 being base level.
Returns
Data format from given mipmap level.
byte* kanzi::BitmapImage::getData ( )

Returns a pointer to the raw image data in memory.

Returns
A pointer to the image data.
byte* kanzi::BitmapImage::getData ( size_t  mipmapLevel)

Returns a pointer to the raw image data at a specific mipmap level.

Parameters
mipmapLevelThe wanted mipmap level, 0 being base level.
Returns
A pointer to the mipmap level image data.
const byte* kanzi::BitmapImage::getData ( ) const

Returns a const pointer to the raw image data in memory.

Returns
A const pointer to the raw image data.
const byte* kanzi::BitmapImage::getData ( size_t  mipmapLevel) const

Returns a const pointer to the raw image data at a specific mipmap level.

Parameters
mipmapLevelThe wanted mipmap level, 0 being base level.
Returns
A const pointer to the mipmap level image data.
size_t kanzi::BitmapImage::getDataSize ( ) const

Returns the size of image data in bytes.

Returns
Size of the image data in bytes.
size_t kanzi::BitmapImage::getDataSize ( size_t  mipmapLevel) const

Returns the size of image data at a specific mipmap level in bytes.

Parameters
mipmapLevelThe wanted mipmap level, 0 being base level.
Returns
Size of the mipmap level image data in bytes.
size_t kanzi::BitmapImage::getMipmapLevelCount ( ) const

Returns the count of mipmap levels held by this image.

For the images that have only the base level and no mipmaps, the level count is 1. This function never returns 0.

Returns
Count of mipmap levels.
void kanzi::BitmapImage::setName ( string_view  name)

Sets the name for an image.

Images can have empty names and the names do not have to be unique.

Parameters
nameThe name of the image.
string_view kanzi::BitmapImage::getName ( ) const

Gets the name of an image.

Images can have empty names and the names do not have to be unique.

Returns
The name of the image.
bool kanzi::BitmapImage::isCompressedFormat ( ) const

Returns whether an image uses a compressed format.

You cannot resize or flip compressed images.

Returns
True if the image uses a compressed format, otherwise False.
void kanzi::BitmapImage::resize ( unsigned int  newWidth,
unsigned int  newHeight,
ImageResizeFilter  resizeFilter 
)

Resizes the image and discards any existing mipmap images.

You cannot resize images that use a compressed format. To check whether an image uses a compressed format, use the isCompressedFormat function.

Parameters
newWidthNew width of the image in pixels.
newHeightNew height of the image in pixels.
resizeFilterThe resize filter to use. This affects the quality of the resized image.
void kanzi::BitmapImage::flip ( ImageFlipAxis  axis)

Flip data over an axis.

You cannot flip images that use a compressed format. To check whether an image uses a compressed format, use the isCompressedFormat function.

Parameters
axisAxis to flip over.
void kanzi::BitmapImage::flipHorizontally ( )
inline

Flips an image horizontally.

See also
flip().
void kanzi::BitmapImage::flipVertically ( )
inline

Flips an image vertically.

See also
flip().
void kanzi::BitmapImage::premultiplyAlpha ( )

Premultiplies the color and luminance channels by the alpha channel.

void kanzi::BitmapImage::generateMipmaps ( )

Generates mipmap images for an image. The size of the smallest mipmap image is 1x1 pixels.

void kanzi::BitmapImage::convert ( GraphicsFormat  newFormat)

Converts the graphics format of the image data.

Parameters
newFormatThe graphics format to which you want to convert the image data.
static BitmapImageUniquePtr kanzi::BitmapImage::createCopy ( const BitmapImage image)
static

Creates a copy of an image.

Allocates and rewrites all image data, including mipmaps.

Parameters
imageThe image you want to copy.
Returns
Unique pointer to the copied image.
static BitmapImageUniquePtr kanzi::BitmapImage::createFromMemory ( unsigned int  width,
unsigned int  height,
GraphicsFormat  format,
const byte data,
string_view  name = "" 
)
static

Creates an image by copying the pixel data from memory.

Parameters
widthThe width in pixels.
heightThe height in pixels.
formatThe graphics format.
dataThe pixel data to copy. Must cover the width * height * bytes_per_pixel of memory.
name(Optional) A name for the image.
Returns
Unique pointer to the created image.
static BitmapImageUniquePtr kanzi::BitmapImage::createFromMemoryFlipped ( unsigned int  width,
unsigned int  height,
GraphicsFormat  format,
const byte data,
ImageFlipAxis  axis,
string_view  name = "" 
)
static

Creates an image by copying the pixel data from memory.

Parameters
widthThe width in pixels.
heightThe height in pixels.
formatThe graphics format.
dataThe pixel data to copy. Must cover the width * height * bytes_per_pixel of memory.
axisAxis to flip over.
name(Optional) A name for the image.
Returns
Unique pointer to the created image.
static BitmapImageUniquePtr kanzi::BitmapImage::createEmpty ( unsigned int  width,
unsigned int  height,
GraphicsFormat  format,
string_view  name = "" 
)
static

Creates an empty image, initializes all pixel data to zero.

Parameters
widthThe width in pixels.
heightThe height in pixels.
formatThe graphics format.
name(Optional) A name for the image.
Returns
Unique pointer to the created image.
static BitmapImageUniquePtr kanzi::BitmapImage::createEmptyMipmapped ( unsigned int  width,
unsigned int  height,
GraphicsFormat  format,
string_view  name = "" 
)
static

Creates an empty image with empty mipmaps, initializes all pixel data to zero.

Parameters
widthThe width in pixels.
heightThe height in pixels.
formatThe graphics format.
name(Optional) A name for the image.
Returns
Unique pointer to the created image.
static BitmapImageUniquePtr kanzi::BitmapImage::createMipmapped ( BitmapImageVector  mipmapImages)
static

Creates a mipmapped image from a vector of mipmap level images.

The first image in the vector is the base level image. The sizes of each consecutive image must be scaled down by the power of two. For example, if the base level image is 128x128, then the sizes of the following images must be 64x64, 32x32, 16x16, 8x8, 4x4, 2x2, and 1x1.

Parameters
mipmapImagesThe mipmap images.
Returns
Unique pointer to the created image.
void kanzi::BitmapImage::setMipmapLevels ( BitmapImageVector  images)
protected

Replaces the mipmap level images for an image.

Parameters
imagesThe mipmap images, including the base level image.
static BitmapImageUniquePtr kanzi::BitmapImage::createCopyMoveData ( BitmapImage other)
staticprotected

Kanzi internally uses this function to create a copy of an image by moving over the image data.

This invalidates the original image.

Parameters
[in,out]otherThe image to copy.
Returns
Unique pointer to the copied image.

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