-- ColorDisplayFace.mesa
-- Last edit by Doug Wyatt,  9-Jul-81 15:21:55

DIRECTORY
  Environment USING [Base, PageCount, PageNumber];

ColorDisplayFace: DEFINITIONS = {

-- Processor-independent interface to color display.

-- Types

Mode: TYPE = RECORD[full, useA, useB: BOOLEAN, lgBitsPerPixelA,lgBitsPerPixelB: [0..3]];
-- Encodes the color display modes that may be available on a given processor.
-- full=TRUE specifies 24 bit per pixel mode; the other fields are ignored.
-- full=FALSE specifies a mode with one or two bitmaps addressing a color map:
--   if useA=TRUE, lgBitsPerPixelA specifies 1,2,4 or 8 bits per pixel for bitmap "A"
--   if useB=TRUE, lgBitsPerPixelB specifies 1,2,4 or 8 bits per pixel for bitmap "B"

Color: TYPE = [0..256); -- an 8 bit color value (red, green, or blue)

-- Interface variables

globalStateSize: READONLY CARDINAL; -- number of words required by Initialize
displayType: READONLY CARDINAL; -- display type; 0 means display is not available
pixelsPerInch: READONLY CARDINAL; -- size of a pixel

mixedRG: READONLY BOOLEAN; -- red and green mixed in bitmap A
-- Applies only to 24 bit per pixel mode: if mixedRG is TRUE, then the A bitmap
-- contains alternating red and green values, and the B bitmap contains blue values;
-- otherwise, bitmaps A, B, and C contain red, green, and blue respectively.

-- The following variables are established by Connect (see below).
-- They remain unchanged between a call to Connect and a call to Disconnect.

width,height: READONLY CARDINAL; -- raster dimensions in pixels (0,0 if disconnected)
baseA,baseB,baseC: READONLY LONG POINTER; -- bitmap addresses (NIL if bitmap not in use)
bplA,bplB,bplC: READONLY CARDINAL; -- bitmap bits per line (0 if bitmap not in use)

-- Procedures

Initialize: PROCEDURE [globalState: Environment.Base RELATIVE POINTER];
-- Initializes the implementation; the client must supply a block of
-- globalStateSize words, permanently allocated in first 64K of address space.
InitializeCleanup: PROCEDURE;
-- Initializes the cleanup coroutine for world swaps.

HasMode: PROCEDURE[mode: Mode] RETURNS[BOOLEAN];
-- Returns TRUE if the specified mode is available.

PagesForMode: PROCEDURE[mode: Mode] RETURNS[Environment.PageCount];
-- Returns the number of pages required to Connect the specified mode,
-- with a raster the size of the full screen.

Connect: PROCEDURE[mode: Mode,
  firstPage: Environment.PageNumber, nPages: Environment.PageCount];
-- Establishes the specified mode; allocates bitmap(s) and colormap(s)
--  from a client-supplied block of nPages pages of mapped virtual memory.
-- If mode.full=TRUE, nPages may be less than PagesForMode[mode];
--  in this case, the raster size will be reduced to fit.
-- Subsequent changes to the bitmap or color map will affect the color image,
--  but the image will not appear on the screen until TurnOn is called.

Disconnect: PROCEDURE;
-- Disconnects the display; releases all references to the pages passed to Connect.

TurnOn: PROCEDURE;
-- Turns display on, causing an image to appear on the screen.
-- Caution: the connected pages must be made resident before TurnOn is called!

TurnOff: PROCEDURE;
-- Turns display off, causing the screen to be dark.
-- The bitmap(s) and colormap are retained; the image will reappear if TurnOn is called.
-- The connected pages may be made swappable after TurnOff is called. 

Show: PROCEDURE[a,b,c: BOOLEAN ← TRUE];
-- Makes each bitmap visible (TRUE) or invisible (FALSE).

-- Procedures for mapped modes (mode.full=FALSE)

GetColor: PROCEDURE[pixelA,pixelB: CARDINAL ← 0] RETURNS[r,g,b: Color];
-- Returns the current color map entry for the given combination of pixel values
-- from bitmaps A and B. (For a bitmap not in use, the pixel value is always 0.)

SetColor: PROCEDURE[pixelA,pixelB: CARDINAL ← 0, r,g,b: Color];
-- Sets the color map entry for the given combination of pixel values.
-- If the display is 'on', the screen will show the change by the next frame time.

-- Procedures for 24 bit per pixel mode (mode.full=TRUE)

GetRedMap,GetGreenMap,GetBlueMap: PROCEDURE[in: Color] RETURNS[out: Color];
-- Returns the current entry from the red, green, or blue map.

SetRedMap,SetGreenMap,SetBlueMap: PROCEDURE[in,out: Color];
-- Sets an entry in the red, green, or blue map.
-- If the display is 'on', the screen will show the change by the next frame time.

}.