[Indigo]<Mesa>Doc>System>Display.bravo!1

Page Numbers: Yes First Page: 18 X: 527 Y: 10.5"
Margins: Binding: 13
Odd Heading: Not-on-first-page

Alto/Mesa Display Package

Even Heading:

Alto/Mesa Display Package

Alto/Mesa Display Package
October 1980

The Mesa Display Package provides a simple, teletype style interface to the Alto display (see AltoDisplay). There is provision for using any available font; however the display is restricted to a single font for any particular incarnation. The font operations (described at the end of this document) are independent of the display implementation and may be used by any other display package. The package will optionally maintain a typescript of displayed output.

Display Stream

Normal access to the display is through a stream interface (see the section on Streams). There is no provision for multiple display streams. The module SystemDisplay implements the following procedures defined in StreamDefs:

GetDefaultDisplayStream: PROCEDURE RETURNS [DisplayHandle];

The interpretation of the basic stream operations is:

reset clears the display and resets the typescript.

put displays the character at the next sequential location.

get, putback and destroy SIGNAL StreamError[StreamAccess].

endof returns FALSE.

In addition, the following operations are defined for display streams:

clearCurrentLine: PROCEDURE [stream: StreamHandle]

This procedure clears the current line of the display. The next character will be displayed at the left margin. The typescript is repositioned to the beginning of the line.

clearLine: PROCEDURE [stream: StreamHandle, line: CARDINAL]

Clears line on the the display. The next character will be displayed at the left margin of that line. The typescript is repositioned to the beginning of the line. In the current Alto/Mesa implementation, clearLine is a no-op.

clearDisplayChar: PROCEDURE [stream: StreamHandle, char: CHARACTER]

Erases the last character written on the display. The character must be supplied since the stream retains no knowledge of what characters are displayed (the typescript is optional).

DisplayDefs defines some additional interface procedures:

InitDisplay: PROCEDURE [
dummySize, textLines, nPages: CARDINAL, f: FontDefs.FontHandle];

This procedure initializes the display with dummySize blank scan lines at the top and room for at most textLines lines of text using nPages pages of memory for data structures and bitmap. The number of text lines and the display width are reduced if necessary to make everything fit in nPages.

The amount of memory necessary to guarantee that n full width lines of text can be displayed is n*(4+h*w) words, where h is the height of the font in scan lines (rounded up to an even number) and w is the width of the display in words.

SetSystemDisplaySize: PROCEDURE [nTextLines, nPages: CARDINAL];

Clears the display and reinitializes it with the new parameters.

SetSystemDisplayWidth: PROCEDURE [indent, width: CARDINAL];

Clears the display and reinitializes it with the new width parameters. indent is the number of bits from the left edge of the screen to the first display position and width is the width of a display line in bits. (The actual width will be the nearest multiple of 32 bits.).

Indenting by multiples of 16 bits is very efficient.

SetDummyDisplaySize: PROCEDURE [nScanLines: CARDINAL];

Changes the size of the blank space at the top of the display. The space will be rounded up to an even number of scan lines and may be zero.

Background: TYPE = {white, black};

DisplayOff: PROCEDURE [color: Background];

DisplayOn: PROCEDURE;

DisplayOff releases all of the space allocated to the display and swaps out the font. All of the parameters of the display are saved so that DisplayOn can restore the previous state (but not the contents) of the display.

StartCursor: PROCEDURE;

StopCursor: PROCEDURE;

StartCursor forks a process in DisplayControl that blinks the cursor. If the cursor process is already running, it is a no op. StopCursor stops it.

BlinkCursor: PROCEDURE RETURNS [BOOLEAN];

Blinks a "cursor" at the position where the next character will be displayed. Each call changes the state of the cursor from "on" to "off" or vice versa. BlinkCursor returns TRUE if the last call changed the cursor state to on. The cursor is always turned off before a character is displayed or erased.

SetTypeScript: PROCEDURE [StreamDefs.DiskHandle];

