Image Class

This class is intended to handle textures and other images.

See Also

Image Class

Members

---

Image ()

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

Image (variable v)

Constructor. Creates a new image instance.

Arguments

• variable v - This value can be:
  • string - path to an image file.
  • Image - source image.

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. Images of different formats can be blended as follows:

Current Image Format	Source Image Format
R8	R8, RG8
RG8	RG8, RGB8
RGB8	RGB8, RGBA8
RGBA8	RGBA8 only
R16	R16, RG16
RG16	RG16, RGB16
RGB16	RGB16, RGBA16
RGBA16	RGBA16 only
R32F	R32F, RG32F
RG32F	RG32F, RGB32F
RGB32F	RGB32F, RGBA32F
RGBA32F	RGBA32F 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 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.
• 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.

Arguments

• int size - Blur 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 and the blurring kernel is 5x5 pixels.

Return value

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

void clear ()

Clears all data associated with the image and resets its size, type and format to defaults.

int combineMipmaps ()

Combines the loaded 2D-image with the mipmap image. 2D-image shouldn't be of compressed format and combining of only one mipmap image is available.

Return value

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

int combine (int new_format = -1)

Converts the image to a combined format. The following variants of conversion are possible:

Source type	Target type
RGB8	R5G6B5
RGBA8	RGB5A1 (by default) RGBA4
RGBA16	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 compare (Image image, int x0, int y0, int x1, int y1, int width, int height, int threshold = 0)

Compares the region of the specified image with the region of loaded one. Neither of images should be of a float, half-float, combined or compressed format.

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

Source type	Target type
R8	EAC1 if the format is specified as EAC1 ATI1 by default
RG8	EAC2 if the format is specified as EAC2 ATI2 by default
RGB8	ATC1 if the format is specified as ATC1 ETC1 if the format is specified as ETC1 ETC2 if the format is specified as ETC2 DXT1 by default
RGBA8	DXT3 if the format is specified as DXT3 ETC5 if the format is specified as ETC5 ATC3 if the format is specified as ATC3 ATC5 if the format is specified as ATC5 PVR4 if the format is specified as PVR4 DXT5 by default

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 conversion into compressed format is successful; 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
R8	ATI1, RG8, RGB8, RGBA8, R16, RG16, RGBA16, PVR4, ATC1, ATC3, ATC5, ETC1, ETC2, ETC5, EAC1, EAC2, ZLC1, ZLC2
RG8	ATI2, R8, RGB8, RGBA8, R16, RG16, RGBA16, PVR4, ATC1, ATC3, ATC5, ETC1, ETC2, ETC5, EAC1, EAC2, ZLC1, ZLC2
RGB8	R5G6B5, R8, RG8, RGBA8, R16, RG16, RGBA16, PVR4, DXT1, ATC1, ATC3, ETC2, ETC5, EAC1, EAC2, ZLC1, ZLC2
RGBA8	RGBA4, RGB5A1, DXT3, DXT5, R8, RG8, RGB8, R16, RG16, RGB16, RGBA16, ATC1, ATC3, ATC5, ETC1, ETC2, ETC5, EAC1, EAC2, ZLC1, ZLC2
R16	R8, RG8, RGB8, RGBA8, RG16, RGBA16, PVR4, ATC1, ATC3, ATC5, ETC1, ETC2, ETC5, EAC1, EAC2, ZLC1, ZLC2
RG16	R8, RG8, RGB8, RGBA8, R16, RGBA16, PVR4, ATC1, ATC3, ETC1, ETC2, ETC5, EAC1, EAC2, ZLC1, ZLC2
RGB16	R8, RG8, RGB8, RGBA8, R16, RG16, RGBA16, PVR4, ATC1, ATC3, ATC5, ETC1, ETC2, ETC5, EAC1, EAC2, ZLC1, ZLC2
RGBA16	RGB10A2, R8, RG8, RGB8, RGBA8, R16, RG16, PVR4, ATC1, ATC3, ATC5, ETC1, ETC2, ETC5, EAC1, EAC2, ZLC1, ZLC2
R16F	RG16F, RGBA16F, ZLC1, ZLC2
RG16F	R16F, RGBA16F, ZLC1, ZLC2
RGB16F	R16F, RG16F, RGBA16F
RGBA16F	R16F, RG16F, ZLC1, ZLC2
R32F	RG32F, RGBA32F, ZLC1, ZLC2
RG32F	R32F, RGBA32F, ZLC1, ZLC2
RGB32F	R32F, RG32F, RGBA32F, ZLC1, ZLC2
RGBA32F	R32F, RG32F, RGBA32F, 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 - One of image types: IMAGE_2D , IMAGE_3D , IMAGE_CUBE . IMAGE_2D_ARRAY .

