{comment this file contains the first part of the display chapter, with sections on:
POSITION
REGION
BITMAP
BITBLT
TEXTURE
Saving BITMAPs
Screen Operation
Characters and Fonts
}
{Begin SubSec POSITION}
{Title POSITION}
{Text
A position denotes a point in an X,Y coordinate system. A {lisp POSITION} is an instance of a record with fields {lisp XCOORD} and {lisp YCOORD} and is manipulated with the standard record package facilities. For example, {lisp (create POSITION XCOORD ← 10 YCOORD ← 20)} creates a position representing the point (10,20).
{FnDef {Name POSITIONP} {Args X}
{Text
Returns {arg X} if {arg X} is a {lisp POSITION}; {lisp NIL} otherwise.
}}
}{End SubSec POSITION}
{Begin SubSec REGION}
{Title REGION}
{Text
A Region denotes a rectangular area in a coordinate system. Regions are characterized by the coordinates of their bottom left corner and their width and height. A {lisp REGION} is a record with fields {lisp LEFT}, {lisp BOTTOM}, {lisp WIDTH}, and {lisp HEIGHT}. It can be manipulated with the standard record package facilities. There are access functions for the {lisp REGION} record that returns the {lisp TOP} and {lisp RIGHT} of the region.
The following functions are provided for manipulating regions:
{FnDef {Name CREATEREGION} {Args LEFT BOTTOM WIDTH HEIGHT}
{Text
Returns an instance of the {lisp REGION} record which has {arg LEFT}, {arg BOTTOM}, {arg WIDTH} and {arg HEIGHT} as respectively its {lisp LEFT}, {lisp BOTTOM}, {lisp WIDTH}, and {lisp HEIGHT}.
Example: {lisp (CREATEREGION 10 -20 100 200)} will create a region that denotes a rectangle whose width is 100, whose height is 200, and whose lower left corner is (10,-20).
}}
{FnDef {Name REGIONP} {Args X}
{Text
Returns {arg X} if {arg X} is a region, {lisp NIL} otherwise.
}}
{FnDef {Name INTERSECTREGIONS}
{Args REGION{sub 1} REGION{sub 2} {ellipsis} REGION{sub n}}
{Type nospread}
{Text
Returns a region which is the intersection of a number of regions. Returns {lisp NIL} if the intersection is empty. If there are no regions given, it returns a very large region.
}}
{FnDef {Name UNIONREGIONS}
{Args REGION{sub 1} REGION{sub 2} {ellipsis} REGION{sub n}}
{Type nospread}
{Text
Returns a region which is the union of a number of regions, i.e. the smallest region that contains all of them. Returns {lisp NIL} if there are no regions given.
}}
{FnDef {Name REGIONSINTERSECTP} {Args REGION1 REGION2}
{Text
Returns {lisp T} if {arg REGION1} intersects {arg REGION2}. Returns {lisp NIL} if they do not intersect.
}}
{FnDef {Name SUBREGIONP} {Args LARGEREGION SMALLREGION}
{Text
Returns {lisp T} if {arg SMALLREGION} is a subregion (is equal to or entirely contained in) {arg LARGEREGION}; otherwise
returns {lisp NIL}.
}}
{FnDef {Name EXTENDREGION} {Args REGION INCLUDEREGION}
{Text
Changes (destructively modifies) the region {arg REGION} so that it includes the region {arg INCLUDEREGION}. It returns {arg REGION}.
}}
{FnDef {Name MAKEWITHINREGION} {Args REGION LIMITREGION}
{Text
Changes (destructively modifies) the left and bottom of the region {arg REGION} so that it is within the region {arg LIMITREGION}, if possible. If the dimension of {arg REGION} are larger than {arg LIMITREGION}, {arg REGION} is moved to the lower left of {arg LIMITREGION}. If {arg LIMITREGION} is {lisp NIL}, the value of the variable {var WHOLEDISPLAY} (the screen region) is used. {fn MAKEWITHINREGION} returns {arg REGION}.
}}
{FnDef {Name INSIDEP} {Args REGION X Y}
{Text
If {arg X} and {arg Y} are numbers, it returns {lisp T} if the point ({arg X},{arg Y}) is inside of {arg REGION}. If {arg X} is a {lisp POSITION}, it returns {lisp T} if {arg X} is inside of {arg REGION}. If {arg REGION} is a {lisp WINDOW}, the window's interior region in window coordinates is used. Otherwise, it returns {lisp NIL}.
}}
}{End SubSec REGION}
{Begin SubSec BITMAP}
{Title BITMAP}
{Text
The display primitives manipulate graphical images in the form of {term bitmaps}. A bitmap is a rectangular array of "pixels," each of which is an integer representing the color of one point in the bitmap image. A bitmap is created with a specific number of bits allocated for each pixel. Most bitmaps used for the display screen use one bit per pixel, so that at most two colors can be represented. If a pixel is 0, the corresponding location on the image is white. If a pixel is 1, its location is black. (This interpretation can be changed with the function {fn VIDEOCOLOR}; see {PageRef Fn VIDEOCOLOR}.) Bitmaps with more than one bit per pixel are used to represent color or grey scale images.
Bitmaps use a positive integer coordinate system with the lower left corner pixel at coordinate (0,0). Bitmaps are represented as instances of the datatype {lisp BITMAP} with fields {lisp BITMAPWIDTH}, {lisp BITMAPHEIGHT}, {lisp BITMAPBITSPERPIXEL}, {lisp BITMAPRASTERWIDTH}, and {lisp BITMAPBASE}. Only the width, height, and bits per pixel fields are of interest to the user, and can be accessed with the following functions:
{note do we need to tell about what fields are in bitmaps??}
{FnDef {Name BITMAPWIDTH} {Args BITMAP}
{Text
Returns the width of {arg BITMAP} in pixels.
}}
{FnDef {Name BITMAPHEIGHT} {Args BITMAP}
{Text
Returns the height of {arg BITMAP} in pixels.
}}
{FnDef {Name BITSPERPIXEL} {Args BITMAP}
{Text
Returns the number of bits per pixel of {arg BITMAP}.
}}
The functions used to manipulate bitmaps are:
{FnDef {Name BITMAPCREATE} {Args WIDTH HEIGHT BITSPERPIXEL}
{Text
Creates and returns a new bitmap which is {arg WIDTH} pixels wide by {arg HEIGHT} pixels high, with {arg BITSPERPIXEL} pits per pixel. If {arg BITSPERPIXEL} is {lisp NIL}, the default is 1.
}}
{FnDef {Name BITMAPBIT} {Args BITMAP X Y NEWVALUE}
{Text
If {arg NEWVALUE} is between 0 and the maximum value for a pixel in {arg BITMAP}, the pixel ({arg X,Y}) is changed to {arg NEWVALUE} and the old value is returned. If {arg NEWVALUE} is {lisp NIL}, {arg BITMAP} is not changed but the value of the pixel is returned. If {arg NEWVALUE} is anything else, an error is generated. If ({arg X,Y}) is outside the limits of {arg BITMAP}, 0 is returned and no pixels are changed. {arg BITMAP} can also be a window.
}}
{FnDef {Name BITMAPCOPY} {Args BITMAP}
{Text
Returns a new bitmap which is a copy of {arg BITMAP} (same dimensions and contents).
}}
{FnDef {Name EXPANDBITMAP} {Args BITMAP WIDTHFACTOR HEIGHTFACTOR}
{Text
Returns a new bitmap that is {arg WIDTHFACTOR} times as wide as {arg BITMAP} and {arg HEIGHTFACTOR} times as high. Each pixel of {arg BITMAP} is copied into a {arg WIDTHFACTOR} times {arg HEIGHTFACTOR} block of pixels. If {lisp NIL}, {arg WIDTHFACTOR} defaults to 4, {arg HEIGHTFACTOR} to 1.
{note WIDTHFACTOR defaults to 4, HEIGHTFACTOR to 1.
this is so that this could be used to translate 1 bitperpixel bitmaps to 4 bitperpixel color bitmaps. However, we don't want to do this, because this relies on knowing that bitmaps are stored width-first. For now, perhaps this should be done by allocating a new array, and doing a BITBLT.}
{note Q: I assume that the new bitmap returned by expand macro has the same bitsperpixel??}
}}
{FnDef {Name SHRINKBITMAP} {Args BITMAP WIDTHFACTOR HEIGHTFACTOR DESTINATIONBITMAP}
{Text
Returns a copy of {arg BITMAP} that has been shrunken by {arg WIDTHFACTOR} and {arg HEIGHTFACTOR} in the width and height, respectively. If {lisp NIL}, {arg WIDTHFACTOR} defaults to 4, {arg HEIGHTFACTOR} to 1. If {arg DESTINATIONBITMAP} is not provided, a bitmap that is 1/{arg WIDTHFACTOR} by 1/{arg HEIGHTFACTOR} the size of {arg BITMAP} is created and returned. {arg WIDTHFACTOR} and {arg HEIGHTFACTOR} must be positive integers.
}}
There are two distinguished bitmaps that are read by the hardware to become visible as the screen and the cursor. The screen is a bitmap {lisp SCREENWIDTH} (=1024) wide by {lisp SCREENHEIGHT} (=808) high. The cursor is a bitmap {lisp CURSORWIDTH} (=16) wide by {lisp CURSORHEIGHT} (=16) high. They are accessed by:
{FnDef {Name SCREENBITMAP}
{Text
Returns the screen bitmap.
}}
{FnDef {Name CURSORBITMAP}
{Text
Returns the cursor bitmap.
Note: The cursor bitmap can be changed with the function {fn CURSOR} ({PageRef Fn CURSOR}).
}}
}{End SubSec BITMAP}
{Begin SubSec BITBLT}
{Title BITBLT}
{Text
{fn BITBLT} is the primitive function for moving bits from one bitmap to another. It is similar to the function {lisp RASTEROP}{index RASTEROP Fn} that is used in other systems.
{FnDef {Name BITBLT} {Args SOURCE SOURCELEFT SOURCEBOTTOM
DESTINATION DESTINATIONLEFT DESTINATIONBOTTOM WIDTH HEIGHT SOURCETYPE OPERATION TEXTURE CLIPPINGREGION}
{Text}}
{arg WIDTH} and {arg HEIGHT} define a pair of rectangles, one in each of the {arg SOURCE} and {arg DESTINATION} whose left, bottom corners are at, respectively, ({arg SOURCELEFT}, {arg SOURCEBOTTOM}) and ({arg DESTINATIONLEFT}, {arg DESTINATIONBOTTOM}). If these rectangles overlap the boundaries of either source or destination they are both reduced in size (without translation) so that they fit within their respective boundaries. If {arg CLIPPINGREGION} is non-{lisp NIL} it should be a {lisp REGION} and is interpreted as a clipping region within {arg DESTINATION}; clipping to this region may further reduce the defining rectangles. These (possibly reduced) rectangles define the source and destination rectangles for {fn BITBLT}. {arg SOURCE} can be a display stream or window, in which case its associated bitmap is used. {arg DESTINATION} can be a bitmap or arbitrary imagestream.
The mode of transferring bits is defined by {arg SOURCETYPE} and {arg OPERATION}. {arg SOURCETYPE} and {arg OPERATION} specify boolean functions that are used to determine, respectively, the method of combining {arg SOURCE} bits with the {arg TEXTURE} and the operation between these resultant bits and {arg DESTINATION}. {arg TEXTURE} is a gray pattern, as described on {PageRef Tag Textures}. (Note: The alignment of the texture pattern with {fn BITBLT} is such that the origin of the destination bitmap is at an intersection of the "tiles.")
{arg SOURCETYPE} specifies how to combine the bits from {arg SOURCE} with the bits from {arg TEXTURE} (a background pattern) to produce a "Source". This is designed to allow characters and figures to be placed on a background.
{index SOURCETYPE (BITBLT argument)}
{Begin Table Sourcetype specifies}
{COLUMN 25percent} {COLUMN}
{First {arg SOURCETYPE}} {Next Source}
{First {lisp INPUT}} {Next {arg SOURCE}}
{First {lisp INVERT}} {Next {lisp (NOT {arg SOURCE})}}
{First {lisp TEXTURE}} {Next {arg TEXTURE}}
{End Table Sourcetype specifies}
For the {lisp INPUT} and {lisp INVERT} case, the {arg TEXTURE}
argument to {fn BITBLT} is ignored. For the {lisp TEXTURE} case,
the {arg SOURCE}, {arg SOURCELEFT}, and {arg SOURCEBOTTOM}
arguments are ignored.
{arg OPERATION} specifies how this source is combined with the bits in {arg DESTINATION} and stored back into {arg DESTINATION}.
{index OPERATION (BITBLT argument)}
{Begin Table Operation specifies}
{COLUMN 25percent} {COLUMN}
{First {arg OPERATION}} {Next {arg DESTINATION} becomes}
{First {lisp REPLACE}} {Next Source}
{First {lisp PAINT}} {Next {lisp (OR {arg DESTINATION}} Source{lisp )}}
{First {lisp INVERT}} {Next {lisp (XOR {arg DESTINATION}} Source{lisp )}}
{First {lisp ERASE}} {Next {lisp (AND {arg DESTINATION} (NOT} Source{lisp ))}}
{End Table Operation specifies}
{arg SOURCELEFT}, {arg SOURCEBOTTOM}, {arg DESTINATIONLEFT}, and {arg DESTINATIONBOTTOM} default to 0. {arg WIDTH} and {arg HEIGHT} default to the width and height of the {arg SOURCE}.
{arg TEXTURE} defaults to white. {arg SOURCETYPE} defaults to {lisp INPUT}. {arg OPERATION} defaults to {lisp REPLACE}.
If {arg CLIPPINGREGION} is not provided, no additional clipping is done.
{fn BITBLT} returns {lisp T} if any bits were moved;{note ???}
{lisp NIL} otherwise.
Note: {fn BITBLT} and {fn BITMAPBIT} accept windows and display streams as their bitmap arguments. In these cases, the remaining arguments are interpreted as values in the coordinate system of the window or display stream and the operation of the functions are translated and clipped accordingly. If a window or imagestream is used as the destination to {fn BITBLT}, its clipping region limits the operation involved.
{note no longer true ==>
However, if a display stream is used as the source to {fn BITBLT}, its clipping region does not limit the bits transferred.}
{FnDef {Name BLTSHADE} {Args TEXTURE DESTINATION DESTINATIONLEFT DESTINATIONBOTTOM WIDTH HEIGHT OPERATION CLIPPINGREGION}
{Text
{fn BLTSHADE} is the {arg SOURCETYPE} = {lisp TEXTURE} case of {fn BITBLT}. It fills the specified region of the destination bitmap {arg DESTINATION} with the shade {arg TEXTURE}. {arg DESTINATION} can be a bitmap or image stream.
}}
{FnDef {Name BITMAPIMAGESIZE} {Args BITMAP DIMENSION STREAM}
{Text
Returns the size that {arg BITMAP} will be when {fn BITBLT}ed to {arg STREAM}, in {arg STREAM}'s units. {arg DIMENSION} can be one of {lisp WIDTH}, {lisp HEIGHT}, or {lisp NIL}, in which case the dotted pair {lisp ({arg WIDTH} . {arg HEIGHT})} will be returned.
}}
{FnDef {Name DRAWPOINT} {Args X Y BRUSH STREAM}
{Text
Draws {Arg BRUSH} entered around point ({Arg X}, {Arg Y}) on {Arg STREAM}. {Arg BRUSH} may be a bitmap or a brush (see {PageRef Term brush}).
}}
{note EXAMPLES, WITH PICTURES!! -- lmm}
}{End SubSec BITBLT}
{Begin SubSec TEXTURE}
{Title TEXTURE}
{Text
{index Textures}
{Tag Textures}
A Texture denotes a pattern of gray which can be used by {fn BITBLT} to (conceptually) tessellate the plane to form an infinite sheet of gray. It is currently either a 4 by 4 pattern or a 16 by n (n <= 16) pattern. Textures are created interactively using the function {fn EDITSHADE} ({PageRef Fn EDITSHADE}) or from bitmaps using the following function:
{FnDef {Name CREATETEXTUREFROMBITMAP} {Args BITMAP}
{Text
Returns a texture object that will produce the texture of {arg BITMAP}. If {arg BITMAP} is too large, its lower left portion is used. If {arg BITMAP} is too small, it is repeated to fill out the texture.
}}
{FnDef {Name TEXTUREP} {Args OBJECT}
{Text
Returns {arg OBJECT} if it is a texture, i.e. a legal texture argument to {fn BITBLT}.
}}
The functions which accept textures ({fn TEXTUREP}, {fn BITBLT}, {fn DSPTEXTURE}, etc.) also accept bitmaps up to 16 bits wide by 16 bits high as textures. When a region is being filled with a bitmap texture, the texture is treated as if it were 16 bits wide (if less, the rest is filled with white space).
The common textures white and black are available as system constants {var WHITESHADE}{index WHITESHADE Var} and {var BLACKSHADE}.{index BLACKSHADE Var} The global variable {var GRAYSHADE}{index GRAYSHADE Var} is used by many system facilities as a background gray shade and can be set by the user. The original background shade of the window system is kept in {var WINDOWBACKGROUNDSHADE}.{index WINDOWBACKGROUNDSHADE Var}{index background shade} The background shade can be changed by the following function:
{FnDef {Name CHANGEBACKGROUND} {Args SHADE}
{Text
Changes the background shade of the window system. {arg SHADE} determines the pattern of the background. If {arg SHADE} is a texture, then the background is simply painted with it. If {arg SHADE} is a {lisp BITMAP}, the background is tesselated (tiled) with it to cover the screen. If {arg SHADE} is {lisp T}, it changes to the original shade, the value of {var WINDOWBACKGROUNDSHADE}. It returns the previous value of the background.
}}
{FnDef {Name CHANGEBACKGROUNDBORDER} {Args SHADE}
{Text
On the Xerox 1108, changes the shade of the border of the display to {arg SHADE}, which should be a texture. It returns the previous texture of the background border. {fn CHANGEBACKGROUNDBORDER} is a no-op on the Xerox 1132.
}}
{Begin Note}
Textures can be (and TEXTUREP is true of) BITMAPs of 16 bits wide by up to 16 bits high. 4x4 textures can still be represented as integers.
{End Note}
}{End SubSec TEXTURE}
{Begin SubSec Saving BITMAPs}
{Title Saving BITMAPs}
{Text
Bitmaps can be saved on files with the {filecom VARS} file package command ({PageRef FileCom VARS}). The following two functions translate bitmaps into and out of a representation which may be used to transfer bitmaps between Interlisp and other computer systems' representations.
{FnDef {Name READBITMAP} {Args FILE}
{Text
Creates a bitmap by reading an expression (written by {fn PRINTBITMAP}) from the file {arg FILE}.
}}
{FnDef {Name PRINTBITMAP} {Args BITMAP FILE}
{Text
Prints the bitmap {arg BITMAP} on the file {arg FILE} in a format that can be read back in by {fn READBITMAP}.
{note (If {arg BITMAP} is an atom whose value is a bitmap, its value will be used.) -- crock, sez Larry}
}}
}{End SubSec Saving BITMAPs}
{Begin SubSec Screen Operation}
{Title Screen Operation}
{Text
The following functions control the display screen.
{FnDef {Name VIDEOCOLOR} {Args BLACKFLG}
{Type NOSPREAD}
{Text
Sets the interpretation of the bits in the screen bitmap. If {arg BLACKFLG} is {lisp NIL}, a 0 bit will be displayed as white, otherwise a 0 bit will be displayed as black. {fn VIDEOCOLOR} returns the previous setting. If {arg BLACKFLG} is not given, {fn VIDEOCOLOR} will return the current setting without changing anything.
Note: This function only works on the Xerox 1100 and Xerox 1108.
}}
{FnDef {Name VIDEORATE} {Args TYPE}
{Text
Sets the rate at which the screen is refreshed. {arg TYPE} is one of {lisp NORMAL} or {lisp TAPE}. If {arg TYPE} is {lisp TAPE}, the screen will be refreshed at the same rate as TV (60 cycles per second). This makes the picture look better when video taping the screen. Note: Changing the rate may change the dimensions of the display on the picture tube.
}}
Several functions are provided for turning off the display (partially or completely). See {PageRef Fn SETDISPLAYHEIGHT}.
}{End SubSec Screen Operation}