Image Class

Interface for handling textures and other images.

Textures are stored on CPU.

Image Class

Members

---

static Image()

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

static Image(string name)

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

Arguments

• string name - Image file name.

int 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

1 if the values is set successfully; otherwise, 0.

void set2D(int x, int y, float r, float g, float b, float a, variable color)

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].
• float r - Red component of a color normalized in range from 0 to 1.
• float g - Green component of a color normalized in range from 0 to 1.
• float b - Blue component of a color normalized in range from 0 to 1.
• float a - Alpha component of a color normalized in range from 0 to 1.
• variable color - Color. It can be a vector of 4 float or integer components (vec4 or ivec4) or a scalar (for images with a single channel).

vec4 get2DArray(variable x, variable y, int layer)

Returns a color of a given pixel. The image must be a 2D texture array. Compressed formats are not supported.If float coordinates are provided, linear interpolation is used to get a color sample.

Arguments

• variable x - The X coordinate of a pixel. It can be one of the following:
  • int in range [0; width]
  • 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.
• variable y - 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.
• int layer - Image layer number.

Return value

Color. It can be a vector of 4 float or integer components (vec4 or ivec4) or a scalar (for images with a single channel).

int 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, float r, float g, float b, float a)

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].
• float r - Red component of a color normalized in range from 0 to 1.
• float g - Green component of a color normalized in range from 0 to 1.
• float b - Blue component of a color normalized in range from 0 to 1.
• float a - Alpha component of a color normalized in range from 0 to 1.

vec4 get3D(variable x, variable y, variable z)

Returns a color of a given pixel. The image must be of the 2D type. Compressed formats are not supported. If float coordinates are provided, linear interpolation is used to get a color sample.

Arguments

• variable x - X coordinate of a pixel. It can be:
  • int in range [0; width].
  • 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.
• variable y - Y coordinate of a pixel. It can be:
  • int in range [0; width].
  • 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.
• variable z - Z coordinate of a pixel. It can be:
  • int in range [0; width].
  • 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

Color. It can be a vector of 4 float or integer components (vec4 or ivec4) or a scalar (for images with a single channel).

vec4 get3D(variable x, variable y, variable z)

Returns a color of a given pixel. The image must be of the 3D type. Compressed formats are not supported. If float coordinates are provided, linear interpolation is used to get a color sample.

Arguments

• variable x - X coordinate of a pixel. It can be:
  • int in range [0; width].
  • 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.
• variable y - 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.
• variable z - Z coordinate of a pixel. Must be of the same type as x:
  • int in range [0; depth].
  • 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

Color. It can be a vector of 4 float or integer components (vec4 or ivec4) or a scalar (for images with a single channel).

int is3DType()

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

Return value

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

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

int getBlockSize()

Returns the compressed image block size.

Return value

Block size in bytes.

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

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

vec4 getCubeArray(variable v1, variable v2, int face, vec3 direction, int layer)

Returns the color of a given pixel of the cube array image. Both the first and the second passed arguments mush be either of the float or of the integer type.

Arguments

• variable v1 - Argument of one of the following types:
  • int x - X coordinate of the pixel normalized in range [0; width].
  • float x - X coordinate of the pixel normalized in range [0; 1].
• variable v2 - Argument of one of the following types:
  • int y - Y coordinate of the pixel normalized in range [0; height].
  • float y - Y coordinate of the pixel normalized in range [0; 1].
• int face - Face number (in the range from 0 to 5).
• vec3 direction - Cube direction vector used for color sampling.
• int layer - Image layer number.

Return value

Color. It can be a vector of 4 float or integer components (vec4 or ivec4) or a scalar (for images with a single channel).

vec4 getCubeArray(variable v1, variable v2, int face, int layer, vec3 direction)

Returns the color of a given pixel of the cube array image. Both the first and the second passed arguments mush be either of the float or of the integer type.

Arguments

• variable v1 - Argument of one of the following types:
  • int x - X coordinate of the pixel normalized in range [0; width].
  • float x - X coordinate of the pixel normalized in range [0; 1].
• variable v2 - Argument of one of the following types:
  • int y - Y coordinate of the pixel normalized in range [0; height].
  • float y - Y coordinate of the pixel normalized in range [0; 1].
• int face - Face number in range from 0 to 5.
• int layer - Image layer number.
• vec3 direction - Cube direction vector used for color sampling.

