MOVE Move graphics cursor
Syntax: RUN GFX("MOVE",xcorycor)
Function: Moves the invisible graphics cursor to the specified location on the screen. MOVE does not change the display in any way.

 Parameters:
xcor,ycor The coordinates for the cursor.

 Examples:
RUN GF X ("MOVE" , 1 92 , 1 28 )

 Sample Program:
This procedure draws and pops bubbles on the screen using the CIRCLE function. It uses MOVE to select the position for the circles.

 PROCEDURE bubbles
 ODIM XCOR,YCOR,T,R,ARRAY(3,100):INTEGER
 ORUN GFX("MODE",1,0)
 ERUN GFX("CLEAR")
 OFOR T=1 TO 20
 DARRAY(1,T)=RND(255)
 DARRAY(2,T)=RND(192)
 DARRAY(3,T)=RND(50)
 ORUN GFX("MOVE",ARRAY(1,T),ARRAY(2,T))
 ORUN GFX("CIRCLE",ARRAY(3,T),3)
 ONEXT T
 OFOR T=1 TO 20
 ORUN GFX("MOVE",ARRAY(1,T),ARRAY(2,T))
 ORUN GFX("CIRCLE",ARRAY(3,T),0)
 OSHELL "DISPLAY 07"
 ONEXT T
 REND

 9-27
 BASIC09 Reference
POINT Set point to specified color
Syntax: RUN GFX("POINT",xcor, ycor(, color] )

 Function: Displays a dot at the specified coordinates. If you specify a color, POINT sets the pixel at the new coordinates to that color. Otherwise, POINT sets the pixel at the new coordinates to the foreground color.

 Parameters:
 xcorycor The X- and Y-coordinates for a pixel.
 color The code of the color you want the pixel to be.
 See the chart earlier in this section for color
 information.
 Examples:
RUN GFX("POINT", 192,1 28)

 RUN GFX("POINT",192,128,2)

 Sample Program:
This procedure uses POINT to draw filled boxes on the screen.

 PROCEDURE boxup
 ODIM XCOR,YCOR,BEGIN,COLOR,QUIT,TERMINATE,LINE:
 INTEGER
 ODIM T,X,Y:INTEGER
 OXCOR=50 \YCOR=30 \COLOR=1
 OBEGIN=1 \START=1 \QUIT=20 \TERMINATE=S0
 ORUN GFX("MODE",1,0)
 ORUN GFX("CLEAR")
 OFOR T=1 TO 4
 OFOR X=BEGIN TO QUIT
 OFOR Y=START TO TERMINATE
 ORUN GFX("POINT",XCOR+Y,YCOR,COLOR)
 ONEXT Y
 OYCOR=YCOR+1
 ONE XT X
 OSTART=START+ 1 0

 9-28

pTERMINATE=TERMINATE-10 pCOLOR=COLOR+1

 pNEXT T pI NPUT Z$ REND

 9-29
 BASIC09 Reference
QUIT Deallocate graphics screen

 Syntax: RUN GFX("QUIT")

 Function: Switches the screen to the alphanumeric (text) mode and deallocates graphics memory.

 Parameters: None

 Examples:

 RUN GFXt"QUIT")

 9-30
 Displaying Text and Graphics / 9
High-Resolution Graphics

BASIC09's high-resolution graphics greatly expand the capabilities of the Color Computer 3. You can have greater screen resolution (up to 640 by 192 pixels), as many as 64 colors, and the ability to mix graphics and text on one screen. In addition, you can use different text fonts, or styles.


The high-resolution module, GFX2, has many more functions than its medium resolution counterpart. GFX2 gives you the ability to:





· Turn an automatic scaling function off or on.
 · Draw outline or filled boxes.
 Draw ellipses and arcs.
 Fill specified areas with specified colors.
 · GET and PUT sections of the graphics screen.

· Move the cursor. Erase portions of a line or of the screen.
 · Select reverse or normal video.
 Underline text.

Also, high-resolution graphics operate through the OS-9 Windowing System. This means that you can run several procedures in different windows. You can establish windows to display text, or to display graphics, or both. You can easily display any window.



