Image

Type

Image

An Image contains pixel data making up an image. The data can be in multiple formats (see the 'Image Pixel Formats' section below).

The type also has various functions for manipulating image data and reading the various formats supported by SLADE (see ImageFormat).

Image Pixel Formats

An image can have one of three pixel formats, which determines how data for each pixel is stored:

Format	Description
`PIXELFORMAT_INDEXED`	The image is 8-bit with a mask. Each pixel is 2 bytes - one palette index and one alpha value. The palette can be stored in the image (see palette/hasPalette properties). If it doesn't have an internal palette, an external one needs to be supplied in any functions dealing with colours in the image
`PIXELFORMAT_RGBA`	The image is 32-bit. Each pixel is 4 bytes - red, green, blue, alpha
`PIXELFORMAT_ALPHA`	The image is purely an 8-bit alpha map. Each pixel is 1 byte - the alpha value

Constants

Name	Value
`PIXELFORMAT_INDEXED`	0
`PIXELFORMAT_RGBA`	1
`PIXELFORMAT_ALPHA`	2
`SOURCE_BRIGHTNESS`	0
`SOURCE_ALPHA`	1

Properties

Property	Type	Description
pixelFormat	integer	The format of the pixels in the image (see Image Pixel Formats)
width	integer	The width of the image
height	integer	The height of the image
hasPalette	boolean	Whether this image has an internal palette
palette	Palette	The image's internal palette. If hasPalette is `false` this will be greyscale
offsetX	integer	The X offset of the image
offsetY	integer	The Y offset of the image
stride	integer	The number of bytes per row of image data
bpp	integer	The number of bytes per pixel in the image data

Constructors

Image.new()

Creates a new, empty image with pixelFormat PIXELFORMAT_RGBA.

Image.new(pixelFormat)

Creates a new, empty image of pixelFormat.

Parameters

pixelFormat (integer): The pixel format of the image (see PIXELFORMAT_ constants)

Functions

Overview

General

Clear() Copy(other) Create(width, height, type, palette)

Image Info

CountUniqueColours() -> integer FindUnusedColour() -> integer IsValid() -> boolean PixelAt(x, y, [palette]) -> Colour PixelIndexAt(x, y) -> integer

Read Data

LoadData(data, [index], [typeHint]) -> boolean LoadEntry(entry, [index]) -> boolean, string

Write Data

WriteIndexedData(block) -> boolean WriteRGBAData(block, [palette]) -> boolean WriteRGBAData(block, [palette]) -> boolean

Pixel Format Conversion

ConvertAlphaMap(alphaSource, [palette]) -> boolean ConvertIndexed(newPalette, [currentPalette]) -> boolean ConvertRGBA([palette]) -> boolean

General Modification

Crop(left, top, right, bottom) -> boolean MirrorHorizontal() -> boolean MirrorVertical() -> boolean Resize(newWidth, newHeight) -> boolean Rotate(angle) -> boolean Trim()

Colour Modification

ApplyTranslation(translation, [palette], [trueColour]) -> boolean Colourise(colour, [palette]) -> boolean SetPixelColour(x, y, colour, [palette]) -> boolean SetPixelIndex(x, y, index, [alpha]) -> boolean Tint(colour, amount, [palette]) -> boolean

Alpha Modification

FillAlpha(alpha) MaskFromBrightness([palette]) -> boolean MaskFromColour(colour, [palette]) -> boolean

Drawing

DrawImage(x, y, srcImage, drawOptions, [srcPalette], [destPalette]) -> boolean DrawPixel(x, y, colour, drawOptions, [palette]) -> boolean

Clear

Clears all image data, resetting size and offsets to 0.

Copy

Copies all data and properties from another Image.

Parameters

other (Image): The image to copy from

Create

(Re)Creates the image with the given properties.

Parameters

width (integer): The width of the image
height (integer): The height of the image
type (integer): The type of image to create (see PIXELFORMAT_ constants)
[palette] (Palette, default nil): The palette to use as the internal image palette

CountUniqueColours

Counts the number of unique colours present in the image.

