CTM_$INTRO Domain/OS CTM_$INTRO
NAME
intro - Color Table Manager
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/gpr.h>
#include <apollo/ctm.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/gpr.ins.pas';
%include '/sys/ins/ctm.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/ctm.ins.ftn'
DESCRIPTION
The Color Table Manager (CTM) allows different Graphics Primitives
Resource (GPR) applications running on the same node to share the
display's color map (also called the "color table") without interfering
with each other.
The following is a list of the ctm_$ calls.
ctm_$alloc_pv allocate unused pixel values
ctm_$find_color find a color in the color map
ctm_$inc_use_count increment pixel value use counts
ctm_$mark_read_only share pixel values with other processes
ctm_$release_pv decrement pixel value use counts
The color map is an indexed table of colors that is shared by all
processes using GPR in direct mode or frame mode. Borrow mode applica-
tions have a separate, private copy of the color map, which is initial-
ized to default values by gpr_$init.
The Color Map
The color map must be shared because there is only one physical color map
for the display device. For example, if one process modifies the color
value at an index, all other process running on the node will get the new
color when they access that index.
The size of the color map - and, therefore, the number of colors that can
be used simultaneously - depends on the number of planes in the node's
display bitmap. The number of bits in a color map's index is just the
number of planes in the display's bitmap.
_________________________________________________
| Color Map Sizes |
|________________________________________________|
| | Number of colors |
| Display Type | Available Simultaneously |
|_____________________|__________________________|
|(1-Plane) Monochrome | 2 |
|_____________________|__________________________|
|4-Plane Color | 16 |
|_____________________|__________________________|
|8-Plane Color | 256 |
|_____________________|__________________________|
An index into the color map is usually called a "pixel value" because a
pixel is colored by adding the weighted values of the bits set in the
planes of the display bitmap at the pixel's location and using the sum as
an index into the color map. The color in the color map at the resulting
pixel value is the color displayed for the pixel. Thus, each bit in the
color map index, or pixel value, represents a plane in the display bit-
map.
A default color map is loaded by the Display Manager from
/sys/dm/color_map at startup time. Each entry in the color map consists
of 1-byte intensity values for each of the three primary colors (red,
green, and blue). After the Display Manager starts up, the CTM can
change any entry in the color map from its default to create a new color.
The default color map for a 4-plane display is shown in the following
table; the default color map for an 8-plane display is similar but has
256 color entries available. The Display Manager always loads colors 16
through 255 of an 8-plane display with "black" (or "0 0 0" as in pixel
value 0) when it starts up.
____________________________________________________
| The Default 4-Plane Color Map |
|___________________________________________________|
| Pixel Value | Color Value | Visible |
|_________________|____________________| Color |
|decimal | binary | red | green | blue | |
|________|________|____________________|____________|
| 0 | 0000 | 0 0 0 | black |
| 1 | 0001 | 255 0 0 | red |
| 2 | 0010 | 0 255 0 | green |
| 3 | 0011 | 0 0 255 | blue |
| 4 | 0100 | 0 255 255 | cyan |
| 5 | 0101 | 255 255 0 | yellow |
| 6 | 0110 | 255 0 255 | magenta |
| 7 | 0111 | 255 255 255 | white |
| 8 | 1000 | 240 255 190 | off white |
| 9 | 1001 | 30 155 0 | dark green |
| 10 | 1010 | 255 255 230 | off white |
| 11 | 1011 | 210 20 0 | dark red |
| 12 | 1100 | 255 255 230 | off yellow |
| 13 | 1101 | 60 60 200 | dark blue |
| 14 | 1110 | 240 240 170 | off white |
| 15 | 1111 | 150 90 0 | brown |
|________|________|____________________|____________|
The CTM keeps track of how many processes are using a color by maintain-
ing a use count for each entry in the color map. All entries in the
color map, except those preallocated by the Display Manager (color
indexes 0, 1, and 7 through 15), have an initial use count of 0 which
means that they are unused and that a process is free to change the color
value there without affecting any other process. When a process requests
use of a pixel value, the CTM increments the pixel value's use count.
For example, if five processes are sharing the color at pixel value 100,
then its use count is 5. When a process is finished using a color, it
can release the pixel value it allocated for that color by calling
ctm_$release_pv, and the CTM will decrement the pixel value's use count.
When its use count reaches 0 again, an entry in the color table and the
associated pixel value are free to be assigned a new color.
The CTM routines are advisory in nature and do not prevent manipulation
of the color map by other managers and processes. A process is free to
change color values anywhere in the color map (directly with gpr_$ calls,
for example) without calling the CTM, though such unsociable behavior may
cause the display to behave erratically while other processes are using
it.
Using the CTM
There are two basic ways to use the CTM: with ctm_$find_color, or with
ctm_$alloc_pv, ctm_$inc_use_count, ctm_$mark_read_only.
The easiest way is with ctm_$find_color. Ctm_$find_color lets a process
access any color in the table and any other color supported by the
display if there are enough unused entries in the color map. Use it for
programs that run in a single process and don't need to contend with
other programs for display resources.
Programs that frequently manipulate colors or share display resources
between processes will probably need ctm_$alloc_pv, ctm_$inc_use_count,
and ctm_$mark_read_only. They allow much more control over the color map
and use counts.
The ctm_$release_pv call releases a color table entry for possible use by
other processes by decrementing its use count, and is sometimes useful in
either programming context.
Data Types
ctm_$alloc_options_t
A small set type for specifying a set of pixel values to the CTM.
Though defined as a small set, arguments of type
ctm_$alloc_options_t may currently take only a single value and the
elements of the set are mutually exclusive. Therefore, arguments of
this type can take one of the following values:
ctm_$contiguous
Contiguous pixel values.
____________________________________________________
| Two Examples of 5 Contiguous Pixel Values |
| from the Default 4-Plane Color Map |
|___________________________________________________|
| Pixel Value | Color Value | Visible |
|_________________|____________________| Color |
|decimal | binary | red | green | blue | |
|________|________|____________________|____________|
| 2 | 0010 | 0 255 0 | green |
| 3 | 0011 | 0 0 255 | blue |
| 4 | 0100 | 0 255 255 | cyan |
| 5 | 0101 | 255 255 0 | yellow |
| 6 | 0110 | 255 0 255 | magenta |
|________|________|____________________|____________|
| 10 | 1010 | 255 255 230 | off white |
| 11 | 1011 | 210 20 0 | dark red |
| 12 | 1100 | 255 255 230 | off yellow |
| 13 | 1101 | 60 60 200 | dark blue |
| 14 | 1110 | 240 240 170 | off white |
|________|________|____________________|____________|
ctm_$zero_only
Pixel values with 0s in a specified plane or bit position.
____________________________________________________
| Pixel Values with Only 0s in Plane 2 |
| from the Default 4-Plane Color Map |
|___________________________________________________|
| Pixel Value | Color Value | Visible |
|_________________|____________________| Color |
|decimal | binary | red | green | blue | |
|________|________|____________________|____________|
| 0 | 0000 | 0 0 0 | black |
| 1 | 0001 | 255 0 0 | red |
| 4 | 0100 | 0 255 255 | cyan |
| 5 | 0101 | 255 255 0 | yellow |
| 8 | 1000 | 240 255 190 | off white |
| 9 | 1001 | 30 155 0 | dark green |
| 12 | 1100 | 255 255 230 | off yellow |
| 13 | 1101 | 60 60 200 | dark blue |
|________|________|____________________|____________|
ctm_$one_only
Pixel values with 1s in a specified plane or bit position.
___________________________________________________
| Pixel Values with Only 1s in Plane 2 |
| from the Default 4-Plane Color Map |
|__________________________________________________|
| Pixel Value | Color Value | Visible |
|_________________|____________________| Color |
|decimal | binary | red | green | blue | |
|________|________|____________________|___________|
| 2 | 0010 | 0 255 0 | green |
| 3 | 0011 | 0 0 255 | blue |
| 6 | 0110 | 255 0 255 | magenta |
| 7 | 0111 | 255 255 255 | white |
| 10 | 1010 | 255 255 230 | off white |
| 11 | 1011 | 210 20 0 | dark red |
| 14 | 1110 | 240 240 170 | off white |
| 15 | 1111 | 150 90 0 | brown |
|________|________|____________________|___________|
ctm_$both
Pairs of pixel values that differ only in a specified plane;
that is, pixel value pairs that differ in only one bit.
____________________________________________________
| Five Pixel Value Pairs |
| Differing Only in Plane 3 |
| from the Default 4-Plane Color Map |
|___________________________________________________|
| Pixel Value | Color Value | Visible |
|_________________|____________________| Color |
|decimal | binary | red | green | blue | |
|________|________|____________________|____________|
| 0 | 0000 | 0 0 0 | black |
| 4 | 0100 | 0 255 255 | cyan |
|________|________|____________________|____________|
| 1 | 0001 | 255 0 0 | red |
| 5 | 0101 | 255 255 0 | yellow |
|________|________|____________________|____________|
| 3 | 0011 | 0 0 255 | blue |
| 7 | 0111 | 255 255 255 | white |
|________|________|____________________|____________|
| 9 | 1001 | 30 155 0 | dark green |
| 13 | 1101 | 60 60 200 | dark blue |
|________|________|____________________|____________|
| 10 | 1010 | 255 255 230 | off white |
| 14 | 1110 | 240 240 170 | off white |
|________|________|____________________|____________|
ctm_$pixel_value_vector_t
An array of type gpr_$pixel_value_t; that is, an array of indexes
into the color map or array of pixel values.
gpr_$color_t
A pixel color defined as a triplet of red, green, and blue intensi-
ties. Each intensity is an unsigned 8-bit integer. It has the fol-
lowing format:
15 8 7 0
______________________________________________________________
| NOT USED | red |
|______________________________|______________________________|
| green | blue |
______________________________________________________________
15 8 7 0
gpr_$pixel_value_t
An index into the color map. Also the weighted sum of set bits in
the planes of the display bitmap at a pixel location.
Errors
ctm_$not_allocated
Returned by ctm_$release_pv, ctm_$inc_use_count, or
ctm_$mark_read_only when a requested pixel value was not allocated
to the calling process. A process must allocate entries in the
color map with ctm_$alloc_pv or ctm_$find_color before using them
with other CTM calls.
ctm_$cant
The CTM can't supply a requested pixel value because the color map
is full. Try using ctm_$find_color to locate a needed color that is
already allocated, or use ctm_$release_pv to free up the needed
color table entries.
ctm_$no_space
The CTM was unable to allocate enough memory for its internal use.