RTR logo

BBC BASIC for Windows

BBC BASIC for SDL 2.0

Graphics and Colours



Introduction to graphics

BBC BASIC for Windows and BBC BASIC for SDL 2.0 have an extensive range of graphics commands. These commands are compatible with those available on the BBC Micro/Master and Acorn Archimedes, but are different from many other versions of BASIC.

This section draws together the information about graphics facilities and colours given under various keywords. Although it repeats much of the information presented elsewhere in this manual it provides a consolidated explanation of the graphics facilities and colours available.


Display modes

BBC BASIC for Windows and BBC BASIC for SDL 2.0 programs start with a default output window, having black text on a white background. In the former case the size of this initial window is determined by Windows™ and depends on the current display settings of your PC. Whilst this default window may be adequate for simple programs outputting only text, it is unlikely to be acceptable if your program mixes graphics and text, or needs a specific number of text rows and columns, especially if you want it to work correctly with different display settings (for example on other people's PCs).

In these cases you should always select an explicit window size. You can do that using the MODE statement, or by selecting a user-defined mode with VDU 23,22.... In BBC BASIC text rows are counted from the top of the window and graphics coordinates are measured from the bottom of the window, so selecting a display mode with known dimensions is particularly important to ensure consistent alignment of text and graphics. When a MODE statement is executed the window dimensions are changed to those appropriate to that mode, with (initially) white text on a black background. The 'screen' (BASIC's output window) is cleared and all the graphics and text parameters (colours, origin, etc) are reset to their default values.

A good general-purpose mode is MODE 8 which has 80 columns by 32 rows of text, and graphics dimensions of 640 pixels by 512 pixels (1280 x 1024 graphics units). This mode is small enough to fit easily within the desktop area on the majority of PCs. You can select MODE 8 as follows:

MODE 8
If you prefer black text on a white background a mode of the same size can be selected as follows:
VDU 23,22,640;512;8,16,16,128
Don't be tempted to use a MODE whose nominal dimensions are the same as your display resolution; by the time you've made allowances for the window's title bar and borders, and the task bar, it won't fit! So if your display is set to a resolution of 1024 x 768 don't use a MODE bigger than about 800 x 600 pixels (e.g. MODE 20). If you (exceptionally) want to use the entire screen you can either maximise the window or operate in full screen mode. You should not attempt to achieve the same effect by choosing a MODE larger than will fit.

Available modes

The available display modes and the resolution of which they are capable are listed below; MODEs 0 to 7 are compatible with MODEs 0 to 7 on the BBC Micro (with some minor differences). No attempt has been made to emulate the screen modes of the Acorn Archimedes, other than MODEs 0 to 7.
Mode Text (chars)Graphics (pixels) Graphics unitsLogical Colours 
0 80x32 640x512 1280x1024 2
1 40x32 640x512 1280x1024 4
2 20x32 640x512 1280x1024 16
3 80x25 640x500 1280x1000 16
4 40x32 640x512 1280x1024 2
5 20x32 640x512 1280x1024 4
6 40x25 640x500 1280x1000 16
7 40x25 teletext teletext 8
8 80x32 640x512 1280x1024 16
9 40x32 640x512 1280x1024 16
10 90x36 720x576 1440x1152 16
11 45x36 720x576 1440x1152 16
12 120x48 960x768 1920x1536 16
13 60x48 960x768 1920x1536 16
14 160x64 1280x1024 2560x2048 16
15 80x64 1280x1024 2560x2048 16
16 80x25 640x400 1280x800 16
17 40x25 640x400 1280x800 16
18 80x30 640x480 1280x960 16
19 40x30 640x480 1280x960 16
20 100x30 800x600 1600x1200 16
21 50x30 800x600 1600x1200 16
22 128x48 1024x768 2048x1536 16
23 64x48 1024x768 2048x1536 16
24 144x54 1152x864 2304x1728 16
25 72x54 1152x864 2304x1728 16
26 160x60 1280x960 2560x1920 16
27 80x60 1280x960 2560x1920 16
28 180x54 1440x1080 2880x2160 16
29 90x54 1440x1080 2880x2160 16
30 200x75 1600x1200 3200x2400 16
31 100x75 1600x1200 3200x2400 16
32 80x25 640x400 1280x800 2
33 40x25 640x400 1280x800 4
This table indicates the number of logical colours available in each display mode. As described in The Palette sub-section, the number of physical colours available depends upon the display settings.

With 'paletted' displays (256 colours or fewer) the number of logical colours represents the maximum number of different colours that can be displayed in the BBC BASIC window at any one time. Palette animation is possible: changing the contents of the palette affects colours previously plotted.

With 'non-paletted' displays (32768 colours or more) the number of colours which can be shown at any one time is limited only by the display settings. Changing the contents of the palette affects only colours subsequently plotted.

The command *EGA ON automatically maps mode numbers 0 to 7 to EGA-compatible modes in the same way as it does with BBC BASIC (86).

The command *EGA OFF automatically maps mode numbers 0 to 7 to CGA-compatible modes, as used by BBC BASIC (86) for MS-DOS. When converting a BBC BASIC (86) graphics program add a *EGA OFF command at the beginning.

As well as these predefined MODEs, you can also select a 'custom' mode using VDU 23,22.


Colours

The Palette

You can set the text and graphics background and foreground colours using the COLOUR and GCOL (Graphics COLour) statements. These commands use numbers to specify the colours.

Initially, and after a MODE change, the colour numbers refer to default colours which depend on the mode, as follows:

Two colour modes: 0, 4 and 32

Foreground  Background  Colour
0128Black
1129White

Four colour modes: 1, 5 and 33

Foreground  Background  Colour
0128Black
1129Magenta
2130Green
3131White

Sixteen colour modes: 2, 3, 6 and 8-31

Foreground  Background  Colour
0128Black
1129Red
2130Green
3131Yellow
4132Blue
5133Magenta
6134Cyan
7135White
8136Intensified Black (Grey)
9137Intensified Red
10138Intensified Green
11139Intensified Yellow
12140Intensified Blue
13141Intensified Magenta
14142Intensified Cyan
15143Intensified White
However you can (with certain limitations) set the actual colour displayed by these colour numbers to any one of the physical colours available, using the VDU 19 command or a variant of the COLOUR statement.

Because you can change the actual colour displayed by a colour number to any one of the physical colours available to you, these numbers are called logical colours. You could, if you wished, set all the logical colour numbers to the same physical colour.

It may help you to visualise the logical colours as an artist's palette with up to 16 numbered areas where colours may be placed. You could place any of the colours available to you in any one of the areas on the palette. Once the colours were in place on the palette, you could 'paint by numbers'.

Logical colours

The number of logical colours available depends upon the chosen display mode:

Physical colours

The physical colours are also referred to by numbers. However, a physical colour number always refers to the same colour. You can specify a physical colour in one of three ways:

The physical palette

The physical colour palette has sixteen colours, as follows:
Colour Number  Physical Colour
0Black (normal background)
1Red
2Green
3Yellow
4Blue
5Magenta (blue-red)
6Cyan (blue-green)
7White (normal foreground)
8Intensified Black (grey)
9Intensified Red
10Intensified Green
11Intensified Yellow
12Intensified Blue
13Intensified Magenta
14Intensified Cyan
15Intensified White
To select a logical colour to one of these physical colours you use either the VDU 19 command or the COLOUR statement:
VDU 19,logical,physical,0,0,0
COLOUR logical,physical

6-bit RGB colours

In the 6-bit RGB mode you set the physical colour by specifying the values of the individual red, green and blue components as numbers in the range 0 (minimum) to 63 (maximum). Hence the value 0,0,0 corresponds to black and the value 63,63,63 corresponds to peak (intensified) white.

To select a logical colour to one of these physical colours you must use the VDU 19 command:

VDU 19,logical,-1,red,green,blue
This mode is provided for compatibility with BBC BASIC (86).

8-bit RGB colours

In the 8-bit RGB mode you set the physical colour by specifying the values of the individual red, green and blue components as numbers in the range 0 (minimum) to 255 (maximum). Hence the value 0,0,0 corresponds to black and the value 255,255,255 corresponds to peak (intensified) white.

To select a logical colour to one of these physical colours you use either the VDU 19 command or the COLOUR statement:

VDU 19,logical,16,Red,Green,Blue
COLOUR logical,Red,Green,Blue

Text colours

You can set the text foreground and background colours with the COLOUR (or VDU 17) statement. The colour referenced by this statement is the logical colour, in the range 0 to 15:
COLOUR colour
If the colour number is less than 128, the colour of the text is set to that value. If the number is 128 or greater, the colour of the text background is set to the value minus 128.

Graphics colours

You can set the graphics foreground and background colours with the GCOL (or VDU 18) statement. The colour referenced by this statement is the logical colour, in the range 0 to 15.

The GCOL command also (optionally) specifies how the colour is to be plotted on the screen. It can be plotted directly, ANDed, ORed or Exclusive-ORed with the colour already there, or the existing colour can be inverted. If the plotting mode is omitted, it defaults to zero (plot):

GCOL colour
GCOL mode,colour
If the colour number is less than 128, the graphics colour is set to that value. If the number is 128 or greater, the colour of the graphics background is set to the value minus 128. Generally, you will not notice a change in the graphics background colour until you clear the graphics screen with a CLG statement.

The plotting modes are as follows:

mode=0 Plot the colour specified.
mode=1 OR the specified colour with the colour that is already there.
mode=2 AND the specified colour with the colour that is already there.
mode=3 Exclusive-OR the specified colour with the colour that is already there.
mode=4 Invert the colour that is already there.
See the Compatibility limitations section for important notes on the use of these plotting modes.


Drawing on the screen

Introduction

This sub-section describes the statements and functions available for drawing on the graphics screen and discovering the colour of any pixel (picture element) on the screen.

Screen dimensions

BBC BASIC for Windows and BBC BASIC for SDL 2.0 use 'graphics units' such that one pixel (picture element) corresponds to two graphics units. For example, in MODE 8, BASIC's 'screen' (the output window) is 640 pixels wide by 512 pixels high. This corresponds to a size of 1280 graphics units wide by 1024 graphics units high

The graphics viewport

The graphics viewport is a rectangular region of the 'screen' (BASIC's output window) in which you can draw graphics. You can move the graphics origin and the current graphics cursor position outside of this area, but any graphics drawn outside the graphics viewport are invisible.

By default, the graphics viewport is the full size of BASIC's output window and the graphics origin is at the bottom left-hand corner of that window. You may change the size of the graphics viewport with the VDU 24 command and the graphics origin with the VDU 29 command or ORIGIN statement. The action of these commands is described later in the Text and graphics viewports sub-section.

You can move or draw to any point, whether or not this point is outside the current graphics viewport. If you draw a line to a point outside the graphics viewport, the line is not displayed beyond the boundary of the viewport.

Drawing a line

You can use the DRAW statement to draw a straight line on the screen in any mode except MODE 7. The keyword DRAW is followed by the X and Y coordinates of the end of the line. The coordinates must be in the range −32768 to +32767.

The start of the line is the current graphics cursor position. This is either the end of the last line drawn or a point specified by a previous MOVE or PLOT statement.

The line is drawn in the current graphics foreground colour. This colour can be changed using the GCOL statement.

DRAW x,y

MOVE 200,300
DRAW 640,800
The DRAW statement is identical to PLOT 5.

Alternatively you can draw a straight line by specifying both ends:

LINE x1,y1,x2,y2
LINE 200,300,640,800

Moving the graphics cursor

You can move the graphics cursor to an absolute position without drawing a line with the MOVE statement.
MOVE X,Y
MOVE 124,327
The MOVE statement is identical to PLOT 4.

Plotting modes

PLOT is a multi-purpose drawing statement. Three numbers follow the PLOT statement: the first specifies the type of point, line or shape to be drawn; the second and third give the X and Y coordinates to be used. The coordinates must be in the range −32768 to +32767.
PLOT mode,X,Y
As previously described, the two most commonly used statements, PLOT 4 and PLOT 5, have the duplicate keywords MOVE and DRAW. The keywords CIRCLE, ELLIPSE, FILL, LINE and RECTANGLE also duplicate certain of the PLOT commands.

The available PLOT modes are as follows:

ModeAction
0-7 Basic line drawing modes.
8-63 Enhanced line drawing modes.
64-71 Plot a single point.
72-79 Horizontal line fill to non-background.
80-87 Plot and fill a triangle.
88-95 Horizontal line fill to background right.
96-103 Plot and fill an axis-aligned rectangle.
104-111 Horizontal line fill to foreground.
112-119 Plot and fill a parallelogram.
120-127 Horizontal line fill to non-foreground right.
128-135 Flood-fill to non-background.
136-143 Flood-fill to foreground.
144-151 Draw a circle.
152-159 Plot and fill a disc.
160-167 Draw a circular arc.
168-175 Plot and fill a segment.
176-183 Plot and fill a sector.
185/189 Move a rectangular block.
187/191 Copy a rectangular block.
192-199 Draw an outline axis-aligned ellipse.
200-207   Plot and fill a solid axis-aligned ellipse.
249/253 Swap a rectangular block.

Basic line drawing modes - PLOT 0 to 7

 Mode Action
0 Move relative to the last point.
1 Draw a line, in the current graphics foreground colour, relative to the last point.
2 Draw a line, in the logical inverse colour, relative to the last point.
3 Draw a line, in the current graphics background colour, relative to the last point.
4 Move to the absolute position.
5 Draw a line, in the current graphics foreground colour, to the absolute coordinates specified by X and Y.
6 Draw a line, in the logical inverse colour, to the absolute coordinates specified by X and Y.
7 Draw a line, in the current graphics background colour, to the absolute coordinates specified by X and Y.
Lines are drawn from the current graphics cursor position (the last point 'visited') to the specified X,Y coordinates. The coordinates must be in the range −32768 to +32767.

Enhanced line drawing modes - PLOT 8 to 63

 Mode Action
8-15 As 0-7, except that the last point is omitted.
16-31 As 0-15, but the line is drawn dotted.
32-47 As 0-15, but the line is drawn dashed.
48-63 As 0-15, but the line is drawn broken.
There may seem little point in omitting the last point (modes 8-15) but this can be useful in 'inverse' or 'exclusive-or' plotting modes. For example, when drawing a polygon in an 'exclusive-or' mode this can ensure that each vertex is correctly plotted.

Note that in BBC BASIC for Windows dotted, dashed and broken lines can only be drawn at the (default) thickness of one pixel. If you increase the thickness using VDU 23,23 lines are always drawn continuous. This limitation does not apply to BBC BASIC for SDL 2.0.

Plot a single point - PLOT 64 to 71

As 0-7, but plot a single point. Exceptionally, the size of the point plotted depends on the MODE in use: it is always one eighth of the width of a character cell by one eighth of the height of a character cell. PLOT X,Y is synonymous with PLOT 69,X,Y.

If you want to plot a single pixel you can use:

MOVE X,Y:DRAW X,Y or 
LINE X,Y,X,Y

Horizontal line fill to non-background - PLOT 72 to 79

The graphics cursor first moves to the specified coordinate (relative or absolute). Next it moves left until the first non-background pixel is encountered. Then it moves right until the first non-background pixel is encountered. Finally, a line is drawn between these two points. Note that the graphics cursor is moved to the specified X,Y position not the end of the drawn line. This is different from some other versions of BBC BASIC.

Triangle plot and fill - PLOT 80 to 87

As 0-7, but plot and fill a triangle. The triangle is formed from the given X,Y coordinates and the previous two points 'visited', however they were specified. The coordinates must be in the range −32768 to +32767.

The following example plots and fills the triangle illustrated in the current graphics foreground colour.
MOVE 150,200
MOVE 400,300
PLOT 85,500,150
triangle

If the PLOT number is 81 or 85, the triangle is drawn and filled in the current foreground colour.

Horizontal line fill to background right - PLOT 88 to 95

The graphics cursor moves to the specified coordinate. It then moves to the right until the first background coloured pixel is encountered. Finally, a line is drawn between these two points. Note that the graphics cursor is moved to the specified X,Y position not the end of the drawn line. This is different from some other versions of BBC BASIC.

Rectangle plot and fill - PLOT 96 to 103

Plot and fill an axis-aligned rectangle. The opposite corners are at the point plotted and the point last 'visited', however it was specified.

The following example plots and fills the rectangle illustrated in the current graphics foreground colour.
MOVE 150,200
PLOT 101,500,300
rectangle

If the PLOT number is 97 or 101, the rectangle will be drawn and filled in the current foreground colour.

See also the RECTANGLE FILL statement.

Horizontal line fill to foreground - PLOT 104 to 111

The graphics cursor moves to the specified coordinate. It then moves to the right until the first foreground coloured pixel is encountered. It then moves left until the first foreground coloured pixel is encountered. Finally, a line is drawn between these last two points. Note that the graphics cursor is moved to the specified X,Y position not the end of the drawn line. This is different from some other versions of BBC BASIC.

Parallelogram plot and fill - PLOT 112 to 119

Plot and fill a parallelogram whose vertices are defined by the previous two points visited and the point specified. For reference purposes, call the previous two points visited point1 and point2 in order, and the point specified in the PLOT command, point3. The x and y coordinates of the fourth point are calculated by:
point3-point2+point1
The order in which the points are visited is important.

The following example plots and fills the parallelogram illustrated in the current graphics foreground colour.
MOVE 150,200
MOVE 250,350
PLOT 117,500,300
parallelogram

If the PLOT number is 113 or 117, the parallelogram will be drawn and filled in the current foreground colour.

Horizontal line fill to non-foreground right - PLOT 120 to 127

The graphics cursor moves to the specified coordinate. It then moves to the right until the first non-foreground coloured pixel is encountered. Finally, a line is drawn between these two points. Note that the graphics cursor is moved to the specified X,Y position not the end of the drawn line. This is different from some other versions of BBC BASIC.

Flood fill to non-background - PLOT 128 to 135

Flood fill starting at the given point and continuing until non-background pixels are found. This may fail if the colour being used to fill can itself be filled, or if the background colour is not available as a 'solid' colour and has been approximated by 'dithering'.

In BBC BASIC for SDL 2.0 a substantial speed improvement may be achievable by first defining a graphics viewport which only just encloses the area to be filled.

See also the FILL statement.

Flood fill to foreground - PLOT 136 to 143

Flood fill starting at the given point and continuing until foreground pixels are found. This may fail if the colour being used to fill can itself be filled.

In BBC BASIC for SDL 2.0 a substantial speed improvement may be achievable by first defining a graphics viewport which only just encloses the area to be filled.

Draw circle - PLOT 144 to 151

Draw a circle on the screen with the centre at the current graphics cursor position. The supplied X,Y coordinates specify either a point on the circumference of the circle or its radius. If the 'absolute' plot codes (148 to 151) are used the point specified will be on the circumference of the circle. For example,
MOVE x1,y1
PLOT 149,x2,y2
will draw a circle centred on x1,y1 with the point x2,y2 in its circumference. If the 'relative' plot codes (144 to 147) are used either of the parameters may be used to specify the radius. For example, either
MOVE x,y
PLOT 145,R,0
or
MOVE x,y
PLOT 145,0,R
will draw a circle of radius R centred about the point x,y.

See also the CIRCLE statement.

Draw solid disc - PLOT 152 to 159

Draw a disc on the screen with its centre at the current graphics cursor position. A point on the circumference or the radius of the disc may be specified in a similar manner to a circle.

If plot codes 156 to 159 are used, the point specified will be on the circumference of the disc. If plot codes 152 to 155 are used, the non-zero parameter is interpreted as the radius of the disc.

See also the CIRCLE FILL statement.

Draw circular arc - PLOT 160 to 167

Draw an arc defined such that the previous two points visited correspond to the centre of the circle and the start of the arc respectively (i.e. the second point is on the circumference of the circle). The specified X,Y position lies anywhere on the line from the centre of the circle to the end of the arc. The arc is always drawn counterclockwise.

The following example draws the arc illustrated in the current graphics foreground colour:
MOVE 150,200
MOVE 500,300
PLOT 165,250,350
arc

Draw solid segment - PLOT 168 to 175

Plot and fill a segment, i.e. the area between an arc and the chord joining the ends of the arc. The previous two points visited correspond to the centre of the circle and the start of the arc respectively (i.e. the second point is on the circumference of the circle). The specified X,Y position lies anywhere on the line from the centre of the circle to the end of the arc. The segment is always drawn counterclockwise.

The following example draws the segment illustrated in the current graphics foreground colour:
MOVE 150,200
MOVE 500,300
PLOT 173,250,350
segment

Draw solid sector - PLOT 176 to 183

Plot and fill a sector, i.e. the area between an arc and the two radii to the ends of the arc. The previous two points visited correspond to the centre of the circle and the start of the arc respectively (i.e. the second point is on the circumference of the circle). The specified X,Y position lies anywhere on the line from the centre of the circle to the end of the arc. The sector is always drawn counterclockwise.

The following example draws the sector illustrated in the current graphics foreground colour:
MOVE 150,200
MOVE 500,300
PLOT 181,250,350
sector

Move rectangular block - PLOT 185 and 189

Move the contents of a rectangular region. The previous two points visited define diagonally-opposite corners of the source region. The specified X,Y position defines the bottom-left corner of the destination region. The source region is cleared to the current graphics background colour. The source and destination rectangles may overlap.

See also the RECTANGLE FILL ... TO statement.

Copy rectangular block - PLOT 187 and 191

Copy the contents of a rectangular region. The previous two points visited define diagonally-opposite corners of the source region. The specified X,Y position defines the bottom-left corner of the destination region. The source region is left unmodified (unless the source and destination rectangles overlap, in which case the source region is overwritten).

See also the RECTANGLE ... TO statement.

Swap rectangular block - PLOT 249 and 253

Swap the contents of two rectangular regions. The previous two points visited define diagonally-opposite corners of the first region. The specified X,Y position defines the bottom-left corner of the second region. If the first and second regions overlap, what was originally in the first region is preserved.

See also the RECTANGLE SWAP ... TO statement.

Draw outline ellipse - PLOT 192 to 199

Draw an outline axis-aligned ellipse such that the previous two points visited correspond to the centre of the ellipse and a point on a vertical tangent to the ellipse (i.e. the horizontal radius). The specified X,Y position lies anywhere on a horizontal tangent to the ellipse (i.e. the vertical radius). BBC BASIC for Windows and BBC BASIC for SDL 2.0 can draw only axis-aligned ellipses; to draw an angled ellipse use the ELLIPSE library routines.

The following example draws the ellipse illustrated in the current graphics foreground colour:
MOVE 250,200
MOVE 500,300
PLOT 197,150,350
ellipse

See also the ELLIPSE statement.

Draw solid ellipse - PLOT 200 to 207

Plot and fill an axis-aligned ellipse such that the previous two points visited correspond to the centre of the ellipse and a point on a vertical tangent to the ellipse (i.e. the horizontal radius). The specified X,Y position lies anywhere on a horizontal tangent to the ellipse (i.e. the vertical radius). BBC BASIC for Windows and BBC BASIC for SDL 2.0 can draw only axis-aligned ellipses; to draw an angled ellipse use the ELLIPSE library routines.

The following example draws the filled ellipse illustrated in the current graphics foreground colour:
MOVE 250,200
MOVE 500,300
PLOT 205,150,350
filled ellipse

See also the ELLIPSE FILL statement.

Draw relative

The 'draw relative' commands act relative to the last point plotted. Suppose, for example, the current X and Y coordinates were 200, 300. The command
PLOT 1,0,150
would draw a line in the current graphics foreground colour from 200, 300 to 200,450.

Logical inverse colour

The meaning of logical inverse colour depends on the selected mode, as follows:

Two colour modes

 Logical  Inverse 
01
10

Four colour modes

 Logical  Inverse 
03
12
21
30

Sixteen colour modes

 Logical  Inverse 
015
114
213
312
etc.
123
132
141
150

Reading a pixel's colour

The POINT function returns a number giving the logical colour of the screen at the coordinates specified. If the point is outside the graphics viewport, then −1 is returned.

There must not be a space between POINT and the opening bracket.

If two or more palette entries have the same (or nearly the same) physical colour, POINT may not return the expected value.

colour=POINT(X,Y)
IF POINT(X,Y)=3 THEN 300
You can use POINT to find out the colour of the screen at the specified point and take action accordingly. In an adventure game, for example, the swamps may be marked in green. If the explorer ventured into a green area he must be in the swamp and 'swamp type demons' would be activated.

See also the TINT function.


Text and graphics viewports

Introduction

Since the original BBC BASIC used the term 'window' differently from the sense in which it is used in the context of Graphical User Interfaces such as Microsoft Windows™ there is room for confusion. In this manual the word 'window' is used in its modern sense and the word 'viewport' is used to indicate a rectangular region of the window within which text or graphics are displayed. For historical reasons the word 'screen' is sometimes used to mean BASIC's output window.

BBC BASIC writes text to the text viewport and graphics to the graphics viewport. The text and graphics viewports can overlap. By default, the text and graphics viewports are the full size of BASIC's output window, but their size and position may be changed.

The text and graphics viewports may be restored to their default state with the VDU 26 command (but see the important note there).

The CLS command clears the text viewport to the current text background colour. The CLG command clears the graphics viewport to the current graphics background colour with the current graphics background plotting action (set by GCOL). If the text and graphics viewports overlap, the background colour of the overlapping area will be set by the last clear command issued.

Text viewport

The text origin is the top left-hand corner of the current text viewport. The reference point for defining a text viewport is the top left-hand corner of BASIC's output window.

Define text viewport

The VDU 28 command defines a text viewport. The four bytes following VDU 28 define the X and Y coordinates of the bottom left corner of the viewport and the X and Y coordinates of the top right corner of the viewport, in that order. The coordinates are measured in 'character positions'.

If the text cursor is outside the new viewport, it is moved to the new home position (top left of the viewport). If it is inside the new viewport, it is not moved.

The following example defines a text viewport with the bottom left corner at 0,15 (X across, Y down) and the top right corner at 30,3 (X across, Y down).

VDU 28,0,15,30,3

Clear text viewport

The CLS (or VDU 12) command clears the text viewport to the current text background colour. If you subsequently change the text background colour, the background of each character cell will be set to the new background colour as each new character is displayed. When the viewport scrolls, the 'empty' line will have the new background colour.

Graphics viewport

The graphics origin is initially the bottom left-hand corner of BASIC's output window. A graphics viewport is defined with reference to the current graphics origin. The graphics origin may be set with the VDU 29 command or the ORIGIN statement.

Define graphics viewport

In modes other than MODE 7, the VDU 24 command defines a graphics viewport. The four words (pairs of bytes) following the VDU 24 command are the X and Y coordinates of the bottom left corner of the viewport and the X and Y coordinates of the top right corner of the viewport in that order. The coordinates are with respect to the current graphics origin; they must be in the range −32768 to +32767.

It is particularly easy to select invalid viewport limits if the graphics origin has been moved. It is advisable, therefore, to precede a VDU 24 command with a VDU 29,0;0; or ORIGIN 0,0 command to reset the graphics origin.

The following example defines a graphics viewport with the bottom left corner at 200,100 (X,Y) and the top right corner at 500,300 (X,Y).

VDU 24,200;100;500;300;
Note the use of semicolons in this VDU command; their significance is explained under VDU in the keywords section. In particular, be very careful not to omit the final semicolon.

Clear graphics viewport

The CLG (or VDU 16) command clears the graphics viewport to the current graphics background colour using the current background plotting action (set by GCOL). If you change the graphics background colour, you will probably not notice the change until you next clear the graphics viewport. However, some of the PLOT modes use the current background colour.

Changing the graphics origin

In the graphics modes, ORIGIN (or VDU 29) moves the graphics origin to the specified coordinates. Subsequent graphics commands operate with respect to this origin. The coordinates must be in the range −32768 to +32767.

The following statements both set the graphics origin to X=640, Y=400:

ORIGIN 640,400
VDU 29,640;400;
Note the use of semicolons in the VDU command. Their significance is explained under VDU in the keywords section.

Positioning the cursor

Text cursor

The text cursor may be positioned within the text viewport with the TAB(X,Y) command. For example;
PRINT TAB(10,15)"Fred"
will print the word 'Fred' starting at column 15 of row 10. The top left hand corner of the text viewport is 0,0.

Graphics cursor

Within the graphics viewport, the graphics cursor is positioned by the MOVE, DRAW or PLOT commands.

When printing characters at the graphics cursor position, the top left-hand corner of the character cell is positioned at the graphics cursor position.

Homing the cursor

In VDU 4 mode, VDU 30 homes the text cursor to the top left corner of the text viewport. In VDU 5 mode, VDU 30 homes the graphics cursor to the top left corner of the graphics viewport.


Writing text to the screen

Text positioning

In all modes except MODE 7, text may be written at the text or graphics cursor position. In MODE 7 there is only a text cursor.

Text at text cursor

VDU 4 causes text to be written at the text cursor position in the normal way. This is the default mode

The characters are 'opaque' and they can be positioned only at text coordinates within the text viewport. The text within the viewport scrolls as necessary.

Text at graphics cursor

VDU 5 causes text to be written at the graphics cursor position.

The characters have a 'transparent' background and they are plotted according to the current foreground GCOL rules and colour. VDU 127 (DEL) is an exception; it backspaces and deletes just as it does in the normal text mode using the current background GCOL colour and action.

In the graphics modes, characters may be positioned at any graphics coordinate within the graphics viewport. The top left of the character cell is the reference point. Characters are clipped to the limits of the graphics viewport if necessary. No scrolling takes place.

Changing the font

You can change the text font using the *FONT command, for example:
*FONT Courier New,16
Note that selecting a proportional spaced font may affect the operation of certain features, such as INPUT editing, positioning of text using TAB(X) and reading the current character with GET(X,Y).

Selecting the character set

You can select the required character set (ANSI, OEM or UTF-8) using the VDU 23,22 command. Selecting the UTF-8 (Unicode) character set may affect the operation of certain features, such as positioning of text using TAB(X).

User-defined characters

Characters from &20 to &FF (32 to 255) may be programmed using the VDU 23 command (programmable characters are not available in MODE 7).

Current character

The easiest way to discover the character located at a specific position in the output window is to use the GET(X,Y) or GET$(X,Y) function. However BBC BASIC for Windows and BBC BASIC for SDL 2.0 also emulate the BBC Micro OSBYTE call which returns the the ASCII code of the character at the current text cursor position:
A%=&87
char=(USR(&FFF4) AND &FF00) DIV 256

Character dot pattern

BBC BASIC for Windows and BBC BASIC for SDL 2.0 emulate the BBC Micro OSWORD call which reads the 'dot pattern' of a character, however it returns the pattern of an internal 8x8 character font, not necessarily that of the actual characters which would be displayed.

In order to use the OSWORD call, you need to define a 9 byte area of memory in which the character code is passed and the dot pattern is returned. As with the BBC Micro, the OSWORD function number is passed in A% and the address of the parameter block is passed in X% and Y%. The least significant byte is passed in X% and the most significant in Y%

The following program segment:

  DIM pattern 8
  ?pattern=character
  A%=&A
  X%=pattern MOD 256:Y%=pattern DIV 256
  CALL &FFF1
The character dot pattern is returned in the 8 bytes 'pattern?1' to 'pattern?8'.


Capturing the screen contents

You can 'capture' (i.e. save to the clipboard) the contents of BASIC's output window - in other words what has been displayed by your program - in two ways:

Pixel-perfect graphics

Because of differences in the underlying hardware and Operating System, the graphics statements may not have identical effects in BBC BASIC for Windows and BBC BASIC for SDL 2.0, nor will they necessarily be the same as other versions of BBC BASIC. In most cases the differences will be insignificant (usually no more than one pixel) but occasionally even such small differences may matter.

In earlier versions of BBC BASIC, the size and shape of the physical pixels varied with the selected screen mode. For example in MODE 1 the pixels were twice as wide as in MODE 0. This does not apply in the case of BBC BASIC for Windows or BBC BASIC for SDL 2.0: the size of the physical pixels is determined solely by the current screen resolution. Although changing BASIC's screen mode can affect the size of text characters, and the maximum number of colours available, the pixels remain the same size: one pixel always corresponds to two BASIC graphics units. For example, MODEs 0, 1 and 2 are all 640 pixels wide by 512 pixels high, or 1280 graphics units wide by 1024 graphics units high.

An attempt could have been made to emulate more closely (in software) the detailed characteristics of the BBC Microcomputer and Acorn Archimedes screens. However this would have adversely affected performance and made it difficult to mix the use of BASIC graphics statements with native Windows™ or SDL 2.0 API functions. Instead, the graphics statements are mapped to API functions in the most straightforward way, consistent with a reasonable degree of compatibility.

When these small differences matter, the following sections describe in detail how BBC BASIC for Windows and BBC BASIC for SDL 2.0 behave, and therefore makes it possible to write programs which have precisely the desired effect on the screen. Alternatively you may want to consider using the anti-aliased graphics functions in the GDIPLIB and aagfxlib libraries respectively.

General considerations

Because each physical pixel corresponds to two BASIC graphics units, when you need to determine precisely which pixels are affected it is best to ensure that only even-numbered coordinates are used. This applies both to the setting of the graphics origin (ORIGIN or VDU 29 statements) and to the coordinates passed to the various graphics statements. This is particularly important in the case of relative coordinates, where the use of odd-numbered values can result in truncation effects which accumulate to cause quite large errors.

Straight lines

Straight lines are drawn between the specified end-points, which are normally inclusive, i.e. the line includes both end-points. In general, it is difficult to predict exactly which pixels will be plotted to create the line, because this depends on the precise algorithm used; it may even depend on the type of video card fitted in your computer and the version of its driver software. When it is essential to determine which pixels are 'lit', the line should be drawn as a series of individual points. However, in the case of horizontal and vertical lines the pixels lit should be predictable.

Whereas on earlier versions of BBC BASIC the thickness of a line may vary depending on the screen MODE in use, this is not the case with BBC BASIC for Windows and BBC BASIC for SDL 2.0 where it will always be (by default) one pixel thick. If you need to draw a thicker line you can use VDU 23,23.

Outline shapes

Outline shapes, such as triangles, rectangles and parallelograms, consist of a series of straight-line segments between the vertices. Each of these lines can be considered in isolation, and the same factors as described above for straight lines apply. Note in particular that although the RECTANGLE statement specifies the width and height of the rectangle, since the end-points of the lines forming the edges are inclusive, the actual dimensions (measured to the outer edges of the lit pixels) will be one pixel greater than those specified.

Solid (filled) shapes

In BBC BASIC for Windows only, solid shapes, such as filled triangles, rectangles and parallelograms, are drawn using the Polygon API function. This function treats the supplied vertices in a special way: vertices to the left and top of the polygon are inclusive of the plotted shape whereas vertices to the right and bottom are exclusive.

For example, if plotting a rectangle with:

MOVE 100,300 : PLOT 101,300,100
the point 100,300 (the top-left corner) will be inside the rectangle but 300,100 (the bottom-right corner) will be outside the rectangle. Put another way, the width and height of the rectangle will both be 200 graphics units (100 pixels) with the bottom-left corner of the rectangle at coordinates 100,102 (not 100,100). This behaviour is independent of the order in which the vertices are specified, therefore the position and size of the rectangle will be same for all the following methods:
MOVE 300,300 : PLOT 101,100,100
MOVE 100,100 : PLOT 97,200,200
RECTANGLE FILL 100,100,200,200
The above does not apply to BBC BASIC for SDL 2.0 in which solid shapes should be drawn inclusive of all the vertex coordinates, which is more standard for BBC BASIC.

Plotting single points

PLOT modes 64 to 71 plot a single 'dot' at the specified coordinates. Because these commands are commonly used to draw complex shapes, BBC BASIC for Windows and BBC BASIC for SDL 2.0 (exceptionally) plot a different-sized 'dot' depending on the screen MODE in use. If it did not do so, programs written for earlier versions of BBC BASIC would be likely to plot a series of separated pixels rather than a solid shape. The 'dot' plotted is a rectangle whose width and height are one-eighth of the width and height, respectively, of a character cell in that particular screen mode. For example, in MODEs 2 and 5 it is 4 pixels wide by 2 pixels high (8 x 4 graphics units); if necessary you can change the size using the @vdu.d.x% and @vdu.d.y% system variables. The specified coordinates correspond to the top-left corner of this rectangle.

If you need to plot a single (hardware) pixel, you can do that by drawing a 'line' of zero length:

MOVE X,Y : DRAW X,Y
or
LINE X,Y,X,Y

User-defined characters

User-defined characters (created with the VDU 23 command) vary in size according to the screen mode. For example, in MODE 0 they are 8 pixels wide by 16 pixels high, in MODE 1 they are 16 pixels by 16 pixels and in MODE 2 they are 32 pixels wide by 16 pixels high. When plotted as graphics (VDU 5 mode) the reference position is the top-left corner of the character cell.


Compatibility limitations

The characteristics of modern displays impose a few limitations on the compatibility of BBC BASIC for Windows and BBC BASIC for SDL 2.0 plotting modes with those of some earlier versions of BBC BASIC. In particular the BBC Micro and some other early displays used a hardware palette or colour look-up table, in which the colour of each pixel could be chosen only from a limited set of colours, whereas modern displays are almost invariably true colour (each pixel can have any colour).

There are two main respects in which compatibility may be impacted. Firstly, many early BBC BASIC programs (e.g. for the BBC Micro) used 'palette animation', in which the colour of every pixel with a specific 'colour number' can be changed instantaneously by modifying the contents of the palette using VDU 19; true colour (RGB) displays do not provide a comparable facility. Secondly, the 'logical' plotting operations (OR, AND, exclusive-OR and invert, as selected by GCOL) can behave in a way different from that which you might expect. Whilst it may sometimes be possible to configure your screen to emulate a 'paletted' or 'indexed' display, it may still not be fully compatible and performance may suffer.

In 'true color' modes there is no physical palette; the screen memory holds the RGB (Red, Green, Blue) colour directly. BBC BASIC still uses a 'logical' palette of 16 colours, but this is purely for software convenience and to maximise compatibility between paletted and non-paletted displays. The actual number of colours which can be displayed in BASIC's output window at any one time is limited only by the display settings. Changing the contents of BASIC's palette affects only things subsequently plotted; the existing screen contents are unaffected.

In these modes the 'logical' plotting operations (OR, AND etc.) operate on the physical RGB colour, not on the logical colour. Suppose you have selected (using VDU 19 or COLOUR) colour 1 to be red, colour 2 to be green and colour 3 to be blue. If you firstly use GCOL 0,1 to plot in red, then use GCOL 1,2 to combine the existing colour with colour 2 using the OR plotting mode, you would expect the end result to be colour 3 (1 OR 2) i.e. blue. However, what will actually happen is that the RGB value for red will be logically ORed with the RGB value for green, resulting in yellow, not blue.

Compatibility summary

In general you should be aware that the 'logical' plotting modes (OR, AND, exclusive-OR and invert) operate on the number stored in the physical screen memory (whether hardware palette index or RGB colour value) and not on BASIC's colour number. Combinations of logical operations which restore a colour to its original value (for example a double inversion) will work, but otherwise the result may not be what you intended.

Left CONTENTS

CONTINUE Right


Best viewed with Any Browser Valid HTML 3.2!
© Richard Russell 2021