Translation

Type

Translation

A colour translation definition. Can either be a built in translation or a custom translation made up of one or more TransRanges.

See the Translation page on the ZDoom wiki for more information.

Properties

Property	Type	Description
ranges	TransRange[]	An array of all custom ranges in the translation
rangeCount	integer	The number of custom ranges in the translation
standardName	string	The name of the 'built in' translation to use (for TEXTURES). If this is set the ranges above will be ignored. See TEXTURES for information on the available options.
desatAmount	integer	The desaturation amount (`1` - `31`) if standardName is `desaturate`

Constructors

Translation.new()

Creates a new, empty translation.

Functions

Overview

General

AsText() -> string Clear() Copy(other) IsEmpty() -> boolean Parse(definition) Translate(colour, [palette]) -> Colour

Custom Ranges

Range(index) -> TransRange AddRange(definition) -> TransRange AddPaletteRange(rangeStart, rangeEnd) -> TransRangePalette AddColourRange(rangeStart, rangeEnd) -> TransRangeColour AddDesatRange(rangeStart, rangeEnd) -> TransRangeDesat AddBlendRange(rangeStart, rangeEnd) -> TransRangeBlend AddTintRange(rangeStart, rangeEnd) -> TransRangeTint AddSpecialRange(rangeStart, rangeEnd) -> TransRangeSpecial ReadTable(data) RemoveRange(index) SwapRanges(index1, index2)

AsText

Gets the translation as a text string (in ZDoom format).

Returns

string: A text representation of the translation (in ZDoom format)

Example

local translation = Translation.new()

-- Add palette range
local palRange = translation:AddPaletteRange(0, 10)
palRange.destStart = 100
palRange.destEnd = 110

-- Add colour range
local colRange = translation:AddColourRange(40, 50)
colRange.startColour = Colour.new(100, 0, 0)
colRange.endColour = Colour.new(255, 100, 100)

App.LogMessage(translation:AsText()) -- "0:10=100:110", "40:50=[100,0,0]:[255,100,100]"

Clear

Clears all custom ranges in the translation as well as standardName if it is set.

Copy

Copies all translation info from another Translation

Parameters

other (Translation): The translation to copy from

IsEmpty

Returns true if the translation is 'empty' (ie. the ranges and standardName properties are both empty).

Returns

boolean: true if the translation is 'empty'

Parse

Clears the current translation and loads new translation information from the given text definition.

Parameters

definition (string) : A full (comma-separated) translation definition in text format

Translate

Applies the translation to a colour.

Parameters

colour (Colour): The colour to apply the translation to
[palette] (Palette): The palette to use for the translation. Default is nil, which means the currently selected global palette will be used

Returns

Colour: The translated colour

Range

Gets a single part (TransRange) of the translation.

Parameters

index (integer) : The index of the range to get

Returns

TransRange: The range at the specified index in this translation, or nil if index was out of bounds

AddRange

Adds a new custom translation range to the translation, parsed from the given text definition.

Parameters

definition (string): A single translation range definition in text format

Returns

TransRange: The created translation range, or nil if the given definition was invalid

AddPaletteRange

Adds a new custom translation range of type TransRangePalette to the translation, from rangeStart to rangeEnd.

Parameters

rangeStart (integer): The first palette index of the range (0 - 255)
rangeEnd (integer): The last palette index of the range (0 - 255)

Returns

TransRangePalette: The new range that was added

Example

local translation = Translation.new()
local palRange = translation:AddPaletteRange(0, 20)
palRange.destStart = 50
palRange.destEnd = 60
App.LogMessage(translation:AsText()) -- '0:20=50:60'

AddColourRange

Adds a new custom translation range of type TransRangeColour to the translation, from rangeStart to rangeEnd.

Parameters

rangeStart (integer): The first palette index of the range (0 - 255)
rangeEnd (integer): The last palette index of the range (0 - 255)

Returns

TransRangeColour: The new range that was added

AddDesatRange

Adds a new custom translation range of type TransRangeDesat to the translation, from rangeStart to rangeEnd.

Parameters

rangeStart (integer): The first palette index of the range (0 - 255)
rangeEnd (integer): The last palette index of the range (0 - 255)

Returns

TransRangeDesat: The new range that was added

AddBlendRange

Adds a new custom translation range of type TransRangeBlend to the translation, from rangeStart to rangeEnd.

Parameters

rangeStart (integer): The first palette index of the range (0 - 255)
rangeEnd (integer): The last palette index of the range (0 - 255)

Returns

TransRangeBlend: The new range that was added

AddTintRange

Adds a new custom translation range of type TransRangeTint to the translation, from rangeStart to rangeEnd.

Parameters

rangeStart (integer): The first palette index of the range (0 - 255)
rangeEnd (integer): The last palette index of the range (0 - 255)

Returns

TransRangeTint: The new range that was added

AddSpecialRange

Adds a new custom translation range of type TransRangeSpecial to the translation, from rangeStart to rangeEnd.

Parameters

rangeStart (integer): The first palette index of the range (0 - 255)
rangeEnd (integer): The last palette index of the range (0 - 255)

Returns

TransRangeSpecial: The new range that was added

ReadTable

Adds translation ranges from the given translation table data.

Parameters

data (string): The translation table binary data to read

RemoveRange

Removes the custom translation range at index in ranges

Parameters

index (integer): The index of the range to remove

SwapRanges

Swaps the custom translation ranges at index1 and index2 in ranges

Parameters

index1 (integer): The index of the first range to swap
index2 (integer): The index of the second range to swap