BASIC09 Reference
Establishing a Hardware Window

For your convenience, OS-9 has a number of predefined or hardware window formats. Hardware windows are text windows, and you cannot use them for graphic applications. Because hardware windows are predefined, you can easily establish them with the INIZ command. For instance, to establish Window 7, type:


i n i z w 7 ENTER

However, you cannot see the window until you send a message to it. Type:


echo Hello Window 7 > /w7 ENTER

Now, to see the window and your message press CLEAR . To return to the original screen, press CLEAR again.


To OS-9, a window is a device and you can send data to it. To view the Errmsg file in the SYS directory of your system diskette, list it to Window 7 by typing:


list sys/errm5g > /w7 ENTER

Press CLEAR to move to Window 7 and see the listing. Press SHIFT CLEAR to return to the previous screen.


You can also fork a shell (an execution environment) to a window. To cause a shell to operate in Window 7, type:


shell i=/w7& ENTER

The i = function of SHELL tells OS-9 that the window is immortal. It does not die after completing a task. To operate OS-9 from the window, press CLEAR .


Besides Window 7, you have six other predefined windows. The following chart shows all the hardware windows and their parameters:


9-32

Starting
 Coordinates
 Window Screen Size X-Coord, Window Size
 Number Chars/line Y-Coord Cols Rows
 1 40 0,0 27 11
 2 40 28,0 12 11
 3 40 0,12 40 12
 4 80 0,0 60 11
 5 80 60,0 19 11
 6 80 0,13 80 12
 7 80 0,0 80 24

 Defining Windows

As well as hardware windows, OS-9 also lets you establish windows to your own specifications. You can set definable windows for either text or graphics, or both. You can locate them anywhere on a screen, and you can make them any size.


You initialize definable windows in the same manner you initialize hardware windows, using INIZ. If you want to have text on the window, you must merge SYS/Stdfonts (found on your system diskette) with the window. You can also establish a shell in a definable window, from which you can use OS-9 or BASIC09.


To establish definable windows you must supply OS-9 with information about the type of window you want (its graphic format), its size, and its location on the screen. The easiest way to do this is with the OS-9 WCREATE command.


r
BASIC09 Reference

WCREATE requires a window format code in the form - 5 = f o r ma t c ode to tell OS-9 what type of a window you want. The following chart shows the possible window formats you can

choose: -

Format Screen Size Resolution No. of Memory Screen
 Code Cols x Rows Width/Height Colors Required Type

 01 40 x 24 16t 1600 Text
 02 80 x 24 16t 4000 Text
 05 80 x 24 640 x 192 2 16000 Graphics
 06 40 x 24 320 x 192 4 16000 Graphics
 07 80 x 24 640 x 192 4 32000 Graphics
 08 40 x 24 320 x 192 16 32000 Graphics
 00* Specifies the current screen.
 FF Current display screen. Use when putting several windows on the same
 physical screen.
t You have to reconfigure the palette to get 16 colors rather than the default of eight colors. The following section provides information on the palette.

Fbrmat Codes 01 and 02 select text screens, and Format Codes 58 select graphics screens. The Screen Size column shows the maximum number of text columns and rows available for each screen. The Resolution column shows the maximum pixels (graphic units) available for each of the graphic screens. The Memory column shows how much memory OS-9 must set aside for each screen format. Memory requirements depend on the resolution and number of colors selected for a window.


The Palette

BASIC09 has 64 colors you can select for screen displays. The colors are available through a palette. The Color Computer's palette can hold 16 colors at once.


9-34

The following chart shows the default colors for the palette in Screen Format 7:














Instead of the default colors, you can select any of the 64 colors (0-63) for any of the palette registers. You do this using the PALETTE command described later in this chapter. The BORDER and COLOR commands also affect the colors available in the palette by changing the color in the background and foreground registers, Registers 02 and 03, respectively.


Note: The information in the next section assumes you have a Color Computer 3 with 512 kilobytes of memory. If your computer has 128 kilobytes of memory, skip to the section "High-Level Graphics With 128K."

 Establishing a Graphics Window

