UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
Extending Editor Functionality
FAQ
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes

Unigine::Image Class

Header: #include <UnigineImage.h>

Interface for handling textures and other images.

Textures are stored on CPU.

See Also#

  • C++ API sample located in the folder <UnigineSDK>/source/samples/Api/Systems/Images
  • C# API sample located in the folder <UnigineSDK>/source/csharp/samples/Api/Systems/Images

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 example demostrates 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.
  • Get color information for each pixel of the image using the Pixel structure.
  • Clear the image.
Source code (C++)
// AppWorldLogic.cpp

#include <UnigineMaterials.h>

/* .. */

int AppWorldLogic::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);
		}

	// setting our image as an albedo texture of the ground_grid material		
	MaterialPtr material = Materials::findMaterial("ground_grid");
	material->setTextureImage(material->findTexture("albedo"), image);

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

	// 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();
	
	return 1;
}

/* .. */

Image Class

Members


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.

bool set ( int channel, int value ) #

Sets a 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.

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

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

Returns image data for the specified pixel coordinates and mipmap offset (along with neigboring 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 ) #

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

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

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

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

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

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.

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

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].Y coordinate of a pixel. Must be of the same type as x:
    • int in range [0; height]
    • float in range [0.0f; 1.0f]
      Notice
      If the provided value is outside the range, modulus is used to count pixels from the beginning.

Return value

Pixel color represented by a Pixel structure.

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

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

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.
Notice
If 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.

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.

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

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

Arguments

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

Return value

Pixel color represented by a Pixel structure.

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

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.

bool is2DType ( ) #

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

Return value

1 if the image is a 2D image; otherwise - 0.

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.

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

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

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 get3DSmooth ( float x, float y, float z ) #

Returns a color of a given pixel obtained using linear interpolation. Compressed formats are not supported.
Notice
This 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].

bool is3DType ( ) #

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

Return value

1 if the image is a 3D image; otherwise, 0.

bool isArrayType ( ) #

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

Return value

1 if the image is of an array type; otherwise, 0.

bool isBCCompressedFormat ( ) #

Returns a value indicating if the image is compressed via GPU-accelerated DXT compression (DXT1, DXT1A, DXT3, DXT5, ATI1, ATI2 formats).

Return value

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

bool isBCCompressedFormat ( int format ) #

Returns a value indicating if a given format is a format using GPU-accelerated DXT compression (DXT1, DXT1A, DXT3, DXT5, ATI1 or ATI2).

Arguments

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

Return value

1 if the specified format is a format using GPU-accelerated DXT compression; otherwise, 0.

int getBlockSize ( ) #

Returns the compressed image block size.

Return value

Block size in bytes.

bool isCombinedFormat ( ) #

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

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

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, ZLC1 or ZLC2).

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

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

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

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.

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.

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

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

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

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.

bool isCubeType ( ) #

Returns a value indicating if the image is Cube image.

Return value

1 if the image is a cube image; otherwise, 0.

int getDepth ( int level = 0 ) #

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

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

Returns a numerical code of the image format.

Return value

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

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

Returns an image format name.

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, ZLC1, ZLC2.

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, ZLC1, ZLC2.

bool isHalfFormat ( ) #

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

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

Returns a value indicating whether the image is loaded.

Return value

1 if the image is loaded; otherwise, 0.

int getNumChannels ( ) #

Returns the number of image channels.

Return value

Number of image channels.

int getNumFaces ( ) #

Returns the number of faces in the image.

Return value

Number of image faces.

int getNumLayers ( ) #

Returns the number of layers in the image.

Return value

Number of layers.

int getNumMipmaps ( ) #

Returns the number of mipmaps stored with the image.

Return value

Number of mipmap levels.

size_t getOffset ( int level ) #

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 * pixels ) #

Sets image pixels by copying data from a given source array.

Arguments

  • unsigned char * pixels - Source array.

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

Sets image pixels by copying data 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 ( ) #

Returns the pointer to the array of pixels.

Return value

Pointer to the array of pixels.

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

Copies the image data to a given target blob.

Arguments

  • const Ptr<Blob> & blob - Target blob.

unsigned char * getPixels2D ( int level = 0 ) #

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

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

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

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

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.

int getPixelSize ( ) #

Returns the uncompressed image pixel size.

Return value

