<*PRAGMA LL*>A
ScrnColorMap.T is a handle on a colormap that is valid for some
particular screentype, called the {\it owner} of the handle. Some
handles have names; others are anonymous. A named handle is valid
forever. The colormap referenced by an anonymous handle will be
garbage-collected when all handles to it have been dropped.
Every colormap has a {\it depth}; the pixel values defined by the
color map are in the range [0..(2^depth)-1]. Every color-mapped
screentype defines a set of {\it preferred} colors that cover the
spectrum reasonably densely. Some preferred colors are designated
as {\it stable}.
Clients can allocate pixels out of a color map as read-only shared entries or as writable exclusive entries. The implementation maintains reference counts on the read-only entries so that an entry can be freed when it is no longer allocated to any client.
INTERFACE\subsubsection{Obtaining handles from the oracle}ScrnColorMap ; IMPORT TrestleComm;
TYPE
Oracle = Private OBJECT
METHODS
<* LL.sup <= VBT.mu *>
standard(): T RAISES {TrestleComm.Failure};
new(name: TEXT := NIL; preLoaded := TRUE): T
RAISES {TrestleComm.Failure, Failure};
lookup(name: TEXT): T
RAISES {TrestleComm.Failure};
list(pat: TEXT; maxResults: CARDINAL := 1)
: REF ARRAY OF TEXT RAISES {TrestleComm.Failure}
END;
Private <: ROOT;
EXCEPTION Failure;
Every color-mapped screentype st contains a field st.cmap of
type Oracle, which hands out colormaps owned by st:
The method call
st.cmap.standard()
returns the default colormap owned by st. This is the colormap
that a top-level window will initially have when it is rescreened
to st. Initially, the stable colors are allocated read-only with
a reference count of one.
The method call
st.cmap.new(name, preLoaded)
creates and returns a new colormap owned by st with the given name.
If preLoaded is true, the stable colors are initially allocated
read-only; otherwise nothing is allocated initially.
The method call
st.cmap.lookup(name)
returns the colormap owned by st with the given name, or NIL
if no colormap has this name.
The method call
st.cmap.list(pat, maxResults)
returns the names of colormaps owned by st that match the pattern
pat. The list of results may be truncated to length maxResults.
A * matches any number of characters and a ? matches any single
character.
\subsubsection{The handle object}
TYPE
T <: Public;
Public = OBJECT (*CONST*)
depth: INTEGER;
readOnly: BOOLEAN;
ramp: Ramp;
METHODS
<* LL.sup <= VBT.mu *>
fromRGB(rgb: RGB; mode := Mode.Normal): Pixel
RAISES {Failure, TrestleComm.Failure};
read(VAR res: ARRAY OF Entry)
RAISES {TrestleComm.Failure};
write(READONLY new: ARRAY OF Entry)
RAISES {Failure, TrestleComm.Failure};
new(dim: CARDINAL): Cube RAISES
{Failure, TrestleComm.Failure};
free(READONLY cb: Cube)
RAISES {TrestleComm.Failure};
END;
Mode = {Stable, Normal, Accurate};
Ramp = RECORD
base: INTEGER;
last, mult: ARRAY Primary OF INTEGER;
END;
Primary = {Red, Green, Blue};
Cube = RECORD lo, hi: Pixel END;
Pixel = INTEGER;
RGB = RECORD r, g, b: REAL END;
Entry = RECORD pix: Pixel; rgb: RGB END;
The field cm.depth is the depth of cm, and cm.readOnly is
TRUE if cm cannot be written. The field cm.ramp defines
a three dimensional lattice of colors preallocated in cm,
as follows.
If cm.ramp.base is -1, the lattice of preallocated colors is empty.
If cm.ramp.base is not -1, then the pixel value
base + r*mult[Red] + g*mult[Green] + b*mult[Blue]
represents the color (r/last[Red], g/last[Green], b/last[Blue]), for r
in the range [0..last[Red]], g in the range [0..last[Green]], and
b in the range [0..last[Blue]].
\medskip An RGB represents the color with the given blend of red,
green, and blue. Each of the numbers is in the range [0.0..1.0];
thus the triple (0.0, 0.0, 0.0) specifies black. In case of a gray scale
display, only the r component is relevant.
The method call
cm.fromRGB(rgb, mode)
extends the read-only portion of cm with a new entry whose value
is near rgb and returns the pixel of the new entry. If the
read-only portion of cm already contains an entry whose value is
near rgb, that entry's pixel is returned. The mode argument
controls how near the new entry's value will be to rgb, as follows.
If mode is Stable, the new entry's color is the nearest stable
color to rgb. If mode is Normal, the new entry's color is
the nearest preferred color to rgb. If mode is Accurate, the
new entry's color is the nearest color to rgb that the hardware
supports. The method raises Failure if a new entry is
required but the colormap is full.
For each entry e in the array res, the method call
cm.read(res)
sets e.rgb to the color in cm of the pixel e.pixel.
The method call
cm.write(new)
changes the value of cm at p to be rgb, for each pair (p, rgb)
in the array new, assuming all these pixels are writable. Otherwise
the method raises Failure. The array new must be sorted.
The method call
cm.new(dim)
extends the writable portion of cm with a set of $2^{dim}$ new
entries whose pixels form a cube, and returns the cube. The method
raises Failure if the free entries of the colormap do not contain
a cube of the given dimension.
A Cube cb represents a set of pixels by the following rule:
a pixel p is in cb if Word.And(lo, pix) = lo and
Word.Or(hi, pix) = hi.
The method call cm.free(cb) deallocates from the writable portion
of cm each entry whose pixel is in the cube cb, assuming all
of these pixels are allocated.
END ScrnColorMap.