Unigine::Image Class

Data Storage (Levels, Layers, Faces)#

An image storage contains one or more sub-images with certain dimensions. Each type of image has a specific arrangement of sub-images in its storage. Images can have mipmaps - smaller versions of the same image used to help in sampling and filtering. Each mipmap level has a separate set of sub-images.

Since an image can store multiple sub-images, it is important to be able to identify a specific sub-image in it. Each sub-image can be uniquely identified by the following numbers, depending on the image type:

For images that can have mipmaps, the mipmap level that contains the sub-image.
For Array Images, the array layer that contains the sub-image.
For Cubemap Images, the face within that array layer and mipmap level.

Notice
For Cubemap Array Images, the layer and face are combined into layer-faces.

Therefore, an image can be thought of as a three-dimensional array of sub-image. The first index is the mipmap level, the second is the array layer, and the third is the cube map face. Another way to think of it is that an image has a number of mipmap levels. Each mipmap can have a number of array layers. And each array layer has a number of faces. Every sub-image of an image can therefore be uniquely referenced by the face, layer, and level indices.

Pixels#

The color of each pixel of an image is represented by the Pixel structure. Pixel format is determined by the image file format (see the table below).

Image type	Pixel format
8-bit unsigned formats: R8, RG8, RGB8, RGBA8	Pixel color components are in range from 0 to 255. E.g. Pixel(10, 10, 255, 255) for RGBA8 Color components are accessed via *Pixel.i*
16-bit unsigned formats: R16, RG16, RGB16, RGBA16	Pixel color components are in range from 0 to 65535. Color components are accessed via *Pixel.i*
16-bit float formats: R16F, RG16F, RGB16F, RGBA16F	Pixel color components are in range from 0.0f to 1.0f. Color components are accessed via *Pixel.i*
32-bit float formats: R32F, RG32F, RGB32F, RGBA32F	Pixel color components are in range from 0.0f to 1.0f. Color components are accessed via *Pixel.f*

Usage Example#

This sample component demonstrates how to:

Create an image.
Set color information for each pixel of the image using the Pixel structure.
Save the image to a file.
Get current image format.
Convert the image to another format.
Use the created image as an albedo texture for a material assigned to an object.
Get color information for each pixel of the image using the Pixel structure.

Create a new class named ImageClass and copy .h and .cpp files into respective files of a class. Then assign a property generated for your component to any desired node of the Object type, to see its albedo texture replaced by a new created image.

ImageClass.h

#pragma once
#include <UnigineComponentSystem.h>
class ImageClass :
	public Unigine::ComponentBase
{
public:
	COMPONENT_DEFINE(ImageClass, Unigine::ComponentBase);
	COMPONENT_INIT(init);

private:
	void init();

};

ImageClass.cpp

#include "ImageClass.h"
REGISTER_COMPONENT(ImageClass);

using namespace Unigine;

void ImageClass::init()
{
	// image size parameters
	const int ASPECT_RATIO = 1;
	const int width = 256;
	const int height = width / ASPECT_RATIO;

	ImagePtr image = Image::create();

	// creating an image of the specified size
	image->create2D(width, height, Image::FORMAT_RGBA8);

	// declaring a pixel to store color information
	Image::Pixel pixel;

	for (int x = 0; x < width; x++)
		for (int y = 0; y < height; y++)
		{
			// setting pixel components
			pixel.i.r = x;
			pixel.i.g = 0;
			pixel.i.b = 0;
			pixel.i.a = 195;

			// setting the color of the image pixel at (x,y)
			image->set2D(x, y, pixel);
		}

	// if a node is an object, we set our image as an albedo texture for its material
	if (getNode()->isObject()) {
		ObjectPtr obj = checked_ptr_cast<Object>(getNode());
		MaterialPtr material = obj->getMaterial(0)->inherit();

		// setting our image as an albedo texture of the material
		material->setTextureImage(material->findTexture("albedo"), image);
		obj->setMaterial(material, 0);
	}
	else {
		Log::message("\nNode is not an object!");
	}
	
	// saving our image to a *.DDS file
	image->save("myimage.dds");

	// printing current image format to the console
	Log::message("\nImage format: %s", image->getFormatName());

	// converting our image to the 32-bit float format
	image->convertToFormat(Image::FORMAT_RGBA32F);

	// printing image format after conversion to the console
	Log::message("\nImage format after conversion: %s", image->getFormatName());

	// saving a converted image to a *.DDS file
	image->save("myimage_converted.dds");

	// getting the first pixel for each row of the image and printing its color value to the console
	for (int x = 0; x < width; x++)
	{
		pixel = image->get2D(x, 0);
		Log::message("\nPixel(%d, 0) color = (%f,%f,%f,%f)", x, pixel.f.r, pixel.f.g, pixel.f.b, pixel.f.a);
	}

	// clearing the image
	image->clear();
}

Методы:

Имя	Описание View: Sort by:
*create*	Default constructor.
getNumChannels	Returns the current number of image channels.
getType	Returns the current numerical code of the image type.
getTypeName	Returns the current image type name.
getNumMipmaps	Returns the current number of mipmaps stored with the image.
getNumLayers	Returns the current number of layers in the image.
getNumFaces	Returns the current number of faces in the image.
isLoaded	Returns the current value indicating whether the image is loaded.
getBlockSize	Returns the current compressed image block size.
getPixelSize	Returns the current uncompressed image pixel size.
isCubeType	Returns the current value indicating if the image is cube image.
isArrayType	Returns the current value indicating if the image is of an array type (see *_ARRAY variables).
is3DType	Returns the current value indicating if the image is a 3D image.
is2DType	Returns the current value indicating if the image is a 2D image.
getFormat	Returns the current numerical code of the image format.
getFormatName	Returns the current image format name.
getDepth	Returns the current image depth, in pixels.
getHeight	Returns the current image height, in pixels.
getWidth	Returns the current image width, in pixels.
getPixelsSize	Returns the current size of all pixels of the image.
getNumPixels	Returns the current number of pixels in the image.
setFileCompression	Setter and Getter for file compression type used for the image.
getFileCompression
allocData	Allocates memory for the image data.
clearData	Clears all image data.
set	Sets a value for a pixel by its id.
get	Gens a value for a pixel by its id and puts it to value.
get8F	Returns a set of 8-bit float values stored in the specified image pixel and neighboring ones and puts them to the output vector.
get16F	Returns a set of 16-bit float values stored in the specified image pixel and neighboring ones and puts them to the output vector.
get32F	Returns a set of 32-bit float values stored in the specified image pixel and neighboring ones and puts them to the output vector.
set2D	Sets a color for a given pixel of a 2D image.
get2D	Returns a color of a given pixel of a 2D image.
set2DArray	Sets a color of a given pixel.
get2DArray	Returns a color of a given pixel.
set3D	Sets a color of a given pixel of a 3D image.
get3D	Returns a color of a given pixel of a 3D image.
get3DSmooth	Returns a color of a given pixel obtained using linear interpolation.
isCombinedFormat	Returns a value indicating if the image is stored in a combined format (RGB565, RGBA4, RGB5A1 or RGB10A2).
isCompressedFormat	Returns a value indicating if the image is stored in a compressed format (DXT1, DXT3, DXT5, ATI1, ATI2).
setCube	Sets a color of a given pixel.
getCube	Returns a color of a given pixel.
setCubeArray	Sets a color of a given pixel.
getCubeArray	Returns the color of a given pixel of the cube array image.
getDepth	Returns the image depth on a given mipmap level.
isFloatFormat	Returns a value indicating if the image is stored in a float format (R32F, RG32F, RGB32F or RGBA32F).
getFormat	Returns a numerical code of the image format for the specified format and number of channels.
getFormatName	Returns the name of the image format by the given format ID.
isHalfFormat	Returns a value indicating if the image is stored in a half-float format (R16F, RG16F, RGB16F or RGBA16F).
getHeight	Returns image height on a given mipmap level.
setChannelInt	Sets an integer value for a given image channel.
setChannelFloat	Sets a float value for a given image channel.
swapChannels	Swaps values of two channels with the specified numbers.
getOffset	Returns the image offset on a given mipmap level.
setPixels	Sets image pixels to be taken from the specified source array.
getPixels	Returns the pointer to the array of pixels.
getPixels2D	Returns the pointer to the array of pixels with the given mipmap level for the 2D image.
getPixels2DArray	Returns the pointer to the array of pixels with the given mipmap level and image layer for the 2D Array image.
getPixels3D	Returns the pointer to the array of pixels with the given mipmap level for the 3D image.
getPixelsCube	Returns the pointer to the array of pixels with the given mipmap level for the cube image.
getPixelsCubeArray	Returns the pointer to the array of pixels with the given mipmap level and image layer for the Cube Array image.
getPixelsSize	Returns the size of all pixels for the image of the specified format and size.
isRawFormat	Returns a value indicating if the image is uncompressed (stored in R8, RG8, RGB8, RGBA8, R16, RG16, RGB16, RGBA16, R16F, RG16F, RGB16F, RGBA16F, R32F, RG32F, RGB32F, RGBA32F, RGB565, RGBA4, RGB5A1 or RGB10A2 format).
getSize	Returns the current image size.
getStride	Returns the image stride on a given mipmap level.
getDepthStride	Returns the image depth stride on a given mipmap level.
getTypeName	Returns the name of the image type by its identifier.
isUCharFormat	Returns a value indicating if the image is stored in an unsigned char format (R8, RG8, RGB8, RGBA8, DXT1, DXT3, DXT5, ATI1 or ATI2).
isUShortFormat	Returns a value indicating if the image is stored in an unsigned short format (R16, RG16, RGB16 or RGBA16).
getWidth	Returns the image width on a given mipmap level.
blend	Blends the specified image with the current one.
blur	Filters the image using two-pass Gaussian blur.
sharpen	Sharpens the image.
clear	Clears all data associated with the image and resets its type, format, size to default.
combine	Converts the image to a combined format.
combineMipmaps	Combines the loaded 2D image with the mipmap image.
compare	Compares a region of a specified image with a specified region of the current image.
compress	Converts the image to a compressed format.
convertToFormat	Converts the image to a specified format.
convertToType	Converts the image to a specified type.
assignFrom	Copies the data from the specified source image.
resizeFrom	Copies the data from the specified source image, resizing the source.
copy	Copies data from the specified source image according to the specified layer parameter.
copyFast	Copies a data fragment with specified width, height, and coordinates from the source image.
create2D	Creates an empty 2D image filled with black color.
create2DArray	Creates an empty 2D texture array filled with black color.
create3D	Creates an empty 3D image filled with black color.
create3DTurbulence	Creates a 3D turbulence image (RGBA8).
createCube	Creates the empty cube image filled with black color.
createCubeArray	Creates the empty cube array image filled with black color.
createMipmaps	Generates mipmaps for the image.
createMipmapsCubeGGX	Generates GGX mipmaps on CPU with the specified quality, of course slower and with lower quality than on GPU but it provides the result synchronously (actually this should be the only case, when this method is to be used).
removeMipmaps	Removes mipmaps generated for the image.
decombine	Automatically converts the image from the combined format to a correct one.
decombineMipmaps	Decombines the loaded 2D-image and the mipmap images.
decompress	Decompresses the image from the compressed format to a correct one.
extrude	Extrudes contour of the image in the alpha=0 region on the given number of pixels.
flipX	Flips the 2D image horizontally.
flipY	Flips the 2D image vertically.
hasMipmaps	Returns a value indicating if the source image has mipmaps.
info	Returns information about the given image.
invert	Inverts values of all the image channels.
load	Loads an image from a specified file.
normalize	Creates a three-component normal map out of the image.
resize	Resizes the image.
rotate	Rotates the image by a given angle (with the step of 90 degrees).
save	Saves the image to a file with the specified name.
sign	Converts the image from unsigned type to signed char.
swap	Swaps the data of the current image with the source image.
toPixel	Converts a vec4 color vector (R, G, B, A) to Pixel color.
toVec4	Converts Pixel color to a vec4 color vector (R, G, B, A).
getNumChannels	Returns the number of channels for the specified image format.
getPixelSize	Returns the pixel size for the specified image format.
getBlockSize	Returns the block size for the specified image format.
invertChannel	Inverts the values stored in the specified channel.
saveDDS	Saves the DDS image to a specified stream.
loadDDS	Loads a DDS image from a specified stream.
getRawFormat	Returns the closest RAW format of the uncompressed image.
calcRange	Calculates the image range for all available channels in total.
changeRange	Changes the image range.
normalizeRange	Normalizes the image range either per channel or for all channels altogether.
flipCubemapX	Flips the cubemap image along the X axis.
flipCubemapY	Flips the cubemap image along the Y axis.
flipCubemapZ	Flips the cubemap image along the Z axis.
getSupportedExtensions	Returns a list of supported file extensions.
isSupportedExtension	Returns a value indicating if the file extension is supported.
isSupported	Returns a value indicating if the extension of a file provided by path is supported.