To create any window, you should first initialize it with the INIZ command. Type:




So that you can later type in the new window, merge the Stdfonts file with it. Type:




Using the information in the preceding tables, use WCREATE to establish a graphics window. The following command line creates a graphics window in Window 1 that has 320 x 192 resolution and that fills the entire screen. The new window has 16 colors available and provides 40 column by 24 line text:


9-35
 BASIC09 Reference
wcreate /w1 -s=8 00 00 40 24 03 02 02
Starting a Shell in a Window

The screen background color The screen foreground color

 The screen length in rows The screen width in columns The Y-Coordinate for the beginning of the screen The X-coordinate for the beginning of the screen The screen type The window name The command name

 At this point, the new window exists, and you can send data to it. However, if you want to operate from the window, you must install a shell in it. Type:


Press CLEAR to move to the new window. To load BASIC09, type:

Select either more or less memory, according to your needs. Using BASIC09 in a graphics window, you can write procedures to create high-resolution graphics, and you can display the graphics on the same screen.

 9-36

Using High-Level Graphics With 128K

If your computer is equipped with only 128 kilobytes of memory, you cannot use more than one window with BASIC09. Also, to use even one window, you must follow certain steps to provide enough memory for BASIC09 operations.


Refer to Table 9.6. You must select a window mode that does not use more than 16000 byte of memory-either window Format 5 or Format 6.


To provide enough memory to use BASIC09, you must fork a shell to the window you create, then kill the shell in TERM. Doing this means that you can no longer operate from your TERM screen. However, you can run OS-9 and BASIC09 from the window.


The following steps show you how to create a Format 6 graphics screen in Window 1, write a BASIC09 high-resolution graphics procedure, and execute it using minimum memory.


1. Boot OS-9. Then, create a graphics window by typing:







3. Enter the edit mode, and type the following procedure:











9-37
 BASIC09 Reference



























5. Compile Squeeze by typing:



6. Exit BASIC09 by typing:








8. MERGE does not set the new file Yawn as an executable file. Before you execute it, you must make the file executable by typing:




9. To execute Yawn, type:



The merging procedure in Step ? saves a considerable amount of memory. Every module you load uses one or more 8-kilobyte blocks of storage space. For instance, INKEY is only 94 bytes in length. However, if you load it as a separate module, it requires 8192 bytes. RUNB is 12185 bytes in length. This means that it requires two 8-kilobyte blocks, or 16384 bytes of memory. GFX2 is 2190 bytes in length, and Squeeze is 605 bytes in length. Loaded individually, they also require two memory blocks.


If you load all four modules independently, they use 40960 bytes. However, by combining them into one file, they load into two memory blocks, or 16384 bytes.


Using the information in this section, you can write and execute numerous BASIC09 procedures with only 128 kilobytes of memory. However, if your computer has 512 kilobytes of memory, you can bypass many of these steps. Also, the additional memory enables you to have several windows open at one time. For instance, you can create one window in which to write BASIC09 procedures, another window in which to execute your procedures, and a third window from which you can use OS-9 commands.


Note: The remainder of this chapter assumes you have 512 kilobytes of memory. If you don't, you can still run many of the sample procedures by implementing the steps in this section.

 Creating Windows from BASIC09

Using GFX2 routines, BASIC09 provides the means to create and manage windows. The steps for creating windows from BASIC09 are as follows:


1. DIM a variable to hold the path number to the window you want to create.


9-39
 BASIC09 Reference
2. OPEN a path to the window.
 3. SELECT the new window as the display window.

4. Send commands, data, or text to the window through the open path.

5. CLOSE the open path.
 6. Use SELECT to return to your original window.

If you do not want to return immediately to the screen or window of origin, you can skip Steps 5 and 6.


The following sample procedure shows how to open Window 2 as a 320 x 192 graphics window, draw a circle, then return to the original screen when you press a key.