Return value

1 if the conversion is successful; otherwise, 0.

int copy (Image image, int layer)

Copies a given layer of the source image to the 2D texture.

Arguments

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

Return value

1 if the layer has been copied successfully; otherwise, 0.

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

Copies a channel value of a source image into a specified channel of the current image. Compressed and combined image formats are not supported for both the source and the target images. The images must have the same dimensions.

Arguments

• Image image - Source image.
• int channel - Target channel.
• int index - Source channel.

Return value

1 if the channel has been copied successfully; otherwise, 0.

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

Copies part of a specified image into the current one. Neither of images should of a compressed format. If the rectangle to be copied lies outside the bounds of the source image, it will lead to engine crash due to the memory corruption error. If the safe flag is set to 1, the rectangle won't be rendered outside the boundaries of the destination image.

Arguments

• Image image - Source image, from which data will be copied.
• int x_dst - X coordinate of a position in the image, where data will be copied to.
• int y_dst - Y coordinate of a position in the image, where data will be copied to.
• 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 a region to copy.
• int height - Height of a 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 copying is successful; otherwise, 0.

void copy (Image image)

Copies the specified image into the current one.

Arguments

• Image image - Source image.

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 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 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 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 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 createMipmaps (int filter = IMAGE_FILTER_LINEAR, float gamma = 1.0f)

Generates mipmaps for the image. Mipmaps cannot be created for compressed images.

Arguments

• int filter - Type of the filter to be used: linear or point.
• float gamma - Value of gamma correction. If 1 is provided, no gamma correction is applied. This is an optional argument.

Return value

1 if mipmaps are generated successfully; otherwise, 0.

int decombineMipmaps ()

Decombines the loaded 2D-image and the mipmap image. For the operation to be successful, 2D-image shouldn't be of compressed format.

Return value

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

int decombine ()

Automatically converts the image from the combined format into a correct one. The following conversions will be done:

Source type	Target type
R5G6B5	RGB8
RGBA4	RGBA8
RGB5A1	RGBA8
RGB10A2	RGBA16

Return value

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

int decompress ()

Automatically decompresses the image into a correct format. The following conversions will be done:

Source type	Target type
DXT1	RGBA8
DXT1 without alpha data	RGB8
DXT3	RGBA8
DXT5	RGBA8
ATI1	R8
ATI2	RG8
ETC1	RGB8
ETC2	RGB8
ETC5	RGBA8
EAC1	R8
EAC2	RG8
ATC1	RGB8
ATC3	RGBA8
ATC5	RGBA8
PVR4	RGBA8

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 given number of pixels.

Arguments

• int pixels - Extrusion depth.

Return value

1 if the contour was 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.

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 - X coordinate of a pixel. It can be:
  • int in range [0; width]
  • float (in range [0;1]
    If the provided value is outside the range, modulus is used 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;1]
    If the provided value is outside the range, modulus is used is used to count pixels from the beginning.
• int layer - Layer number.

Return value

Color of the target pixel with components normalized in range from 0 to 1.

vec4 get2D (variable x, variable y)

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;1]
    If the provided value is outside the range, modulus is used 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;1]
    If the provided value is outside the range, modulus is used is used to count pixels from the beginning.

Return value

Color of the target pixel with components 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 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;1]
    If the provided value is outside the range, modulus is used 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;1]
    If the provided value is outside the range, modulus is used 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;1]
    If the provided value is outside the range, modulus is used is used to count pixels from the beginning.

Return value

Color of the target pixel with components normalized in range from 0 to 1.

int getBlockSize ()

Returns the compressed image block size.

