P21Forth 1.02
P21Forth has two graphics bit block transfer words, pixel write words, and an arrow sprite pointer word. The bit block transfer words GGET and GPUT get and put rectangular blocks of pixels from or to the video screen. The screen is 384 pixels wide and 482 pixels high. The upper left corner of the video screen is 0,0.
The present bit block transfer words are set to work on word boundries ( 4 pixels) in the horizontal dimension and on pixel boundries in the vertical directly. Thus the the screen dimensions for bit block transfers is 96 by 482.
These words use five parameters on the data stack. The first two parameters are the X and Y location of the upper left hand corner of the rectangle to be transfered. 0 0 would be the upper left corner of the screen. 48 241 would be the center of the screen. The second two numbers are the size of the rectange to be transfered. 1 1 would specify 1 word to or from the screen. 96 482 would specify the full screen and would only be valid if the transfer is taking place at 0 0. 48 241 would specify 1/4 of the screen, 1/2 of the width and 1/2 of the height. The last parameter is an address in memory. This is the address in memory with which the screen transfer takes place. To copy a block of pixels 10 words wide (40 pixels) and 40 pixels high from location column 50 and row 50 to location 10000 in memory you would issue the command:
50 50 10 40 10000 GGET
This will get a copy of this part of the screen and move
it from the rectangle format on the screen to a linear array
at address 10000 in memory.The command:
0 0 10 40 10000 GPUT
would copy that same rectangular block of pixel from address
10000 in memory back to the screen in the upper left hand
corner.The graphic bit block transfers the address of the upper left hand corner of the screen is stored in a table pointed to by a user variable. The user variable WINDOW initially holds the address of the table WIN1. The reason for this is that graphics bit block transfers can run in a background task with the multitasker. Each task will have its own pointer to its own table so multiple tasks can manipulate multiple graphics windows with the same code.
The words PSCR and GSCR will put and get full screens. They only need an address parameter as they are defined to use paramets to define an entire screen. The definition of PSCR is:
: PSCR ( a -- ) >R 0 0 96 482 R> GPUT ;
The definition of GSCR is:
: GSCR ( a -- ) >R 0 0 96 482 R> GGET ;
These words are used in the graphic demo example DEMO.
Read Chapter 10 Examples and Demos before running DEMO.
There are some steps need before you can safely run the
graphic bit block transfer demo.Further bit block transfer words including GAND, GOR, GXOR, and GSPRITE will be added to a later version of the system. These words do a logical AND, OR, XOR, or in the case of GSPRITE a series of logical operations combining the pixels in memory with the pixels on the screen.
These words will be used in a GUI toolkit. It will offer such features as multiple fonts, multiple characters sets, variable window sizes, variable scroll direction, proportional fonts. The package will also offer routines to create, open, close, move, resize, layer, and manipulate multiple video windows from multiple tasks in P21Forth.
P21Forth 1.02 also adds four words for writing pixels, WPIXEL, BPIXEL, and CPIXEL write white, black, or colored pixels. >COLOR takes a color value from the stack and sets the color to be used. CPIXEL can accept a solid color such as BLUE >COLOR or it can accept a pattern with a mixture of colors such as RED WHITE BLUE GREEN MIX >COLOR. In this case all 0 pixels will be written as red while 1 pixels will be written as white 2 pixels written as blue, and pixels in position 3 will be written as green by CPIXEL. These pixel write words use pixel addressing. They take an x and y argument from the stack within the range 0 to 383 for x and 0 to 481 for y.
These words like the bit block transfer words do not clip to the size of the screen or the window for graphics that has been set up by the user. They get the address of the upper left corner of the graphics window from the user variable WINDOW. WINDOW @ gives the address of this parameter. The value normally stored in this location is ABDE4 as is shown by the command WINDOW @ @ . which will print ABDE4.
To move the graphics output window to a different location on the display this value can be changed. Adding 73H will move the value down one line and adding 1 will move it right 4 pixels (one word). So to place the upper left corner of the graphics window in the center of the 60H word by 1E2H word screen you would add 30H for the horizontal offset and F1H * 73H for the vertical offset.
0 0 WPIXEL will normally write a white pixel to the upper left corner of the video window. HEX F1 73 * 30 + WINDOW @ +! will move the upper left corner of the graphics window to the center of the screen.
P21Forth 1.02 also includes a second video display buffer. The primary buffer is at address AAAAA and the upper left pixel in this page is at ABDE4, the second video buffer is at 9AAAA and its upper left pixel is at 9BDE4.
P21Forth 1.02 includes words for Ping Pong Graphics. The word SCREEN1 causes the system to display the primary graphics page. The word SCREEN2 causes the system to display the second video display buffer. The word DRAW1 causes the system to set the address in WINDOW @ to ABDE4 so that it will draw graphics on screen1, and it resets the CLS function to clear screen1. The word DRAW2 sets WINDOW @ to 9BDE4 so that graphics words draw to the second video buffer, and it sets the CLS function to clear the second video display buffer. The variable SCREEN# is used by PING. PING causes the system to draw to one page and display the other. Each time PING is executed it changes the page being displayed and the page for drawing. The word TEXT is defined as
: TEXT ( -- ) SCREEN1 DRAW1 ;
so that the user can return to the primary display page
where text will be displayed. If PING is executed an odd
number of times the user will be viewing screen2, but
writing text to screen1 and will not see the output until
they execute SCREEN1 or TEXT.The word PING is used in the 3D graphics demos contributed by Dave Lowry. The souce for this demo is included in the file 3D3.FOX on the distribution diskette for P21Forth 1.02. The demo is included in a binary overlay that can be run with the command:
2B LOAD 2C LOAD GET3D DEMO1 DEMO2 DEMO3
The variable N-DO contains the number of frames to be
displayed for each demo. DEMO1 will display a rotating,
scaled, transformed, and clipped cube using ping pong
graphics. It will display about 20 frames a second even
thought the demo is all written in high level code, even the
line drawing is done in high level code.The word DEMO2 will display the cube with a reference grid, and the word DEMO3 will display the above and outline the clipping window on the screen.
The word ARROW draws an arrow on the screen and takes x and y parameters from the stack. The size of the arrow is 2 words wide and 20 pixels high, and it aligned on word boundries. Thus when using a full screen it may be placed from 0 0 to 94 461 decimal or 5E 1CD in hex. The word CBUF is the address of a buffer in which the background behind the arrow can be saved. The word CURSOR saves the background from the screen to CBUF and calls ARROW to draw the arrow there to make sprite. The word XCURSOR restores the background that was behind the arrow. CURSOR and XCURSOR use the variables XX and YY for the screen location to draw the arrow and restore the background respectively they do not take parameters from the stack. The word XKEY is used in a demo called GUI. GUI calls GCLS to clear the screen and put the screen in 40X16 character mode, draws a box and places the arrow cursor on the screen. XKEY reads keys and moves the cursor until it sees a CR when it will exit. XKEY interprets 1AH as left cursor, 1CH as up cursor, 19H as right cursor, and 1DH as down cursor.
The demo GUI will move the arrow on the screen, but will not move it off the screen if the graphics window size has not been changed. The demo GUI will continue until a CR (0DH) has been pressed.
The demo GUI is not a real Graphic User Interface. A full GUI with pointer device input, multiple fonts, multiple movable windows, ICONS, and other features of a conventional GUI is under development at Ultra Technology, and will be released some time later in 1995.