Virtual: TYPE = REF Object;
Object:
TYPE =
RECORD [
characteristics of the keyboard and mouse
keyboard: PRIVATE LONG POINTER TO READONLY Keys.KeyBits,
mouse: PRIVATE LONG POINTER TO READONLY Position,
characteristics of the black-and-white display (if any)
hasBlackAndWhiteDisplay: --READONLY-- BOOL,
bwWidth: --READONLY-- NAT,
bwHeight: --READONLY-- NAT,
bwHasBorder: --READONLY-- BOOL,
bwPixelsPerInch: --READONLY-- NAT,
bwCursor: PRIVATE LONG POINTER TO Position,
characteristics of the color display (if any)
hasColorDisplay: --READONLY-- BOOL,
colorWidth: --READONLY-- NAT,
colorHeight: --READONLY-- NAT,
colorPixelsPerInch: --READONLY-- NAT,
colorDisplayType: --READONLY-- ColorDisplayType,
colorMode: PRIVATE ColorMode,
The following may change whenever the colorMode changes and are not valid if the color bitmap state is "none".
colorBitmapA: --READONLY-- LONG POINTER, -- channel A bitmap base
colorBitmapB: --READONLY-- LONG POINTER, -- channel B bitmap base
colorWordsPerLineA: --READONLY-- NAT, -- channel A bitmap width
colorWordsPerLineB: --READONLY-- NAT, -- channel B bitmap width
implementation data
impl: PRIVATE REF ANY
];
SwapAction: TYPE = {coming, here, going, gone};
SwapNotifier: TYPE = PROC [Virtual, SwapAction];
Position: TYPE = MACHINE DEPENDENT RECORD [x, y: INTEGER];
BitmapState:
TYPE = {none, allocated, displayed};
This state applies to both black-and-white and color display bitmaps.
BWBackground: TYPE = {white, black};
BWBorder: TYPE = [0..256);
BWCursorBitmap: TYPE = ARRAY [0..16) OF WORD;
ColorDisplayType: TYPE = {ramtek525, hitachi3619};
ChannelValue: TYPE = [0..256);
maxBitsPerChannelValue: NAT = --Log2 ChannelValue.LAST+1-- 8;
ColorMode:
TYPE =
RECORD [
full: BOOL,
bitsPerPixelChannelA: [0..maxBitsPerChannelValue],
bitsPerPixelChannelB: [0..maxBitsPerChannelValue]
];
ChannelsVisible: TYPE = {none, aOnly, bOnly, all};
Color: TYPE = [0..256);
bitsPerColorValue: NAT = --Log2 Color.LAST+1-- 8;
ColorCursorBitmap:
TYPE =
ARRAY [0..16)
OF
WORD;
Note: This type is presently defined in such a way that it is type-compatible with BWCursorBitmap. This is because the client is expected to treat the black-and-white and color cursors as a single logical entity, which moves between screens without being transformed. However, since the color cursor is implemented in software, it is not limited to a 16x16 bit array, as the black-and-white cursor is. We are willing to risk an interface change to make the two cursors different, since such a change will have more serious ramifications for the client than for us.
ColorCursorPresentation: TYPE = {onesAreWhite, onesAreBlack};
ColorCursorBitmapState: TYPE = {visible, invisible};
This interface provides a facility for multiplexing virtual terminals on a single physical terminal. The interface is designed for an arbitrary number of virtual terminals and is intended to be used to support debugging of new versions of terminal-handling code. This multiplexing facility has the following primary features:
1) The human user at the keyboard can cycle through the extant virtual terminals by a particular key combination (control-shift-shift). (This is equivalent to an implicit call of Select[NIL]; see below.)
2) A client program can select which virtual terminal is to be connected to the physical terminal, and can prevent a change of virtual terminal by clients or the user.
3) Clients may register procedures to be invoked whenever the virtual-to-physical terminal correspondance changes.
The implementation initially supplies a single virtual terminal, available through Current.
Create:
PROC
RETURNS [vt: Virtual];
This procedure creates a new virtual terminal. If the hardware includes a black-and-white display, vt.hasBlackAndWhiteDisplay is TRUE and the border, screen dimensions, and resolution values are set to the characteristics of the hardware. Analogous remarks apply to the color display information in vt. The initial state of this terminal, in terms of the procedures below, is:
GetKeys[vt] = ALL[up]
GetMousePosition[vt] = [0,0]
GetBWCursorPosition[vt] = [0,0]
GetBWCursorPattern[vt] = ALL[0]
GetBWBitmapState[vt] = none
GetBWBackground[vt] = white
Errors: CantDoIt is raised if insufficient virtual memory exists to create the virtual terminal.
Select:
PROC [vt: Virtual ←
NIL, lock:
BOOL ←
FALSE]
RETURNS [worked:
BOOL];
This procedure causes the indicated virtual terminal to be "connected" to the physical terminal; that is, its keyboard, mouse display(s) and cursor(s) interact directly with the hardware. If "lock" is TRUE, Select executes an implicit PreventSwaps (see below) after connecting the requested virtual terminal to the physical terminal. If the lock count (see PreventSwaps, below) is positive, Select has no effect (and "lock" is ignored). In this case, the return value is FALSE; otherwise, it is TRUE. (Note: if vt = NIL, the "next" virtual terminal, in an unspecified order, is selected. Thus, repeated calls of Select[NIL] cause each virtual terminal to be connected in succession.)
Errors: It is illegal to invoke Select from a SwapNotifier procedure.
Current:
PROC
RETURNS [vt: Virtual, lockCount:
NAT];
This procedure returns the identity of the presently selected virtual terminal (lockCount is described under PreventSwaps, below).
Errors: It is illegal to invoke Current from a SwapNotifier procedure.
PreventSwaps:
PROC [vt: Virtual];
If the specified virtual terminal is not presently selected, PreventSwaps waits until it becomes selected. It then increments a global "lock count" which may be interrogated by Current. When this count is positive, Select and control-shift-shift are disabled (i.e., have no effect).
Errors: It is illegal to invoke PreventSwaps from a SwapNotifier procedure.
PermitSwaps:
PROC [vt: Virtual];
This procedure decrements the global lock count that may be interrogated by Current. If the specified virtual terminal is not presently selected or if PermitSwaps is called when the lock count is zero, it has no effect.
RegisterNotifier:
PROC [vt: Virtual, notifier: SwapNotifier];
This procedure registers a client procedure with the specified virtual terminal. The registered procedure will be invoked whenever a swap of virtual terminals occurs. When a terminal swap occurs, the following client-visible steps occur:
1) Notifiers for current terminal are called with SwapAction[going].
2) Notifiers for the new terminal are called with SwapAction[coming].
3) The actual terminal swap occurs.
4) Notifiers for the former current terminal are called with SwapAction[gone].
5) Notifiers for the new current terminal are called with SwapAction[here].
The SwapNotifiers are invoked in the order of their registration in steps 2 and 5, and in the reverse order of their registration in steps 1 and 4.
Unless otherwise noted, all the procedures in this interface may be invoked from a SwapNotifier.
Errors: It is illegal to invoke RegisterNotifier from a SwapNotifier procedure.
UnregisterNotifier:
PROC [vt: Virtual, notifier: SwapNotifier];
The specified SwapNotifier is disassociated from the specified virtual terminal. If it is not presently registered, UnregisterNotifier has no effect.
Errors: It is illegal to invoke UnregisterNotifier from a SwapNotifier procedure.
All of the procedures in this section are valid only if vt.hasBlackAndWhiteDisplay is TRUE.
GetBWCursorPosition:
ENTRY
PROC [vt: Virtual]
RETURNS [Position] =
GetBWCursorPosition returns the position of the virtual cursor associated with the black-and-white display on the specified virtual terminal. This position changes only as a result of calls on SetBWCursorPosition.
TRUSTED INLINE {RETURN[vt.bwCursor^]};
SetBWCursorPosition:
ENTRY
PROC [vt: Virtual, position: Position] =
SetBWCursorPosition sets the cursor position of the specified virtual terminal to the indicated value. This position will be reflected on the screen when the virtual terminal is next selected (or, if it is presently selected, immediately). It is the responsibility of the client to clip the position, if desired, to ensure that the cursor remains on the visible area of the display.
TRUSTED INLINE {vt.bwCursor^ ← position};
GetBWCursorPattern:
PROC [vt: Virtual]
RETURNS [pattern: BWCursorBitmap];
GetBWCursorPattern returns the bitmap of the virtual cursor associated with the black-and-white display on the specified virtual terminal. This bitmap changes only as a result of calls on SetBWCursorPattern.
SetBWCursorPattern:
PROC [vt: Virtual, pattern: BWCursorBitmap];
SetBWCursorPattern sets the cursor bitmap of the specified virtual terminal to the indicated value. This bitmap will be reflected on the screen when the virtual terminal is next selected (or, if it is presently selected, immediately).
All of the procedures in this section are valid only if vt.hasBlackAndWhiteDisplay is TRUE.
GetBWBitmapState: PROC [vt: Virtual] RETURNS [BitmapState];
SetBWBitmapState:
PROC [vt: Virtual, new: BitmapState]
RETURNS [old: BitmapState];
These procedures manage the virtual memory used for the black-and-white display's bitmap. These manipulations occur whether or not the virtual terminal is presently selected, but their effect, if any, on the display can only be observed when the terminal is selected.
BitmapState[none] means that the display has no associated bitmap; if the virtual terminal is selected, the appearance of black-and-white screen is determined by the background value (see GetBWBackground and SetBWBackground below).
BitmapState[allocated] means that virtual memory has been allocated for the display's bitmap, but is not presently associated with the screen. That is, even if the virtual terminal is selected, the contents of the bitmap will not be displayed. They may, however, be manipulated via GetBitBltTable and PrincOpsUtils.BITBLT.
BitmapState[displayed] means that, when the specified virtual terminal is selected, its associated bitmap will appear on the black-and-white display. The background and border values (see below) will affect the appearance of the bitmap.
If GetBWBitmapState[vt] = BitmapState[none] and SetBWBitmapState[vt, allocated] is called and there is insufficient virtual memory to allocate a bitmap, the error CantDoIt is raised.
GetBWBackground: PROC [vt: Virtual] RETURNS [BWBackground];
SetBWBackground:
PROC [vt: Virtual, new: BWBackground]
RETURNS [old: BWBackground];
These procedures control the interpretation of bits in the black-and-white display's bitmap. (For the purposes of these procedures, a non-existent bitmap is equivalent to a bitmap containing all zeros.) BWBackground[white] causes zeros in the bitmap to appear white and ones to appear black. BWBackground[black] causes zeros in the bitmap to appear black and ones to appear white. These procedures may be invoked whether or not the virtual terminal is presently selected, but their effect, if any, on the display can only be observed when the terminal is selected.
GetBWBorder: PROC [vt: Virtual] RETURNS [oddPairs, evenPairs: BWBorder];
SetBWBorder:
PROC [vt: Virtual, oddPairs, evenPairs: BWBorder];
These procedures control the appearance of the region of the black-and-white display that is not occupied by the bitmap. These procedures may be invoked whether or not the virtual terminal is presently selected, but their effect, if any, on the display can only be observed when the terminal is selected.
GetBitBltTable:
UNSAFE PROC [vt: Virtual]
RETURNS [bbt: PrincOps.BBTable];
This procedure returns a BITBLT table for the black-and-white display bitmap of the specified virtual terminal. This table is properly aligned for use with PrincOpsUtils.BITBLT. Its contents are as follows:
PrincOps.BBTable[
dst: IF GetBWBitmapState[vt] = none THEN NIL ELSE base of bitmap
dstBpl: an appropriate width (at least vt.bwWidth)
src: IF GetBWBitmapState[vt] = none THEN NIL ELSE base of bitmap
srcDesc: [srcBpl[an appropriate width (at least vt.bwWidth)]]
width: vt.bwWidth,
height: vt.bwHeight,
flags: [
direction: forward,
disjoint: FALSE,
disjointItems: FALSE,
gray: FALSE,
srcFunc: null,
dstFunc: null
]
]
WaitForBWVerticalRetrace:
PROC [vt: Virtual];
If the specified virtual terminal is not presently selected, WaitForVerticalRetrace waits until the terminal becomes selected. It then waits until the next back-and-white display scan begins and returns.
BlinkBWDisplay:
PROC [vt: Virtual];
This procedure blinks the black-and-white display if the specified virtual terminal is presently selected. Otherwise, it has no effect.
All of the procedures in this section are valid only if vt.hasColorDisplay is TRUE.
GetColorBitmapState: PROC [vt: Virtual] RETURNS [BitmapState];
SetColorBitmapState:
PROC [
vt: Virtual, newState: BitmapState, newMode: ColorMode, newVisibility: ChannelsVisible]
RETURNS [oldState: BitmapState, oldMode: ColorMode, oldVisibility: ChannelsVisible];
These procedures manage the virtual memory used for the color display's bitmap and colormap. These manipulations occur whether or not the virtual terminal is presently selected, but their effect, if any, on the display can only be observed when the terminal is selected.
BitmapState[none] means that the display has no associated bitmap; if the virtual terminal is selected, the color screen will appear black.
BitmapState[allocated] means that virtual memory has been allocated for the display's bitmap and colormap, but is not presently associated with the screen. That is, even if the virtual terminal is selected, the contents of the bitmap will not be displayed. They may be (indeed, they are expected to be) manipulated by software through the appropriate bitmap pointers in "vt". Several arrangements of storage for the bitmap and colormap are supported; the "newMode" parameter specifies the way in which the display will be used.
BitmapState[displayed] means that, when the specified virtual terminal is selected, its associated bitmap will appear on the color display.
If newState = none, the mode and visibility settings are remembered (and can be accessed by GetColorMode and GetVisibility, respectively).
Note that there is there is no formal distinction between <newMode: displayed, newVisibility: none> and <newMode: allocated or none, newVisibility: all>. However, these two situtions have different performance characteristics. When newMode = displayed, the bitmap and colormap are pinned in memory; that is, the real memory they occupy cannot be stolen by the virtual memory machinery. In other modes, the bitmap and colormap (if any) can be swapped out. Therefore, <newMode: displayed, newVisibility: none> should be used only for short-term disabling of the display, since the bitmap and colormap remained pinned.
If SetColorBitmapState is invoked with newMode equal to the previous ColorMode, the previously allocated bitmap and colormap (if any) is undisturbed.
Invoking SetColorBitmapState with newMode such that ~LegalColorMode[vt, newMode] raises CantDoIt.
GetColorMode:
ENTRY
PROC [vt: Virtual]
RETURNS [ColorMode] =
TRUSTED INLINE {RETURN[vt.colorMode]};
SetColorMode:
PROC [vt: Virtual, new: ColorMode]
RETURNS [old: ColorMode] =
INLINE {RETURN[SetColorBitmapState[vt, allocated, new, all].oldMode]};
LegalColorMode:
PROC [vt: Virtual, mode: ColorMode]
RETURNS [
BOOL];
This procedure returns TRUE if the color display implements the indicated mode.
TurnOnColorDisplay:
PROC [vt: Virtual] =
INLINE {[] ← SetColorBitmapState[vt, displayed, GetColorMode[vt], all]};
TurnOffColorDisplay:
PROC [vt: Virtual] =
INLINE {[] ← SetColorBitmapState[vt, allocated, GetColorMode[vt], none]};
GetVisibility: PROC [vt: Virtual] RETURNS [ChannelsVisible];
SetVisibility:
PROC [vt: Virtual, visibility: ChannelsVisible] =
INLINE {[] ← SetColorBitmapState[vt, GetColorBitmapState[vt], GetColorMode[vt], visibility]};
These procedures manipulate the visibility of the bitmaps accessed on the color channels. The effect of SetVisibility can be seen only when vt is selected and GetColorBitmapState[vt] = displayed, but it can be invoked in any state.
GetRedMap: PROC [vt: Virtual, in: Color] RETURNS [Color];
GetGreenMap: PROC [vt: Virtual, in: Color] RETURNS [Color];
GetBlueMap: PROC [vt: Virtual, in: Color] RETURNS [Color];
SetRedMap: PROC [vt: Virtual, in: Color, out: Color];
SetGreenMap: PROC [vt: Virtual, in: Color, out: Color];
SetBlueMap:
PROC [vt: Virtual, in: Color, out: Color];
These procedures are defined only if GetColorBitmapState[vt] ~= none and GetColorMode[vt].full is TRUE. They support gamma correction.
GetColor:
PROC [vt: Virtual, aChannelValue, bChannelValue: ChannelValue ← 0]
RETURNS [red, green, blue: Color];
SetColor:
PROC [
vt: Virtual, aChannelValue, bChannelValue: ChannelValue ← 0, red, green, blue: Color];
These procedures are defined only if GetColorBitmapState[vt] ~= none and GetColorMode[vt].full is FALSE. They permit inspection and manipulation of the colormap.
All of the procedures in this section are valid only if vt.hasColorDisplay is TRUE.
GetColorCursorPosition:
PROC [vt: Virtual]
RETURNS [Position];
GetColorCursorPosition returns the position of the virtual cursor associated with the color display on the specified virtual terminal. This position changes only as a result of calls on SetColorCursorPosition.
SetColorCursorPosition:
PROC [vt: Virtual, position: Position];
SetColorCursorPosition sets the cursor position of the specified virtual terminal to the indicated value. This position will be reflected on the screen when the virtual terminal is next selected (or, if it is presently selected, immediately). It is the responsibility of the client to clip the position, if desired, to ensure that the cursor remains on the visible area of the display.
GetColorCursorPattern:
PROC [vt: Virtual]
RETURNS [pattern: ColorCursorBitmap];
GetColorCursorPattern returns the bitmap of the virtual cursor associated with the color display on the specified virtual terminal. This bitmap changes only as a result of calls on SetColorCursorPattern and/or SetColorCursorPresentation.
SetColorCursorPattern:
PROC [vt: Virtual, pattern: ColorCursorBitmap];
SetColorCursorPattern sets the cursor bitmap of the specified virtual terminal to the indicated value. This bitmap will be reflected on the screen when the virtual terminal is next selected (or, if it is presently selected, immediately).
GetColorCursorPresentation: PROC [vt: Virtual] RETURNS [ColorCursorPresentation];
SetColorCursorPresentation:
PROC [vt: Virtual, new: ColorCursorPresentation]
RETURNS [old: ColorCursorPresentation];
These procedures control the manner in which the cursor bitmap is presented on the color display. "onesAreWhite" means a one-bit in the ColorCursorBitmap is mapped to a color value of all ones (conventionally white) and a zero-bit is mapped to a color value of all zeros (conventionally black). "onesAreBlack" reverses this interpretation.
GetColorCursorState: PROC [vt: Virtual] RETURNS [ColorCursorBitmapState];
SetColorCursorState:
PROC [vt: Virtual, new: ColorCursorBitmapState]
RETURNS [old: ColorCursorBitmapState];
These procedures control the visibility of the cursor bitmap on the color display. When the state is "visible", the cursor bitmap (supplied by SetColorCursorPattern and influenced by SetColorCursorPresentation) is displayed at the position determined by SetColorCursorPosition. When the state is "invisible", no cursor appears on the color display. In the "visible" state, the cursor is merged into the color display bitmap by software, which caches the contents of the display bitmap that lie "under" the cursor. If the cursor moves (as a result of SetColorCursorPosition), the display bitmap is restored to the cached value. The procedures used to modify the display bitmap do not check to see if this cache should be invalidated. Therefore, if the client wants to change the display bitmap under the cursor, it must first flush the cache by setting the cursor state to "invisible".
The effect of these procedures can only be observed when vt is selected and GetColorBitmapState[vt] = displayed.