Graphics

The RFO-BASIC! graphics interface lets you combine text, shapes, and images on the graphics screen. This screen occupies the entire display of the Android device. Display of the graphics screen prevents the display of the text output screen, which is the simpler method of interaction between user and program, but does not destroy it. Pressing the BACK key recalls the text output screen. In addition, a GR.FRONT statement lets the program switch between the graphics screen and the text output screen. Statements that raise a pop-up window for user input (such as INPUT and SELECT) work normally even when the graphics screen is displayed.

Unlike the text output screen, the graphics screen gives the program precise control over size, position, color, and transparency.

The GR.OPEN statement initializes the graphics interface and puts the graphics screen on display. The GR.CLOSE statement ends graphics operations. Graphics operations also end when the program ends, such as after the user presses the MENU key. To keep the graphics screen on display after the program has completed its computing, use a long PAUSE statement or an infinite loop with a method, such as an interrupt routine, to let the user force the program to terminate.

The GR.CLS statement clears the graphics screen and destroys all graphics elements. The GR.RENDER statement puts graphics elements onto the graphics screen. Nothing appears on the graphics screen until the program executes GR.RENDER. GR.RENDER achieves a flicker-free transition from what was displayed on the graphics screen and elements the program specified more recently.

A typical use of graphics is to put elements on the graphic screen, and to update them based on real-world events such as received messages. There are two ways to achieve this:
 * 1) Code a main loop that begins with GR.CLS, uses graphics statements to place the desired graphic elements on the screen, and finally executes GR.RENDER.
 * 2) Do the above only once, then code a main loop in which the program uses GR.MODIFY to change the parameters of certain elements and finally executes GR.RENDER.

Graphics operations work in portrait and landscape mode. The GR.OPEN command can state that the program operates in one specific orientation, or can specify that the orientation will change as the Android device is rotated.
 * Geometry

When drawing an object onto the graphics screen, the location (typically of the upper-left corner) and the size of the object are stated as a number of pixels. The upper-left corner of the graphics screen is identified with horizontal location x=0 and vertical location y=0. Pixels to the right and below this corner are identified with increasing positive pixel addresses (as in Quadrant IV of a Cartesian coordinate system).

A program can use the GR.SCREEN statement to query the size of the graphics screen. If the program has allowed the orientation to shift, the size of the graphics screen may change if the user rotates the Android device during the program's execution. RFO-BASIC! attempts to reconstruct the graphics objects in the new orientation, but the program may elect to re-draw the entire screen (notably because the program has different preferred uses or layouts based on the orientation). GR.SCREEN indicates that the device is in Portrait Mode if y > x.


 * Display Lists

Each command that draws a graphical object (line, circle, text, etc.) places that object on a list called the Object List. The command returns the object's Object Number. This Object Number, or Object Pointer, is the object’s position in the Object List. This Object Number can be used to change the object on the fly. You can change the parameters of any object in the Object List with the Gr.modify command. This feature allows you easily to create animations without the overhead of having to recreate every object in the Object List.

To draw graphical objects on the graphics screen, BASIC! uses a Display List. The Display List contains pointers to graphical objects on the Object List. Each time a graphical object is added to the Object List, its Object Number is also added to the Display List. Objects are drawn on the screen in the order in which they appear in the Display List. The Display List objects are not visible on the screen until the Gr.render command is called.

You may use the Gr.NewDL command to replace the current Display List with a custom display list array. This custom display list array may contain some or all of the Object Numbers in the Object List.

One use for custom display lists is to change the Z order of the objects. In other words you can use this feature to change which objects will be drawn on top of other objects.

See the Sample Program file, f24_newdl, for a working example of Gr.NewDL.


 * Drawing Coordinates

The size and location of an object drawn on the screen are specified in pixels. The coordinates of the pixel at the upper-left corner of the screen are x = 0 (horizontal position) and y = 0 (vertical position). Coordinate values increase from left to right and from top to bottom of the screen.

Coordinates are measured with respect to the physical screen, not to anything on it. If you choose to show the Android Status Bar, anything you draw at the top of the screen is covered by the Status Bar.


 * Drawing into Bitmaps

You can draw into bitmaps in addition to drawing directly to the screen. You notify BASIC! that you want to start drawing into a bitmap instead of the screen with the Gr.bitmap.drawinto.start command. This puts BASIC! into the draw-into-bitmap mode. All draw commands issued while in this mode will draw directly into the bitmap. The objects drawn in this mode will not be placed into the Object List. The Object Number returned by a draw command while in this mode is invalid and should not be used for any purpose including Gr.modify.

The draw-into-bitmap mode is ended by the Gr.bitmap.drawinto.end command. Subsequent draw commands will place the objects on the Object List and object numbers in the Display List for rendering on the screen. If you wish to display the drawn-into bitmap on the screen, issue a Gr.bitmap.draw command for that bitmap. The drawn-into bitmap may be drawn at any time before, during or after the draw-into process.


 * Colors

BASIC! colors consist of a mixture of Red, Green, and Blue. Each component has a numerical value ranging from 0 to 255. Black occurs when all three values are zero. White occurs when all three values are 255. Solid Red occurs with a Redvalue of 255 while Blue and Green are zero.

Colors also have what is called an Alpha Channel. The Alpha Channel describes the level of opaqueness of the color. An Alpha value of 255 is totally opaque. No object of any color can show through an object with an Alpha value of 255. An Alpha value of zero renders the object invisible.