Chapter 2 Viewport Graphics The viewport graphics library is a relatively simple toolbox of graphics commands.

The library is not very powerful; it is intended as a simplified alternative to Mr d!s full graphical toolbox. The graphics library originated as "#$lib% a library of $ &indows commands available within Che' "cheme at (ice )niversity. The functionality of that library has been reproduced *with bac+ward compatibility, in this version. To use the viewport graphics library in a -.T language% load it via re/uire0 *re/uire *lib 1graphics.ss1 1graphics1,, which loads the graphics.ss library from the graphics collection. 2ll of the names defined in this chapter will then be available. 2.3 4asic Commands 5 *open6graphics, #nitiali'es the library!s graphics routines. #t must be called before any other graphics operations. 5 *close6graphics, Closes all of the windows and until open6graphics is called again% no graphics routines will wor+. 5 *open6viewport name hori' vert, Ta+es a string name and integers hori' and vert and creates a new window called name. The window is hori' pixels wide and vert pixels high. 7or bac+ward compatibility% a single posn value *see below, can be submitted in the place of hori' and vert. open6 viewport returns a viewport descriptor. 5 *open6pixmap name hori' vert, .i+e open6viewport% but the resulting viewport is not displayed on the screen. 8ffscreen pixmaps are useful for executing a se/uence of drawing commands and displaying them all at once with copy6viewport. 8ffscreen pixmaps are also useful in con9unction with viewport6:snip *see below,. This allows functions to compute with graphical ob9ects and view the graphics when results are returned to the interactions window. 5 *close6viewport viewport, Ta+es a viewport descriptor. #t removes the viewport from the screen and ma+es subse/uent operations dealing with the viewport illegal. 2.2 -osition 8perations