Variables:

Name	Description
AUTO_FORMAT = -1	Format is set automatically.
FORMAT_R8 = 0	Non-compressed unsigned format. Stores data in one 8-bit channel (red).
FORMAT_RG8 = 1	Non-compressed unsigned format. Stores data in two 8-bit channels (red, green).
FORMAT_RGB8 = 2	Non-compressed unsigned format. Stores data in three 8-bit channels (red, green, blue).
FORMAT_RGBA8 = 3	Non-compressed unsigned format. Stores data in four 8-bit channels (red, green, blue, alpha).
FORMAT_R16 = 4	Non-compressed unsigned format. Stores data in one 16-bit channel (red).
FORMAT_RG16 = 5	Non-compressed unsigned format. Stores data in two 16-bit channels (red, green).
FORMAT_RGB16 = 6	Non-compressed unsigned format. Stores data in three 16-bit channels (red, green, blue).
FORMAT_RGBA16 = 7	Non-compressed unsigned format. Stores data in four 16-bit channels (red, green, blue, alpha).
FORMAT_R16F = 8	Non-compressed float format. Stores data in one 16-bit channel (red).
FORMAT_RG16F = 9	Non-compressed float format. Stores data in two 16-bit channels (red, green).
FORMAT_RGB16F = 10	Non-compressed float format. Stores data in three 16-bit channels (red, green, blue).
FORMAT_RGBA16F = 11	Non-compressed float format. Stores data in four 16-bit channels (red, green, blue, alpha).
FORMAT_R32F = 12	Non-compressed float format. Stores data in one 32-bit channel (red).
FORMAT_RG32F = 13	Non-compressed float format. Stores data in two 32-bit channels (red, green).
FORMAT_RGB32F = 14	Non-compressed float format. Stores data in three 32-bit channels (red, green, blue).
FORMAT_RGBA32F = 15	Non-compressed float format. Stores data in four 32-bit channels (red, green, blue, alpha).
FORMAT_RGB565 = 16	Combined unsigned format. Stores 16 bit color values without alpha.
FORMAT_RGBA4 = 17	Combined unsigned format. Stores data in four 4-bit channels (red, green, blue, alpha).
FORMAT_RGB5A1 = 18	Combined unsigned format. Stores data in three 5-bit channels (red, green, blue) and one 1-bit channel (alpha).
FORMAT_RGB10A2 = 19	Combined unsigned format. Stores data in three 10-bit channels (red, green, blue) and one 2-bit channel (alpha).
FORMAT_RG11B10F = 20	Combined unsigned float format. Stores data in two 11-bit channels (red, green) and one 10-bit channel (blue).
FORMAT_DXT1 = 21	A DXT1 compressed image file format. Compresses RGB images by a factor of 6:1 compared to RGB8. Uses 4×4 blocks for color interpolation and stores color values in 16 bits per pixel (R5:G6:B5). Can also store 1-bit alpha data; in this case, compresses images by a factor of 8:1 compared to RGBA8. This format is not recommended for storing normal maps.
FORMAT_DXT3 = 22	A DXT3 compressed image file format. Compresses RGBA images by a factor of 4:1 compared to RGBA8. Stores RGB color values as the DXT1 format and uses four more bits for alpha data. Color values are interpreted as not having been pre-multiplied by alpha. Alpha values are not interpolated. Recommended for images with sharp alpha transitions.
FORMAT_DXT5 = 23	A DXT5 compressed image file format. Compresses RGBA images by a factor of 4:1 compared to RGBA8. Stores RGB color values as the DXT1 format and uses four more bits for alpha data. Color values are interpreted as not having been pre-multiplied by alpha. Alpha values are interpolated. Recommended for images with smooth alpha transitions.
FORMAT_ATI1 = 24	An ATI1 compressed image file format. Compresses single-channel images by a factor of 2:1 compared to R8. Compression is the same as the one used for alpha data in the DXT5 format. Supported by all graphics cards compatible with DirectX 10; additionally, all ATI graphics cards since X800.
FORMAT_ATI2 = 25	An ATI2 compressed image file format. Compresses two-channel images by a factor of 2:1 compared to RG8. Compression for each channel is the same as the one used for alpha data in the DXT5 format. Supported by all graphics cards compatible with DirectX 10; additionally, all ATI graphics cards since X800.
AUTO_IMAGE_TYPE = -1	Image type is set automatically.
IMAGE_2D = 0	A 2D texture.
IMAGE_3D = 1	A 3D texture.
IMAGE_CUBE = 2	A cube texture.
IMAGE_2D_ARRAY = 3	A 2D texture array. Each texture of the array has its own mipmap levels, which is the difference between it and a 3D image.
IMAGE_CUBE_ARRAY = 4	A cube texture array.

Image Class

Перечисления (Enums)

FILE_COMPRESSION#

Имя	Описание
FILE_COMPRESSION_DISABLE = 0	Image data is uncompressed.
FILE_COMPRESSION_ZLC_LOW = 1	Fast compression used for images stored in the system memory (based on zlib library).
FILE_COMPRESSION_ZLC_HIGH = 2	Compression used for images stored in the system memory (based on zlib library). It is used when a smaller file size is required, compared to ZLC LOW (compression is slower).
FILE_COMPRESSION_LZ4_LOW = 3	LZ4 lossless data compression algorithm that is focused on compression and decompression speed. It belongs to the LZ77 family of byte-oriented compression schemes (greater file size, faster comression).
FILE_COMPRESSION_LZ4_HIGH = 4	LZ4 lossless data compression algorithm that is focused on compression and decompression speed. It belongs to the LZ77 family of byte-oriented compression schemes (smaller file size, slower comression).

FILTER#

Имя	Описание
FILTER_POINT = 0	A point mipmap filter.
FILTER_LINEAR = 1	A linear mipmap filter.
FILTER_MIN = 2	A minimum mipmap filter.
FILTER_BLUR = 3	A blurring mipmap filter.
FILTER_SHARPEN = 4	A sharpening mipmap filter.

GGX_MIPMAPS_QUALITY#

Quality of GGX mipmaps.

Имя	Описание
GGX_MIPMAPS_QUALITY_LOW = 0	Low quality of GGX mipmaps.
GGX_MIPMAPS_QUALITY_MEDIUM = 1	Medium quality of GGX mipmaps.
GGX_MIPMAPS_QUALITY_HIGH = 2	High quality of GGX mipmaps.
GGX_MIPMAPS_QUALITY_ULTRA = 3	Ultra quality of GGX mipmaps.

Members

int getNumChannels() const#

Returns the current number of image channels.

Return value

Current number of image channels.

int getType() const#

Returns the current numerical code of the image type.

Return value

Current numerical code of the image type: 0 for a 2D image, 1 for a 3D image, 2 for a cube image, 3 for a 2D Array. See the Unigine::Image:: Enumeration with IMAGE_* prefixes.

const char * getTypeName() const#

Returns the current image type name.

Return value

Current image type name: 2D for a 2D image, 3D for a 3D image, Cube for a cube image, 2D_Array for a 2D Array.

int getNumMipmaps() const#

Returns the current number of mipmaps stored with the image.

Return value

Current number of mipmap levels.

int getNumLayers() const#

Returns the current number of layers in the image.

Return value

Current number of layers.

int getNumFaces() const#

Returns the current number of faces in the image.

Return value

Current number of image faces.

bool isLoaded() const#

Returns the current value indicating whether the image is loaded.

Return value

true if the image is loaded; otherwise false.

int getBlockSize() const#

Returns the current compressed image block size.

Return value

Current block size in bytes.

int getPixelSize() const#

Returns the current uncompressed image pixel size.

Return value

Current pixel size, in bytes.

bool isCubeType() const#

Returns the current value indicating if the image is cube image.

Return value

true if the image is a cube image; otherwise false.

bool isArrayType() const#

Returns the current value indicating if the image is of an array type (see *_ARRAY variables).

Return value

true if the image is of an array type; otherwise false.

bool is3DType() const#

Returns the current value indicating if the image is a 3D image.

Return value

true if the image is a 3D image; otherwise false.

bool is2DType() const#

Returns the current value indicating if the image is a 2D image.

Return value

true if the image is a 2D image; otherwise false.

int getFormat() const#

Returns the current numerical code of the image format.

Return value

Current Numerical code of the image format. See the FORMAT_* variables.

const char * getFormatName() const#

