All Manuals > CAPI User Guide and Reference Manual > 15 The Color System


15.4 Color models

Three color models are defined by default: RGB, HSV and GRAY. RGB and HSV allow specification of any color within conventional color space using three orthogonal coordinate axes, while gray restricts colors to one hue between white and black. All color models contain an optional alpha component, though this is used only on Cocoa and Windows.


Color models defined by default



Component: Range


Red Green Blue

RED (0.0 to 1.0)

GREEN (0.0 to 1.0)

BLUE (0.0 to 1.0)

ALPHA (0.0 to 1.0)


Hue Saturation Value

HUE (0.0 to 5.99999)

SATURATION (0.0 to 1.0)

VALUE (0.0 to 1.0)

ALPHA (0.0 to 1.0)



GRAY (0.0 to 1.0)

ALPHA (0.0 to 1.0)

The Hue value in HSV is mathematically in the open interval [0.0 6.0). All values must be specified in floating point values.

You can convert color-specs between models using the available ensure-< model > functions. For example:

(setf green (make-rgb 0.0 1.0 0.0))
    => #(:RGB 0.0 1.0 0.0)
(eq green (ensure-rgb green)) => T 
(ensure-hsv green) => #(:HSV 2.0 0.0 1.0)
(eq green (ensure-hsv green)) => NIL
(ensure-rgb (ensure-hsv green)) => #(:RGB 0.0 1.0 0.0)
(eq green (ensure-rgb (ensure-hsv green))) => NIL

Of course, information can be lost when converting to GRAY:

(make-rgb 0.3 0.4 0.5) => #(:RGB 0.3 0.4 0.5)
(ensure-gray (make-rgb 0.3 0.4 0.5)) 
    => #(:GRAY 0.39999965)
(ensure-rgb (ensure-gray 
             (make-rgb 0.3 0.4 0.5)))
       => #(:RGB 0.39999965 0.39999965 0.39999965)

There is also ensure-color which takes two color-spec arguments. It converts if necessary the first argument to the same model as the second. For example:

(ensure-color (make-gray 0.3) green) 
     => #(:RGB 0.3 0.3 0.3)

ensure-model-color takes a model as the second argument. For example:

(ensure-model-color (make-gray 0.3) :hsv)
     => #(:HSV 0 1.0 0.3)

The function colors= compares two color-spec objects for color equality.

The function color-level returns the gray level of a color-spec, and the functions color-blue, color-green, color-red, color-hue, color-saturation and color-value return the associated components.

The color models above represent the color in a portable (and externalizable) way. To actually use it, the system needs to convert to the representation used by the underlying display system. The user can do the conversion using convert-color. The result is called a "converted color" or "color representation" or "color-rep", and is more efficient to use in drawing functions, because it saves the system from doing the conversion each time it uses the color.

CAPI User Guide and Reference Manual (Unix version) - 25 Feb 2015