PROCEDURE make-win
 DIM PATH: INTEGER
 DIM RESPONSE:STRINGf11
 OPEN #PATH,"/W2":WRITE
 RUN GFX2 (PATH,"DWSET",08,00,00,40,24,03,02,02)
 RUN GFX2 (PATH,--SELECT--)
 RUN GFX2 (PATH,"CIRCLE",200,90,80)
 GET #1 ,RESPONSE
 CLOSE #PATH
 RUN GFX2 ("SELECT")
 END

This procedure establishes a Format 8 window, beginning at Coordinates 0,0 and covering the total screen. The foreground color is green, the background color is black, and the border color is black.


Because this procedure does not INIZ the window it opens, the
 window automatically disappears when the procedure closes its
 path. To create a window that stays in the system, even after
 you close the path to it, use INIZ before the OPEN statement,
 like this: _

 SHELL "INIZ /W2"

 After you create and define the window, view it by pressing

CLEAR J. To get back to the screen you are working on, press sH i Fr CLEAR . If you intend to use a window more than once in a procedure, you do not need to close its path until the procedure no longer needs it.


9-40
 Displaying Text and Graphics / 9
Creating Overlay Windows

 When you establish a window, you are initializing an OS-9 device. However, an overlay window is only a new screen for an existing window. An overlay screen can be the same size as its window, or it can be smaller. OS-9 automatically transfers to the overlay window any current procedures operating in the device window.

 The process for creating overlay windows lets you select whether you want to save the contents of the screen covered by the new window. If you choose to save the contents, the previous screen is redisplayed when you end the overlay.

 The following procedure provides an example of using overlay windows. It creates six overlays, each smaller than the preceding window. The procedure then waits for you to press a key. When you do, it removes the overlay windows.

 PROCEDURE overwindow5
 ODIM X,Y,X1,Y1,T,J,H,L,PLACE:INTEGER
 ODIM RESPONSE:STRINGf13
 OX=0 \Y=0
 OX1 =80 \Y1 =24
 OPLACE=33
 OFOR T=1 TO 6
 OIF T=2 OR T=6 THEN
 OH = 3
 DELSE H=2
 REND I F
 ORUN GFX2C"OWSET",1 ,X,Y,X1 ,Y1 ,H,T)
 OX=X+6 \Y=Y+2
 OX1 =X1 -1 2 \Y1 =Y1 -4
 OFOR J=1 TO S

 OPRINT TAHCPLACE); "Overlay Screen
 ONEXT J
 OPLACE=PLACE-6
 ONEXT T
 OPRINT "Overlay Screen 6"
 OPRINT "Pre55 A Key...";
 OGET #1 ,RESPONSE
 OFOR T=1 TO 6
 DRUN GFX2C"OWEND")
 ONEXT T
 REND

 9-41
 BASIC09 Reference
The Graphics Cursor and the
 Draw Pointer

High-resolution graphics provide a test cursor, a graphics cursor, and a draw pointer. The text cursor and the graphics cursor can be either visible or invisible. The draw pointer is always invisible.


Text functions always begin at the current location of the text cursor. Whenever you print on the screen, the cursor automatically moves to the end of the text or to the beginning of the next line, depending on whether or not you use a semicolon after the print statement. You can reset the text cursor to any place on the screen with the CURXY function of GFX2.


Many BASIC09 graphics functions also begin operating at a location pointed to by the draw pointer. When you begin graphics, the draw pointer is located at coordinates 0,0. BASIC09 then updates the pointer as you execute certain graphics functions. For instance, the LINE function of GFX2 draws from the draw pointer position to the specified end coordinates. The draw pointer is left pointing to the end coordinates.


Because some functions begin at the draw pointer, you need to keep track of its location and make certain it is placed properly. Use the SETDPTR function to move the draw pointer to new locations.


The graphics cursor is for use with joystick or mouse operations. It provides a pointer for graphics applications. The system diskette provides patterns that can be loaded into the graphics cursor buffer. You can select from a variety of pointer images.


High-Resolution Text

When you create a graphics window, you can display either text characters, graphics characters, or both.


To display graphics, move the draw pointer to the location where you want the graphics to begin. Then, execute the graphics routines.


To display text, move the text cursor to the location where you want the text to begin. Then, use normal BASIC commands to print text.