Returns the current image format name.

Return value

Current Image format name. The following values can be returned: R8, RG8, RGB8, RGBA8, R16, RG16, RGB16, RGBA16, R16F, RG16F, RGB16F, RGBA16F, R32F, RG32F, RGB32F, RGBA32F, RGB565, RGBA4, RGB5A1, RGB10A2, DXT1, DXT3, DXT5, ATI1, ATI2.

int getDepth() const#

Returns the current image depth, in pixels.

Return value

Current image depth, in pixels.

int getHeight() const#

Returns the current image height, in pixels.

Return value

Current image height, in pixels.

int getWidth() const#

Returns the current image width, in pixels.

Return value

Current image width, in pixels.

size_t getPixelsSize() const#

Returns the current size of all pixels of the image.

Return value

Current size of all pixels of the image, in bytes.

size_t getNumPixels() const#

Returns the current number of pixels in the image.

Return value

Current number of pixels.

void setFileCompression ( Image::FILE_COMPRESSION compression ) #

Sets a new file compression type used for the image.

Arguments

Image::FILE_COMPRESSION compression - The file compression type to be used for the image. One of the FILE_COMPRESSION_* values.

Image::FILE_COMPRESSION getFileCompression() const#

Returns the current file compression type used for the image.

Return value

Current file compression type to be used for the image. One of the FILE_COMPRESSION_* values.

static ImagePtr create ( ) #

Default constructor. An empty instance with default parameters is created.

static ImagePtr create ( const char * name ) #

Constructor. Creates an image loading data from the specified file.

Arguments

const char * name - Image file name.

static ImagePtr create ( const Ptr<Image> & image ) #

Constructor. Creates an image by copying a given source image.

Arguments

const Ptr<Image> & image - Source image.

bool allocData ( bool clear = true ) #

Allocates memory for the image data.

Arguments

bool clear - Clear flag: set true to fill allocated memory with zero-values; otherwise, set false.

Return value

true if memory for the image data is allocated successfully; otherwise, false.

void clearData ( ) #

Clears all image data.

void set ( int id, const Math::dvec4 & value ) #

Sets a value for a pixel by its id. Compressed and combined image formats are not supported.The code below sets the specified color value for all image pixels:

Source code (C++)

void image_set_pixel_color(ImagePtr& image, const Math::dvec4& value)
{
	// getting image size
	int width = image->getWidth();
	int height = image->getHeight();

	// running through all image pixels of the specified channel in a loop
	for (int y = 0; y < height; y++)
	{
		for (int x = 0; x < width; x++)
		{
			// composing pixel id from its coords; (0, 0) - top-left corner
			int id = x + y * width;

			// setting a value for a pixel by its id
			image->set(id, value);
		}
	}
}

Arguments

int id - Pixel ID: id = image_width * Y + X, (0 , 0) - top left corner of the image.
const Math::dvec4 & value - RGBA color of a pixel with the specified ID.

void get ( int id, Math::dvec4 & value ) const#

Gens a value for a pixel by its id and puts it to value.

Arguments

int id - Pixel ID: id = image_width * Y + X, (0 , 0) - top left corner of the image.
Math::dvec4 & value - RGBA color of a pixel with the specified ID.

Math::vec4 get ( const Math::ivec2& coord, int offset ) const#

Returns image data for the specified pixel coordinates and mipmap offset as a four-component vector.

Arguments

const Math::ivec2& coord - Pixel coordinates (X, Y) - X in range [0; width], Y in range [0; height].
int offset - Mipmap offset value.

Return value

A vec4 vector (R, G, B, A) containing image data for the specified pixel coordinates, with components normalized in the [0.0f; 1.0f] range.

void get ( const Math::ivec2& coord, int offset, Math::vec4 & p00, Math::vec4 & p01, Math::vec4 & p10, Math::vec4 & p11 ) const#

Returns image data for the specified pixel coordinates and mipmap offset (along with neighboring pixels) as a set of four-component vectors.

Arguments

const Math::ivec2& coord - Pixel coordinates (X, Y) - X in range [0; width], Y in range [0; height].
int offset - Mipmap offset value.
Math::vec4 & p00 - A vec4 vector (R, G, B, A) containing image data for the specified pixel coordinates (X, Y), with components normalized in the [0.0f; 1.0f] range.
Math::vec4 & p01 - A vec4 vector (R, G, B, A) containing image data for the neighboring pixel coordinates (X, Y+1), with components normalized in the [0.0f; 1.0f] range.
Math::vec4 & p10 - A vec4 vector (R, G, B, A) containing image data for the neighboring pixel coordinates (X+1, Y), with components normalized in the [0.0f; 1.0f] range.
Math::vec4 & p11 - A vec4 vector (R, G, B, A) containing image data for the neighboring pixel coordinates (X+1, Y+1), with components normalized in the [0.0f; 1.0f] range.

void get8F ( const Math::ivec2 & coord, Math::vec4 & p ) const#

Returns a set of 8-bit float values stored in the specified image pixel and neighboring ones and puts them to the output vector.

Arguments

const Math::ivec2 & coord - Pixel coordinates (X, Y) - X in the [0; width] range, Y in the [0; height] range.
Math::vec4 & p - Output vec4 vector (P00, P01, P10, P11) to receive 8-bit float values stored in the specified image pixel and neighboring ones:
- P00 - (X, Y)
- P01 - (X, Y+1)
- P10 - (X+1, Y)
- P11 - (X+1, Y+1)
Notice
Values are normalized in the [0.0f; 1.0f] range.

float get8F ( const Math::ivec2 & coord ) const#

Returns an 8-bit float value stored in the specified pixel of the image.

Arguments

const Math::ivec2 & coord - Pixel coordinates (X, Y) - X in the [0; width] range, Y in the [0; height] range.

Return value

An 8-bit float value stored in the specified pixel of the image normalized in the [0.0f; 1.0f] range.

void get16F ( const Math::ivec2 & coord, Math::vec4 & p ) const#

Returns a set of 16-bit float values stored in the specified image pixel and neighboring ones and puts them to the output vector.

Arguments

const Math::ivec2 & coord - Pixel coordinates (X, Y) - X in the [0; width] range, Y in the [0; height] range.
Math::vec4 & p - Output vec4 vector (P00, P01, P10, P11) to receive 16-bit float values stored in the specified image pixel and neighboring ones:
- P00 - (X, Y)
- P01 - (X, Y+1)
- P10 - (X+1, Y)
- P11 - (X+1, Y+1)
Notice
Values are normalized in the [0.0f; 1.0f] range.

float get16F ( const Math::ivec2 & coord ) const#

Returns a 16-bit float value stored in the specified pixel of the image.

Arguments

const Math::ivec2 & coord - Pixel coordinates (X, Y) - X in the [0; width] range, Y in the [0; height] range.

Return value

A 16-bit float value stored in the specified pixel of the image normalized in the [0.0f; 1.0f] range.

void get32F ( const Math::ivec2 & coord, Math::vec4 & p ) const#

Returns a set of 32-bit float values stored in the specified image pixel and neighboring ones and puts them to the output vector.

Arguments

const Math::ivec2 & coord - Pixel coordinates (X, Y) - X in the [0; width] range, Y in the [0; height] range.
Math::vec4 & p - Output vec4 vector (P00, P01, P10, P11) to receive 32-bit float values stored in the specified image pixel and neighboring ones:
- P00 - (X, Y)
- P01 - (X, Y+1)
- P10 - (X+1, Y)
- P11 - (X+1, Y+1)
Notice
Values are normalized in the [0.0f; 1.0f] range.

float get32F ( const Math::ivec2 & coord ) const#

Returns a 32-bit float value stored in the specified pixel of the image.

Arguments

const Math::ivec2 & coord - Pixel coordinates (X, Y) - X in the [0; width] range, Y in the [0; height] range.

Return value

A 32-bit float value stored in the specified pixel of the image normalized in the [0.0f; 1.0f] range.

void set2D ( int x, int y, const Image::Pixel& p ) #

Sets a color for a given pixel of a 2D image. Compressed formats are not supported.

Arguments

int x - X integer coordinate of a pixel in range [0; width].
int y - Y integer coordinate of a pixel in range [0; height].
const Image::Pixel& p - Pixel color represented by a Pixel structure.

void set2D ( const Math::ivec2& coord, const Image::Pixel& p ) #

Sets a color for a given pixel of a 2D image. Compressed formats are not supported.

Arguments

const Math::ivec2& coord - Integer coordinates of a pixel in the following ranges: X - [0; width], Y - [0; height].
const Image::Pixel& p - Pixel color represented by a Pixel structure.

Image::Pixel get2D ( int x, int y ) const#

Returns a color of a given pixel of a 2D image. Compressed formats are not supported.

Arguments

int x - X integer coordinate of a pixel in range [0; width].
int y - Y integer coordinate of a pixel in range [0; height].

Return value

Pixel color represented by a Pixel structure.

Image::Pixel get2D ( float x, float y ) const#

Returns a color of a given pixel of a 2D image. Linear interpolation is used to get a color sample. Compressed formats are not supported.

Arguments

float x - X float coordinate of a pixel in range [0.0f; 1.0f].
float y - Y float coordinate of a pixel in range [0.0f; 1.0f].

Return value

Pixel color represented by a Pixel structure.

Image::Pixel get2D ( float x, float y, const Image::Pixel& skip_pixel ) const#

Returns a color of a given pixel of a 2D image. Linear interpolation is used to get a color sample. Compressed formats are not supported.

NoticeIf at least one of four interpolated pixels is equal to skip_pixel, the method will return skip_pixel.

Arguments

float x - X float coordinate of a pixel in range [0.0f; 1.0f].
float y - Y float coordinate of a pixel in range [0.0f; 1.0f].
const Image::Pixel& skip_pixel - Skip pixel color represented by a Pixel structure.

Return value

Pixel color represented by a Pixel structure.

Image::Pixel get2D ( const Math::ivec2& coord ) const#

Returns a color of a given pixel of a 2D image. Compressed formats are not supported.

Arguments

const Math::ivec2& coord - Integer coordinates of a pixel in the following ranges: X - [0; width], Y - [0; height].

Return value

Pixel color represented by a Pixel structure.

Image::Pixel get2D ( const Math::vec2& uv ) const#

Returns a color of a given pixel of a 2D image. Linear interpolation is used to get a color sample. Compressed formats are not supported.

Arguments

const Math::vec2& uv - Float coordinates of a pixel in range [0.0f; 1.0f].

Return value

Pixel color represented by a Pixel structure.

Image::Pixel get2D ( const Math::vec2& uv, const Image::Pixel& skip_pixel ) const#

