Turismo

A ScrnColorMap.Tis a handle on a colormap that is valid for some particular screentype, called the 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 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

preferred colors that cover the spectrum reasonably densely. Some preferred colors are

designated as 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 ScrnColorMap; IMPORT TrestleComm;

7.11.1 Obtaining handles from the oracle

TYPE

Oracle = Private OBJECT METHODS

<* LL.sup <= VBT.mu *>

7.11 Color maps 101

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 screentypestcontains a fieldst.cmapof typeOracle, which hands out colormaps owned byst:

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 tost. 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 bystwith the given name. IfpreLoaded

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 bystwith the given name, orNILif no colormap has this name.

The method call

st.cmap.list(pat, maxResults)

returns the names of colormaps owned by stthat match the pattern pat. The list of results may be truncated to lengthmaxResults. A *matches any number of characters and a?matches any single character.

7.11.2 The handle object

TYPE

T <: Public;

Public = OBJECT (*CONST*) depth: INTEGER;

readOnly: BOOLEAN; ramp: Ramp;

<* 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 fieldcm.depthis the depth ofcm, andcm.readOnlyisTRUEifcmcannot be written. The fieldcm.rampdefines a three dimensional lattice of colors preallocated incm, as follows.

Ifcm.ramp.baseis-1, the lattice of preallocated colors is empty. Ifcm.ramp.baseis 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]), forr

in the range[0..last[Red]],gin the range[0..last[Green]], andbin the range[0..last[Blue]].

AnRGBrepresents 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 thercomponent is relevant. The method call

cm.fromRGB(rgb, mode)

extends the read-only portion ofcmwith a new entry whose value is near rgband returns the pixel of the new entry. If the read-only portion ofcmalready contains an entry whose value is near rgb, that entry’s pixel is returned. Themode argument controls how near the new entry’s value will be torgb, as follows. IfmodeisStable, the new entry’s color is the nearest stable color torgb. IfmodeisNormal, the new entry’s color is the nearest preferred color torgb. If modeisAccurate, the new

7.11 Color maps 103

entry’s color is the nearest color torgbthat the hardware supports. The method raises

Failureif a new entry is required but the colormap is full. For each entryein the arrayres, the method call

cm.read(res)

setse.rgbto the color incmof the pixele.pixel. The method call

cm.write(new)

changes the value ofcmatpto bergb, for each pair(p, rgb)in the arraynew, assuming all these pixels are writable. Otherwise the method raisesFailure. The arraynewmust be sorted.

The method call

cm.new(dim)

extends the writable portion ofcmwith a set of2

dim

new entries whose pixels form a cube, and returns the cube. The method raisesFailureif the free entries of the colormap do not contain a cube of the given dimension.

ACube cbrepresents a set of pixels by the following rule: a pixelpis incbif

Word.And(lo, pix) = loandWord.Or(hi, pix) = hi.

The method callcm.free(cb)deallocates from the writable portion ofcmeach entry whose pixel is in the cubecb, assuming all of these pixels are allocated.

In document Acuerdo Municipal No. 002 de 2012 (página 145-183)