E.

Graphics Programming with RAPTORgraph

By Dr. Steve Hadfield, Maj Jason Moore and Lt Col Tom Schorsch

In Computer Science 110, we will be creating graphics programs using a simple graphics
package called RAPTORgraph, which was adapted from Adagraph written by Jerry van
Dijk of the Netherlands and modified slightly for our use at USAFA. This reading explains
how to get started using RAPTORgraph, and it describes the RAPTORgraph routines you
will need this semester.

Overview of RAPTORgraph
All RAPTORgraph commands are relative to a special graphics window, an example of
which is depicted below (Figure 1). In this graphics window you can draw lines,
rectangles, circles, arcs and ellipses of various sizes and colors. You can also display text
in the graphics window. If you are viewing this on-line, you can download and execute
the program by clicking here: RaptorGraph_Image1.rap

Figure 1. Example RAPTORgraph output

Several filled and unfilled graphic shapes have been drawn in the graphics window above.
The green wire-frame cylinder was created by drawing two ellipses and then drawing a
line between the tops the bottoms of the ellipses. The brown wire-frame cube was
created by drawing two rectangles and then connecting the four corners of the rectangles
with lines. The yellow, moon-shaped object right-of-center was created by flood-filling an
enclosed area.

You can interact with a graphical program by determining the position of the mouse in the
graphics window and determining if and where a mouse button was clicked. You can also
simulate movement in the graphics window by drawing an object, erasing it (drawing it

E-1
again in white think white-out), and then redrawing the object in a slightly different
position.

Getting Started with RAPTORgraph

To use RAPTORgraph, you must create a graphics window. This graphics window must
be created prior to calling any other RAPTORgraph procedures or functions.

Open_Graph_Window (X_Size, Y_Size)

If you used the above procedure call in your program, a graphics window 500 pixels wide
by 300 pixels tall would be created. Such a graphics window is depicted in Figure 2 below.
+Y axis

+X axis
Figure 2. Graphics window coordinate system

The graphics window always starts off with a white background. The origin of the
graphics windows (X,Y) coordinate system is at the bottom left-hand corner of the
window. The X-axis starts from 1 going left to right. The Y-axis starts from 1 going
bottom to top.

After your program is finished with all other graphic commands it should delete the
graphic window with the following procedure call:

Close_Graph_Window

E-2
All other calls to RAPTORgraph procedures need to be between the calls that create and
destroy the graphic window. The following example program (Figure 3) illustrates where
the various commands are placed in your RAPTOR program (Simple Example.rap).

Figure 3. Simple RAPTORgraph program

Graphics Output with RAPTORgraph

RAPTORgraph has a collection of procedures that draw shapes on the graphics window.
All of these routines let the programmer specify the (X,Y) locations where the item is to
appear in the graphic window.

For example, the Draw_Circle procedure can draw a filled circle that is centered at
an (X,Y) coordinate in the graphics window and that has a particular radius and color.
Calls to Draw_Circle have the following format:

Draw_Circle( X, Y, Radius, Color, Filled)

Where X and Y are the horizontal and vertical positions of the circle's center point,
Radius is the distance (in pixels) from the center point to the circle's edge, Color is the
color of the circle, and Filled is either True/Filled or False/Unfilled. A value of True (or

E-3
Filled) produces a solid circle, while a value of False (or Unfilled) only draws the circle's
outside edge. For example,

Draw_Circle( 250, 150, 140, Blue, Filled)

produces a solid blue circle centered at (250, 150) with a radius of 140 pixels.

The ordering of graphics commands is important because each shape is drawn on top of
previously drawn shapes. For example, a Bulls-eye can be made by drawing concentric
circles starting with the largest, outermost circle first. The effect of the program
Concentric_Circles.rap below can be seen in the Figure 4 graphic window.

E-4
 Figure 4. Concentric circles drawn from the outside to the center

The shape drawing routines available in RAPTORgraph are:

Put_Pixel Sets a single pixel to the desired color