2 position is a pixel location within a viewport. The upper6left corner is pixel *;% ;, and the orientation of the position coordinates within a viewport is as follows0 . 5 *ma+e6posn x y, Ta+es two integers and returns a position with the specified x and y coordinates. 5 *posn6x p,% *posn6y p, (eturn the x and y coordinates% respectively% of a position. 5 *posn< v, (eports whether v is a position. 5 **get6pixel viewport, p, (eturns the color of the pixel at position p in viewport; ; denotes white and 3 denotes not white. 5 **get6color6pixel viewport, p, (eturns an (G4 value for color of the pixel at position p in viewport. 5 **test6pixel viewport, color, (eturns the color that will actually be used if color is used to draw. 2.= Color 8perations 2 color can be represented in three ways0 as a color index *an integer in ; to 2>>% inclusive,% as a color name string% or as a rgb value. 2ll drawing functions which ta+e a color argument accept colors in any form. 2n rgb value is assigned to an index with change6color. 5 *ma+e6rgb red green blue, Ta+es three values in the range ; *dar+, to 3 *bright, and returns an rgb *a color,. 5 *rgb6red color, *rgb6blue color, *rgb6green color, (eturn the red% green% and blue components% respectively% of a color. 5 *rgb< v, (eports whether v is a color. 5 *change6color index rgb, Changes the color at index in the color table to the color specified in rgb. 8nly the first twenty6one indices are initiali'ed; a color index should not be used until it has been initiali'ed. 5 *default6display6is6color<, (eturns ?t if the default display screen for viewports is in color or ?f otherwise.

2.@ Araw% Clear and 7lip 8perations These are the basic graphics operations for drawing to a viewport. ach function ta+es a viewport as its argument and returns a function operating within that viewport. 7urther arguments% if any% are curried. 7or example% *draw6line viewport, returns a function% that can then be applied to the proper arguments to draw a line in the viewport corresponding to viewport descriptor viewport. 2n example follows. &here BBdraw6!! commands ma+e pixels blac+% BBclear6!! commands ma+e them white. &here BBdraw6!! commands ma+e pixels blac+% a BBflip6!! commands cause them to change. 2.@.3 Viewports 5 **draw6viewport viewport, color, Ta+es a viewport descriptor. #t returns a function that colors the entire contents of viewport. The optional color argument defaults to blac+. 5 **clear6viewport viewport,, Ta+es a viewport descriptor. #t returns a function that whitens the entire contents of viewport. 5 **flip6viewport viewport,, Ta+es a viewport descriptor. #t returns a function that flips the contents of viewport. 5 *copy6viewport source6viewport destination6viewport, Ta+es two viewport descriptors. #t copies the source6viewport into the destination6 viewport. 2.@.2 -ixels 5 **draw6pixel viewport, p color, Ta+es a viewport descriptor. #t returns a function that draws a pixel in viewport at the specified position. The optional color argument defaults to blac+. 5 **clear6pixel viewport, p, Ta+es a viewport descriptor. #t returns a function that clears a pixel in viewport at the specified position. 5 **flip6pixel viewport, p, Ta+es a viewport descriptor. #t returns a function that flips a pixel in viewport at the specified position. 2.@.= .ines 5 **draw6line viewport, p3 p2 color, Ta+es a viewport descriptor. #t returns a function that draws a line in the viewport connecting positions p3 and p2. The optional color argument defaults to blac+.

5 **clear6line viewport, p3 p2, Ta+es a viewport descriptor. #t returns a function that clears a line in viewport connecting positions p3 and p2. 5 **flip6line viewport, p3 p2, Ta+es a viewport descriptor. #t returns a function that flips a line in viewport connecting positions p3 and p2. 2.@.@ (ectangles 5 **draw6rectangle viewport, posn width height color, Ta+es a viewport descriptor. #t returns a function that draws a rectangle border in the viewport with the top6left of the rectangle at the position posn and with sides width across and height tall. The optional color argument defaults to blac+. 5 **clear6rectangle viewport, posn width height, Ta+es a viewport descriptor. #t returns a function that clears a rectangle border in the viewport with the top6left of the rectangle at the position posn and with sides width across and height tall. The optional color argument defaults to blac+. 5 **flip6rectangle viewport, posn width height color, Ta+es a viewport descriptor. #t returns a function that flips a rectangle border in the viewport with the top6left of the rectangle at the position posn and with sides width across and height tall. The optional color argument defaults to blac+. 5 **draw6solid6rectangle viewport, posn width height color, Ta+es a viewport descriptor. #t returns a function that paints a solid rectangle in the viewport with the top6left of the rectangle at the position posn and with sides width across and height tall. The optional color argument defaults to blac+. 5 **clear6solid6rectangle viewport, posn width height, Ta+es a viewport descriptor. #t returns a function that erases a solid rectangle in the viewport with the top6left of the rectangle at the position posn and with sides width across and height tall. The optional color argument defaults to blac+. 5 **flip6solid6rectangle viewport, posn width height color, Ta+es a viewport descriptor. #t returns a function that flips a solid rectangle in the viewport with the top6left of the rectangle at the position posn and with sides width across and height tall. The optional color argument defaults to blac+. 2.@.C llipses

5 **draw6ellipse viewport, posn width height color, Ta+es a viewport descriptor. #t returns a function that draws an ellipse border in the viewport. The posn% width% and height arguments are as in draw6rectangle; the ellipse is inscribed within the specified rectangle. The optional color argument defaults to blac+. 5 **clear6ellipse viewport, posn width height,

Ta+es a viewport descriptor. #t returns a function that clears an ellipse border in the viewport. The posn% width% and height arguments are as in clear6rectangle; the ellipse is inscribed within the specified rectangle. The optional color argument defaults to blac+. 5 **flip6ellipse viewport, posn width height color, Ta+es a viewport descriptor. #t returns a function that flips an ellipse border in the viewport. The posn% width% and height arguments are as in flip6rectangle; the ellipse is inscribed within the specified rectangle. The optional color argument defaults to blac+. 5 **draw6solid6ellipse viewport, posn width height color, Ta+es a viewport descriptor. #t returns a function that paints a solid ellipse in the viewport. The posn% width% and height arguments are as in draw6rectangle; the ellipse is inscribed within the specified rectangle. The optional color argument defaults to blac+. 5 **clear6solid6ellipse viewport, posn width height, Ta+es a viewport descriptor. #t returns a function that erases a solid ellipse in the viewport. The posn% width% and height arguments are as in clear6rectangle; the ellipse is inscribed within the specified rectangle. The optional color argument defaults to blac+. 5 **flip6solid6ellipse viewport, posn width height color, Ta+es a viewport descriptor. #t returns a function that flips a solid ellipse in the viewport. The posn% width% and height arguments are as in flip6rectangle; the ellipse is be inscribed within the specified rectangle. The optional color argument defaults to blac+. 2.@.D -olygons 5 **draw6polygon viewport, posn6list posn color, Ta+es a viewport descriptor. #t returns a function that draws a polygon border in the viewport using posn6list for the polygon vertices and posn as an offset for the polygon. The optional color argument defaults to blac+. 5 **clear6polygon viewport, posn6list posn, Ta+es a viewport descriptor. #t returns a function that erases a polygon border in the viewport using posn6list for the polygon vertices and posn as an offset for the polygon. 5 **flip6polygon viewport, posn6list posn, Ta+es a viewport descriptor. #t returns a function that flips a polygon border in the viewport using posn6list for the polygon vertices and posn as an offset for the polygon. 5 **draw6solid6polygon viewport, posn6list posn color, Ta+es a viewport descriptor. #t returns a function that paints a solid polygon in the viewport using posn6list for the polygon vertices and posn as an offset for the polygon. The optional color argument defaults to blac+. 5 **clear6solid6polygon viewport, posn6list posn, Ta+es a viewport descriptor. #t returns a function that erases a solid polygon in the viewport using posn6list for the polygon vertices and posn as an offset for the polygon. 5 **flip6solid6polygon viewport, posn6list posn,

Ta+es a viewport descriptor. #t returns a function that flips a solid polygon in the viewport using posn6list for the polygon vertices and posn as an offset for the polygon. 2.@.E "trings 5 **draw6string viewport, p string color, Ta+es a viewport descriptor. #t returns a function that draws a string at a specified location in the viewport. The lower left of the string begins at p. The optional color argument defaults to blac+. 5 **clear6string viewport, p string, Ta+es a viewport descriptor. #t returns a function that clears a string at a specified location in viewport. The lower left of the string begins at p. 5 **flip6string viewport, p string, Ta+es a viewport descriptor. #t returns a function that flips a string at a specified location in viewport. The lower left of the string begins at p. 2.@.F -ixmaps 5 ***draw6pixmap6posn filename type, viewport, posn color, Araws a pixmap into viewport with its upper left corner at position posn. The type is an optional symbol% one of !gif% !gifGmas+% !xbm% !xpm% !bmp% !pict% !un+nown% or !un+nownGmas+% and defaults to !un+nownGmas+. #f type is !un+nown or !un+nownGmas+% then the content of the file is examined to determine the type. 2ll formats are supported on all platforms% except !pict which is only supported under Mac 8" $. The !gifGmas+ and !un+nownGmas+ types draw the bitmap with a transparent bac+ground if filename refers to a G#7 file with a transparent bac+ground. The argument color is only used when the pixmap is blac+ and white. #n that case% the color is used instead of blac+ in the drawn image. 5 **draw6pixmap viewport, filename p color, Araws a pixmap into viewport w with its upper left corner at position p. #f color is not ?f it is passed to set6viewport6pen with the viewport. #t defaults to ?f. 5 **save6pixmap viewport, filename type, "aves the current content of viewport to filename. The type is an optional symbol% one of !xbm% !xpm% !bmp *&indows only,% or !pict *Mac 8" $ only,; the default is !xpm. 2.C Miscellaneous 8perations 5 **get6string6si'e viewport, string, Ta+es a viewport descriptor. #t returns a function that returns the si'e of a string as a list of two numbers0 the width and height. 5 *viewport6:snip viewport,

Ta+es a viewport descriptor. #t returns an ob9ect that can be inserted into an editor buffer to display the current image in the viewport. *"ubse/uent drawing to the viewport does not affect the snip!s image., &hen snips are the results of computations in the interactions window% Ar"cheme will print show the contents of the viewport% right in the interactions window. 5 *viewport6dc viewport, Ta+es a viewport descriptor. #t returns an ob9ect that can be used with the primitive Mr d toolbox functions to draw into the viewport!s on6screen representation *if any,. Mirror all such drawing to the result of *viewport6offscreen6dc viewport,% too. 5 *viewport6offscreen6dc viewport, Ta+es a viewport descriptor. #t returns an ob9ect that can be used with the primitive Mr d toolbox functions to draw into the viewport!s off6screen representation. Mirror all such drawing to the result of *viewport6dc viewport,% too. 2.D 2n xample *open6graphics, ;; nothing appears to happen% but the library is initiali'ed... *define w *open6viewport 1practice1 =;; =;;,, ;; viewport appears **draw6line w, *ma+e6posn =; =;, *ma+e6posn 3;; 3;;,, ;; line appears *close6viewport w, ;; viewport disappears *close6graphics, ;; again% nothing appears to happen% but ;; unclosed viewports *if any, would disappear 2.E 2 More Complicated xample The use of multiple viewports% viewport descriptors% drawing operations for multiple viewports is as easy as the use of a single viewport0 *open6graphics, *let5 *;; w3 and w2 are viewport descriptors for different windows Hw3 *open6viewport 1viewport 31 =;; =;;,I Hw2 *open6viewport 1viewport 21 2;; C;;,I ;; d3 and d2 are functions that draw lines in different viewports Hd3 *draw6line w3,I Hd2 *draw6line w2,I, ;; draws a line in viewport labeled 1viewport 31 *d3 *ma+e6posn 3;; C, *ma+e6posn C 3;;,, ;; draws a line in viewport labeled 1viewport 21

*d2 *ma+e6posn 3;; 3;;, *ma+e6posn 3;3 @;;,,, ;; we no longer have access to viewports 3 and 2% ;; since their descriptors did not escape the let *close6graphics, ;; removes the viewports 2.F -rotecting Graphics 8perations To guarantee the proper closing of viewports in cases of errors% especially when a program manages several viewports simultaneously% a programmer should use dynamic6 wind0 *let *Hw *open6viewport 1hello1 3;; 3;;,I, *dynamic6wind ;; what we want to happen first0 nothing void ;; the main program *errors constrained to this piece, *lambda *, *draw6pixel 3=,, ; an error ;; what we would li+e to happen% whether the main program finishes ;; normally or not *lambda *, *close6viewport w,,,, 2.> Mouse 8perations The graphics library contains functions that determine where the mouse is% if there are any clic+s% etc. The functions get6mouse6clic+ and ready6mouse6clic+ first return a BBmouse6clic+ descriptor%!! and then other functions ta+e the descriptor and return the mouse!s position% which button was pushed% etc. Mouse clic+s are buffered and returned in the same order in which they occurred. Thus% the descriptors returned by get6mouse6 clic+ and ready6mouse6clic+ may be from clic+s that occurred long before these functions were called. 5 *get6mouse6clic+ viewport, Ta+es a viewport descriptor and returns a mouse clic+ descriptor. #t returns the next mouse clic+ in the viewport% waiting for a clic+ if necessary. 5 *ready6mouse6clic+ viewport, Ta+es a viewport descriptor and returns either a mouse clic+ descriptor% or else ?f if none is available. )nli+e the previous function% ready6mouse6clic+ returns immediately. 5 *ready6mouse6release viewport, Ta+es a viewport descriptor and returns either a clic+ descriptor from a mouse6release *button6up, event% or else ?f if none is available. 5 */uery6mouse6posn viewport, Ta+es a viewport descriptor and returns either the position of the mouse cursor within the viewport% or else ?f if the cursor is currently outside the viewport. 5 *mouse6clic+6posn mouse6clic+,

Ta+es a mouse clic+ descriptor and returns the position of the pixel where the clic+ occurred. 5 *left6mouse6clic+< mouse6clic+, Ta+es a mouse clic+ descriptor and returns ?t if the clic+ occurred with the left mouse button% or else ?f. 5 *middle6mouse6clic+< mouse6clic+, "imilar to left6mouse6clic+<. 5 *right6mouse6clic+< mouse6clic+, "imilar to left6mouse6clic+<. 2.3; Jeyboard 8perations The graphics library contains functions that report +ey presses from the +eyboard. The functions get6+ey6press and ready6+ey6press return a BB+ey6press descriptor%!! and then +ey6value ta+es the descriptor and returns a character or symbol *usually a character, representing the +ey that was pressed. Jey presses are buffered and returned in the same order in which they occurred. Thus% the descriptors returned by get6+ey6press and ready6 +ey6press may be from presses that occurred long before these functions were called. 5 *get6+ey6press viewport, Ta+es a viewport descriptor and returns a +ey press descriptor. #t returns the next +ey press in the viewport% waiting for a clic+ if necessary. 5 *ready6+ey6press viewport, Ta+es a viewport descriptor and returns either a +ey press descriptor% or else ?f if none is available. )nli+e the previous function% ready6+ey6press returns immediately. 5 *+ey6value +ey6press, Ta+es a +ey press descriptor and returns a character or special symbol for the +ey that was pressed. 7or example% the nter +ey generates ?Kreturn% and the up6arrow +ey generates !up. 7or a complete list of possible return values% see -.T Mr d0 Graphical Toolbox Manual. 2.33 7lushing 5 *viewport6flush6input viewport, 2s noted above% +ey presses and mouse clic+s are buffered. viewport6flush6input ta+es a viewport descriptor and empties the input buffer of mouse and +eyboard events. 2.32 )niti'ed Graphics To use a uniti'ed version of the graphics library *see -.T M'.ib0 .ibraries Manual for more information on units,% get the signatures graphicsL% graphics0posn6lessL% and graphics0posnL with0 *re/uire *lib 1graphics6sig.ss1 1graphics1,,

The graphicsL signature includes all of the names defined in this chapter. The graphics0posn6lessL signature contains everything except the posn structure information% and graphics0posnL contains only the posn structure. To obtain graphicsM% which imports mredL *all of the Mr d classes% functions% and constants, and exports graphicsL0 *re/uire *lib 1graphics6unit.ss1 1graphics1,, The graphics6posn6less6unit.ss library provides graphics6posn6lessM% which imports graphics0posnL in addition to Mr d.