Image
An
The type also has various functions for manipulating image data and reading the various formats supported by SLADE (see
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 |
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 |
---|---|---|
The format of the pixels in the image (see Image Pixel Formats) | ||
The width of the image | ||
The height of the image | ||
Whether this image has an internal palette | ||
The image's internal palette. If false this will be greyscale |
||
The X offset of the image | ||
The Y offset of the image | ||
The number of bytes per row of image data | ||
The number of bytes per pixel in the image data |
Constructors
Creates a new, empty image with PIXELFORMAT_RGBA
.
Creates a new, empty image of
Parameters
pixelFormat (integer ): The pixel format of the image (seePIXELFORMAT_
constants)
Functions
Overview
General
Image Info
Read Data
Write Data
Pixel Format Conversion
General Modification
Colour Modification
Alpha Modification
Drawing
Clear
Clears all image data, resetting size and offsets to 0
.
Copy
Copies all data and properties from another
Parameters
other (Image ): The image to copy from
Create
(Re)Creates the image with the given properties.
Parameters
width (integer ): The width of the imageheight (integer ): The height of the imagetype (integer ): The type of image to create (seePIXELFORMAT_
constants)[palette] (Palette , defaultnil
): 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, or0
if the image isn'tPIXELFORMAT_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 pixely (integer ): The Y position of the pixel[palette] (Palette ): The palette to use if the image isPIXELFORMAT_INDEXED
and has no internal palette. Default isnil
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 (-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 pixely (integer ): The Y position of the pixel
Returns
integer : The palette index of the pixel at (x ,y )
LoadData
Reads the given
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 is0
[typeHint] (string ): The image format id to try loading first, before auto-detecting. Default is""
Returns
boolean :true
on success
LoadEntry
Reads the given
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 is0
Returns
boolean :true
on successstring : An error message if loading failed
Notes
This function can additionally load various 'font' formats to the image, which are as yet unsupported by
WriteIndexedData
Writes the raw image data into
Parameters
Returns
boolean :true
on success
WriteRGBData
Writes the raw image data into
Parameters
block (DataBlock ): TheDataBlock to write the data to (will be resized to fit the data)[palette] (Palette ): The palette to use if the image isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
Returns
boolean :true
on success
WriteRGBAData
Writes the raw image data into
Parameters
block (DataBlock ): TheDataBlock to write the data to (will be resized to fit the data)[palette] (Palette ): The palette to use if the image isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
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 valuesSOURCE_BRIGHTNESS
: Determine alpha from the brightness of each pixel's colour
[palette] (Palette ): The palette to use if the image isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
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'spalette will also be set to this)[currentPalette] (Palette ): The 'current' palette to use if the image isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
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 isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
Returns
boolean :true
if the image was converted
Crop
Crops the image to a new rectangle between (
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
Parameters
newWidth (integer ): The new image widthnewHeight (integer ): The new image height
Returns
boolean :true
on success
Rotate
Rotates the image by
Parameters
angle (integer ): The amount (in degrees) to rotate the image
Returns
boolean :true
if the image was rotated successfully
Notes
The
Trim
Automatically crops the image to remove fully transparent rows/columns from the edges.
ApplyTranslation
Applies the given
Parameters
translation (Translation ): The translation to apply[palette] (Palette ): The palette to use if the image isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
[trueColour] (boolean ): Iftrue
, the translation will be performed in 'truecolour' (32-bit) and the image converted toPIXELFORMAT_RGBA
. Default isfalse
Returns
boolean :true
on success
Colourise
Colourises the image to
Parameters
colour (Colour ): The colour to apply[palette] (Palette ): The palette to use if the image isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
Returns
boolean :true
on success
SetPixelColour
Sets the pixel at (
Parameters
x (integer ): The X position of the pixely (integer ): The Y position of the pixelcolour (Colour ): The colour to set the pixel to[palette] (Palette ): The palette to use if the image isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
Returns
boolean :false
if the given position was out of range
SetPixelIndex
Ses the pixel at (
Parameters
x (integer ): The X position of the pixely (integer ): The Y position of the pixelindex (integer ): The palette colour index[alpha] (integer ): The alpha value for the pixel. Default is255
(fully opaque)
Returns
boolean :false
if the given position was out of range
Tint
Tints the image to
Parameters
colour (Colour ): The colour to applyamount (float ): The amount to tint (0.0
-1.0
)[palette] (Palette ): The palette to use if the image isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
Returns
boolean :true
on success
FillAlpha
Sets all alpha values in the image to
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 isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
Returns
boolean :true
on success
MaskFromColour
Changes the mask/alpha channel so that pixels that match
Parameters
colour (Colour ): The colour to set as transparent[palette] (Palette ): The palette to use if the image isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
Returns
boolean :true
on success
DrawImage
Draws
Parameters
x (integer ): The X position to drawsrcImage . Can be negativey (integer ): The Y position to drawsrcImage . Can be negativesrcImage (Image ): The image to drawdrawOptions (ImageDrawOptions ): Options for blendingsrcImage 's pixels with the existing image[srcPalette] (Palette ): The palette to use forsrcImage if it isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
[destPalette] (Palette ): The palette to use if this image isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
Returns
boolean :true
on success
Notes
This will not resize the current image - any part of the drawn
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
DrawPixel
Draws a pixel of
Parameters
x (integer ): The X position to draw the pixely (integer ): The Y position to draw the pixelcolour (Colour ): The colour of the pixel to drawdrawOptions (ImageDrawOptions ): Options for blending the pixel with the existing image[palette] (Palette ): The palette to use if the image isPIXELFORMAT_INDEXED
but doesn't have an internalpalette . Default isnil
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
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)