This procedure establishes a disk stream as a typescript for the display. Passing NIL will disable the typescript. Characters sent to the display stream while the display is off will appear in the typescript. The typescript must be an open byte stream with ReadWriteAppend access.

GetTypeScript: PROCEDURE RETURNS [StreamDefs.DiskHandle];

This procedure returns the disk stream that is behind the typescript for the display.

DisplayControl: PROGRAM;

This is the control module used in Mesa.image. It will initialize the display, font and typescript (using either MesaFont.al or SysFont.al and Mesa.Typescript) and start a process to call BlinkCursor at half second intervals. It will also reestablish the display (including font and typescript) after a MakeImage or MakeCheckPoint.

DestroyDisplay: PROCEDURE;

This procedure deletes the display package; it turns off the display, deallocates the bitmap, destroys the font and UNNEWs all the display modules.

Fonts

A FontObject provides a simple object style interface to character fonts. Operations are provided for painting or erasing characters from the font in a bitmap. FontDefs defines the following TYPEs and PROCEDUREs:

BitmapState: TYPE = RECORD [
origin: POINTER,
wordsPerLine, x, y: [0..77777B)];

A BitmapState describes where a character will be placed within a bitmap. origin is a POINTER to the beginning of the bitmap. wordsPerLine is the horizontal width of the bitmap (it must be even if the bitmap is to be displayed). x and y are measured from the upper left corner in bits right and scan lines down respectively.

FontHandle: TYPE = POINTER TO FontObject;

FontObject: TYPE = RECORD [
paintChar: PROCEDURE [FontHandle, CHARACTER, POINTER TO BitmapState],
clearChar: PROCEDURE [FontHandle, CHARACTER, POINTER TO BitmapState],
charWidth: PROCEDURE [FontHandle, CHARACTER] RETURNS [CARDINAL],
charHeight: PROCEDURE [FontHandle, CHARACTER] RETURNS [CARDINAL],
close: PROCEDURE [FontHandle],
destroy: PROCEDURE [FontHandle],
lock: PROCEDURE [FontHandle] RETURNS [POINTER],
unlock: PROCEDURE [FontHandle]];

A FontObject implements the following operations:

paintChar: ORs the specified character from the font into the bitmap position specified in the BitmapState; x is updated to point to the next character position. There is no bounds checking.

clearChar: erases the bit rectangle that bounds the character. The input state points just beyond the character and is modified to point to where the character used to be. paintChar[f, c, s] followed by clearChar[f, c, s] leaves s unchanged.

charWidth, charHeight: return the width and height of a character in bits and scan lines respectively.

close: swaps the font out of memory if it is not otherwise in use. The font will always be swapped in when needed. It is not generally locked.

destroy: calls close and then releases the space allocated for the FontObject. The font segment is not deleted.

lock: locks the font segment in memory and returns a POINTER to the first word. This can be used to implement other operations on the bits in the font. Note that nothing in a FontObject dictates what font format is used.

unlock: unlocks the font after a call to lock.

CharWidth: PROCEDURE [font: FontHandle, char: CHARACTER] RETURNS [CARDINAL];

Equivalent to font.charWidth[font, char].

CharHeight: PROCEDURE [font: FontHandle, char: CHARACTER] RETURNS [CARDINAL];

Equivalent to font.charHeight[font, char].

CreateFont: PROCEDURE [SegmentDefs.FileSegmentHandle] RETURNS [FontHandle];

Allocates space (from the system heap) for a FontObject and initializes its operations to use the font in the supplied segment.

The following procedure from DisplayDefs can be called to obtain a handle for the current system font.

GetFont: PROCEDURE RETURNS [FontHandle];

Returns the FontHandle for the system font.

The module AlFont implements FontObjects for "Al" format fonts. Modules for other font formats can be substituted easily. At this time no other modules have been written or planned.

Mesa.image uses SystemDisplay, AlFont, and DisplayControl for its default display. They are also available as a separate package in DisplayPackage, which also contains an instance of StreamIO.