Return value

Block size, in bytes.

vec4 getCubeArray (variable v1, variable v2, int face, 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).
• int layer - Image layer number.

Return value

Color of the pixel.

vec4 getCubeArray (vec3 direction, int layer)

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

Arguments

• vec3 direction - Cube direction vector used for color sampling.
• int layer - Image layer number.

Return value

Color of the target pixel with components normalized in range from 0 to 1.

vec4 getCube (variable x, variable y, int face)

Returns a color of a given pixel. The image must be of the cube 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;1]
    If the provided value is outside the range, modulus is used 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;1]
    If the provided value is outside the range, modulus is used is used to count pixels from the beginning.
• int face - Number of a face in range from 0 to 5.

Return value

Color of the target pixel with components normalized in range from 0 to 1.

vec4 getCube (vec3 direction)

Returns a color of a given pixel. The image must be of the cube type.

Arguments

• vec3 direction - Direction vector used for color sampling.

Return value

Color of the target pixel with components normalized in range from 0 to 1.

int getDepth (int level = 0)

Returns image depth on a given mipmap level.

Arguments

• int level - Mipmap level. This is an optional argument.

Return value

Image depth (limits the Z coordinate of pixels).

string getFormatName ()

Returns a format name.

Return value

Image format name.

int getFormat ()

Returns a numerical code of the image format.

Return value

Numerical code of the image format.

int getHeight (int level = 0)

Returns image height on a given mipmap level.

Arguments

• int level - Mipmap level. This is an optional argument.

Return value

Image height (limits the Y coordinate of pixels).

int getNumChannels ()

Returns the number of image channels.

Return value

Number of image channels.

int getNumFaces ()

Returns the number of image faces.

Return value

Number of image faces.

int getNumLayers ()

Returns a number of layers in the texture array.

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 the given mipmap level.

Arguments

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

Return value

Image offset, in bytes.

int getPixelSize ()

Returns the uncompressed image pixel size.

Return value

Pixel size, in bytes.

void getPixels (Blob image)

Gets the image from the blob.

Arguments

• Blob image - The target image.

int getSize ()

Returns the current size of the image.

Return value

Size of the image, bytes.

int getSize (int level)

Returns the image size on a given mipmap level.

Arguments

• int level - Mipmap level.

Return value

Image size.

int getStride (int level)

Returns the image stride on the given mipmap level.

Arguments

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

Return value

Image stride, in bytes.

string getTypeName ()

Returns a type name.

Return value

Image type name.

int getType ()

Returns a numerical code of the image type.

Return value

Numerical code of the image type.

int getWidth (int level = 0)

Returns image width on a given mipmap level.

Arguments

• int level - Mipmap level. This is an optional argument.

Return value

Image width (limits the X coordinate of pixels).

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.

Return value

1 if values are inverted successfully; otherwise, 0.

int is2DType ()

Returns a value indicating if the image is 2D.

Return value

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

int is3DType ()

Returns a value indicating if the image is 3D.

Return value

1 if the image is 3D; otherwise - 0.

int isArrayType ()

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

Return value

1 if the image is 3D; otherwise - 0.

int isCombinedFormat ()

Returns a value indicating if the image is in a combined format.

Return value

1 if the image format is one of the following:

• IMAGE_FORMAT_R5G6B5
• IMAGE_FORMAT_RGBA4
• IMAGE_FORMAT_RGB5A1
• IMAGE_FORMAT_RGB10A2

Otherwise, 0 is returned.

int isCompressedFormat ()

Returns a value indicating if the image is compressed.

Return value

1 if the image format is one of the following:

• IMAGE_FORMAT_DXT1
• IMAGE_FORMAT_DXT3
• IMAGE_FORMAT_DXT5
• IMAGE_FORMAT_ATI1
• IMAGE_FORMAT_ATI2
• IMAGE_FORMAT_ETC1
• IMAGE_FORMAT_PVR4

Otherwise, 0 is returned.

int isCubeType ()

Returns a value indicating if the image is a cube texture.

Return value

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

int isFloatFormat ()

Returns a value indicating if the image is stored in a float format.

Return value

1 if the image format is one of the following:

• IMAGE_FORMAT_R32F
• IMAGE_FORMAT_RG32F
• IMAGE_FORMAT_RGB32F
• IMAGE_FORMAT_RGBA32F

Otherwise, 0 is returned.

int isHalfFormat ()

Returns a value indicating if the image is stored in a half-float format.

Return value

1 if the image format is one of the following:

• IMAGE_FORMAT_R16F
• IMAGE_FORMAT_RG16F
• IMAGE_FORMAT_RGB16F
• IMAGE_FORMAT_RGBA16F

Otherwise, 0 is returned.

int isLoaded ()

Returns a value indicating whether the image data are loaded.

Return value

1 if the image is loaded; otherwise, 0.

int isRawFormat ()

Returns a value indicating if the image is uncompressed. See the IMAGE_FORMAT_* variables.

Return value

1 if the image format is one of the following:

• FORMAT_R8
• FORMAT_RG8
• FORMAT_RGB8
• FORMAT_RGBA8
• FORMAT_R16
• FORMAT_RG16
• FORMAT_RGB16
• FORMAT_RGBA16
• FORMAT_R16F
• FORMAT_RG16F
• FORMAT_RGB16F
• FORMAT_RGBA16F
• FORMAT_R32F
• FORMAT_RG32F
• FORMAT_RGB32F
• FORMAT_RGBA32F
• FORMAT_R5G6B5
• FORMAT_RGBA4
• FORMAT_RGB5A1
• FORMAT_RGB10A2

Otherwise, 0 is returned.

int isUCharFormat ()

Returns a value indicating if the image is stored in an unsigned char format.

Return value

1 if the image format is one of the following:

• IMAGE_FORMAT_R8
• IMAGE_FORMAT_RG8
• IMAGE_FORMAT_RGB8
• IMAGE_FORMAT_RGBA8
• IMAGE_FORMAT_DXT1
• IMAGE_FORMAT_DXT3
• IMAGE_FORMAT_DXT5
• IMAGE_FORMAT_ATI1
• IMAGE_FORMAT_ATI2
• IMAGE_FORMAT_ETC1
• IMAGE_FORMAT_PVR4

Otherwise, 0 is returned.

int isUShortFormat ()

Returns a value indicating if the image is stored in an unsigned short int format.

Return value

1 if the image format is one of the following:

• IMAGE_FORMAT_R16
• IMAGE_FORMAT_RG16
• IMAGE_FORMAT_RGB16
• IMAGE_FORMAT_RGBA16

Otherwise, 0.

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:

• #IMAGE_FORMAT_ZLC1
• #IMAGE_FORMAT_ZLC2

Otherwise, 0.

int load (string file)

Loads image data from a specified file.

Arguments

• string file - Name of a file, from which data will be loaded.

Return value

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

int load (string file, int offset)

Loads image data from a specified file with given mipmap offset.

Arguments

• string file - Name of a file, from which data will be loaded.
• int offset - Mipmap offset.

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 is successful; otherwise, 0.

int resize (int new_width, int new_height, int filter = IMAGE_FILTER_LINEAR)

Sets new image dimensions. The image should be uncompressed and of the 2D type.

Arguments

• int new_width - New image width.
• int new_height - New image height.
• int filter - Quality setting, accepts one of the IMAGE_FILTER_* values.

Return value

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

int rotate (int angle)

Rotates the image by a given angle (with the step of 90 degrees). Compressed images 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, float quality)

Saves the image to a specified file. Supported file formats: DDS, JPG, PNG, PSD, TGA, HDR.

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

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

int save (string name)

Saves the image to a specified file. Supported file formats: DDS, JPG, PNG, PSD, TGA, HDR.

Arguments

• string name - Name of a file with extension into which data will be saved.

Return value

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

void set2DArray (int x, int y, int layer, float r, float g = 0.0f, float b = 0.0f, float a = 1.0f)

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

Arguments

• int x - X coordinate of a pixel.
• int y - Y coordinate of a pixel.
• int layer - Layer number
• 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.

void set2DArray (int x, int y, int layer, variable color)

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

Arguments

• int x - X coordinate of a pixel.
• int y - Y coordinate of a pixel.
• int layer - Layer number
• 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).