Return value

Color. It can be a vector of 4 float or integer components (vec4 or ivec4) or a scalar (for images with a single channel).

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

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

int getFormat()

Returns a numerical code of the image format.

Return value

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

string getFormatName()

Returns an image format name. For more details about image formats see the article on ImageDDS tool.

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.

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

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.

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

int 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(Blob blob)

Adds the image to the blob.

Arguments

• Blob blob - The image to be added.

void getPixels(Blob blob)

Gets the image from the blob.

Arguments

• Blob blob - The target image.

int getPixelSize()

Returns the uncompressed image pixel size.

Return value

Pixel size, in bytes.

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

int getSize()

Returns the current image size.

Return value

Image size, in bytes.

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

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

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.

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

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

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

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.

int 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 format is one of the following:

• FORMAT_ZLC1
• FORMAT_ZLC2

Otherwise, 0.

int blend(Image image, int x0, int y0, int x1, int y1, int width, int height, float scale = 1.0f, int 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

• 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.
• int safe - 1 for safe blending with respect to destination image boundaries; otherwise, 0.

Return value

Returns 1 if blending is successful; otherwise, 0.

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

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

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

int compare(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

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

int 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 IMAGE_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.

int copy(const Image & image, int layer)

Copies a specified layer between images.

Arguments

• const Image & image - Source image.
• int layer - Layer number.

Return value

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

int copy(const Image & image, int x_dst, int y_dst, int x_src, int y_src, int width, int height, int safe = 0)

Copies a given layer between images.

Arguments

• const Image & image - Source image.
• int x_dst - Layer number.
• int y_dst - Source channel.
• int x_src - X coordinate of a position in a source image, where data will be copied from.
• int y_src - Y coordinate of a position in a source image, where data will be copied from.
• int width - Width of an image region to copy.
• int height - Height of an image region to copy.
• int 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 boundries.

Return value

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

int copy(const Image & image, int channel, int index)

Copies a given layer between images.

Arguments

• const Image & image - Source image.
• int channel - Layer number.
• int index - Source channel.

Return value

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

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

Creates an empty 2D image filled with black color.

Arguments

• int width - Desired width.
• int height - Desired height.
• int format - Desired 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.
• int 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.
• int 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.

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

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

Arguments

• int width - Desired width.
• int height - Desired height.
• int num_layers - Number of texture layers.
• int format - Desired 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.
• int 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.
• int 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.

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

Creates an empty 3D image filled with black color.

Arguments

• int width - Desired width.
• int height - Desired height.
• int depth - Desired depth.
• int format - Desired 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.
• int 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.
• int 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.

int createCube(int width, int height, int format, int num_mipmaps = 1, int clear = 1, int 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 IMAGE_FORMAT_* variables.
• int num_mipmaps - Number of mipmaps to create. This is an optional argument.
• int 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.
• int 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.

int createCubeArray(int width, int height, int num_layers, int format, int num_mipmaps = 1, int clear = 1, int 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 IMAGE_FORMAT_* variables.
• int num_mipmaps - Number of mipmaps to create. This is an optional argument.
• int 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.
• int 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.

int 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

Returns 1 if the mipmaps are generated successfully; otherwise, 0.

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

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

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

int 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 - Extrusion depth.

Return value

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

int flipX()

Flips the non-compressed 2D image about the X axis.

Return value

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

int flipY()

Flips the non-compressed 2D image about the Y axis.

Return value

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

int info(string name)

Returns information about the given image.

Arguments

• string name - Name of a file.

Return value

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

int 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

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

int load(string file, int offset)

Loads an image from a specified file.

Arguments

• string file - Name of the image file. The following file formats are supported: JPG and PNG.
• int offset - Mipmap offset.

Return value

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

int load(string file)

Loads an image from a specified file.

Arguments

• string file - Name of the image file. The following file formats are supported: JPG and PNG.

Return value

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

int normalize()

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

Return value

1 if normalization was successful; otherwise, 0.

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

int 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 will be multiplied by the step (angle * 90) to set the image rotation degree.

Return value

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

int save(string name)

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

• DDS
• JPG
• PNG
• PSD
• TGA

Arguments

• string name - Name of the file (with the specified extension) to save image data.

Return value

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

int save(string name, float quality)

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

• DDS
• JPG
• PNG
• PSD
• TGA

Arguments

• string name - 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.

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

int swap(int channel, int index)

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

Arguments

• int channel
• int index

Return value

1 if the values are swapped successfully; otherwise, 0.

void swap(Image image)

Swaps the data of the current mesh file with the source mesh file.

Arguments

• Image image - Source mesh.

---

int IMAGE_FILTER_LINEAR

Description

A linear mipmap filter.

int IMAGE_FILTER_POINT

Description

A point mipmap filter.

int IMAGE_FORMAT_ATI1

Description

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.

int IMAGE_FORMAT_ATI2

Description

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.

int IMAGE_FORMAT_DXT1

Description

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.

int IMAGE_FORMAT_DXT3

Description

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.

int IMAGE_FORMAT_DXT5

Description

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.

int IMAGE_FORMAT_LZ4

Description

An LZ4 lossless data compression algorithm that is focused on compression and decompression speed. It belongs to the LZ77 family of byte-oriented compression schemes.

int IMAGE_FORMAT_R16

Description

Non-compressed unsigned format. Stores data in one 16-bit channel (red).

int IMAGE_FORMAT_R16F

Description

Non-compressed float format. Stores data in one 16-bit channel (red).

int IMAGE_FORMAT_R32F

Description

Non-compressed float format. Stores data in one 32-bit channel (red).

int IMAGE_FORMAT_R8

Description

Non-compressed unsigned format. Stores data in one 8-bit channel (red).

int IMAGE_FORMAT_RG16

Description

Non-compressed unsigned format. Stores data in two 16-bit channels (red, green).

int IMAGE_FORMAT_RG16F

Description

Non-compressed float format. Stores data in two 16-bit channels (red, green).

int IMAGE_FORMAT_RG32F

Description

Non-compressed float format. Stores data in two 32-bit channels (red, green).

int IMAGE_FORMAT_RG8

Description

Non-compressed unsigned format. Stores data in two 8-bit channels (red, green).

int IMAGE_FORMAT_RGB10A2

Description

Combined unsigned format. Stores data in three 10-bit channels (red, green, blue) and one 2-bit channel (alpha).

int IMAGE_FORMAT_RGB16

Description

Non-compressed unsigned format. Stores data in three 16-bit channels (red, green, blue).

int IMAGE_FORMAT_RGB16F

Description

Non-compressed float format. Stores data in three 16-bit channels (red, green, blue).

int IMAGE_FORMAT_RGB32F

Description

Non-compressed float format. Stores data in three 32-bit channels (red, green, blue).

int IMAGE_FORMAT_RGB565

Description

Combined unsigned format. Stores 16 bit color values without alpha.

int IMAGE_FORMAT_RGB5A1

Description

Combined unsigned format. Stores data in three 5-bit channels (red, green, blue) and one 1-bit channel (alpha).

int IMAGE_FORMAT_RGB8

Description

Non-compressed unsigned format. Stores data in three 8-bit channels (red, green, blue).

int IMAGE_FORMAT_RGBA16

Description

Non-compressed unsigned format. Stores data in four 16-bit channels (red, green, blue, alpha).

int IMAGE_FORMAT_RGBA16F

Description

Non-compressed float format. Stores data in four 16-bit channels (red, green, blue, alpha).

int IMAGE_FORMAT_RGBA32F

Description

Non-compressed float format. Stores data in four 32-bit channels (red, green, blue, alpha).

int IMAGE_FORMAT_RGBA4

Description

Combined unsigned format. Stores data in four 4-bit channels (red, green, blue, alpha).

int IMAGE_FORMAT_RGBA8

Description

Non-compressed unsigned format. Stores data in four 8-bit channels (red, green, blue, alpha).

int IMAGE_FORMAT_ZLC1

Description

Compressed format used for images stored in the system memory (based on zlib library). It is used for fast compression (for example, in run-time).

int IMAGE_FORMAT_ZLC2

Description

Compressed format used for images stored in the system memory (based on zlib library). It is used when a smaller file size is required, if compared to ZLC1 format.

int IMAGE_2D

Description

A 2D texture.

int IMAGE_2D_ARRAY

Description

A 2D texture array. Each texture of the array has its own mipmap levels, which is the difference between it and a 3D image.

int IMAGE_3D

Description

A 3D texture.

int IMAGE_CUBE

Description

A cube texture.

int IMAGE_CUBE_ARRAY

Description

A cube texture array.