9-42

Instructions for the draw pointer relate to a 640 x 192 grid, numbered 0-639 and 0-191. Instructions for the text cursor relate to the number of characters per line and the number of lines on the current screen format.


Using Fonts

OS-9 has built-in fonts (character sets). You can also create your own fonts and instruct BASIC09 to use them. If you create your own fonts, you can design any symbols or graphics characters you want to use.


To use fonts, you must be in a graphics window. See "Establishing a Graphics Screen" earlier in this chapter. Use the FONT function to tell OS-9 what font you want. BASIC09 has three fonts installed in Group 200, Buffers 1, 2, and 3. The following procedure uses characters in Buffer 3 to draw a border, then prints a message using the characters in Buffer 2. It then returns to Buffer 3 and asks you to press a key to end the procedure.


PROCEDURE borders
 ODIM T,B,V,J,K:INTEGER
 ODIM RESPONSE:STRINGL1J
 OB=1 99
 OPRINT CHR$C12)
 ORUN GFX2C"FONT",200,3)
 ORUN GFX2C"COLOR",1,2)
 OFOR T=0 TO 79
 OPRINT CHR$CB);
 ONEXT T
 OFOR T=1 TO 21
 ORUN GFX2C"CURXY",0,T)
 OPRINT CHR$CB); CHR$CB);
 ORUN GFX2C"CURXY",78,T)
 OPRINT CHR$CB); CHR$CB);
 ONEXT T
 ORUN GFX2C"CURXY",0,21)
 OFOR T=0 TO 79
 OPRINT CHR$CB);
 ONEXT T
 ORUN GFX2C"FONT",200,2)
 ORUN GFX2C"COLOR",0,2)
 ORUN GFX2C"CURXY",45,9)
 DPRINT "A Demonstration"

 9-43
 BASIC09 Reference
RUN GFX2C"CURRY",50,10)
 OPR I NT "Of A"
 pRUN GFX2C"CURRY",43,11)
 OPR I NT "Buffer Three Border"
 pRUN GFX2("CURRY",51 ,1 2)
 OPRINT "And"
 ORUN GFX2("CURRY",45,13)
 OPR I NT "Buffer Two Text"
 pRUN GFX2("FONT",200,1)
 ORUN GFX2C"COLOR",3,2)
 ORUN GFX2C"CURXY",33,15)
 OPRINT "Pre55 A Key...";
 OGET #1 ,RESPONSE
 OPRINT CHRS(12)
 REND

 High-Resolution Quick Reference

High-resolution functions are all part of the GFX2 module. You call them in a BASIC 09 procedure with the following syntax:




Path is an optional variable name that tells OS-9 the window in which you want the function performed. Function is the highresolution task you want to perform. Parameter is an essential or optional value that affects the performance of the function. Different functions require or permit different numbers of parameters.


The following reference gives a brief description of the highresolution graphics functions. This list is organized by function. Following the quick reference is a detailed reference organized alphabetically.


9-44

    Window Commands


Command Function
 DWSet Establishes a window and sets its location
 on the screen, its size, its background color,
 its foreground color, and its border color.
 OWSet Establishes an overlay window on a device
 window that already exists. The function
 also sets the overlay window size, back
 ground color, foreground color, and border
 color. When using this function, you can
 choose whether or not to save the contents
 of the original screen.
 OWEnd Deallocates the specified overlay window.
 Select Selects the window to display.
 DWEnd Deallocates an established window.
 '" ~CWArea Changes the size of a window. You can only
 reduce the working area of a window, not
 increase it.
 DWProtectsw Lets you unprotect a window and set other
 device windows over it. This might destroy
 the contents of either or both windows.

 9-45
 BASIC09 Reference
Drawing Commands:

 Command Function
 Point Sets the pixel under the draw pointer to the
 specified color or to the default color.
 Line Draws a line.
 Box Draws a rectangle outline.
 Bar Draws a filled rectangle.
 Circle Draws a circle.
 Ellipse Draws an ellipse.
 Arc Draws an arc.
 Fill Fills the area of the window the same color
 as the pixel under the draw pointer.
 Clear Clears the window.

 8-46
                Displaying Text and Graphics / 9


