Skip to content

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

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, default nil): The 'current' palette to use if the image is PIXELFORMAT_INDEXED but doesn't have an internal palette

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

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)