Murl Engine Lua Addon API  Version 1.0 beta
Murl.Color

A color class.

This class holds four individual 32bit floating point values representing an RGBA color, each of them with a "regular" range of 0.0 (black) to 1.0 (full color). Actual values may lie beyond that range (in both directions), to define oversaturated colors or even "negative" ones.

When specified as an attribute value in an XML file, there exist a number of different notations. For specifying multiple components in one value, the following ones can be used:

  • A 6-digit hex string representing an unsigned 24bit integer RGB color value (100% alpha)
  • An 8-digit hex string representing an unsigned 32bit integer ARGB color value

For these, a trailing 'h' character defines the hex notation. For specifying individual values, either 3 (RGB) or 4 (RGBA) values must be given as a comma-separated string. Each of these values must be postfixed by one of the following characters:

  • 'f' to specify a floating point value that directly maps to the internal range
  • 'i' to specify an integer value, which will be divided by 255
  • 'h' to specify a hex string, which will be converted and divided by 255

String-to-color conversion in the described way can also be done from code, by using the Util::StringToColor() function.

Examples:

  • "ffc080h": 100% alpha (implicitly), 100% red, 75% green and 50% blue (RGB)
  • "40ffc080h": 25% alpha, 100% red, 75% green and 50% blue (ARGB)
  • "1f,1f,1f,0.5f": 100% white with 50% alpha (RGBA)
  • "128i,64i,192i": 50% red, 25% green, 75% blue and (implicitly) 100% alpha (RGB)
  • "00h,00h,00h,ffh": black with 100% alpha (RGBA)
  • "0.5f,128i,80h": 50% grey with (implicitly) 100% alpha (RGB)


Table members

Enumerations


Components

Enumeration of the components raw data.

Murl.Color.REDIndex to the red component
Murl.Color.GREENIndex to the green component
Murl.Color.BLUEIndex to the blue component
Murl.Color.ALPHAIndex to the alpha component
Murl.Color.NUM_COMPONENTSNumber of components

StringFormat

String formats

Murl.Color.STRING_FORMAT_UNKNOWNUnknown format
Murl.Color.STRING_FORMAT_FLOATFloat format, e.g. "0.75f,0.5f,0.25f,1f" (RGBA)
Murl.Color.STRING_FORMAT_INTInteger format, e.g. "192i,128i,64i,255i" (RGBA)
Murl.Color.STRING_FORMAT_HEXHex format, e.g. "ffc08040h" (ARGB)
Murl.Color.STRING_FORMAT_MIXEDString contains different format identifiers
Murl.Color.STRING_FORMAT_INCOMPLETEString does not contain a format identifier for all components
Murl.Color.NUM_STRING_FORMATSNumber of formats


Functions


Murl.Color.new()

The default constructor.

Murl.Color new()

Returns
Murl.Color

Murl.Color.new(value)

Constructor to set all color components to a given value.

Murl.Color new(Number value)

Parameters
valueThe value for the red, green, blue and alpha component.
Returns
Murl.Color

Murl.Color.new(red, green, blue, alpha)

Constructor to initialize a color with given component values.

Murl.Color new(Number red, Number green, Number blue, Number alpha)

Parameters
redThe red component.
greenThe green component.
blueThe blue component.
alphaThe alpha component.
Returns
Murl.Color

Murl.Color.FromInt(red, green, blue, alpha)

Named constructor to set all components to a set of given integer component values. The integer values are divided by 255.

Murl.Color FromInt(Integer red, Integer green, Integer blue, Integer alpha)

Parameters
redThe red integer component.
greenThe green integer component.
blueThe blue integer component.
alphaThe alpha integer component.
Returns
Murl.Color The color object.

Murl.Color.GetLuminanceRedWeight()

Get the red component's weight for luminance conversion, according to the ITU-R BT.601 standard.

Number GetLuminanceRedWeight()

Returns
Number The weight of the red component.

Murl.Color.GetLuminanceGreenWeight()

Get the green component's weight for luminance conversion, according to the ITU-R BT.601 standard.

Number GetLuminanceGreenWeight()

Returns
Number The weight of the green component.

Murl.Color.GetLuminanceBlueWeight()

Get the blue component's weight for luminance conversion, according to the ITU-R BT.601 standard.

Number GetLuminanceBlueWeight()

Returns
Number The weight of the blue component.


Methods


Set(red, green, blue, alpha)

Set all components of the color instance to a set of given component values.

Set(Number red, Number green, Number blue, Number alpha)

Parameters
redThe red component.
greenThe green component.
blueThe blue component.
alphaThe alpha component.

SetInt(red, green, blue, alpha)

Set all components of the color instance to a set of given integer component values. The integer values are divided by 255.

SetInt(Integer red, Integer green, Integer blue, Integer alpha)

Parameters
redThe red integer component.
greenThe green integer component.
blueThe blue integer component.
alphaThe alpha integer component.

GetRed()

Get the red component.

Number GetRed()

Returns
Number The red component.

SetRed(red)

Set the red component.

SetRed(Number red)

Parameters
redThe red component.

GetRedInt()