Configuring Commands:
Command Function
 Color Sets any of the foreground, background, or
 border colors.
 DefCol Sets palette registers to the default colors.
 Border Sets the border palette register.
 Palette Changes colors in the palette registers.
 Pattern Establishes a buffer from which BASIC09
 gets a pattern for graphics functions.
 Logic Turns on AND, OR, or XOR logic functions
 for draw functions.
 GCSet Establishes a buffer from which BASIC09
 gets the graphics cursor.
 ScaleSw Turns scaling on or off.
 SetDPtr Positions the draw pointer.
 PutGC Positions the graphics cursor.
 Draw Draws an image from directions provided in
 a draw string.

 Get/Put Commands:
Command Function
 Get Saves a specified portion of a window to a
 buffer.
 Put Places the image stored in a buffer onto a
 window.
 DefBuff Defines a buffer for storage.
 GPLoad Preloads a buffer from a disk file.
 KillBuff Deallocates a buffer.

 s
 BASIC09 Reference
Text/Cursor Handling Routines:

 Command Function '~'`
 CurHome Positions the cursor at coordinates 0,0.
 CurXY Positions the cursor at specified
 coordinates.
 ErLine Erases the line under the cursor.
 ErEOLine Erases from the cursor to the end of the
 line.
 Curoff Turns the graphics cursor off.
 CurOn Turns the graphics cursor on.
 CurRgt Moves the graphics cursor right one space.
 Bell Sounds the terminal bell.
 CurLft Moves the graphics cursor left one space.
 CurUp Moves the graphics cursor up one line.
 CurDvvn Moves the graphics cursor down one line.

 9-48
                Displaying Text and Graphics / 9


Font Handling Commands:
Command Function
 Font Specifies the buffer from which BASIC09
 selects its font characters.
 TCharSw Selects or deselects transparent characters.
 BoldSw Selects or deselects bold characters.
 Propsw Selects or deselects proportional characters.
 ErEoWndw Erases from the graphics cursor to the end
 of the window.
 Clear Erases window and homes the cursor.
 CrRtn Performs a carriage return by moving the
 cursor down one line and to the extreme left
 of the window.
 ReVOn Turns reverse video on.
 ReVOff Turns reverse video off.
 UndlnOn Turns the underline function on.
 UndlnOff Turns the underline function off.
 BlnkOn Turns blinking characters on (only for hard
 ware text screens).
 BlnkOff Turns blinking characters off (only for hard
 ware text screens).
 InsLin Inserts a blank line at the graphics cursor
 position.
 DelLin Deletes the line at the graphics cursor
 position.

 9-49
 BASIC09 Reference
ARC Draw an arc
Syntax: RUN GFX2([path,]"ARC"[,mxmy],
        xradyradxcorl,ycorl,xcor2, ycor2)


Function: Draws an arc at the current or specified draw position with the specified X and Y radius. If you specify the same radius for both X and Y, the function draws a circular arc, otherwise the arc is elliptical. The X coordinates are in the range 0-639. The Y coordinates are in the range 0-191.


ARC begins drawing from the point on the screen closest to the first set of coordinates (xcorl, ycorl). It stops at the portion of the screen closest to the second set of coordinates (xcor2, ycor2). You can determine on which side of the line ARC draws by selecting which set of coordinates is the beginning and which set is the end.


Parameters:
path The route to the window in which you want to
 draw an arc.
 mx,my The X- and Y-coordinates for the center of the
 arc. If you do not specify mx and my, BASIC09
 uses the current draw pointer position.
 xrad The radius of the arc's width.
 yrad The radius of the arc's height.
 xcorl,ycorl The beginning and ending coordinates for an
 xcor2,ycor2 imaginary line from which the function draws
 an arc. The line is relative to the center of the
 arc (the center point is at 0,0 for these coordi
 nates) and extends through the two coordi
 nates from one edge of the screen to the other.
 Examples:
    RUN GFX2C"ARC",50,100,50,100,50,150)


9-50