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.

void	flip (ImageFlipAxis axis)
	Flip data over an axis.

void	flipHorizontally ()
	Flips an image horizontally.

void	flipVertically ()
	Flips an image vertically.

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

byte *	getData ()
	Returns a pointer to the raw image data in memory.

const byte *	getData () const
	Returns a const pointer to the raw image data in memory.

byte *	getData (size_t mipmapLevel)
	Returns a pointer to the raw image data at a specific mipmap level.

const byte *	getData (size_t mipmapLevel) const
	Returns a const pointer to the raw image data at a specific mipmap level.

GraphicsFormat	getDataFormat () const
	Returns the pixel data format of an image.

GraphicsFormat	getDataFormat (size_t mipmapLevel) const
	Returns the pixel data format at specified mipmap level.

size_t	getDataSize () const
	Returns the size of image data in bytes.

size_t	getDataSize (size_t mipmapLevel) const
	Returns the size of image data at a specific mipmap level in bytes.

unsigned int	getHeight () const
	Returns the height of an image in pixels.

unsigned int	getHeight (size_t mipmapLevel) const
	Returns the height of a an image in pixels at specific mipmap level.

size_t	getMipmapLevelCount () const
	Returns the count of mipmap levels held by this image.

string_view	getName () const
	Gets the name of an image.

unsigned int	getWidth () const
	Returns the width of an image in pixels.

unsigned int	getWidth (size_t mipmapLevel) const
	Returns the width of a an image in pixels at specific mipmap level.

bool	isCompressedFormat () const
	Returns whether an image uses a compressed format.

void	premultiplyAlpha ()
	Premultiplies the color and luminance channels by the alpha channel.

void	resetData (unsigned int newWidth, unsigned int newHeight, GraphicsFormat newFormat)
	Resets an image with a new width, height, and data format.

void	resize (unsigned int newWidth, unsigned int newHeight, ImageResizeFilter resizeFilter)
	Resizes the image and discards any existing mipmap images.

void	setName (string_view name)
	Sets the name for an image.

Static Public Member Functions
static BitmapImageUniquePtr	createCopy (const BitmapImage &image)
	Creates a copy of an image.

static BitmapImageUniquePtr	createEmpty (unsigned int width, unsigned int height, GraphicsFormat format, string_view name="")
	Creates an empty image, initializes all pixel data to zero.

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.

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.

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.

static BitmapImageUniquePtr	createMipmapped (BitmapImageVector mipmapImages)
	Creates a mipmapped image from a vector of mipmap level images.

Protected Member Functions
	BitmapImage ()
	Constructs an image with all members set to zero.

	BitmapImage (unsigned int width, unsigned int height, GraphicsFormat format, bool mipmaps, string_view name="")
	Constructs an image with data set to all zeroes.