Draw_Line Draws a line given its two (X,Y) endpoint coordinates
Draw_Box Draws a rectangle given the upper-left and lower-right corner
(X,Y) coordinates
Draw_Circle Draws a circle given its center and radius
Draw_Ellipse Draws an ellipse given the upper-left and lower-right corner (X,Y)
coordinates of the rectangle bounding the ellipse.
Draw_Arc Draws an arc (a section of an ellipse) given the upper-left and
lower-right corner (X,Y) coordinates of the rectangle bounding the
ellipse and the starting and stopping coordinates.
Clear_Window Erases (clears) the entire graphics window.

With closed shapes like rectangles, ellipses, and circles, we can optionally specify to fill the
shape. If a closed shape is created by a series of graphic calls (such as a collection of
Draw_Lines), then the Flood_Fill command can be used to fill in the enclosed area.

Flood_Fill Fills a closed-in area containing the given (X,Y) coordinate with the
given color.

Text and numbers can be displayed on the graphics window by specifying a string of
characters (e.g., "Apples are red") and the text's position.

E-5
Display_Text Draws a string of characters, where the given (X,Y) coordinate
marks the top-left corner of the first text character

Display_Number Draws a number, where the given (X,Y) coordinate marks the top-
left corner of the first, left-most digit of the number

To specify the color of an object, use one of the following values:

Black Magenta Light_Green White

Blue Brown Light_Cyan
Green Light_Gray Light_Red
Cyan Dark_Gray Light_Magenta
Red Light_Blue Yellow

Example Calls to Output Routines

1) To make the single pixel at position (20,30) black, call the Put_Pixel procedure as
shown:

In general, Put_Pixel( X, Y, Color) makes the pixel at coordinate (X,Y) have the value of
Color.

2) To draw a light blue line from coordinate (15,99) to coordinate (12,13), call:

In general, Draw_Line( X1, Y1, X2, Y2, Color) creates a line one pixel wide from the
starting coordinate (X1,Y1) to the ending coordinate (X2,Y2) with the specified Color.

We can also use variables to pass the coordinates to the drawing procedures. For
example, if a brown line is to be drawn from (1,1) to the point whose x and y coordinates
are stored in variables My_X and My_Y, respectively, we would use the following call:
Draw_Line( 1, 1, My_X, My_Y, Brown). A different line will be drawn
depending on the values of variables My_X and My_Y. The following program has the
user type in values for variables My_X and My_Y, but the variables could have gotten their
values through an assignment statement or from other procedure calls.

E-6
3) To draw a solid, cyan-colored box with corners at (38, 100) and (76,20), call:

In general, Draw_Box( X1, Y1, X2, Y2, Color, Filled ) draws a box whose upper-left
corner is at coordinate (X1,Y1) and whose lower-right corner is at (X2,Y2). This is the
first shape we have discussed that encloses an area. When we specify that an object be
Filled, its interior pixels are changed to the Color value. If we want the object to be a
wire frame (i.e., only draw the object's edges), used Unfilled for the final value.

In the call below, we draw a solid black box using equations to calculate its corner
locations.

If the variables Width and Height were used to create the graphic window, what can
we infer about the location and size of this box?

4) To draw a filled green circle with a radius of 9 pixels centered at coordinates

(X_Circle,Y_Circle), use:

In general, Draw_Circle( X_Center, Y_Center, Radius, Color, Filled) draws a circle

whose size is defined as Radius pixels and whose center point is at the coordinate
(X_Center,Y_Center).

E-7
 5) Drawing ellipses and arcs may be slightly less intuitive than the previous shapes. For
ellipses, we specify the (X,Y) coordinates of the smallest rectangle bounding the ellipse.
The figure below shows the output of the RAPTOR commands to the right. Note that the
filled ellipse is drawn with the same coordinates as the unfilled box.

Box upper left (50, 75)

Graphic window is 300 x 100

Box lower right (250, 25)

6) For arcs we specify the bounding box (as we did for an ellipse), and we also specify the
starting and stopping points - (startx, starty) and (endx, endy). The drawn arc starts on
the ellipse at the intersection point of the ellipse with a line from the center of the ellipse to
the point (startx, starty). The arc ends on the ellipse at the intersection of the ellipse with
a line from the center to point (endx, endy). The arc is drawn in a counter-clockwise
direction.

The following figure illustrates how an arc is drawn; it was created using the
RAPTORgraph procedure calls to the right of the figure.

Center point

Starting intersection
Ending intersection

