open-palette

Arguments: stream rgb-vector &optional animated-entries

Creates and returns a palette and returns a handle to that palette (i.e. an integer) that is appropriate to assign to stream. stream should be a cg-stream. Generally this palette will be compatible with all windows, and (screen *system*) (see screen and *system*) may be used as a value for stream. Palettes should be needed only if Windows is running in 256-color mode or less and the standard VGA colors are not sufficient.

rgb-vector should be a vector of up to 256 rgb colors. For example, the following form returns a vector of six colors using predefined colors (cyan, red, black, and white) and new colors created with make-rgb:

(setq cv (vector cyan (make-rgb :blue 10 :red 33) 
                 red (make-rgb :green 154 :red 0 :blue 99)
                 black white))

animated-entries should be a list of indices of rgb-vector which are candidates for animation. See animate-color-number. The Operating System is instructed not to share these colors.

With cv as defined just above, create a suitable palette for (screen *system*) (see screen and *system*) with

(setq my-palette (open-palette (screen *system*) cv))

Note that this function does not assign the returned palette to stream. That must be done with (setf palette).

Efficiency note: When a window is closed or a palette is removed from it by calling (setf palette), Common Graphics does not automatically close the palette to clean up its operating system resources. The reason is that other windows could be using the same palette (now or in the future), so Common Graphics does not know when it is safe to close it. Therefore, if an application creates many palettes, it may need to call close-palette to close each one to prevent the operating system from running out of palette resources. This should be done only when each palette is no longer being used by any window. The resources are cleaned up when Lisp exits.

Warning: the palette handle returned by this function is an address. This address will be valid so long as the current invocation of Lisp is running but may not be valid if the image is dumped (with dumplisp) and rerun (it may be valid if rerun on the same machine, it is less likely to be valid on a different machine running the same operating system, it is very unlikely to be valid on a different machine running a different operating system). Therefore, palettes should be initialized each time Allegro CL (or an Allegro CL application) is run.

For information on when palettes are useful (or necessary) see cg-color-palettes.htm.

GTK Note

Palettes have not yet been implemented on the GTK platform. Calling the palette-related functions on GTK will have no effect.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.