Returns a color of a given pixel of a 2D image. Linear interpolation is used to get a color sample. Compressed formats are not supported.

NoticeIf at least one of four interpolated pixels is equal to skip_pixel, the method will return skip_pixel.

Arguments

const Math::vec2& uv - Float coordinates of a pixel in range [0.0f; 1.0f].
const Image::Pixel& skip_pixel - Skip pixel color represented by a Pixel structure.

Return value

Pixel color represented by a Pixel structure.

void set2DArray ( int x, int y, int layer, const Image::Pixel& p ) #

Sets a color of a given pixel. The image must be a 2D image array. Compressed formats are not supported.

Arguments

int x - X integer coordinate of a pixel in range [0; width].
int y - Y integer coordinate of a pixel in range [0; height].
int layer - Image layer number.
const Image::Pixel& p - Pixel color represented by a Pixel structure.

void set2DArray ( const Math::ivec2& coord, int layer, const Image::Pixel& p ) #

Sets a color of a given pixel. The image must be a 2D texture array. Compressed formats are not supported.

Arguments

const Math::ivec2& coord - Coordinates of a pixel.
int layer - Image layer number.
const Image::Pixel& p - Pixel color represented by a Pixel structure.

Image::Pixel get2DArray ( int x, int y, int layer ) const#

Returns a color of a given pixel. The image must be a 2D texture array. Compressed formats are not supported.

Arguments

int x - X integer coordinate of a pixel in range [0; width].
int y - Y integer coordinate of a pixel in range [0; height].
int layer - Image layer number.

Return value

Pixel color represented by a Pixel structure.

Image::Pixel get2DArray ( float x, float y, int layer ) const#

Returns a color of a given pixel. The image must be a 2D image array. Compressed formats are not supported. Linear interpolation is used to get a color sample.

Arguments

float x - X float coordinate of a pixel in range [0.0f; 1.0f].
float y - Y float coordinate of a pixel in range [0.0f; 1.0f].
int layer - Image layer number.

Return value

Pixel color represented by a Pixel structure.

Image::Pixel get2DArray ( const Math::ivec2& coord, int layer ) const#

Returns a color of a given pixel. The image must be a 2D texture array. Compressed formats are not supported.

Arguments

const Math::ivec2& coord - Coordinates of a pixel.
int layer - Image layer number.

Return value

Pixel color represented by a Pixel structure.

Image::Pixel get2DArray ( const Math::vec2& uv, int layer ) const#

Returns a color of a given pixel. The image must be a 2D texture array. Compressed formats are not supported.

Arguments

const Math::vec2& uv - UV coordinates of a pixel.
int layer - Image layer number.

Return value

Pixel color represented by a Pixel structure.

void set3D ( int x, int y, int z, const Image::Pixel& p ) #

Sets a color of a given pixel of a 3D image. Compressed formats are not supported.

Arguments

int x - X integer coordinate of a pixel in range [0; width].
int y - Y integer coordinate of a pixel in range [0; height].
int z - Z integer coordinate of a pixel in range [0; depth].
const Image::Pixel& p - Pixel color represented by a Pixel structure.

void set3D ( const Math::ivec3& coord, const Image::Pixel& p ) #

Sets a color of a given pixel of a 3D image. Compressed formats are not supported.

Arguments

const Math::ivec3& coord - Integer coordinates of a pixel in the following ranges: X - [0; width], Y - [0; height], Z - [0; depth].
const Image::Pixel& p - Pixel color represented by a Pixel structure.

Image::Pixel get3D ( float x, float y, float z ) const#

Returns a color of a given pixel of a 3D image. Linear interpolation is used to get a color sample. Compressed formats are not supported.

Arguments

float x - X float coordinate of a pixel in range [0.0f; 1.0f].
float y - Y float coordinate of a pixel in range [0.0f; 1.0f].
float z - Z float coordinate of a pixel in range [0.0f; 1.0f].

Return value

Pixel color represented by a Pixel structure.

Image::Pixel get3D ( int x, int y, int z ) const#

Returns a color of a given pixel of a 3D image. Compressed formats are not supported.

Arguments

int x - X integer coordinate of a pixel in range [0; width].
int y - Y integer coordinate of a pixel in range [0; height].
int z - Z integer coordinate of a pixel in range [0; depth].

Return value

Pixel color represented by a Pixel structure.

Image::Pixel get3D ( const Math::ivec3& coord ) const#

Returns a color of a given pixel of a 3D image. Compressed formats are not supported.

Arguments

const Math::ivec3& coord - Integer coordinates of a pixel in the following ranges: X - [0; width], Y - [0; height], Z - [0; depth].

Return value

Pixel color represented by a Pixel structure.

Image::Pixel get3D ( const Math::vec3& uvw ) const#

Returns a color of a given pixel of a 3D image. Linear interpolation is used to get a color sample. Compressed formats are not supported.

Arguments

const Math::vec3& uvw - Float coordinates of a pixel in range [0.0f; 1.0f].

Return value

Pixel color represented by a Pixel structure.

Image::Pixel get3DSmooth ( float x, float y, float z ) const#

Returns a color of a given pixel obtained using linear interpolation. Compressed formats are not supported.

NoticeThis method returns pixel color with float components in the range [0.0f, 1.0f] regardless of the image format.

Arguments

float x - X float coordinate of a pixel in range [0.0f; 1.0f].
float y - Y float coordinate of a pixel in range [0.0f; 1.0f].
float z - Z float coordinate of a pixel in range [0.0f; 1.0f].

Return value

Pixel color represented by a Pixel structure with float components in the range [0.0f, 1.0f].

Image::Pixel get3DSmooth ( const Math::vec3& uvw ) const#

Returns a color of a given pixel obtained using linear interpolation. Compressed formats are not supported.

NoticeThis method returns pixel color with float components in the range [0.0f, 1.0f] regardless of the image format.

Arguments

const Math::vec3& uvw - Float coordinates of a pixel in the range [0.0f; 1.0f].

Return value

Pixel color represented by a Pixel structure with float components in the range [0.0f, 1.0f].

bool isCombinedFormat ( ) const#

Returns a value indicating if the image is stored in a combined format (RGB565, RGBA4, RGB5A1 or RGB10A2).

Return value

1 if the image is in combined format; otherwise, 0.

bool isCombinedFormat ( int format ) #

Returns a value indicating if a given format is a combined format (RGB565, RGBA4, RGB5A1 or RGB10A2).

Arguments

int format - Image format identifier. See the FORMAT_* variables.

Return value

1 if the specified format is a combined format; otherwise, 0.

bool isCompressedFormat ( ) const#

Returns a value indicating if the image is stored in a compressed format (DXT1, DXT3, DXT5, ATI1, ATI2).

Return value

1 if the image is in a compressed format; otherwise, 0.

bool isCompressedFormat ( int format ) #

Returns a value indicating if a given format is a compressed format (DXT1, DXT3, DXT5, ATI1, ATI2).

Arguments

int format - Image format identifier. See the FORMAT_* variables.

Return value

1 if the specified format is a compressed format; otherwise, 0.

void setCube ( int x, int y, int face, const Image::Pixel& p ) #

Sets a color of a given pixel. The image must be of the Cube type. Compressed formats are not supported.

Arguments

int x - X integer coordinate of a pixel in range [0; depth].
int y - Y integer coordinate of a pixel in range [0; height].
int face - Face number in range from 0 to 5.
const Image::Pixel& p - Pixel color represented by a Pixel structure.

Image::Pixel getCube ( const Math::vec3& direction ) const#

Returns a color of a given pixel. The image must be of the Cube type. Compressed formats are not supported.

Arguments

const Math::vec3& direction - Cube direction vector used for color sampling.

Return value

Pixel color represented by a Pixel structure.

Image::Pixel getCube ( float x, float y, int face ) const#

Returns a color of a given pixel. The image must be of the Cube type. Compressed formats are not supported.

Arguments

float x - X float coordinate of a pixel in range [0.0f; 1.0f].
float y - Y float coordinate of a pixel in range [0.0f; 1.0f].
int face - Face number in range from 0 to 5.

Return value

Pixel color represented by a Pixel structure.

Image::Pixel getCube ( int x, int y, int face ) const#

Returns a color of a given pixel. The image must be of the Cube type. Compressed formats are not supported.

Arguments

int x - X integer coordinate of a pixel in range [0; width].
int y - Y integer coordinate of a pixel in range [0; height].
int face - Face number in range from 0 to 5.

Return value

Pixel color represented by a Pixel structure.

Image::Pixel getCube ( const Math::ivec2& coord, int face ) const#

Returns a color of a given pixel. The image must be of the Cube type. Compressed formats are not supported.

Arguments

const Math::ivec2& coord - Coordinates of a pixel.
int face - Face number in range from 0 to 5.

Return value

Pixel color represented by a Pixel structure.

Image::Pixel getCube ( const Math::vec2& uv, int face ) const#

Returns a color of a given pixel. The image must be of the Cube type. Compressed formats are not supported.

Arguments

const Math::vec2& uv - UV coordinates of a pixel.
int face - Face number in range from 0 to 5.

Return value

Pixel color represented by a Pixel structure.

void setCubeArray ( int x, int y, int face, int layer, const Image::Pixel& p ) #

Sets a color of a given pixel. The image must be of the Cube Array type. Compressed formats are not supported.

Arguments

int x - X integer coordinate of a pixel in range [0; width].
int y - Y integer coordinate of a pixel in range [0; height].
int face - Face number in range from 0 to 5.
int layer - Image layer number.
const Image::Pixel& p - Pixel color represented by a Pixel structure.

void setCubeArray ( const Math::ivec2& coord, int face, int layer, const Image::Pixel& p ) #

Sets a color of a given pixel. The image must be of the Cube Array type. Compressed formats are not supported.

Arguments

const Math::ivec2& coord - Coordinates of a pixel.
int face - Face number in range from 0 to 5.
int layer - Image layer number.
const Image::Pixel& p - Pixel color represented by a Pixel structure.

Image::Pixel getCubeArray ( const Math::vec3& direction, int layer ) const#

Returns the color of a given pixel of the cube array image.

Notice

Compressed formats are not supported.

Arguments

const Math::vec3& direction - Cube direction vector used for color sampling.
int layer - Image layer number.

Return value

Pixel color represented by a Pixel structure.

Image::Pixel getCubeArray ( int v1, int v2, int face, int layer ) const#

Returns a color of a given pixel. The image must be of the Cube Array type. Compressed formats are not supported.

Arguments

int v1 - X integer coordinate of a pixel in range [0;width].
int v2 - Y integer coordinate of a pixel in range [0; height].
int face - Face number in range from 0 to 5.
int layer - Image layer number.

