Naev

Module colour

Lua bindings to interact with colours.

An example would be:

 col1 = colour.new( "Red" ) -- Get by name
 col2 = colour.new( 0.5, 0.5, 0.5, 0.3 ) -- Create with RGB values
 col3 = colour.new() -- White by default
 col2:setHSV( col1:hsv() ) -- Set colour 2 with colour 1's HSV values
 

Colours are assumed to be given as gamma-corrected values and are stored internally in linear colourspace by default. Most functions have a boolean parameter that allows controlling this behaviour.

Functions

__eq (c1, c2) Compares two colours to see if they are the same.
__tostring (col) Converts a colour to a string.
alpha (col) Gets the alpha of a colour.
gammaToLinear (col) Converts a colour from gamma corrected to linear.
hsv (col[, gamma=false]) Gets the HSV values of a colour.
linearToGamma (col) Converts a colour from linear to gamma corrected.
new (r, g, b[, a=1.[, Whether=false]]) Creates a new colour.
newHSV (h, s, v[, a=1.[, Whether=false]]) Creates a new colour from HSV values.
rgb (col[, gamma=false]) Gets the RGB values of a colour.
rgba (col[, gamma=false]) Gets the RGBA values of a colour.
setAlpha (col, alpha) Sets the alpha of a colour.
setHSV (col, h, s, v) Sets the colours values from the HSV colourspace.
setRGB (col, r, g, b) Sets the colours values from the RGB colourspace.


Functions

__eq (c1, c2)
Compares two colours to see if they are the same.

Parameters:

  • c1 Colour Colour 1 to compare.
  • c2 Colour Colour 2 to compare.

Returns:

    boolean true if both colours are the same.
__tostring (col)
Converts a colour to a string.

Parameters:

  • col Colour Colour to get string from.

Returns:

    string A string representing the colour.
alpha (col)
Gets the alpha of a colour.

Value is from from 0. (transparent) to 1. (opaque).

Parameters:

  • col Colour Colour to get alpha of.

Returns:

    number The alpha of the colour.

Usage:

    colour_alpha = col:alpha()
    
gammaToLinear (col)
Converts a colour from gamma corrected to linear.

Parameters:

  • col Colour Colour to change from gamma corrected to linear.

Returns:

    Colour Modified colour.
hsv (col[, gamma=false])
Gets the HSV values of a colour.

Values are from 0 to 1 except hue which is 0 to 360.

Parameters:

  • col Colour Colour to get HSV values of.
  • gamma boolean Whether or not to get the gamma-corrected value or not. (default false)

Returns:

  1. number The hue of the colour (0-360 value).
  2. number The saturation of the colour (0-1 value).
  3. number The value of the colour (0-1 value).

Usage:

    h,s,v = col:rgb()
    
linearToGamma (col)
Converts a colour from linear to gamma corrected.

Parameters:

  • col Colour Colour to change from linear to gamma.

Returns:

    Colour Modified colour.
new (r, g, b[, a=1.[, Whether=false]])
Creates a new colour. Colours are assumed to be in gamma colourspace by default and are converted to linear unless specified.

Parameters:

  • r number Red value of the colour.
  • g number Green value of the colour.
  • b number Blue value of the colour.
  • a number Alpha value of the colour. (default 1.)
  • Whether gamma to load the colour in the gamma colourspace. (default false)

Returns:

    Colour A newly created colour.

Usage:

  • colour.new( "Red" ) -- Gets colour by name
    
  • colour.new( "Red", 0.5 ) -- Gets colour by name with alpha 0.5
    
  • colour.new() -- Creates a white (blank) colour
    
  • colour.new( 1., 0., 0. ) -- Creates a bright red colour
    
  • colour.new( 1., 0., 0., 0.5 ) -- Creates a bright red colour with
    alpha 0.5
    
newHSV (h, s, v[, a=1.[, Whether=false]])
Creates a new colour from HSV values. Colours are assumed to be in gamma colourspace by default and are converted to linear unless specified.

Parameters:

  • h number Hue of the colour (0-360 value).
  • s number Saturation of the colour (0-1 value).
  • v number Value of the colour (0-1 value).
  • a number Alpha value of the colour. (default 1.)
  • Whether gamma to load the colour in the gamma colourspace. (default false)

Returns:

    Colour A newly created colour.

Usage:

    colour.new( 0., 0.5, 0.5 ) -- Creates a colour with 0 hue, 0.5
    saturation and 0.5 value.
    
rgb (col[, gamma=false])
Gets the RGB values of a colour.

Values are from 0. to 1.

Parameters:

  • col Colour Colour to get RGB values of.
  • gamma boolean Whether or not to get the gamma-corrected value or not. Defaults to internal value that is linear. (default false)

Returns:

  1. number The red value of the colour.
  2. number The green value of the colour.
  3. number The blue value of the colour.

Usage:

    r,g,b = col:rgb()
    
rgba (col[, gamma=false])
Gets the RGBA values of a colour.

Values are from 0. to 1.

Parameters:

  • col Colour Colour to get RGB values of.
  • gamma boolean Whether or not to get the gamma-corrected value or not. (default false)

Returns:

  1. number The red value of the colour.
  2. number The green value of the colour.
  3. number The blue value of the colour.
  4. number The alpha value of the colour.

Usage:

    r,g,b,a = col:rgba()
    
setAlpha (col, alpha)
Sets the alpha of a colour.

Value is from 0. (transparent) to 1. (opaque).

Parameters:

  • col Colour Colour to set alpha of.
  • alpha number Alpha value to set.

Usage:

    col:setAlpha( 0.5 ) -- Make colour half transparent
    
setHSV (col, h, s, v)
Sets the colours values from the HSV colourspace.

Values are from 0. to 1.

Parameters:

  • col Colour Colour to set HSV values.
  • h number Hue value to set.
  • s number Saturation value to set.
  • v number Value to set.

Usage:

    col:setHSV( h, s, v )
    
setRGB (col, r, g, b)
Sets the colours values from the RGB colourspace.

Values are from 0. to 1.

Parameters:

  • col Colour Colour to set RGB values.
  • r number Red value to set.
  • g number Green value to set.
  • b number Blue value to set.

Usage:

    col:setRGB( r, g, b )
    
generated by LDoc 1.5.0 Last updated 2025-05-18 01:00:15