Returns

integer: The number of unique colours present in the image, or 0 if the image isn't PIXELFORMAT_INDEXED

FindUnusedColour

Gets the index of the first unused colour in the palette. Will return -1 if the image isn't PIXELFORMAT_INDEXED or if all colours are used.

Returns

integer: The index of the first colour in the palette not used in the image.

IsValid

Checks if the image is valid (ie. has any data).

Returns

boolean: true if the image has any data

PixelAt

Parameters

x (integer): The X position of the pixel
y (integer): The Y position of the pixel
[palette] (Palette): The palette to use if the image is PIXELFORMAT_INDEXED and has no internal palette. Default is nil

Returns

Colour: The colour of the pixel at (x,y) in the image, or black+transparent if the given coordinates were out of range

PixelIndexAt

Gets the palette index of the pixel at (x,y). Will be -1 if the given coordinates were out of range, or if the image isn't PIXELFORMAT_INDEXED.

Parameters

x (integer): The X position of the pixel
y (integer): The Y position of the pixel

Returns

integer: The palette index of the pixel at (x,y)

LoadData

Reads the given data to the image. The data can be in any supported image format.

Parameters

data (DataBlock): The data to read
[index] (integer): The index of the image to load, for cases where the image format contains multiple images. Default is 0
[typeHint] (string): The image format id to try loading first, before auto-detecting. Default is ""

Returns

boolean: true on success

LoadEntry

Reads the given entry's data to the image. The data can be in any supported image format.

Parameters

entry (ArchiveEntry): The entry to read
[index] (integer): The index of the image to load, for cases where the image format contains multiple images. Default is 0

Returns

boolean: true on success
string: An error message if loading failed

Notes

This function can additionally load various 'font' formats to the image, which are as yet unsupported by ImageFormat and therefore LoadData. It will also use the extra information available from the entry to better detect the correct image format.

WriteIndexedData

Writes the raw image data into block in 8-bit indexed format.

Parameters

block (DataBlock): The DataBlock to write the data to (will be resized to fit the data)

Returns

boolean: true on success

WriteRGBData

Writes the raw image data into block in 24-bit RGB format.

Parameters

block (DataBlock): The DataBlock to write the data to (will be resized to fit the data)
[palette] (Palette): The palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil

Returns

boolean: true on success

WriteRGBAData

Writes the raw image data into block in 32-bit RGBA format.

Parameters

block (DataBlock): The DataBlock to write the data to (will be resized to fit the data)
[palette] (Palette): The palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil

Returns

boolean: true on success

ConvertAlphaMap

Converts the image to PIXELFORMAT_ALPHA.

Parameters

alphaSource (integer): The source to generate the alpha values from:
- SOURCE_ALPHA: Use existing alpha values
- SOURCE_BRIGHTNESS: Determine alpha from the brightness of each pixel's colour
[palette] (Palette): The palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil

Returns

boolean: true if the image was converted

ConvertIndexed

Converts the image to PIXELFORMAT_INDEXED.

Parameters