void	setMipmapLevels (BitmapImageVector images)
	Replaces the mipmap level images for an image.

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.

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.
            BitmapImageUniquePtr image = BitmapImage::createFromMemory(512, 512, GraphicsFormatR8G8B8A8_UNORM, sourceData.get(), "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

◆ BitmapImage() [1/2]

kanzi::BitmapImage::BitmapImage ( )

explicitprotected

Constructs an image with all members set to zero.

◆ BitmapImage() [2/2]

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

width	Width of the image in pixels.
height	Height of the image in pixels.
format	Graphics format to use.
mipmaps	Indicates whether to allocate data for mipmaps.
name	(Optional) A name for the image.

Member Function Documentation

◆ getWidth() [1/2]

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

Returns the width of an image in pixels.

Returns: The width of the image in pixels.

◆ getWidth() [2/2]

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

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

Parameters

mipmapLevel The wanted mipmap level, 0 being base level.

Returns: The width of the specified mipmap image in pixels.

◆ getHeight() [1/2]

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

Returns the height of an image in pixels.

Returns: The height of the image in pixels.

◆ getHeight() [2/2]

unsigned int kanzi::BitmapImage::getHeight ( size_t mipmapLevel ) const

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

Parameters

mipmapLevel The wanted mipmap level, 0 being base level.

Returns: The height of the specified mipmap image in pixels.

◆ resetData()

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

newWidth	New width of the image in pixels.
newHeight	New height of the image in pixels.
newFormat	New pixel format for the image.

◆ getDataFormat() [1/2]

GraphicsFormat kanzi::BitmapImage::getDataFormat ( ) const

Returns the pixel data format of an image.

Returns: The pixel data format of the image.

◆ getDataFormat() [2/2]

GraphicsFormat kanzi::BitmapImage::getDataFormat ( size_t mipmapLevel ) const

Returns the pixel data format at specified mipmap level.

Parameters

mipmapLevel The wanted mipmap level, 0 being base level.

Returns: Data format from given mipmap level.

◆ getData() [1/4]

byte * kanzi::BitmapImage::getData ( )

Returns a pointer to the raw image data in memory.

Returns: A pointer to the image data.

◆ getData() [2/4]

byte * kanzi::BitmapImage::getData ( size_t mipmapLevel )

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

Parameters

mipmapLevel The wanted mipmap level, 0 being base level.

Returns: A pointer to the mipmap level image data.

◆ getData() [3/4]

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.

◆ getData() [4/4]

const byte * kanzi::BitmapImage::getData ( size_t mipmapLevel ) const

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

Parameters

mipmapLevel The wanted mipmap level, 0 being base level.

Returns: A const pointer to the mipmap level image data.

◆ getDataSize() [1/2]

size_t kanzi::BitmapImage::getDataSize ( ) const

Returns the size of image data in bytes.

Returns: Size of the image data in bytes.

◆ getDataSize() [2/2]

size_t kanzi::BitmapImage::getDataSize ( size_t mipmapLevel ) const

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

Parameters

mipmapLevel The wanted mipmap level, 0 being base level.

Returns: Size of the mipmap level image data in bytes.

◆ getMipmapLevelCount()

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.

◆ setName()

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

name	The name of the image.

◆ getName()

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.

◆ isCompressedFormat()

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.

◆ resize()

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

newWidth	New width of the image in pixels.
newHeight	New height of the image in pixels.
resizeFilter	The resize filter to use. This affects the quality of the resized image.

◆ flip()

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

axis	Axis to flip over.

◆ flipHorizontally()

void kanzi::BitmapImage::flipHorizontally ( )

inline

Flips an image horizontally.

See also: flip().

◆ flipVertically()

void kanzi::BitmapImage::flipVertically ( )

inline

Flips an image vertically.

See also: flip().

◆ premultiplyAlpha()

void kanzi::BitmapImage::premultiplyAlpha ( )

Premultiplies the color and luminance channels by the alpha channel.

◆ generateMipmaps()

void kanzi::BitmapImage::generateMipmaps ( )

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

◆ convert()

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

Converts the graphics format of the image data.

Parameters

newFormat The graphics format to which you want to convert the image data.

◆ createCopy()

static BitmapImageUniquePtr kanzi::BitmapImage::createCopy ( const BitmapImage & image )

static

Creates a copy of an image.

Allocates and rewrites all image data, including mipmaps.

Parameters

image The image you want to copy.

Returns: Unique pointer to the copied image.

◆ createFromMemory()

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

width	The width in pixels.
height	The height in pixels.
format	The graphics format.
data	The 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.

◆ createFromMemoryFlipped()

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

width	The width in pixels.
height	The height in pixels.
format	The graphics format.
data	The pixel data to copy. Must cover the width * height * bytes_per_pixel of memory.
axis	Axis to flip over.
name	(Optional) A name for the image.

Returns: Unique pointer to the created image.

◆ createEmpty()

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

width	The width in pixels.
height	The height in pixels.
format	The graphics format.
name	(Optional) A name for the image.

Returns: Unique pointer to the created image.

◆ createEmptyMipmapped()

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

width	The width in pixels.
height	The height in pixels.
format	The graphics format.
name	(Optional) A name for the image.

Returns: Unique pointer to the created image.

◆ createMipmapped()

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

mipmapImages The mipmap images.

Returns: Unique pointer to the created image.

◆ setMipmapLevels()

void kanzi::BitmapImage::setMipmapLevels ( BitmapImageVector images )

protected

Replaces the mipmap level images for an image.

Parameters

images The mipmap images, including the base level image.

◆ createCopyMoveData()

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] other The image to copy.

Returns: Unique pointer to the copied image.

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

kanzi/core.ui/bitmap/bitmap_image.hpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

Examples

Constructor & Destructor Documentation

◆ BitmapImage() [1/2]

◆ BitmapImage() [2/2]

Member Function Documentation

◆ getWidth() [1/2]

◆ getWidth() [2/2]

◆ getHeight() [1/2]

◆ getHeight() [2/2]

◆ resetData()

◆ getDataFormat() [1/2]

◆ getDataFormat() [2/2]

◆ getData() [1/4]

◆ getData() [2/4]

◆ getData() [3/4]

◆ getData() [4/4]

◆ getDataSize() [1/2]

◆ getDataSize() [2/2]

◆ getMipmapLevelCount()

◆ setName()

◆ getName()

◆ isCompressedFormat()

◆ resize()

◆ flip()

◆ flipHorizontally()

◆ flipVertically()

◆ premultiplyAlpha()

◆ generateMipmaps()

◆ convert()

◆ createCopy()

◆ createFromMemory()

◆ createFromMemoryFlipped()

◆ createEmpty()

◆ createEmptyMipmapped()

◆ createMipmapped()

◆ setMipmapLevels()

◆ createCopyMoveData()