Return value

Pixel color represented by a Pixel structure.

Image::Pixel getCubeArray ( float v1, float v2, int face, int layer ) const#

Returns a color of a given pixel. The image must be of the Cube Array type. Compressed formats are not supported.

Arguments

float v1 - X integer coordinate of a pixel in range [0;width].
float v2 - Y integer coordinate of a pixel in range [0;height].
int face - Face number in range from 0 to 5.
int layer - Image layer number.

Return value

Pixel color represented by a Pixel structure.

Image::Pixel getCubeArray ( const Math::ivec2& coord, int face, int layer ) const#

Returns a color of a given pixel. The image must be of the Cube Array type. Compressed formats are not supported.

Arguments

const Math::ivec2& coord - Coordinates of a pixel.
int face - Face number in range from 0 to 5.
int layer - Image layer number.

Return value

Pixel color represented by a Pixel structure.

Image::Pixel getCubeArray ( const Math::vec2& uv, int face, int layer ) const#

Returns a color of a given pixel. The image must be of the Cube Array type. Compressed formats are not supported.

Arguments

const Math::vec2& uv - UV coordinates of a pixel.
int face - Face number in range from 0 to 5.
int layer - Image layer number.

Return value

Pixel color represented by a Pixel structure.

int getDepth ( int level = 0 ) const#

Returns the image depth on a given mipmap level.

Arguments

int level - Mipmap level in range from 0 to the total number of mipmaps. This is an optional argument.

Return value

Image depth if the image exists (its depth is larger than 0); otherwise, 1.

bool isFloatFormat ( ) const#

Returns a value indicating if the image is stored in a float format (R32F, RG32F, RGB32F or RGBA32F).

Return value

1 if the image is in float format; otherwise, 0 is returned.

bool isFloatFormat ( int format ) #

Returns a value indicating if a given format is a float format (R32F, RG32F, RGB32F or RGBA32F).

Arguments

int format - Image format identifier. See the FORMAT_* variables.

Return value

1 if the specified format is a float format; otherwise, 0.

int getFormat ( int num_channels, int format ) #

Returns a numerical code of the image format for the specified format and number of channels.

Arguments

int num_channels - Number of channels in the [1; 4] range.
int format - Numerical code of the image format. See the FORMAT_* variables.

Return value

Numerical code of the image format for the specified number of channels.

const char * getFormatName ( int format ) #

Returns the name of the image format by the given format ID.

Arguments

int format - Image format identifier. See the FORMAT_* variables.

Return value

Image format name. The following values can be returned: R8, RG8, RGB8, RGBA8, R16, RG16, RGB16, RGBA16, R16F, RG16F, RGB16F, RGBA16F, R32F, RG32F, RGB32F, RGBA32F, RGB565, RGBA4, RGB5A1, RGB10A2, DXT1, DXT3, DXT5, ATI1, ATI2.

bool isHalfFormat ( ) const#

Returns a value indicating if the image is stored in a half-float format (R16F, RG16F, RGB16F or RGBA16F).

Return value

1 if the image is in half-float format; otherwise, 0.

bool isHalfFormat ( int format ) #

Returns a value indicating if a given format is a half-float format (R16F, RG16F, RGB16F or RGBA16F).

Arguments

int format - Image format identifier. See the FORMAT_* variables.

Return value

1 if the specified format is a half-float format; otherwise, 0.

int getHeight ( int level = 0 ) const#

Returns image height on a given mipmap level.

Arguments

int level - Mipmap level in range from 0 to the total number of mipmaps. This is an optional argument.

Return value

Image height if the image exists (its height is larger than 0); otherwise, 1.

bool setChannelInt ( int channel, int value ) #

Sets an integer value for a given image channel. Compressed and combined image formats are not supported.

Arguments

int channel - Channel number in range from 0 to number of channels - 1.
int value - Value in range from 0 to 255 (8-bit formats) or from 0 to 65535 (16-bit formats).

Return value

true if the value is set successfully; otherwise, false.

bool setChannelFloat ( int channel, float value ) #

Sets a float value for a given image channel. Compressed and combined image formats are not supported.

Arguments

int channel - Channel number in range from 0 to number of channels - 1.
float value - Value in range from 0.0f to 1.0f.

Return value

true if the value is set successfully; otherwise, false.

bool swapChannels ( int channel_0, int channel_1 ) #

Swaps values of two channels with the specified numbers. Compressed formats are not supported.

Arguments

int channel_0 - Number of the first channel in range from 0 to number of channels - 1.
int channel_1 - Number of the second channel in range from 0 to number of channels - 1.

Return value

true if the two specified channels were swapped successfully; otherwise, false.

size_t getOffset ( int level ) const#

Returns the image offset on a given mipmap level.

Arguments

int level - Mipmap level in range from 0 to the total number of mipmaps.

Return value

Image offset, in bytes.

void setPixels ( unsigned char * OUT_pixels ) #

Sets image pixels to be taken from the specified source array.

NoticeThis method simply performs pointer assignment (without copying data), therefore, it is fast. But make sure the source is not accidentally modified or deleted when its lifetime expires or otherwise.

Arguments

unsigned char * OUT_pixels - Source array.
Notice
This output buffer is to be filled by the Engine as a result of executing the method.

int setPixels ( const Ptr<Blob> & blob ) #

Sets image pixels by copying data (not just a pointer assignment) from a given source blob.

Arguments

const Ptr<Blob> & blob - Source blob containing image data to be copied.

Return value

1 if image data is set successfully; otherwise, 0.

unsigned char * getPixels ( ) const#

Returns the pointer to the array of pixels.The code below fills the specified channel of the image with the specified value:

Source code (C++)

// int channel - number of the target channel to write the specified value
// unsigned char value   - color value
void image_fill_channel(ImagePtr& image, int channel, unsigned char value)
{
	// getting image pixels to a buffer
	unsigned char *data = image->getPixels();

	// getting image size and number of channels
	int channel_num = image->getNumChannels();
	int width = image->getWidth();
	int height = image->getHeight();

	// running through all image pixels of the specified channel in a loop
	for (int y = 0; y < height; y++)
	{
		for (int x = 0; x < width; x++)
		{
			// composing pixel id from its coords and channel number; (0, 0) - top-left corner
			int id = (x + y * width) * channel_num + channel;

			// setting a value for a pixel by its id
			data[id] = value;
		}
	}
}

Return value

Pointer to the array of pixels.

void getPixels ( const Ptr<Blob> & blob ) const#

Copies the image data to a given target blob.

Arguments

const Ptr<Blob> & blob - Target blob.

unsigned char * getPixels2D ( int level = 0 ) const#

Returns the pointer to the array of pixels with the given mipmap level for the 2D image.

Arguments

int level - Mipmap level in range from 0 to the total number of mipmaps. This is an optional argument.

Return value

Pointer to the array of pixels.

unsigned char * getPixels2DArray ( int layer, int level = 0 ) const#

Returns the pointer to the array of pixels with the given mipmap level and image layer for the 2D Array image.

Arguments

int layer - Number of the image layer.
int level - Mipmap level in range from 0 to the total number of mipmaps. This is an optional argument.

Return value

Pointer to the array of pixels.

unsigned char * getPixels3D ( int level = 0 ) const#

Returns the pointer to the array of pixels with the given mipmap level for the 3D image.

Arguments

int level - Mipmap level in range from 0 to the total number of mipmaps. This is an optional argument.

Return value

Pointer to the array of pixels.

unsigned char * getPixelsCube ( int face, int level = 0 ) const#

Returns the pointer to the array of pixels with the given mipmap level for the cube image.

Arguments

int face - Face number in range from 0 to 5.
int level - Mipmap level in range from 0 to the total number of mipmaps. This is an optional argument.

Return value

Pointer to the array of pixels.

unsigned char * getPixelsCubeArray ( int face, int layer, int level = 0 ) const#

Returns the pointer to the array of pixels with the given mipmap level and image layer for the Cube Array image.

Arguments

int face - Face number in range from 0 to 5.
int layer - Number of the image layer.
int level - Mipmap level in range from 0 to the total number of mipmaps. This is an optional argument.

Return value

Pointer to the array of pixels.

size_t getPixelsSize ( int format, int w, int h ) #

Returns the size of all pixels for the image of the specified format and size.

Arguments

int format - Image format identifier. See the FORMAT_* variables.
int w - Image width, in pixels.
int h - Image width, in pixels.

Return value

Size of all pixels of the specified image, in bytes.

bool isRawFormat ( ) const#

Returns a value indicating if the image is uncompressed (stored in R8, RG8, RGB8, RGBA8, R16, RG16, RGB16, RGBA16, R16F, RG16F, RGB16F, RGBA16F, R32F, RG32F, RGB32F, RGBA32F, RGB565, RGBA4, RGB5A1 or RGB10A2 format).

Return value

1 if the image is uncompressed; otherwise, 0.

bool isRawFormat ( int format ) #

Returns a value indicating if a given format is an uncompressed format (R8, RG8, RGB8, RGBA8, R16, RG16, RGB16, RGBA16, R16F, RG16F, RGB16F, RGBA16F, R32F, RG32F, RGB32F, RGBA32F, RGB565, RGBA4, RGB5A1 or RGB10A2).

Arguments

int format - Image format identifier. See the FORMAT_* variables.

Return value

1 if the specified format is an uncompressed format; otherwise, 0.

size_t getSize ( ) const#

Returns the current image size.

Return value

Image size, in bytes.

size_t getSize ( int level ) const#

Returns the current image size.

Arguments

int level - Mipmap level in range from 0 to the total number of mipmaps.

Return value

Image size in bytes.

size_t getStride ( int level = 0 ) const#

Returns the image stride on a given mipmap level.

Arguments

int level - Mipmap level in range from 0 to the total number of mipmaps.

Return value

Image stride in bytes.

size_t getDepthStride ( int level = 0 ) const#

Returns the image depth stride on a given mipmap level.

Arguments

int level - Mipmap level in range from 0 to the total number of mipmaps.

Return value

Image depth stride in bytes.

const char * getTypeName ( int type ) #

Returns the name of the image type by its identifier.

Arguments

int type - Image type. One of the IMAGE_* types.

Return value

Image type name: 2D for a 2D image, 3D for a 3D image, Cube for a cube image, 2D_Array for a 2D Array.

bool isUCharFormat ( ) const#

Returns a value indicating if the image is stored in an unsigned char format (R8, RG8, RGB8, RGBA8, DXT1, DXT3, DXT5, ATI1 or ATI2).

Return value

1 if the image is in unsigned char format; otherwise, 0.

bool isUCharFormat ( int format ) #

