make-hls

Function

Package: cg

ToC

DocOverview

CGDoc

RelNotes

FAQ

Index

PermutedIndex

Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version

make-hls

Arguments: &key hue lightness saturation

Returns an hls color object with the specified values for hue, lightness, and saturation. The values for hue, lightness, and saturation must be as follows:

hue: a single-float between 0.0 and 360.0 inclusive. This specifies the color. A hue of 0.0 denotes red, 120.0 denotes green, and 240.0 denotes blue, with other values specifying other color.
lightness: a single-float between 0.0 and 1.0 inclusive. This denotes the strengh of the requested hue, where 0.0 is always black and 1.0 is full strength.
saturation: a single-float between 0.0 and 1.0 inclusive. This denotes the level to which the color is not grayed out (or whited out, when lightness is high). 1.0 denotes the "pure" color of the requested hue and 0.0 denotes a gray-scale color that varies from black (when lightness is 0.0) through medium gray (when lightness is 0.5) to white (when lightness is 1.0).

Colors used must be RGB color objects

Note that the value of color properties (such as background-color and foreground-color) must be RGB color objects, as made with make-rgb. You should apply the function hls-to-rgb to an HLS color before setting a color property to it. You can use the function rgb-to-hls to get the HLS equivalent of an RGB color.

Translating to RGB causes roundoff

RGB colors (created with make-rgb) have values for red, green, and blue which are integers between 0 and 255 inclusive. Therefore, only 256*256*256 = 16,777,216 different RGB colors can be specified. Because HLS colors are specified with floats, apparently many more HLS colors can be specified (they are not all actually different, of course). Therefore, if you convert a HLS color to an RGB color (with hls-to-rgb), and then convert back with rgb-to-hls, the resulting hue, lightness, and saturation will likely differ from the originals by small amounts. The difference will be greater the smaller saturation and lightness are. A saturation of 0.0, means a shade of gray (with the hue having no effect) so converting such a color to RGB and back is likely to result in a very different hue.