void set2D (int x, int y, float r, float g = 0.0f, float b = 0.0f, float a = 1.0f)

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

Arguments

• int x - X coordinate of a pixel.
• int y - Y coordinate of a pixel.
• 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.

void set2D (int x, int y, variable color)

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

Arguments

• int x - X coordinate of a pixel.
• int y - Y coordinate of a pixel.
• 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).

void set3D (int x, int y, int z, float r, float g = 0.0f, float b = 0.0f, float a = 1.0f)

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

Arguments

• int x - X coordinate of a pixel.
• int y - Y coordinate of a pixel.
• int z - Z coordinate of a pixel.
• 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.

void set3D (int x, int y, int z, variable color)

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

Arguments

• int x - X coordinate of a pixel.
• int y - Y coordinate of a pixel.
• int z - Z coordinate of a pixel.
• 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).

void setCubeArray (int x, int y, int face, int layer, float r, float g = 0.0f, float b = 0.0f, float a = 1.0f)

Sets a color for a given pixel of the cube array image.

Arguments

• int x - X coordinate of a pixel.
• int y - Y coordinate of a pixel.
• int face - Face number (in range from 0 to 5).
• int layer - Image layer number.
• 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.

void setCubeArray (int x, int y, int face, int layer, variable color)

Sets a color for a given pixel of the cube array image.

Arguments

• int x - X coordinate of a pixel.
• int y - Y coordinate of a pixel.
• int face - Face number (in range from 0 to 5).
• int layer - Image layer number.
• 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).

void setCube (int x, int y, int face, float r, float g = 0.0f, float b = 0.0f, float a = 1.0f)

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

Arguments

• int x - X coordinate of a pixel.
• int y - Y coordinate of a pixel.
• int face - Number of a face in range from 0 to 5.
• 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.

void setCube (int x, int y, int face, variable color)

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

Arguments

• int x - X coordinate of a pixel.
• int y - Y coordinate of a pixel.
• int face - Number of a face in range from 0 to 5.
• 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).

void setPixels (Blob image)

Adds the image to the blob.

Arguments

• Blob image - The image to be added.

int set (int channel, int value)

Sets a value for a given channel. Compressed 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.

int sign ()

Returns the value indicating if the image has been converted successfully.

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 - The first channel number in range from 0 to number of channels - 1.
• int index - The second channel number in range from 0 to number of channels - 1.

Return value

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

---

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.

int IMAGE_FILTER_LINEAR

Description

A linear mipmap filter.

int IMAGE_FILTER_POINT

Description

A point mipmap filter.

int IMAGE_FORMAT_ATC1

Description

An ATC1 proprietary compressed image file format used for textures on Qualcomm mobile devices. In addition to color, it is used to store the 1-bit alpha data.

int IMAGE_FORMAT_ATC3

Description

An ATC3 proprietary compressed image file format used for textures on Qualcomm mobile devices. In addition to color, it is used to store alpha values with sharp transitions.

int IMAGE_FORMAT_ATC5

Description

An ATC5 proprietary compressed image file format used for textures on Qualcomm mobile devices. In addition to color, it is used to store alpha values with smooth transitions.

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_EAC1

Description

An EAC1 compressed image file format used for mobile devices: single-channel texture compression for storing gray-scale values.

int IMAGE_FORMAT_EAC2

Description

An EAC2 compressed image file format used for mobile devices: two-channel texture compression, for example, for normal maps.

int IMAGE_FORMAT_ETC1

Description

An ETC1 compressed image file format. Compresses RGB images by a factor of 4:1 compared to R5G6B5. It compresses each 4x4 pixel block to precisely 64 bits of binary data, due to that graphics hardware require exactly one memory access to fetch a texel from the image. ETC1 does not support an alpha channel, so can only be used for opaque textures. This format is natively supported by all Android devices.

int IMAGE_FORMAT_ETC2

Description

An ETC2 compressed image file format used for mobile devices. It has a better color compression quality than ETC1, but alpha is not supported.

int IMAGE_FORMAT_ETC5

Description

Compressed format used for textures on mobile devices. It is similar to ETC2, but with alpha supported.

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.