Pixel size, in bytes.

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

size_t getPixelsSize ( ) #

Returns the size of all pixels of the image.

Return value

Size of all pixels of the image, in bytes.

bool 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).

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

Returns the current image size.

Return value

Image size, in bytes.

size_t getSize ( int level ) #

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

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

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.

int getType ( ) #

Returns a numerical code of the image type.

Return value

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

Returns an image type name.

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.

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

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

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

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

Returns a value indicating if the image is stored in a ZLC1 or ZLC2 format (by ZLIB Image Compression).

Return value

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

bool isZCompressedFormat ( int format ) #

Returns a value indicating if a given format is a format using ZLIB image compression (ZLC1 or ZLC2).

Arguments

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

Return value

1 if the specified format is a format using ZLIB image compression; otherwise, 0.

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 size ) #

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

Arguments

  • int size - Blur filter size. It is the number of neighbouring source pixels (from all sides) that are averaged for each blurred destination pixel. For example, if blur = 2, two pixels from each side are taken and the blurring kernel is 5 x 5 pixels.

Return value

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

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. The following variants of conversion are possible:

Source type Target type
DXT1 DXT3, RGBA8, DXT5, ZLC1, ZLC2
DXT3 DXT1, RGBA8 ZLC1, ZLC2
DXT5 DXT1, RGBA8, ZLC1, ZLC2
ATI1 R8, ATI2, ZLC1, ZLC2
ATI2 RG8, ATI1, ZLC1, ZLC2
RGB565 RGB8, DXT1, ZLC1, ZLC2
RGBA4 RGBA8, DXT3, DXT5, ZLC1, ZLC2
RGB5A1 RGBA8, DXT3, DXT5, ZLC1, ZLC2
RGB10A2 RGBA16, ZLC1, ZLC2
R8 ATI1, RG8, RGB8, RGBA8, R16, RG16, RGBA16, R32F, ATI2, DXT1, DXT3, DXT5, ZLC1, ZLC2
RG8 ATI2, R8, RGB8, RGBA8, R16, RG16, RGBA16, RG32F, DXT1, DXT3, DXT5, ZLC1, ZLC2
RGB8 R5G6B5, DXT1, R8, RG8, RGBA8, R16, RG16, RGBA16, RGB32F, ATI1, ATI2, DXT3, DXT5, ZLC1, ZLC2
RGBA8 RGBA4, RGB5A1, R8, RG8, RGB8, R16, RG16, RGB16, RGBA16, RGBA32F, ATI1, ATI2, DXT1, DXT3, DXT5, ZLC1, ZLC2
R16 R8, RG8, RGB8, RGBA8, RG16, RGBA16, R32F, ATI1, ATI2, DXT1, DXT3, DXT5, ZLC1, ZLC2
RG16 R8, RG8, RGB8, RGBA8, R16, RGBA16, RG32F, ATI1, ATI2, DXT1, DXT3, DXT5, ZLC1, ZLC2
RGB16 R8, RG8, RGB8, RGBA8, R16, RG16, RGBA16, RGB32F, ATI1, ATI2, DXT1, DXT3, DXT5, ZLC1, ZLC2
RGBA16 RGB10A2, R8, RG8, RGB8, RGBA8, R16, RG16, RGBA32F, ATI1, ATI2, DXT1, DXT3, DXT5, ZLC1, ZLC2
R16F RG16F, RGB16F, RGBA16F, R32F, RG32F, RGB32F, RGBA32F, ZLC1, ZLC2
RG16F R16F, RGB16F, RGBA16F, R32F, RG32F, RGB32F, RGBA32F, ZLC1, ZLC2
RGB16F R16F, RG16F, RGBA16F, R32F, RG32F, RGB32F, RGBA32F, ZLC1, ZLC2
RGBA16F R16F, RG16F, RGB16F, R32F, RG32F, RGB32F, RGBA32F, ZLC1, ZLC2
R32F R8, R16, R16F, RG16F, RGB16F, RGBA16F, RG32F, RGB32F, RGBA32F, ATI1, ZLC1, ZLC2
RG32F RG8, RG16, R16F, RG16F, RGB16F, RGBA16F, R32F, RGB32F, RGBA32F, ATI2, ZLC1, ZLC2
RGB32F RGB8, RGB16, R16F, RG16F, RGB16F, RGBA16F, R32F, RG32F, RGB32F, RGBA32F, DXT1, ZLC1, ZLC2
RGBA32F RGBA8, RGBA16, R16F, RG16F, RGB16F, RGBA16F, R32F, RG32F, RGB32F, DXT3, DXT5, ZLC1, ZLC2

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 width*4 × height*3
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.

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