Returns a value indicating if a given format is an unsigned char format (R8, RG8, RGB8, RGBA8, DXT1, DXT3, DXT5, ATI1 or ATI2).

Arguments

int format - Image format identifier. See the FORMAT_* variables.

Return value

1 if the specified format is an unsigned char format; otherwise, 0.

bool isUShortFormat ( ) const#

Returns a value indicating if the image is stored in an unsigned short format (R16, RG16, RGB16 or RGBA16).

Return value

1 if the image is in unsigned short format; otherwise, 0.

bool isUShortFormat ( int format ) #

Returns a value indicating if a given format is an unsigned short format (R16, RG16, RGB16 or RGBA16).

Arguments

int format - Image format identifier. See the FORMAT_* variables.

Return value

1 if the specified format is an unsigned short format; otherwise, 0.

int getWidth ( int level = 0 ) const#

Returns the image width on a given mipmap level.

Arguments

int level - Mipmap level in range from 0 to the total number of mipmaps. This is an optional argument.

Return value

Image width if the image exists (its width is larger than 0); otherwise, 1.

bool blend ( const Ptr<Image> & image, int x0, int y0, int x1, int y1, int width, int height, float scale = 1.0f, bool safe = 0 ) #

Blends the specified image with the current one. Blending takes place within a specified region. If the safe flag is set to 1, rendering of the blended images won't be performed outside the destination image boundaries. Compressed, combined, half-float and float formats are not supported. Images of different formats can be blended as follows:

R8 with R8, RG8;
RG8 with RG8, RGB8;
RGB8 with RGB8, RGBA8;
RGBA8 with RGBA8 only;
R16 with R16, RG16;
RG16 with RG16, RGB16;
RGB16 with RGB16, RGBA16;
RGBA16 with RGBA16 only;

Arguments

const Ptr<Image> & image - Source image to be blended with the current image.
int x0 - X coordinate of a position in the current image.
int y0 - Y coordinate of a position in the current image.
int x1 - X coordinate of a position in a source image, which is blended with the current image.
int y1 - Y coordinate of a position in a source image, which is blended with the current image.
int width - Width of the blending region.
int height - Height of the blending region.
float scale - Scale of blending:
- If blended images are of the same format, the blended image is multiplied by scale value and is added to the destination image.
- If a source image has one more channel compared to the current one, it will serve as alpha value. This channel value is multiplied by scale and is used to alpha blend the images.
- The default scale value is 1.0f.
bool safe - 1 for safe blending with respect to destination image boundaries; otherwise, 0.

Return value

Returns 1 if blending is successful; otherwise, 0.

bool blur ( int radius, float gamma = 1.0f, int level = 0 ) #

Filters the image using two-pass Gaussian blur. Only the 2D or cube image can be blurred. Compressed and combined image formats are not supported.

Arguments

int radius - Blur filter radius, the number of neighbouring source pixels that are averaged for each blurred destination pixel. For example, if Radius = 2, two pixels from each side are taken and the blurring kernel is 5 x 5 pixels.
float gamma - Gamma correction value. If 1 is provided, no gamma correction is applied. This is an optional argument.
int level - Mip level for which the blurring effect is applied. This is an optional argument.

Return value

true if the image was successfully blurred or the size of blur filter is 0; otherwise, false.

bool sharpen ( float radius, float intensity, float gamma = 1.0f, bool sharp_only_lightness = true, int level = 0 ) #

Sharpens the image. Only the 2D or cube image can be sharpened. Compressed and combined image formats are not supported.

Arguments

float radius - Sharpen filter radius, the number of neighbouring source pixels (or subpixels) that are averaged for each sharpened destination pixel.
float intensity - Filter intensity value.
float gamma - Gamma correction value. If 1 is provided, no gamma correction is applied. This is an optional argument.
bool sharp_only_lightness - true to adjust sharpness of the lightness value only, false to sharpen all HSL values. This is an optional argument.
int level - Mip level for which the sharpening effect is applied. This is an optional argument.

Return value

true if the image was successfully sharpened or the size of sharpen filter is 0; otherwise, false.

void clear ( ) #

Clears all data associated with the image and resets its type, format, size to default. Also the number of image layers and mipmaps is set to 1.

bool combine ( int new_format = -1 ) #

Converts the image to a combined format. The following conversions are available:

RGB8 to RGB565
RGBA8 to RGBA4 if the format is specified as RGBA4; otherwise, RGBA8 is converted to RGB5A1 by default
RGBA16 to RGB10A2

Arguments

int new_format - Combined format to convert the image into. This is an optional argument. If no format is specified, default conversion will be performed.

Return value

1 if the conversion into the combined format is successful; otherwise, 0.

bool combineMipmaps ( ) #

Combines the loaded 2D image with the mipmap image. Only one mipmap image can be combined. Compressed image formats cannot be combined.

Return value

1 if the image and a mipmap are successfully combined; otherwise, 0.

bool compare ( const Ptr<Image> & image, int x0, int y0, int x1, int y1, int width, int height, int threshold = 0 ) #

Compares a region of a specified image with a specified region of the current image. Compressed, combined, half-float and float formats are not supported.

Arguments

const Ptr<Image> & image - Source image to compare the loaded image with.
int x0 - X coordinate on the loaded image.
int y0 - Y coordinate on the loaded image.
int x1 - X coordinate on the source image.
int y1 - Y coordinate on the source image.
int width - Width of a region to compare.
int height - Height of a region to compare.
int threshold - A threshold to compare.

Return value

1 if the regions match; otherwise, 0.

bool compress ( int new_format = -1 ) #

Converts the image to a compressed format. The following conversions are available:

R8 to ATI1
RG8 to ATI2
RGB8 to DXT1
RGBA8 to DXT3, DXT5(by default)
ZLC1 to ZLC1
ZLC2 to ZLC2

Arguments

int new_format - Format to compress the image into. This is an optional argument. If no format is specified, default conversion will be performed.

Return value

1 if the image is compressed successfully; otherwise, 0.

int convertToFormat ( int new_format ) #

Converts the image to a specified format. Compressed and combined images are automatically decompressed/decombined.

Arguments

int new_format - Target format to convert the image into. See the FORMAT_* variables.

Return value

1 if the conversion is successful; otherwise, 0.

int convertToType ( int type ) #

Converts the image to a specified type. The following conversions are possible:

Source type	Target type	Target dimensions
2D (height should be proportional to width)	3D	width × height × height/width
2D (height should divide by four, width should divide by three)	Cube	width/4 × height/3
3D	2D	width × height*depth
3D	2D texture array	width × height
Cube	2D	width4 × height3
Cube	2D array texture	width × height
2D array texture	2D	width × height*number of texture layers

Arguments

int type - Type for conversion. One of the IMAGE_* types.

Return value

1 if the conversion is successful; otherwise, 0.

void assignFrom ( const Ptr<Image> & src_image ) #

Copies the data from the specified source image. The size of the image shall be updated according to the size of the source image (unlike the resizeFrom() method).

Arguments

const Ptr<Image> & src_image - Source image.

bool resizeFrom ( const Ptr<Image> & src_image, Image::FILTER filter = FILTER_LINEAR ) #

Copies the data from the specified source image, resizing the source. The source image shall be resized (enlarged/shrinked) to fit the size of the image.

Arguments

const Ptr<Image> & src_image - Source image.
Image::FILTER filter - Filter type to be used: linear or point. The default filter is linear. See the Unigine::Image Enumerations with FILTER_* prefixes.

Return value

true if the data was successfully copied from the source image; otherwise, false.

bool copy ( const Ptr<Image> & src_image, int layer ) #

Copies data from the specified source image according to the specified layer parameter. Depending on the image and the source image types the layer parameter either defines the index of the layer/face to copy data FROM (source), or the index of the layer/face to copy data TO (destination):

Image	Source Image	Copy
Cube	2D	Specified source 2D image is copied to the face of the cubemap image specified by the layer argument in the [0; 5] range: 2D_image TO cubemap_face[ *layer* ]
2D Array	2D	Specified source 2D image is copied to the specified layer of the 2D image array: 2D image TO 2D_array[ *layer* ]
Cube Array	Cube	Specified source cubemap image (all 6 faces) is copied to the specified layer of the cubemap image array: cubemap_image TO cubemap_array[ *layer* ]
2D	Cube	Face of the source cubemap image specified by the layer argument in the [0; 5] range is copied to the 2D image: 2D_image FROM cubemap_face[ *layer* ]
2D	2D Array	Specified layer of the source 2D image array is copied to the 2D image: 2D image FROM 2D_array[ *layer* ]
Cube	Cube Array	Specified layer of the source сubemap image array is copied to the cubemap image (all 6 faces): cubemap_image FROM cubemap_array[ *layer* ]

Source code (C++)

src_image->load(src_image_path);
src_image->convertToFormat(Image::FORMAT_RGB8);// 2D 1024x1024 image
		
dest_image->create2DArray(1024, 1024, 5, Image::FORMAT_RGB8);
dest_image->copy(src_image, 4); // created 2D image is copied to the 5th layer of the 2D image array

Arguments

const Ptr<Image> & src_image - Source image.
int layer - Zero-based index defining layer/face TO or FROM which the data is to be copied.

Return value

1 if the data is copied successfully; otherwise, 0.

bool copy ( const Ptr<Image> & src_image, int dest_channel, int src_channel ) #

Copies a given channel from the specified image to the specified image channel.

Arguments

const Ptr<Image> & src_image - Source image.
int dest_channel - Destination channel.
int src_channel - Source channel.

Return value

true if the channel is copied successfully from the source image; otherwise, false.

bool copy ( const Ptr<Image> & src_image, int x_dst, int y_dst, int x_src, int y_src, int width, int height, bool safe = 0 ) #

Copies a data fragment with specified width, height, and coordinates from the source image.

Arguments

const Ptr<Image> & src_image - Source image, from which a fragment is to be copied.
int x_dst - X coordinate of a position in the image, to which the data fragment is to be copied.
int y_dst - Y coordinate of a position in the image, to which the data fragment is to be copied.
int x_src - X coordinate of a position in a source image, starting from which the data fragment is to be copied.
int y_src - Y coordinate of a position in a source image, starting from which the data fragment is to be copied.
int width - Width of the fragment to be copied from the source image, in pixels.
int height - Height of the fragment to be copied from the source image, in pixels.
bool safe - 1 for safe copying with respect to destination image boundaries; otherwise, 0.
Notice
The safe flag doesn't provide safe copying with respect to source image boundaries.

Return value

true if the specified fragment was successfully copied from the source image; otherwise, false.

bool copyFast ( const Ptr<Image> & src_image, size_t x_dst, size_t y_dst, size_t x_src, size_t y_src, size_t w, size_t h ) #