newPalette (Palette): The new palette to convert to (the image's palette will also be set to this)
[currentPalette] (Palette): The 'current' palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil

Returns

boolean: true if the image was converted

ConvertRGBA

Converts the image to PIXELFORMAT_RGBA.

Parameters

[palette] (Palette): The palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil

Returns

boolean: true if the image was converted

Crop

Crops the image to a new rectangle between (left, top) -> (right, bottom).

Parameters

left (integer): The new left of the image (anything to the left of this will be cut)
top (integer): The new top of the image (anything above this will be cut)
right (integer): The new right of the image (anything to the right of this will be cut)
bottom (integer): The new bottom of the image (anything below this will be cut)

Returns

boolean: false if the given parameters were invalid (must be within the existing dimensions)

MirrorHorizontal

Mirrors the image horizontally.

Returns

boolean: true on success

MirrorVertical

Mirrors the image vertically.

Returns

boolean: true on success

Resize

Resizes the image to newWidth x newHeight, conserving any existing image data.

Parameters

newWidth (integer): The new image width
newHeight (integer): The new image height

Returns

boolean: true on success

Rotate

Rotates the image by angle.

Parameters

angle (integer): The amount (in degrees) to rotate the image

Returns

boolean: true if the image was rotated successfully

Notes

The angle must be a multiple of 90, other rotations are not currently supported.

Trim

Automatically crops the image to remove fully transparent rows/columns from the edges.

ApplyTranslation

Applies the given translation to the image.

Parameters

translation (Translation): The translation to apply
[palette] (Palette): The palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil
[trueColour] (boolean): If true, the translation will be performed in 'truecolour' (32-bit) and the image converted to PIXELFORMAT_RGBA. Default is false

Returns

boolean: true on success

Colourise

Colourises the image to colour.

Parameters

colour (Colour): The colour to apply
[palette] (Palette): The palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil

Returns

boolean: true on success

SetPixelColour

Sets the pixel at (x,y) to colour.

Parameters

x (integer): The X position of the pixel
y (integer): The Y position of the pixel
colour (Colour): The colour to set the pixel to
[palette] (Palette): The palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil

Returns

boolean: false if the given position was out of range

SetPixelIndex

Ses the pixel at (x,y) to the palette colour index, and the pixel's alpha if possible.

Parameters

x (integer): The X position of the pixel
y (integer): The Y position of the pixel
index (integer): The palette colour index
[alpha] (integer): The alpha value for the pixel. Default is 255 (fully opaque)

Returns

boolean: false if the given position was out of range

Tint

Tints the image to colour by amount.

Parameters

colour (Colour): The colour to apply
amount (float): The amount to tint (0.0 - 1.0)
[palette] (Palette): The palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil

Returns

boolean: true on success

FillAlpha

Sets all alpha values in the image to alpha.

Parameters

alpha (integer): The alpha value to set

MaskFromBrightness

Changes the mask/alpha channel so that each pixel's transparency matches its brigntness level (where black is fully transparent).

Parameters

[palette] (Palette): The palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil

Returns

boolean: true on success

MaskFromColour

Changes the mask/alpha channel so that pixels that match colour are fully transparent, and all other pixels fully opaque.

Parameters

colour (Colour): The colour to set as transparent
[palette] (Palette): The palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil

Returns

boolean: true on success

DrawImage

Draws srcImage at (x,y) on the image.

Parameters

x (integer): The X position to draw srcImage. Can be negative
y (integer): The Y position to draw srcImage. Can be negative
srcImage (Image): The image to draw
drawOptions (ImageDrawOptions): Options for blending srcImage's pixels with the existing image
[srcPalette] (Palette): The palette to use for srcImage if it is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil
[destPalette] (Palette): The palette to use if this image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil

Returns

boolean: true on success

Notes

srcImage is drawn with its top-left at the given coordinates.

This will not resize the current image - any part of the drawn srcImage that goes past the edge of the image's bounds will be cut off.

The pixel colour calculations will always be done in 32-bit, and if the image is PIXELFORMAT_INDEXED, the resulting pixel colours will be converted to their nearest match in the image's palette (or the destPalette parameter if the image doesn't have one).

DrawPixel

Draws a pixel of colour at (x,y) on the image.

Parameters

x (integer): The X position to draw the pixel
y (integer): The Y position to draw the pixel
colour (Colour): The colour of the pixel to draw
drawOptions (ImageDrawOptions): Options for blending the pixel with the existing image
[palette] (Palette): The palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette. Default is nil

Returns

boolean: true on success

Notes

The pixel colour calculations will always be done in 32-bit, and if the image is PIXELFORMAT_INDEXED, the resulting pixel colour will be converted to its nearest match in the image's palette (or the palette parameter if the image doesn't have one).

Example

This will draw a red pixel at (10,20) on image blended additively at 50% opacity.

local drawOpt = ImageDrawOptions.new()
drawOpt.blend = Graphics.BLEND_ADD
drawOpt.alpha = 0.5
image:DrawPixel(10, 20, Colour.new(255, 0, 0), drawOpt)