Copies the data from the specified source image.

Arguments

  • const Ptr<Image> & src_image - Source image.

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):
ImageSource ImageCopy
Cube2DSpecified 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 Array2DSpecified source 2D image is copied to the specified layer of the 2D image array:
2D image TO 2D_array[ layer ]
Cube ArrayCubeSpecified source cubemap image (all 6 faces) is copied to the specified layer of the cubemap image array:
cubemap_image TO cubemap_array[ layer ]
2DCubeFace 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 ]
2D2D ArraySpecified layer of the source 2D image array is copied to the 2D image:
2D image FROM 2D_array[ layer ]
CubeCube ArraySpecified 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 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 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 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

1 if 2D image is successfully created; otherwise, 0.

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

1 if 2D texture array is successfully created; otherwise, 0.

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

1 if 3D image is successfully created; otherwise, 0.

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 - 1 to fill the image with black color, 0 is 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 - 1 to allocate memory for the created image. This value should be always set to 1.

Return value

1 if the cube image is successfully created; otherwise, 0.

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, 0 is 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 - 1 to allocate memory for the created image. This value should be always set to 1.

Return value

1 if the cube array image is successfully created; otherwise, 0.

bool createMipmaps ( int filter = FILTER_LINEAR, float gamma = 1.0f ) #

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

Arguments

  • int filter - Filter type to be used: box or point. The default filter is box. See the Unigine::Image Enumerations with FILTER_* prefixes at the end of the article.
  • 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 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

1 if the image is successfully converted from the combined format; otherwise, 0.

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

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.

Arguments

  • const char * file - Name of the image file. The following file formats are supported: PSD, TGA, JPG, PNG, DDS.

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 offset ) #

Loads an image from a specified file.

Arguments

  • const char * file - Name of the image file. The following file formats are supported: DDS.
  • int 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.

Arguments

  • const char * file - Name of the image file.

Return value

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

bool load ( const char * file, int min_mip, int max_mip ) #

Loads an image from the specified file with the specified mipmap levels.

Arguments

  • const char * file - Name of the image file to be loaded. The following file formats are supported: DDS.
  • int min_mip - Minimum mipmap level for the loaded image.
  • int max_mip - Maximum mipmap level for the loaded image.

Return value

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

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

Loads an image from a specified stream.
Notice
Only DDS images can be loaded from a stream.

Arguments

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

Return value

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

bool normalize ( ) #

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

Return value

1 if normalization was successful; otherwise, 0.

bool resize ( int new_width, int new_height, int 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.
  • int filter - Quality setting, accepts one of the FILTER_* values.

Return value

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

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

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

bool save ( const char * file ) #

Saves the image to a DDS file with the specified name.

Arguments

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

Return value

Returns 1 if the image is saved successfully; otherwise, 0.

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

Saves the image to a specified file. The following file formats are supported:
  • DDS
  • JPG
  • PNG
  • PSD
  • TGA

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

Returns 1 if the image is saved successfully; otherwise, 0.

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

Saves the image to a stream. The following file formats are supported:
  • DDS
  • JPG
  • PNG
  • PSD
  • TGA

Arguments

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

Return value

Returns 1 if the image is saved successfully; otherwise, 0.

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.

bool swap ( int channel, int index ) #

Swaps values of two channels. Compressed formats are not supported.

Arguments

  • int channel - First channel number in range of 0 to (number of channels - 1).
  • int index - Second channel number in range of 0 to (number of channels - 1).

Return value

1 if the values are swapped 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

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, ZLC1, ZLC2, LZ4).

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, ZLC1, ZLC2, LZ4).

Arguments

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

Return value

Block size for the specified image format.

int getDepth ( ) #

Returns the image depth, in pixels.

Return value

Image depth, in pixels

int getHeight ( ) #

Returns the image height, in pixels.

Return value

Image height, in pixels

int getWidth ( ) #

Returns the image width, in pixels.

Return value

Image width, in pixels
Last update: 2020-01-21