Copies a data fragment with specified width, height, and coordinates from the source image.

Arguments

const Ptr<Image> & src_image - Source image, from which a fragment is to be copied.
size_t x_dst - X coordinate of a position in the image, to which the data fragment is to be copied.
size_t y_dst - Y coordinate of a position in the image, to which the data fragment is to be copied.
size_t x_src - X coordinate of a position in a source image, starting from which the data fragment is to be copied.
size_t y_src - Y coordinate of a position in a source image, starting from which the data fragment is to be copied.
size_t w - Width of the fragment to be copied from the source image, in pixels.
size_t h - Height of the fragment to be copied from the source image, in pixels.

Return value

true if the specified fragment was successfully copied from the source image; otherwise, false.

bool create2D ( int width, int height, int format, int num_mipmaps = 1, bool clear = 1, bool allocate = 1 ) #

Creates an empty 2D image filled with black color.

Arguments

int width - Required width, in pixels.
int height - Required height, in pixels.
int format - Required format. See the FORMAT_* variables.
int num_mipmaps - Number of mipmaps to create. This is an optional argument. If the value is smaller than 1, an assertion is raised.
bool clear - Positive number to fill the image with black color, 0 not to fill. This optional argument can be set to 0 if new data will fully overwrite the data existing in the memory.
bool allocate - Positive number to allocate memory for the created image. This value should be always set to 1.

Return value

true if 2D image is successfully created; otherwise, false.

bool create2DArray ( int width, int height, int num_layers, int format, int num_mipmaps = 1, bool clear = 1, bool allocate = 1 ) #

Creates an empty 2D texture array filled with black color.

Arguments

int width - Required width, in pixels.
int height - Required height, in pixels.
int num_layers - Number of texture layers.
int format - Required format. See the FORMAT_* variables.
int num_mipmaps - Number of mipmaps to create. This is an optional argument. If the value is smaller than 1, an assertion is raised.
bool clear - Positive number to fill the texture array with black color, 0 not to fill. This optional argument can be set to 0 if new data will fully overwrite the data existing in the memory.
bool allocate - Positive number to allocate memory for the created image. This value should be always set to 1.

Return value

true if 2D texture array is successfully created; otherwise, false.

bool create3D ( int width, int height, int depth, int format, int num_mipmaps = 1, bool clear = 1, bool allocate = 1 ) #

Creates an empty 3D image filled with black color.

Arguments

int width - Required width, in pixels.
int height - Required height, in pixels.
int depth - Required depth.
int format - Required format. See the IMAGE_FORMAT_* variables.
int num_mipmaps - Number of mipmaps to create. This is an optional argument. If the value is smaller than 1, an assertion is raised.
bool clear - Positive number to fill the image with black color, 0 not to fill. This optional argument can be set to 0 if new data will fully overwrite the data existing in the memory.
bool allocate - Positive number to allocate memory for the created image. This value should be always set to 1.

Return value

true if 3D image is successfully created; otherwise, false.

void create3DTurbulence ( int size, float scale, int frequency, int seed ) #

Creates a 3D turbulence image (RGBA8).

Arguments

int size - 3D image size, in pixels. Width, height, and depth are equal.
float scale - Scaling factor applied to the displacement amount.
int frequency - Base frequency, determines how rapidly the displacement amount changes. Increasing this value creates more turbulence.
int seed - Specifies the initial number used for noise generation. Different Seed values produce different random variations and can be useful in changing the result. Keep in mind, that you should use the same Seed value when you want to retain the same variations.

bool createCube ( int width, int height, int format, int num_mipmaps = 1, bool clear = 1, bool allocate = 1 ) #

Creates the empty cube image filled with black color.

Arguments

int width - Image width, in pixels.
int height - Image height, in pixels.
int format - Texture format. See the FORMAT_* variables.
int num_mipmaps - Number of mipmaps to create. This is an optional argument.
bool clear - true to fill the image with black color, false is not to fill. This optional argument can be set to false if new data will fully overwrite the data existing in the memory.
bool allocate - true to allocate memory for the created image. This value should be always set to true.

Return value

true if the cube image is successfully created; otherwise, false.

bool createCubeArray ( int width, int height, int num_layers, int format, int num_mipmaps = 1, bool clear = 1, bool allocate = 1 ) #

Creates the empty cube array image filled with black color.

Arguments

int width - Image width, in pixels.
int height - Image height, in pixels.
int num_layers - Number of image layers.
int format - Texture format. See the FORMAT_* variables.
int num_mipmaps - Number of mipmaps to create. This is an optional argument.
bool clear - 1 to fill the image with black color, false is not to fill. This optional argument can be set to false if new data will fully overwrite the data existing in the memory.
bool allocate - true to allocate memory for the created image. This value should be always set to true.

Return value

true if the cube array image is successfully created; otherwise, false.

bool createMipmaps ( Image::FILTER filter = FILTER_LINEAR, float gamma = 1.0f ) #

Generates mipmaps for the image. Mipmaps cannot be created for compressed and combined image formats.

Arguments

Image::FILTER filter - Filter type to be used: linear or point. The default filter is linear. See the Unigine::Image Enumerations with FILTER_* prefixes.
float gamma - Gamma correction value. If 1 is provided, no gamma correction is applied. This is an optional argument.

Return value

true if the mipmaps are generated successfully; otherwise, false.

bool createMipmapsCubeGGX ( Image::GGX_MIPMAPS_QUALITY quality ) #

Generates GGX mipmaps on CPU with the specified quality, of course slower and with lower quality than on GPU but it provides the result synchronously (actually this should be the only case, when this method is to be used).

Arguments

Image::GGX_MIPMAPS_QUALITY quality - Quality of GGX mipmaps. One of the GGX_MIPMAPS_QUALITY values.

Return value

true if the mipmaps are generated successfully; otherwise, false.

bool removeMipmaps ( ) #

Removes mipmaps generated for the image.

Return value

true if mipmaps generated for the image are removed successfully; otherwise, false.

bool decombine ( ) #

Automatically converts the image from the combined format to a correct one. The following conversions are available:

RGB565 to RGB8
RGBA4 to RGBA8
RGB5A1 to RGBA8
RGB10A2 to RGBA16

Return value

true if the image is successfully converted from the combined format; otherwise, false.

bool decombineMipmaps ( ) #

Decombines the loaded 2D-image and the mipmap images. The number of mipmaps must be larger than 1. Compressed image formats cannot be decombined.

Return value

1 if the 2D-image and mipmap image are successfully decombined; otherwise, 0.

bool decompress ( ) #

Decompresses the image from the compressed format to a correct one. The following conversions are available:

DXT1 to RGB8
DXT1 without alpha data to RGB8
DXT3 to RGBA8
DXT5 to RGBA8
ATI1 to R8
ATI2 to RG8

Return value

1 if the image was successfully decompressed; otherwise, 0.

bool extrude ( int pixels ) #

Extrudes contour of the image in the alpha=0 region on the given number of pixels. Only images of the RGBA8 and RGBA16 formats can be extruded.

Arguments

int pixels - Number of contour pixels.

Return value

1 if the image contour is successfully extruded; otherwise, 0.

bool flipX ( ) #

Flips the 2D image horizontally. Compressed and combined image formats are not supported.

Return value

bool flipY ( ) #

Flips the 2D image vertically. Compressed and combined image formats are not supported.

Return value

1 if the image is successfully flipped; otherwise, 0.

bool hasMipmaps ( ) const#

Returns a value indicating if the source image has mipmaps.

Return value

1 if the image has mipmaps; otherwise, 0.

bool info ( const char * file ) #

Returns information about the given image. The following file formats are supported:

*.texture
*.tga
*.jpg
*.png
*.dds
*.psd
*.ies
tif
- *.tif
- *.tiff

Arguments

const char * file - Name of the image file.

Return value

1 if the operation was a success; otherwise, 0.

bool invert ( ) #

Inverts values of all the image channels. Only R8, RG8, RGB8, RGBA8, R16, RG16, RGB16, RGBA16, R32F, RG32F, RGB32F and RGBA32F formats can be inverted.

Return value

true if the image is inverted successfully; otherwise, false.

bool load ( const char * file, int mip_offset ) #

Loads an image from a specified file. The following file formats are supported:

*.texture
*.tga
*.png
*.dds
*.psd
*.ppm
*.pgm
*.hdr
*.sgi
*.ies
*.exr
tif
- *.tif
- *.tiff
jpg
- *.jpg
- *.jpeg
- *.jpe
- *.jif
- *.jfif
- *.jfi
sgi
- *.bw
- *.la
- *.int
- *.inta
- *.rgb
- *.rgba

Arguments

const char * file - Name of the image file.
int mip_offset - Mipmap offset value for the loaded image.

Return value

true if the image is loaded successfully; otherwise, false.

bool load ( const char * file ) #

Loads an image from the specified file. The following file formats are supported:

*.texture
*.tga
*.png
*.dds
*.psd
*.ppm
*.pgm
*.hdr
*.sgi
*.ies
*.exr
tif
- *.tif
- *.tiff
jpg
- *.jpg
- *.jpeg
- *.jpe
- *.jif
- *.jfif
- *.jfi
sgi
- *.bw
- *.la
- *.int
- *.inta
- *.rgb
- *.rgba

Arguments

const char * file - Name of the image file.

Return value

true if the image is loaded successfully; otherwise, false.

bool load ( const Ptr<Stream> & stream ) #

Loads an image from a specified stream. The following file formats are supported:

*.texture
*.tga
*.png
*.dds
*.psd
*.ppm
*.pgm
*.hdr
*.sgi
*.ies
*.exr
tif
- *.tif
- *.tiff
jpg
- *.jpg
- *.jpeg
- *.jpe
- *.jif
- *.jfif
- *.jfi
sgi
- *.bw
- *.la
- *.int
- *.inta
- *.rgb
- *.rgba

Arguments

const Ptr<Stream> & stream - Stream smart pointer.

Return value

true if the image is loaded successfully; otherwise, false.

bool load ( const unsigned char * data, int size ) #

Loads the image from raw data.

Arguments

const unsigned char * data - Set of raw data.
int size - Raw data size, in bytes.

Return value

true if the image is loaded successfully; otherwise, false.

bool normalize ( ) #

Creates a three-component normal map out of the image.

Return value

true if normalization was successful; otherwise, false.

bool resize ( int new_width, int new_height, Image::FILTER filter = FILTER_LINEAR ) #

Resizes the image. Only the 2D or cube image can be resized. Compressed and combined image formats cannot be resized.

Arguments

