ugBASIC User Manual

Graphics

In this section, you will learn how to master the arts of form and colour: ugBASIC allows the programmer to harness the home computer full graphic potential, and all aspects of design can be controlled simply, accurately and almost instantaneously.

Basics

The computer-graphics artist is provided with a standard electronic canvas SCREEN WIDTH pixels wide and SCREEN HEIGHT pixels high, and there are potentially SCREEN COLOUR different colours to exploit.
In order to apply the chosen colour to the correct point, you will need to know the coordinates of each available pixel, and as long as these graphic coordinates are not confused with the broader scale of text mode (tilemap) coordinates, all will be well.

The PLOT command is the simplest drawing command of all, and plots a single pixel of ink colour between graphic coordinates 0,0 and SCREEN WIDTH,SCREEN HEIGHT. When followed by specific x,y-coordinates, the current ink colour will be plotted at this new position. You are allowed to omit either the x or the y coordinate, provided the comma is left in the correct position. If an optional colour index number is added the new colour will be used for this and all subsequent drawing operations.

BITMAP ENABLE
CLS BLACK
DO
   PLOT RND(SCREEN WIDTH),RND(SCREEN HEIGHT),RND(SCREEN COLORS)
LOOP

You can use the POINT function to find the index number of the colour occupying your chosen coordinates, like this:

BITMAP ENABLE
PLOT 160,100
PRINT "The colour is ";POINT(160,100)

The graphics cursor sets the starting point for most drawing operations. To establish this point, use GR LOCATE to position the graphics cursor at your chosen coordinates.

For example:

BITMAP ENABLE
x=150 : y=10
FOR r=3 TO 87 STEP 3
   GR LOCATE x,y+r
   CIRCLE ,,r
NEXT

You can use the XGR and YGR to find the current coordinates of the graphics cursor, which is the default location for future drawing operations.

For example:

BITMAP ENABLE
CLS
CIRCLE 100,100,50
PRINT XGR,YGR

Drawing lines and outline shapes

Line drawing is extremely simple. Pick two sets of graphic coordinates, and draw your line from one to the other. To draw a line from the current position of the graphics cursor, use DRAW TO followed by a single set of coordinates.

For example:

BITMAP ENABLE
CLS
INK RED
DRAW 50,50 TO 250,150
DRAW TO 275,175

Changing the appearance of straight lines is very simple with ugBASIC. Each line pattern is held in the form of a binary number made up of 16 bits, with zeros setting blank spaces in the current background colour, and ones setting the solid parts of the pattern in the current ink colour. So a normal solid line can be imagined as having all its bits set to one, like this:

%1111111111111111

The SET LINE command sets the style of all straight lines that are subsequently drawn. Theoretically, the 16-bit mask can generate values for different patterns between 0 and 65535, but here is a more practical example:

BITMAP ENABLE
CLS
INK YELLOW
SET LINE $F0F0
BOX 50,100 TO 150,140
SET LINE %1100110011001100
BOX 60,110 TO 160,160

Here is a range of ugBASIC short-cuts for drawing outline shapes on the screen.

The POLYLINE is identical to DRAW except that it accepts multiple coordinate settings at the same time. In this way, complex many-sided outlines can be drawn with a single statement. In its POLYLINE TO form, drawing begins at the current graphic cursor position. For example:

BITMAP ENABLE
CLS
CIRCLE 160,100,95
POLYLINE 160,6 TO 100,173 TO 250,69 TO 71,69 TO 222,173 TO 160,6

Boxed outlines are drawn at settings determined by the top left-hand and bottom right-hand coordinates, as in the following example:

BITMAP ENABLE
CLS
BOX 60,110 TO 160,160

To draw circles you can use the CIRCLE command, with a pair of coordinates sets the position of the centre point around which the shape is to be drawn, followed by the radius of the circle (the distance between the centre point and the circumference or rim of the circle). If the x,y-coordinates are omitted, the circle will be drawn from the current graphic cursor position.

BITMAP ENABLE
CLS
INK RED
GR LOCATE 160,100
CIRCLE ,,45
WAIT 100 MS
DO
   INK RND(SCREEN COLORS)
   x=RND(SCREEN WIDTH/2)
   y=RND(SCREEN HEIGHT/2)+1
   CIRCLE x,y,r
LOOP

An ellipse is drawn in a similar way. After the x,y-coordinates have set the centre location, two radii must be given, one to set the horizontal width and the second to set the height of the ellipse. Coordinates may be omitted as usual,providing the commas remain in place.

For example:

ELLIPSE 100,100,50,20
ELLIPSE ,,20,50

Clipping

The CLIP command is used to set an invisible rectangular boundary on the screen, using the normal top left-hand corner to bottom right-hand corner coordinates. All subsequent drawing operations will be clipped off when they reach these boundaries. To toggle the command and restore the normal screen display area, use CLIP and omit the coordinates. Areas that are preserved outside of the clipped zone can be used for items such as borders and control panels.

For example:
BITMAP ENABLE
CLS BLACK
CLIP 20,20 TO 50,50
r = (POSITION) 0
FOR r=4 TO 96 STEP 4
   GR LOCATE 10, r
   ELLIPSE ,,r+9,r
NEXT

Selecting colors

This section explains how the ugBASIC programmer is free to exploit the colour-handling features. Although the various targets provides different colour schema and registers, ugBASIC allows the use of colour numbers ranging from 0 to SCREEN COLORS (or COLOR COUNT).

You are not restricted to the pre-set colours that have been allocated for drawing operations. The INK command is used to specify which colour is to be used for subsequent drawing, and the number of the colour is set like this:
CLS
COLOR BACK RED
INK YELLOW
DRAW TO 319,199

The INK instruction can also be used to set patterns for filling shapes, as well as colours for borders around shapes, and this will be explained later.

The COLOR BACK command is used to assign your choice of color for the screen's background colour, which fills unused areas at the top and bottom of the visible screen, too (borders).

Any problem?

If you have found a problem, if you think there is a bug or, more simply, you would like something to be improved, write a topic on the official forum, or open an issue on GitHub.

Thank you!