* WHERE-IS library doc * Gather keyboard files, add VIRTUAL.TEDIT * add UNIXCOMM.TEDIT * rest of TEdit library files * save table of contents index for reworking * Don't move around VIRTUALKEYBOARDS files; will move in separate commit * Add MATMULT from Envos/Medley
236 lines
175 KiB
Plaintext
236 lines
175 KiB
Plaintext
1
|
||
|
||
KALEIDOSCOPE MANUAL - 16-JAN-89 - Dev. Draft
|
||
1
|
||
|
||
KALEIDOSCOPE MANUAL - 16-JAN-89 - Dev. Draft
|
||
COLOR
|
||
1
|
||
|
||
ENVOS KALEIDOSCOPE
|
||
1
|
||
|
||
COLOR
|
||
6
|
||
|
||
2
|
||
|
||
Introduction
|
||
1
|
||
|
||
This document describes software for driving color displays. In order to run COLOR, you need either a Sun (3 or 4) with CG4 color hardware and display, a Dorado (Xerox 1132) with attached color display, or a Dandelion (Xerox 1108) with attached BusMaster and color display.
|
||
The color software which is distributed among a number of files can be divided into a machine independent group of files that all users can usefully load and a machine dependent group containing files that work for particular combinations of hardware.
|
||
The machine independent color graphics code is stored in the library files LLCOLOR.LCOM and COLOR.LCOM. LOADing COLOR.LCOM causes LLCOLOR.LCOM to be LOADed.
|
||
The machine dependent portions of Xerox Lisp color software is stored in files such as MAIKOCOLOR.LCOM, DORADOCOLOR.LCOM, or COLORNNCC.LCOM. The user LOADs one of these files according to what kind of machine and color card the user is using.
|
||
The Sun color driver resides in the file MAIKOCOLOR.LCOM which loads LLCOLOR.LCOM and COLOR.LCOM. The CG4 device suppports 8 bpp at 1152 by 900 resolution. The user must be running ldecolor, the special color capable emulator. The physical display monitor is shared by both the monochrome and color screens (described below) .
|
||
The Dorado color driver resides in the file DORADOCOLOR.LCOM which loads LLCOLOR.LCOM and COLOR.LCOM. The Dorado color board supports four or eight bits per pixel (bpp) at 640 by 480 resolution. (The board supports 24 bpp also, but Xerox Lisp doesn't yet.)
|
||
The Dandelion color drivers reside in the files DANDELIONUFO.LCOM, DANDELIONUFO4096.LCOM, and COLORNNCC.LCOM, one package for each of three different kinds of boards. The user should load one of these packages on a Dandelion attached to a BusMaster and color display. The DANDELIONUFO and DANDELIONUFO4096 packages drive 4 bpp at 640 by 400 resolution color boards used inside Xerox which have been made obsolete by COLORNNCC. The COLORNNCC package drives an 8 bpp color at 512 by 480 resolution board, the Revolution 512 x 8, made by Number Nine Computer Corporation. The Revolution 512 x 8 is available both inside and outside Xerox through Number Nine.
|
||
2
|
||
|
||
Hardware Displays and Software Screens
|
||
1
|
||
|
||
On some workstations (such as the Dorado and Dandelion), there may be physically two separate displays. On most Suns, there is a single physical display, which additionally may be shared by two Unix devices. One device is monochrome (b/w), and the other is color.
|
||
To support the various hardware configurations and external display devices, the software has a special datatype, a "screen". There are two distinct instances of screens, a b/w screen, and a color screen. A screen represents and controls a physical hardware display, and contains windows, icons, and tracks the mouse.
|
||
On workstations with physically two separate hardware displays, each display is represented by a corresponding screen data structure. On workstations with a single hardware display, the display is shared by both the b/w screen and the color screen.
|
||
In all cases, before initialization only the b/w screen (and thus display) is visible and active. After initialization both screens are active (can contain screen images), although on single displays, only one screen is visible at a time. Since each screen logically controls a display, we will henceforth use the terms "screen" and "display" interchangeably. Screens are discussed in greater detail below.
|
||
2
|
||
|
||
Turning the Color Display Software On and Off
|
||
1
|
||
|
||
The color display software can be turned on and off. While the color display software is on, the memory used for the color display screen bitmap is locked down, and a small amount of processing time is used to drive the color display.
|
||
(COLORDISPLAYP) [Function]
|
||
returns T if the color display is on; otherwise it returns NIL.
|
||
(COLORDISPLAYONOFF TYPE) [Function]
|
||
turns off the color display if ONOFF is 'OFF. If ONOFF is 'ON, it turns on the color display allocating memory for the color screen bitmap. TYPE should be one of 'MAIKOCOLOR, 'DORADOCOLOR, 'DANDELIONUFO, 'DANDELIONUFO4096, or 'COLORNNCC. The usual sequence of events for the user is to LOAD the software needed to drive a particular color card and then to call COLORDISPLAY with the appropriate TYPE to turn the software on. For example,
|
||
(LOAD 'COLOR.LCOM)
|
||
(LOAD 'COLORNNCC.LCOM)
|
||
(COLORDISPLAY 'ON 'REV512X8)
|
||
will turn on the software needed to drive the Number Nine Computer Corporation's Revolution 512 x 8 card with 1108 and BusMaster.
|
||
Besides initializing or reinitializing a color card that has been powered off, COLORDISPLAY allocates memory for the color screen bitmap. Turning on the color display requires allocating and locking down the memory necessary to hold the color display screen bitmap. Turning off the color display frees this memory.
|
||
2
|
||
|
||
Colors
|
||
1
|
||
|
||
The number of bits per pixel determines the number of different colors that can be displayed at one time. When there are 4 bpp, 16 colors can be displayed at once. When there are 8 bpp, 256 colors can be displayed at once. A table called a color map determines what color actually appears for each pixel value. A color map gives the color in terms of how much of the three primary colors (red, green, and blue) is displayed on the screen for each possible pixel value.
|
||
A color can be represented as a number, an atom, or a triple of numbers. Colors are ultimately given their final interpretation into how much red, blue, and green they represent through a color map. A color map maps a color number ([0 . . . 2nbits-1]) into the intensities of the three color guns (primary colors red, green, and blue). Each entry in the color map has eight bits for each of the primary colors, allowing 256 levels per primary or 224 possible colors (not all of which are distinct to the human eye). Within Xerox Lisp programs, colors can be manipulated as numbers, red-green-blue triples, names, or hue-lightness-saturation triples. Any function that takes a color accepts any of the different representations.
|
||
If a number is given, it is the color number used in the operation. It must be valid for the color bitmap used in the operation. (Since all of the routines that use a color need to determine its number, it is fastest to use numbers for colors. COLORNUMBERP, described below, provides a way to translate into numbers from the other representations.)
|
||
Red Green Blue Triples
|
||
1
|
||
|
||
A red green blue (RGB) triple is a list of three numbers between 0 and 255. The first element gives the intensity for red, the second for green, and the third for blue. When an RGB triple is used, the current color map is searched to find the color with the correct intensities. If none is found, an error is generated. (That is, no attempt is made by the system to assign color numbers to intensities automatically.) An example of an RGB triple is (255 255 255), which gives the color white.
|
||
RGB [Record]
|
||
is a record that is defined as (RED GREEN BLUE); it can be used to manipulate RGB triples.
|
||
COLORNAMES [Association list]
|
||
maps names into colors. The CDR of the color name's entry is used as the color corresponding to the color name. This can be any of the other representations. (Note: It can even be another color name. Loops in the name space such as would be caused by putting '(RED . CRIMSON) and '(CRIMSON . RED) on COLORNAMES are not checked for by the system.) Some color names are available in the initial system and are intended to allow color programs written by different users to coexist. These are:
|
||
Name RGB Number in default color maps
|
||
BLACK (0 0 0) 15 255
|
||
BLUE (0 0 255) 14 252
|
||
GREEN (0 255 0) 13 227
|
||
CYAN (0 255 255) 12 224
|
||
RED (255 0 0) 3 31
|
||
MAGENTA (255 0 255) 2 28
|
||
YELLOW (255 255 0) 1 3
|
||
WHITE (255 255 255) 0 0
|
||
Hue Lightness Saturation Triples
|
||
1
|
||
|
||
A hue lightness saturation triple is a list of three numbers. The first number (HUE) is an integer between 0 and 355 and indicates a position in degrees on a color wheel (blue at 0, red at 120, and green at 240). The second (LIGHTNESS) is a real number between zero and one that indicates how much total intensity is in the color. The third (SATURATION) is a real number between zero and one that indicates how disparate the three primary levels are.
|
||
HLS [Record]
|
||
is a record defined as (HUE LIGHTNESS SATURATION); it is provided to manipulate HLS triples. Example: the color blue is represented in HLS notation by (0 .5 1.0).
|
||
(COLORNUMBERP COLOR BITSPERPIXEL NOERRFLG) [Function]
|
||
returns the color number (offset into the screen color map) of COLOR. COLOR is one of the following:
|
||
<EFBFBD> A positive number less than the maximum number of colors,
|
||
<EFBFBD> A color name,
|
||
<EFBFBD> AN RGB triple, or
|
||
<EFBFBD> An HLS triple.
|
||
If COLOR is one of the above and is found in the screen color map, its color number in the screen color map is returned. If not, an error is generated unless NOERRFLG is non-NIL, in which case NIL is returned.
|
||
(RGBP X) [Function]
|
||
returns X if X is an RGB triple; NIL otherwise.
|
||
(HLSP X) [Function]
|
||
returns X if X is an HLS triple; NIL otherwise.
|
||
2
|
||
|
||
Color Maps
|
||
1
|
||
|
||
The screen color map holds the information about what color is displayed on the color screen for each pixel value in the color screen bitmap. The values in the current screen color map may be changed, and this change is reflected in the colors displayed at the next vertical retrace (approximately 1/30 of a second). The color map can be changed to obtain dramatic effects.
|
||
(SCREENCOLORMAP NEWCOLORMAP) [Function]
|
||
reads and sets the color map that is used by the color display. If NEWCOLORMAP is non-NIL, it should be a color map, and SCREENCOLORMAP sets the system color map to be that color map. The value returned is the value of the screen color map before SCREENCOLORMAP was called. If NEWCOLORMAP is NIL, the current screen color map is returned without change.
|
||
(CMYCOLORMAP CYANBITS MAGENTABITS YELLOWBITS BITSPERPIXEL) [Function]
|
||
Returns a color map that assumes the BITSPERPIXEL bits are to be treated as three separate color planes with CYANBITS bits being in the cyan plane, MAGENTABITS bits being in the magenta plane, and YELLOWBITS bits being in the yellow plane. Within each plane, the colors are uniformly distributed over the intensity range 0 to 255. White is 0 and black is 255.
|
||
(RGBCOLORMAP REDBITS GREENBITS BLUEBITS BITSPERPIXEL) [Function]
|
||
Returns a color map that assumes the BITSPERPIXEL bits are to be treated as three separate color planes with REDBITS bits being in the red plane, GREENBITS bits being in the green plane, and BLUEBITS bits being in the blue plane. Within each plane, the colors are uniformly distributed over the intensity range 0 to 255. White is 255 and black is 0.
|
||
(GRAYCOLORMAP BITSPERPIXEL) [Function]
|
||
Returns a color map containing shades of gray. White is 0 and black is 255.
|
||
(COLORMAPCREATE INTENSITIES BITSPERPIXEL) [Function]
|
||
creates a color map for a screen that has BITSPERPIXEL bits per pixel. If BITSPERPIXEL is NIL, the number of bits per pixel is taken from the current color display setting. INTENSITIES specifies the initial colors that should be in the map. If INTENSITIES is not NIL, it should be a list of color specifications other than color numbers, e.g., the list of RGB triples returned by the function INTENSITIESFROMCOLOR MAP.
|
||
(INTENSITIESFROMCOLORMAP COLORMAP) [Function]
|
||
returns a list of the intensity levels of COLORMAP (default is (SCREENCOLORMAP)) in a form accepted by COLORMAPCREATE. This list can be written on file and thus provides a way of saving color map specifications.
|
||
(COLORMAPCOPY COLORMAP BITSPERPIXEL) [Function]
|
||
returns a color map that contains the same color intensities as COLORMAP if COLORMAP is a color map. Otherwise, it returns a color map with default color values.
|
||
(MAPOFACOLOR PRIMARIES) [Function]
|
||
returns a color map that is different shades of one or more of the primary colors. For example, (MAPOFACOLOR '(RED GREEN BLUE)) gives a color map of different shades of gray; (MAPOFACOLOR 'RED) gives different shades of red.
|
||
Changing Color Maps
|
||
1
|
||
|
||
|
||
The following functions are provided to access and change the intensity levels in a color map.
|
||
(SETCOLORINTENSITY COLORMAP COLORNUMBER
|
||
COLORSPEC) [Function]
|
||
sets the primary intensities of color number COLORNUMBER in the color map COLORMAP to the ones specified by COLORSPEC. COLORSPEC can be either an RGB triple, an HLS triple, or a color name. The value returned is NIL.
|
||
(COLORLEVEL COLORMAP COLORNUMBER PRIMARY
|
||
NEWLEVEL) [Function]
|
||
sets and reads the intensity level of the primary color PRIMARY (RED, GREEN, or BLUE) for the color number COLORNUMBER in the color map COLORMAP. If NEWLEVEL is a number between 0 and 255, it is set. The previous value of the intensity of PRIMARY is returned.
|
||
(ADJUSTCOLORMAP PRIMARY DELTA COLORMAP) [Function]
|
||
adds DELTA to the intensity of the PRIMARY color value (RED, GREEN, or BLUE) for every color number in COLORMAP.
|
||
(ROTATECOLORMAP STARTCOLOR THRUCOLOR) [Function]
|
||
rotates a sequence of colors in the SCREENCOLORMAP. The rotation moves the intensity values of color number STARTCOLOR into color number STARTCOLOR+1, the intensity values of color number STARTCOLOR+1 into color number STARTCOLOR+2, etc., and THRUCOLOR's values into STARTCOLOR.
|
||
(EDITCOLORMAP VAR NOQFLG) [Function]
|
||
allows interactive editing of a color map. If VAR is an atom whose value is a color map, its value is edited. Otherwise a new color map is created and edited. The color map being edited is made the screen color map while the editing takes place so that its effects can be observed. The edited color map is returned as the value. If NOQFLG is NIL and the color display is on, you are asked if you want a test pattern of colors. A yes response causes the function SHOWCOLORTESTPATTERN to be called, which displays a test pattern with blocks of each of the possible colors.
|
||
You are prompted for the location of a color control window to be placed on the black-and-white display. This window allows the value of any of the colors to be changed. The number of the color being edited is in the upper left part of the window. Six bars are displayed. The right three bars give the color intensities for the three primary colors of the current color number. The left three bars give the value of the color's Hue, Lightness, and Saturation parameters. These levels can be changed by positioning the mouse cursor in one of the bars and pressing the left mouse button. While the left button is down, the value of that parameter tracks the Y position of the cursor. When the left button is released, the color tracking stops. The color being edited is changed by pressing the middle mouse button while the cursor is in the interior of the edit window. This brings up a menu of color numbers. Selecting one sets the current color to the selected color.
|
||
The color being edited can also be changed by selecting the menu item "PickPt." This switches the cursor onto the color screen and allows you to select a point from the color screen. It then edits the color of the selected point.
|
||
To stop the editing, move the cursor into the title of the editing window and press the middle button. This brings up a menu. Select Stop to quit.
|
||
2
|
||
|
||
Color Bitmaps
|
||
1
|
||
|
||
A color bitmap is actually a bitmap that has more than one bit per pixel. To test whether a bitmap is a color bitmap, the function BITSPERPIXEL can be used.
|
||
(BITSPERPIXEL BITMAP) [Function]
|
||
returns the bits per pixel of BITMAP; if this does not equal one, BITMAP is a color bitmap.
|
||
In multiple-bit-per-pixel bitmaps, the bits that represent a pixel are stored contiguously. BITMAPCREATE is passed a BITSPERPIXEL argument to create multiple-bit-per-pixel bitmaps.
|
||
(BITMAPCREATE WIDTH HEIGHT BITSPERPIXEL) [Function]
|
||
creates a color bitmap that is WIDTH pixels wide by HEIGHT pixels high allowing BITSPERPIXEL bits per pixel. Currently any value of BITSPERPIXEL except one, four, eight, or NIL (defaults to one) causes an error.
|
||
A four-bit-per-pixel color screen bitmap uses approximately 76K words of storage, and an eight-bit-per-pixel one uses approximately 153K words. There is only one such bitmap. The following function provides access to it.
|
||
(COLORSCREENBITMAP) [Function]
|
||
returns the bitmap that is being or will be displayed on the color display. This is NIL if the color display has never been turned on (see COLORDISPLAY below).
|
||
2
|
||
2
|
||
|
||
Screens, Screenpositions, and Screenregions
|
||
1
|
||
|
||
In addition to positions and regions, the user needs to be aware of screens, screenpositions, and screenregions in the presence of multiple screens.
|
||
Screens
|
||
1
|
||
|
||
SCREEN [Datatype]
|
||
There are generally two screen datatype instances in existence when working with color. This is because the user is attached to two displays, a black and white display and a color display.
|
||
(MAINSCREEN) [Function]
|
||
returns the screen datatype instance that represents the black and white screen. This will be something like {SCREEN}#74,24740.
|
||
(COLORSCREEN) [Function]
|
||
returns the screen datatype instance that represents the color screen. Screens appear as part of screenpositions and screenregions, serving as the extra information needed to make clear whether a particular position or region should be viewed as lying on the black and white display or the color display.
|
||
(SCREENBITMAP SCREEN) [Function]
|
||
returns the bitmap destination of SCREEN. If SCREEN=NIL, returns the black and white screen bitmap.
|
||
Screenpositions
|
||
1
|
||
|
||
SCREENPOSITION [Record]
|
||
Somewhat like a position, a screenposition denotes a point in an X,Y coordinate system on a particular screen. Screenpositions have been defined according to the following record declaration:
|
||
(RECORD SCREENPOSITION (SCREEN . POSITION)
|
||
(SUBRECORD POSITION))
|
||
A SCREENPOSITION is an instance of a record with fields XCOORD, YCOORD, and SCREEN and is manipulated with the standard record package facilities. For example, (create SCREENPOSITION XCOORD _ 10 YCOORD _ 20 SCREEN _ (COLORSCREEN)) creates a screenposition representing the point (10,20) on the color display. The user can extract the position of a screenposition by fetching its POSITION. For example, (fetch (SCREENPOSITION POSITION) of SP12).
|
||
Screenregions
|
||
1
|
||
|
||
SCREENREGION [Record]
|
||
Somewhat like a region, a screenregion denotes a rectangular area in a coordinate system. Screenregions have been defined according to the following record declaration:
|
||
(RECORD SCREENREGION (SCREEN . REGION)
|
||
(SUBRECORD REGION))
|
||
Screenregions are characterized by the coordinates of their bottom left corner and their width and height. A SCREENREGION is a record with fields LEFT, BOTTOM, WIDTH, HEIGHT, and SCREEN. It can be manipulated with the standard record package facilities. There are access functions for the REGION record that return the TOP and RIGHT of the region. The user can extract the region of a screenregion by fetching its REGION. For example, (fetch (SCREENREGION REGION) of SR8).
|
||
Screenposition and Screenregion Prompting
|
||
1
|
||
|
||
The following functions can be used by programs to allow the user to interactively specify screenpositions or screenregions on a display screen.
|
||
(GETSCREENPOSITION WINDOW CURSOR) [Function]
|
||
1
|
||
|
||
Similar to GETPOSITION. Returns a SCREENPOSITION that is specified by the user. GETSCREENPOSITION waits for the user to press and release the left button of the mouse and returns the cursor screenposition at the time of release. If WINDOW is a WINDOW, the screenposition will be on the same screen as WINDOW and in the coordinate system of WINDOW's display stream. If WINDOW is NIL, the position will be in screen coordinates.
|
||
1
|
||
|
||
(GETBOXSCREENPOSITION BOXWIDTH BOXHEIGHT ORGX ORGY WINDOW PROMPTMSG) [Function]
|
||
1
|
||
|
||
Similar to GETBOXPOSITION. Returns a SCREENPOSITION that is specified by the user. Allows the user to position a "ghost" region of size BOXWIDTH by BOXHEIGHT on a screen, and returns the SCREENPOSITION of the lower left corner of the screenregion chosen. A ghost region is locked to the cursor so that if the cursor is moved, the ghost region moves with it. The user can change to another corner by holding down the right button. With the right button down, the cursor can be moved across a screen or to other screens without effect on the ghost region frame. When the right button is released, the mouse will snap to the nearest corner, which will then become locked to the cursor. (The held corner can be changed after the left or middle button is down by holding both the original button and the right button down while the cursor is moved to the desired new corner, then letting up just the right button.) When the left or middle button is pressed and released, the lower left corner of the screenregion chosen at the time of release is returned. If WINDOW is a WINDOW, the screenposition will be on the same screen as WINDOW and in the coordinate system of WINDOW's display stream. If WINDOW is NIL, the position will be in screen coordinates.its lower left corner in screen coordinates.
|
||
1
|
||
|
||
(GETSCREENREGION MINWIDTH MINHEIGHT OLDREGION NEWREGIONFN NEWREGIONFNARG INITCORNERS) [Function]
|
||
1
|
||
|
||
Similar to GETREGION. Returns a SCREENREGION that is specified by the user. Lets the user specify a new screenregion and returns that screenregion. GETSCREENREGION prompts for a screenregion by displaying a four-pronged box next to the cursor arrow at one corner of a "ghost" region: |