int new_width - New image width.
int new_height - New image height.
Image::FILTER filter - Filter type to be used: linear or point. The default filter is linear. See the Unigine::Image Enumerations with FILTER_* prefixes.

Return value

true if the image is resized successfully; otherwise, false.

bool rotate ( int angle ) #

Rotates the image by a given angle (with the step of 90 degrees). Only the 2D or cube image can be rotated. Compressed and combined image formats cannot be rotated.

Arguments

int angle - Angle that is multiplied by the step (angle * 90) to set the image rotation degree.

Return value

true if the image is rotated successfully; otherwise, false.

bool save ( const char * file ) const#

Saves the image to a file with the specified name. The following file formats are supported:

*.texture
*.tga
*.png
*.dds
*.psd
jpg
- *.jpg
- *.jpeg
- *.jpe
- *.jif
- *.jfif
- *.jfi

Arguments

const char * file - Name of the file to save image data to.

Return value

true if the image is saved successfully; otherwise, false.

bool save ( const char * file, float quality ) const#

Saves the image to a specified file. The following file formats are supported:

*.texture
*.tga
*.png
*.dds
*.psd
jpg
- *.jpg
- *.jpeg
- *.jpe
- *.jif
- *.jfif
- *.jfi

Arguments

const char * file - Name of a file with extension into which data will be saved.
float quality - Quality of JPG compression in range [0;1].

Return value

true if the image is saved successfully; otherwise, false.

bool save ( const Ptr<Stream> & stream ) const#

Saves the image data (either compressed or uncompressed) to the specified stream. Current image compression is to be used.

Arguments

const Ptr<Stream> & stream - Pointer to the stream.

Return value

true if the image is successfully saved to the specified stream; otherwise, false.

bool sign ( ) #

Converts the image from unsigned type to signed char. Only R8, RG8, RGB8, RGBA8, R16, RG16, RGB16, RGBA16, ATI1 and ATI2 formats can be converted.

Return value

1 if the image has been converted successfully; otherwise, 0.

void swap ( const Ptr<Image> & image ) #

Swaps the data of the current image with the source image.

Arguments

const Ptr<Image> & image - Source image.

Image::Pixel toPixel ( const Math::vec4& color ) #

Converts a vec4 color vector (R, G, B, A) to Pixel color.

Arguments

const Math::vec4& color - Color vec4 vector (R, G, B, A) with components normalized in range [0.0f; 1.0f]

Return value

Pixel color represented by a Pixel structure.

Image::Pixel toPixel ( int format, const Math::vec4& color ) #

Converts a vec4 color vector (R, G, B, A) to Pixel color depending on the specified image format.

Arguments

int format - Image format identifier. See the FORMAT_* variables.
const Math::vec4& color - Color vec4 vector (R, G, B, A) with components normalized in range [0.0f; 1.0f]

Return value

Pixel color represented by a Pixel structure.

Math::vec4 toVec4 ( const Image::Pixel& pixel ) #

Converts Pixel color to a vec4 color vector (R, G, B, A).

Arguments

const Image::Pixel& pixel - Pixel color represented by a Pixel structure.

Return value

Color vec4 vector (R, G, B, A). Each component is normalized in range [0.0f; 1.0f]

Math::vec4 toVec4 ( int format, const Image::Pixel& p ) #

Converts Pixel color to a vec4 color vector (R, G, B, A) depending on the specified image format.

Arguments

int format - Image format identifier. See the FORMAT_* variables.
const Image::Pixel& p - Pixel color represented by a Pixel structure.

Return value

Color vec4 vector (R, G, B, A). Each component is normalized in range [0.0f; 1.0f]

int getNumChannels ( int format ) #

Returns the number of channels for the specified image format.

Arguments

int format - Image format identifier. See the FORMAT_* variables.

Return value

Number of channels for the specified image format.

int getPixelSize ( int format ) #

Returns the pixel size for the specified image format. Not available for compressed image formats (DXT1, DXT3, DXT5, ATI1, ATI2).

Arguments

int format - Image format identifier. See the FORMAT_* variables.

Return value

Pixel size for the specified image format.

int getBlockSize ( int format ) #

Returns the block size for the specified image format. Available for compressed image formats only (DXT1, DXT3, DXT5, ATI1, ATI2).

Arguments

int format - Image format identifier. See the FORMAT_* variables.

Return value

Block size for the specified image format.

bool invertChannel ( unsigned char channel ) #

Inverts the values stored in the specified channel. Channels of images of half (FORMAT_R16F to FORMAT_RGBA16F) and float (FORMAT_R32F to FORMAT_RGBA32F) formats cannot be inverted.

Arguments

unsigned char channel - Number of the channel to be inverted, in the range from 0 to the total number of channels.

Return value

true if the specified channel is inverted successfully; otherwise, false.

bool saveDDS ( const Ptr<Stream> & stream ) const#

Saves the DDS image to a specified stream.

Arguments

const Ptr<Stream> & stream - Stream smart pointer.

Return value

true if the DDS image is saved successfully; otherwise, false.

bool loadDDS ( const Ptr<Stream> & stream ) #

Loads a DDS image from a specified stream.

Arguments

const Ptr<Stream> & stream - Stream smart pointer.

Return value

true if the DDS image is loaded successfully; otherwise, false.

int getRawFormat ( int format ) #

Returns the closest RAW format of the uncompressed image.

Arguments

int format - Image format identifier. See the FORMAT_* variables.

Return value

Identifier of the uncompressed image (stored in R8, RG8, RGB8, RGBA8, R16, RG16, RGB16, RGBA16, R16F, RG16F, RGB16F, RGBA16F, R32F, RG32F, RGB32F, RGBA32F format).

void calcRange ( Math::dvec2 & range ) #

Calculates the image range for all available channels in total.

Arguments

Math::dvec2 & range - The vector to store the image range (min and max values).

void calcRange ( Math::dvec2 & r, Math::dvec2 & g, Math::dvec2 & b, Math::dvec2 & a ) #

Calculates the image range for each channel separately.

Arguments

Math::dvec2 & r - The vector to store the R channel range (min and max values).
Math::dvec2 & g - The vector to store the G channel range (min and max values).
Math::dvec2 & b - The vector to store the B channel range (min and max values).
Math::dvec2 & a - The vector to store the A channel range (min and max values).

void changeRange ( const Math::dvec4 & range ) #

Changes the image range.

NoticeThe range of the final image will be clamped, if the set range values exceed the maximum values of the image format.

Arguments

const Math::dvec4 & range - Vector that stores the range values: x and y coordinates of the value specify the original range, z and w specify the new range.

void changeRange ( const Math::dvec4 & range_r, const Math::dvec4 & range_g, const Math::dvec4 & range_b, const Math::dvec4 & range_a ) #

Changes the image range for each channel separately.

NoticeThe range of the final image will be clamped, if the set range values exceed the maximum values of the image format.

Arguments

const Math::dvec4 & range_r - Vector that stores the range values for the R channel: x and y coordinates of the value specify the original range, z and w specify the new range.
const Math::dvec4 & range_g - Vector that stores the range values for the G channel: x and y coordinates of the value specify the original range, z and w specify the new range.
const Math::dvec4 & range_b - Vector that stores the range values for the B channel: x and y coordinates of the value specify the original range, z and w specify the new range.
const Math::dvec4 & range_a - Vector that stores the range values for the A channel: x and y coordinates of the value specify the original range, z and w specify the new range.

void normalizeRange ( bool per_cahnnel ) #

Normalizes the image range either per channel or for all channels altogether.

Arguments

bool per_cahnnel - true if per-channel normalization is required; otherwise, false.

bool flipCubemapX ( ) #

Flips the cubemap image along the X axis.

Return value

true if the cubemap is flipped successfully; otherwise, false.

bool flipCubemapY ( ) #

Flips the cubemap image along the Y axis.

Return value

true if the cubemap is flipped successfully; otherwise, false.

bool flipCubemapZ ( ) #

Flips the cubemap image along the Z axis.

Return value

true if the cubemap is flipped successfully; otherwise, false.

Vector< String > getSupportedExtensions ( ) #

Returns a list of supported file extensions.

Return value

Vector of supported file extensions.

bool isSupportedExtension ( const char * ext ) #

Returns a value indicating if the file extension is supported.

Arguments

const char * ext - File extension.

Return value

true if the file extension is supported; otherwise, false.

bool isSupported ( const char * path ) #

Returns a value indicating if the extension of a file provided by path is supported.

Arguments

const char * path - Path to the file.

Return value

true if the file extension is supported; otherwise, false.

Last update: 13.12.2024

Помогите сделать статью лучше

Была ли эта статья полезной?

Сообщить о проблеме в этой статье

(или выберите слово/фразу и нажмите Ctrl+Enter

Unigine::Image Class

In This Article:

Data Storage (Levels, Layers, Faces)#

Pixels#

Usage Example#

See Also

Методы:

Variables:

Image Class

Перечисления (Enums)

FILE_COMPRESSION#

FILTER#

GGX_MIPMAPS_QUALITY#

Members

int getNumChannels() const#

Return value

int getType() const#

Return value

const char * getTypeName() const#

Return value

int getNumMipmaps() const#

Return value

int getNumLayers() const#

Return value

int getNumFaces() const#

Return value

bool isLoaded() const#

Return value

int getBlockSize() const#

Return value

int getPixelSize() const#

Return value

bool isCubeType() const#

Return value

bool isArrayType() const#

Return value

bool is3DType() const#

Return value

bool is2DType() const#

Return value

int getFormat() const#

Return value

const char * getFormatName() const#

Return value

int getDepth() const#

Return value

int getHeight() const#

Return value

int getWidth() const#

Return value

size_t getPixelsSize() const#

Return value

size_t getNumPixels() const#

Return value

void setFileCompression ( Image::FILE_COMPRESSION compression ) #

Arguments

Image::FILE_COMPRESSION getFileCompression() const#

Return value

static ImagePtr create ( ) #

static ImagePtr create ( const char * name ) #

Arguments

static ImagePtr create ( const Ptr<Image> & image ) #

Arguments

bool allocData ( bool clear = true ) #

Arguments

Return value

void clearData ( ) #

void set ( int id, const Math::dvec4 & value ) #

Arguments

void get ( int id, Math::dvec4 & value ) const#

Arguments

Math::vec4 get ( const Math::ivec2& coord, int offset ) const#

Arguments

Return value

void get ( const Math::ivec2& coord, int offset, Math::vec4 & p00, Math::vec4 & p01, Math::vec4 & p10, Math::vec4 & p11 ) const#

Arguments

void get8F ( const Math::ivec2 & coord, Math::vec4 & p ) const#

Arguments

float get8F ( const Math::ivec2 & coord ) const#

Arguments