The arc is drawn along the ellipse border in a counter-clockwise

direction from the starting intersection to the ending intersection

7) If weve drawn shapes in such a way as to enclose a bounded region of the graphics
window, we can fill that enclosed area using a flood fill routine. We must be careful using
a flood fill, because if the area is not totally enclosed, the fill will leak out and possibly
fill the entire graphics window. RAPTORgraphs Flood_Fill procedure begins filling
the interior pixels of a bounded region at a specified (X,Y) pixel coordinate and continues
filling until stopped by the enclosing boundary.

Below we see an example triangle being created and then a flood of the area inside the
triangle. The code for the image is to the right.

E-8
8) Often its nice to put text and numbers on our graphics window. However, we cant
use our standard output command to draw to the graphics window,. Instead, we use a
procedure that lets us specify where to put the text and numbers in the graphics window
and what color they should be. Note that the (X,Y) coordinates passed to the
Display_Text routine specify the top-left corner of the texts position.

In general, Display_Text( X, Y, Text, Color) draws a string of characters starting at

coordinate (X,Y) and continues drawing left to right. The default text height is 8 pixels
high. Generally allow about 12 pixels in the vertical direction between 2 lines of text of
default size. To change the text size, call Set_Font_Size(Height_in_pixels).

The Display_Number procedure is similar to Display_Text, except it receives an

number to draw. Also, you can combine text and numbers by using a string expression in
Display_Text. For example,

Display_Text(10, 20, The answer is + Answer, Black)

9) We can erase all drawings in the graphics window by calling procedure

Clear_Window. The Color value sent to the procedure defines the background color
used to fill the graphics window. As an example, the code below erases the graphics
window to all black.

As a summary, here are the formats for each of these drawing procedures:

E-9
Put_Pixel( X, Y, Color )
Draw_Line( X1, Y1, X2, Y2, Color )
Draw_Box( X1, Y1, X2, Y2, Color, Filled/Unfilled )
Draw_Circle( X, Y, Radius, Color, Filled/Unfilled )
Draw_Ellipse( X1, Y1, X2, Y2, Color, Filled/Unfilled )
Draw_Arc( X1, Y1, X2, Y2, StartX, StartY, EndX, EndY, Color )
Flood_Fill( X, Y, Color )
Display_Text( X, Y, Text_Expression, Color )
Display_Number( X, Y, Number, Color )
Clear_Window( Color )

E-10
To put it all together, the graphic shown below in Figure 5 was produced by the RAPTOR
program at the right that uses all of these RAPTORgraph procedures.

Figure 5. Sample RAPTORgraph output

Input with RAPTORgraph
While RAPTORgraph is fairly simple, it is powerful enough to draw some complicated
pictures. However, in addition to being able to draw sophisticated pictures, we want to
make our graphic programs interactive so that the user is able to direct what happens in
the window. We will now discuss input routines for both the mouse and the keyboard.
The input routines available are:

Wait_For_Key A procedure that simply waits until a keyboard key is pressed.

Key_Hit A function returning the Boolean value True if a key has been
pressed since the last call to Get_Key. Since Key_Hit is a
function call, it can only be used in the "to" portion of an
Assignment Statement or in Decision blocks (diamonds).

Get_Key A function that returns the character typed by the user. If no

character is ready to be processed, Get_Key waits until the
user presses a key.

Wait_For_Mouse_Button A procedure that simply waits until the specified mouse

button (either Left_Button or Right_Button) is pressed.
For example: Wait_For_Mouse_Button( Left_Button)

Mouse_Button_Pressed A function that returns the Boolean value True if the specified
button (either Left_Button or Right_Button) has been pressed
since the last call to Get_Mouse_Button. As a function, it is
only used in Assignment or Decision constructs.

Get_Mouse_Button A procedure that takes a button (either Left_Button or

Right_Button) and returns the coordinates of a click of that
button. If no click is ready to be processed, Get_Mouse_Button
waits until the user presses the desired button. For example,
Get_Mouse_Button(Right_Button, My_X, My_Y) waits for a
click of the right mouse button and then puts the location of the
click into the variables My_X and My_Y.

Get_Mouse_X A function that returns the X coordinate of the current mouse