Get the red integer component. The component is multiplied by 255.

Integer GetRedInt()

Returns
Integer The red integer component.

SetRedInt(red)

Set the red integer component. The component is divided by 255.

SetRedInt(Integer red)

Parameters
redThe red integer component.

GetGreen()

Get the green component.

Number GetGreen()

Returns
Number The green component.

SetGreen(green)

Set the green component.

SetGreen(Number green)

Parameters
greenThe green component.

GetGreenInt()

Get the green integer component. The component is multiplied by 255.

Integer GetGreenInt()

Returns
Integer The green integer component.

SetGreenInt(green)

Set the green integer component. The component is divided by 255.

SetGreenInt(Integer green)

Parameters
greenThe green integer component.

GetBlue()

Get the blue component.

Number GetBlue()

Returns
Number The blue component.

SetBlue(blue)

Set the blue component.

SetBlue(Number blue)

Parameters
blueThe blue component.

GetBlueInt()

Get the blue integer component. The component is multiplied by 255.

Integer GetBlueInt()

Returns
Integer The blue integer component.

SetBlueInt(blue)

Set the blue integer component. The component is divided by 255.

SetBlueInt(Integer blue)

Parameters
blueThe blue integer component.

GetAlpha()

Get the alpha component.

Number GetAlpha()

Returns
Number The alpha component.

SetAlpha(alpha)

Set the alpha component.

SetAlpha(Number alpha)

Parameters
alphaThe alpha component.

GetAlphaInt()

Get the alpha integer component. The component is multiplied by 255.

Integer GetAlphaInt()

Returns
Integer The alpha integer component.

SetAlphaInt(alpha)

Set the alpha integer component. The component is divided by 255.

SetAlphaInt(Integer alpha)

Parameters
alphaThe alpha integer component.

GetLuminance()

Get the luminance (gray scale) value calculated from R, G and B. Luminance calculation uses the standard conversion factors defined by the Rec 601 standard which can be found in PAL and NTSC color models.

Number GetLuminance()

Returns
Number The luminance (R * 0.2990 + G * 0.5864 + B * 0.1146).

GetLuminanceInt()

Get the luminance (gray scale) integer value calculated from R, G and B. Luminance calculation uses the standard conversion factors defined by the Rec 601 standard which can be found in PAL and NTSC color models, multiplied by 255.

Integer GetLuminanceInt()

Returns
Integer The integer luminance.

ToUInt32()

Get the 32 bit ABGR value of the color instance components.

Integer ToUInt32()

Returns
Integer The 32 bit ABGR value.

ToUInt32Clamped()

Get the 32 bit ABGR value of the color instance components, clamped to the range [0..255].

Integer ToUInt32Clamped()

Returns
Integer The 32 bit ABGR value.

FromUInt32(color)

Set the color instance components from a 32 bit ABGR value.

FromUInt32(Integer color)

Parameters
colorThe 32 bit ABGR value.

FromUInt32ARGB(color)

Set the color instance components from a 32 bit ARGB value.

FromUInt32ARGB(Integer color)

Parameters
colorThe 32 bit ARBG value.

BlendSelf(foregroundColor)

Blend a given foreground color over this color using alpha blending in place.

BlendSelf(Murl.Color foregroundColor)

Parameters
foregroundColorThe foreground color to blend.

Blend(foregroundColor)

Blend a given foreground color over this color using alpha blending and return the blended color.

Murl.Color Blend(Murl.Color foregroundColor)

Parameters
foregroundColorThe foreground color to blend.
Returns
Murl.Color The alpha blended color.

IsEqual(color)

Check if the color instance is equal to a given second color. Compares all values within the default epsilon range Limits::Epsilon().

Boolean IsEqual(Murl.Color color)

Parameters
colorThe color to compare.
Returns
Boolean true if all components are equal.

IsEqual(color, epsilon)

Check if the color instance is equal to a given second color. Compares all values within a given epsilon range.

Boolean IsEqual(Murl.Color color, Number epsilon)

Parameters
colorThe color to compare.
epsilonThe epsilon to compare.
Returns
Boolean true if all components are equal.

ToString()

Get the string representation of the object.

String ToString()

Returns
String The string representation of the object.


Metamethods


The tostring operator

Converts the object content to a string in a reasonable format.

Returns
ToString()

The addition operator.

Addition operator.

Returns
Murl.Color = Murl.Color + Murl.Color

The subtraction operator.

Subtraction operator.

Returns
Murl.Color = Murl.Color - Murl.Color

The multiplication operator.

Multiplication operator.

Returns
Murl.Color = Murl.Color * Number

The multiplication operator.

Multiplication operator.

Returns
Murl.Color = Murl.Color * Murl.Color

The division operator.

Division operator.

Returns
Murl.Color = Murl.Color / Number

The division operator.

Division operator.

Returns
Murl.Color = Murl.Color / Murl.Color

The equal to operator.

Equal to comparison operator. Performs a test without an epsilon range, which can be used for detecting changes i.e. DoubleBuffer<Color> class. To compare within an epsilon range use Color::IsEqual().

Returns
Boolean = Murl.Color == Murl.Color