Colour Manipulation

Colours are generally represented as triples of coordinates, representing red, green, and blue components. Sometimes, an opacity is included as a fourth component, to determine how much the colour will let other objects show through. Sometimes it is useful to work with colours in a different space, Hue-Saturation-Light, which is also a triple of coordinates. Each colour component is usually either a real value in the range zero to one, or an integral value in the range zero to 255. A colour type is defined (Colour) which uses a single long integer to store colours as four eight-bit integers. Various macros and functions exist to manipulate these colours:

make_Colour( r, g, b )

Returns a value of type Colour which contains the specified red, green, and blue components, each of which must be within the range zero to 255.

make_rgba_Colour( r, g, b, a )

Returns a value of type Colour which contains the specified red, green, blue, and alpha (opacity) components, each of which must be within the range zero to 255.

get_Colour_r( col )

Given an argument of type Colour, returns the value of the red component, in the range zero to 255.

get_Colour_g( col )

Given an argument of type Colour, returns the value of the green component, in the range zero to 255.

get_Colour_b( col )

Given an argument of type Colour, returns the value of the blue component, in the range zero to 255.

get_Colour_a( col )

Given an argument of type Colour, returns the value of the alpha component, in the range zero to 255.

make_Colour_0_1( r, g, b )

Returns a value of type Colour which contains the specified red, green, and blue components, each of which must be within the range zero to 1.0.

make_rgba_Colour_0_1( r, g, b )

Returns a value of type Colour which contains the specified red, green, blue, and alpha components, each of which must be within the range zero to 1.0.

get_Colour_r_0_1( col )

Given an argument of type Colour, returns the value of the red component, in the range zero to 1.0.

get_Colour_g_0_1( col )

Given an argument of type Colour, returns the value of the green component, in the range zero to 1.0.

get_Colour_b_0_1( col )

Given an argument of type Colour, returns the value of the blue component, in the range zero to 1.0.

get_Colour_a_0_1( col )

Given an argument of type Colour, returns the value of the alpha component, in the range zero to 1.0.

get_Colour_luminance( col )

Given an argument of type Colour, returns the brightness of the colour, in the range zero to 255. This is used to convert colour to gray-scale.

A surface property type is also defined, to provide descriptions of surface lighting characteristics:

fill_Surfprop( spr, a, d, s, e, o )

Fills in the spr structure, which is of type Surfprop, with the five parameters: ambient coefficient, diffuse coefficient, specular coefficient, specular exponent, and opacity.

Surfprop_a( spr )

Returns the ambient coefficient, a number in the range of zero to one.

Surfprop_d( spr )

Returns the diffuse coefficient, a number in the range of zero to one.

Surfprop_s( spr )

Returns the specular coefficient, a number in the range of zero to one.

Surfprop_se( spr )

Returns the specular exponent, a number in the range of zero to infinity, typically less than 100.

Surfprop_t( spr )

Returns the opacity (inverse of transparency), a number in the range of zero to one.

Several functions are available which deal with colours and surface properties:

public  void  rgb_to_hsl(
    Real    r,
    Real    g,
    Real    b,
    Real    *h,
    Real    *s,
    Real    *l )
public  void  hsl_to_rgb(
    Real   h,
    Real   s,
    Real   l,
    Real   *r,
    Real   *g,
    Real   *b )
public  void  convert_colour_to_hsl(
    Colour   rgb,
    Colour   *hsl )
public  void  convert_colour_to_rgb(
    Colour   hsl,
    Colour   *rgb )

Converts between red-green-blue and hue-saturation-light space.

public  BOOLEAN  equal_colours(
    Colour  col1,
    Colour  col2 )

returns TRUE if the two colours are equal.

public  int  get_colour_distance(
    int      r,
    int      g,
    int      b,
    Colour   c2 )

finds the squared Euclidean distance between the first colour, specified by its components, and the second colour, c2.

public  int   find_closest_colour(
    int     r,
    int     g,
    int     b,
    int     n_colours,
    Colour  colours[] )

Given the three components of a target colour, and a list of n_colours colours, returns the index in the list of the closest colour to the target colour.

public  BOOLEAN  lookup_colour(
    char    colour_name[],
    Colour  *col )

Given a colour name, such as ``red'' or ``dark_blue'' looks up the name in a list of colours and passes back the corresponding colour, returning TRUE if successful. The supported colours are from the list of about 300 named X colours.

public  BOOLEAN  lookup_colour_name(
    Colour  col,
    char    colour_name[] )

This performs the inverse of the lookup_colour() function, taking a colour and seeing if it matches one of the known named colours. If so, the colour name is copied into the argument colour_name, and TRUE is returned.