location. It is typically used in an Assignment construct to
save the X location into a variable for later use.

Get_Mouse_Y A function that returns the Y coordinate of the current mouse

location. It is typically used in an Assignment construct to
save the Y location into a variable for later use.

It is important to note that some of the above calls will halt your program until a key or
mouse button is pressed. Other calls do not wait but merely return a True or False or
(X,Y) coordinates. If you do not want your program to wait for a key press or mouse
button click you can use Key_Hit or Mouse_Button_Pressed to check whether
such an event has occurred.

Example Use of RAPTORgraph Input Routines

To understand how you might
use these RAPTORgraph input
routines, carefully read the
RAPTOR program at the right.
The program opens a graphics
window and displays a prompt
for the user to hit a key. It then
waits until the user does so.
Once the user hits a key, the
program clears the graphics
window and fills it with a yellow
background. Then the program
waits for the user to accomplish
two left clicks. It captures and
saves the (X, Y) locations of
these two left clicks in the
(My_X1, My_Y1) and (My_X2,
My_Y2) variables respectively.
Then it draws a blue box using
the two left click locations.
Finally, the program waits for a
right click and then closes the
graphics window and terminates.
To run the demo, click here:
Graphics_Input_Demo.rap
Animation with RAPTORgraph
Sometimes we want to make an object
move across the graphic window.
Recall that movement can be
simulated by drawing an object,
erasing (drawing it again in white),
and then redrawing it in a new
position. To make objects move
smoothly and at a reasonable speed,
we might want to try moving the
object more than one pixel at a time
and with a small delay between times
when the object is drawn. We can
accomplish this with a loop like the
one in the program to the right, which
moves a green circle vertically down
the graphic window. To run the
program click here:
Animation_Demo.rap.

RAPTORgraph command summary

Graphic window opening and closing procedures and functions
Open_Graph_Window( X_Size, Y_Size )
Close_Graph_Window
Get_Max_Width -> returns screen pixel maximum width
Get_Max_Height -> returns screen pixel maximum height
Get_Window_Width -> returns current window pixel width
Get_Window_Height -> returns current window pixel height
Is_Open -> returns True if a graphics window is open
Set_Window_Title( Title )

Keyboard input procedures and functions

Wait_For_Key
Key_Hit > returns True / False
Get_Key -> returns the ASCII value of the key hit
Get_Key_String -> returns a string that defines the Key pressed

Mouse input procedures and functions

Wait_for_Mouse_Button( Which_Button )
Mouse_Button_Pressed( Which_Button ) > returns True / False
Mouse_Button_Released( Which_Button ) > returns True / False
Get_Mouse_Button( Which_Button, X, Y ) -> returns Which_Button, X, & Y
Get_Mouse_X > returns X
Get_Mouse_Y > returns Y

Drawing procedures
Put_Pixel( X, Y, Color )
Draw_Line( X1, Y1, X2, Y2, Color )
Draw_Box( X1, Y1, X2, Y2, Color, Filled/Unfilled )
Draw_Circle( X, Y, Radius, Color, Filled/Unfilled )
Draw_Ellipse( X1, Y1, X2, Y2, Color, Filled/Unfilled )
Draw_Arc( X1, Y1, X2, Y2, StartX, StartY, EndX, EndY, Color )
Clear_Window( Color )
Flood_Fill( X, Y, Color )
Display_Text( X, Y, Text_Expression, Color )
Display_Number( X, Y, Number, Color )

Smoothing Animations procedures

Freeze_Graph_Window -> from now on, graphic calls are buffered
Update_Graph_Window -> immediately draw all buffered graphics call
UnFreeze_Graph_Window -> from now on, graphic calls draw immediately

Miscellaneous functions and procedures

Get_Pixel( X, Y ) -> returns number code for color of pixel at (X, Y)
Set_Font_Size(Size)
Get_Font_Height -> returns the height in pixels of the current font
Get_Font_Width -> returns the width in pixels of the current font
Random_Color -> returns a random color (015, i.e. black thru white)
Random_Extended_Color -> returns a random color value 0-241
Closest_Color(R,G,B) -> returns a color based on the intensity of the
amount of Red (R), Green (G) and Blue (B) you want in the color
R, G, and B must be between 0 and 255.