RISCOS.com

www.riscos.com Technical Support:
BBC BASIC Reference Manual

 


VDU control


The Visual Display Unit (VDU) driver is a part of the operating system which provides a set of routines used to display all text and graphical output. Any bytes sent to the VDU driver are treated either as characters to be displayed or as VDU commands: instructions which tell the driver to perform a specific function. Their interpretation depends on their ASCII values as follows:

ASCII value Interpretation
0-31 VDU commands
32-126 Characters to be displayed
127 Delete
128-159 Characters to be displayed / teletext control codes
160-255 International characters to be displayed

The nearest equivalent to the statement VDU X is PRINT CHR$(X); with the exception that VDU ignores the value of WIDTH and does not affect COUNT.

In addition, the VDU commands can be given from the keyboard by holding down Ctrl and one further key as shown in the table below. For example, to give the command VDU 0, you would press Ctrl-@. Some VDU commands require extra data to be sent. The number of bytes extra is also given in the table.

VDU Code Ctrl plus Extra bytes Meaning
0 2 or @ 0 Do nothing
1 A 1 Send next character to printer only
2 B 0 Enable printer
3 C 0 Disable printer
4 D 0 Write text at text cursor
5 E 0 Write text at graphics cursor
6 F 0 Enable VDU driver
7 G 0 Generate bell sound
8 H 0 Move cursor back one character
9 I 0 Move cursor on one space
10 J 0 Move cursor down one line
11 K 0 Move cursor up one line
12 L 0 Clear text viewport
13 M 0 Move cursor to start of current line
14 N 0 Turn on page mode
15 O 0 Turn off page mode
16 P 0 Clear graphics viewport
17 Q 1 Define text colour
18 R 2 Define graphics colour
19 S 5 Define logical colour
20 T 0 Restore default logical colours
21 U 0 Disable VDU drivers
22 V 1 Select screen mode
23 W 9 Multi-purpose command
24 X 8 Define graphics viewport
25 Y 5 PLOT
26 Z 0 Restore default viewports
27 [ 0 Does nothing
28 \ 4 Define text viewport
29 ] 4 Define graphics origin
30 6 or ^ 0 Home text cursor
31 - or _ 2 Move text cursor

In the VDU commands described below, note the following three points:

  • Expressions followed by a semi-colon are sent as two bytes (low byte first) to the operating system VDU drivers.
  • Expressions followed by a comma (or nothing) are sent to the VDU drivers as one byte, taken from the least significant byte of the expression.
  • The vertical bar | means ,0,0,0,0,0,0,0,0,0, and so sends the expression before it as a byte followed by nine zero bytes. Since the maximum number of parameters required by any of the VDU statements is nine, the vertical bar ensures that sufficient parameters have been sent for any particular call. Any surplus ones are irrelevant, since VDU 0 does nothing.

VDU 0

VDU 0 does nothing.

VDU 1

VDU 1 sends the next character to the printer only, if the printer has been enabled (with VDU 2 for example).

VDU 2

VDU 2 causes all subsequent printable characters, and certain control characters, to be sent to the printer as well as to the screen (subject to FX3 mask etc).

VDU 3

VDU 3 cancels the effects of VDU 2 so that all subsequent printable characters are sent to the screen only.

VDU 4

VDU 4 causes all subsequent printable characters to be printed at the current text cursor position using the current text foreground colour. Cursor control characters (e.g. carriage return and line feed) affect the text cursor and not the graphics cursor.

VDU 5

VDU 5 links the text and graphics cursors and causes all subsequent printable characters to be printed at the current graphics cursor position using the current graphics foreground colour and action. Cursor control characters (e.g. carriage return and line feed) affect the graphics cursor and not the text cursor.

VDU 6

VDU 6 restores the functions of the VDU driver after it has been disabled (using VDU 21). Hence, this command causes all subsequent printable characters to be sent to the screen.

VDU 7

VDU 7 generates the bell sound.

VDU 8

VDU 8 causes either the text cursor (by default or after a VDU 4 command) or the graphics cursor (after a VDU 5 command) to be moved back one character position. It does not cause the last character to be deleted. Note that during command input, Ctrl-H acts as the Delete key, so the last character will be deleted.

VDU 9

VDU 9 causes either the text cursor (by default or after a VDU 4 command) or the graphics cursor (after a VDU 5 command) to be moved on one character position.

VDU 10

VDU 10 causes either the text cursor (by default or after a VDU 4 command) or the graphics cursor (after a VDU 5 command) to be moved on one line.

VDU 11

VDU 11 causes either the text cursor (by default or after a VDU 4 command) or the graphics cursor (after a VDU 5 command) to be moved back one line.

VDU 12

VDU 12 clears either the current text viewport (by default or after a VDU 4 command) or the current graphics viewport (after a VDU 5 command) to the current text or graphics background colour respectively. In addition the text or graphics cursor is moved to its home position (see VDU 30).

VDU 13

VDU 13 causes the text cursor (by default or after a VDU 4 command) or the graphics cursor (after a VDU 5 command) to be moved to the start of the current line.

VDU 14

VDU 14 enters paged mode, and so makes the screen display wait for Shift or Scroll Lock (twice) to be pressed before displaying the next page.

VDU 15

VDU 15 cancels the effect of VDU 14 so that scrolling is unrestricted.

VDU 16

VDU 16 clears the current graphics viewport to the current graphics background colour using the graphics and action. It does not affect the position of the graphics cursor.

VDU 17,n

VDU 17 sets either the text foreground (n<128) or background (n>=128) colours to the value n. It is equivalent to COLOUR n.

VDU 18,k,c

VDU 18 is used to define either the graphics foreground or background colour and the way in which it is to be applied to the screen. The BASIC equivalent is GCOL k,c.

VDU 19,1,p,r,g,b

VDU 19 is used to define the physical colours associated with the logical colour l.

If p <= 15 & p >= 0, r, g and b are ignored, and one of the standard colour settings is used. This is equivalent to COLOUR l,p.

If p = 16, the palette is set up to contain the levels of red, green and blue dictated by r, g and b. This is equivalent to COLOUR l,r,g,b.

If p = 24, the border is given colour components according to r, g and b.

If p = 25, the mouse logical colour lp is given colour components according to r, g and b. This is equivalent to MOUSE COLOUR l,r,g,b.

VDU 20

VDU 20 restores the default palette for the current mode and so cancels the effect of all VDU 19 commands or their BASIC keyword counterparts. It also sets the default text and graphics foreground and background colours.

VDU 21

VDU 21 stops all further text and graphics output to the screen until a VDU 6 command is received.

VDU 21

VDU 22 is used to change mode. It is equivalent to MODE n.

See Appendix G: VDU Commands for full details of the modes available.

VDU 23,p1,p2,p3,p4, p5,p6,p7,p8,p9

VDU 23 is a multi-purpose command taking nine parameters, of which the first identifies a particular function. Each of the available functions is described below. Eight additional parameters are required in each case.

VDU 23,0,n,m|

If n = 8, this sets the interlace as follows:

Value Effect
m = 0 Toggles the screen interlace state
m = 1 Sets the screen interlace state to the current *TV setting
m = &80 Turns the screen interlace off
m = &81 Turns the screen interlace on

If n = 10, then m defines the start line for the cursor and its appearance. Thus:

Bits Effect
0-4 define the start line
5-6 define its appearance:
Bit 6 Bit 5 Meaning
0 0 Steady
0 1 Off
1 0 Fast flash
1 1 Slow flash

If n = 11, then m defines the end line for the cursor.

VDU 23,1,n|

This controls the appearance of the cursor on the screen depending on the value of n. Thus:

Value Effect
n = 0 Stops the cursor appearing (OFF)
n = 1 Makes the cursor reappear (ON)
n = 2 Makes the cursor steady
n = 3 Makes the cursor flash

VDU 23,2 to 5,n1,n2 n3,n4,n5,n6,n7,n8

These define the four colour patterns. Each of the parameters n1 to n8 defines one row of the pattern, n1 being the top row and n8 the bottom row. See the chapter entitled graphics patterns for more details.

VDU 23,6,n1,n2,n3, n4,n5,n6,n7,n8

This sets the dot-dash line style used by dotted line PLOT commands. Each of the parameters n1 to n8 defines eight elements of the line style, n1 controlling the start and n8 the end. The bits in each are read from the most significant to the least significant, zero representing a space and one representing a dot. See the chapter entitled complex graphics for more details.

VDU 23,7,m,d,z|

This scrolls the current text screen. The values of m, d and z determine the area to be scrolled, the direction of scrolling and the amount of scrolling respectively. Thus:

Value Effect
m = 0 Scroll the current text viewport
m = 1 Scroll the entire screen

d = 0 Scroll right
d = 1 Scroll left
d = 2 Scroll down
d = 3 Scroll up

d = 4 Scroll in the positive X direction
d = 5 Scroll in the negative X direction
d = 6 Scroll in the positive Y direction
d = 7 Scroll in the negative Y direction
z = 0 Scroll by one character cell
z = 1 Scroll by one character cell vertically or one byte horizontally

VDU 23,8,t1,t2,x1,y1,x2,y2;0;

This clears a block of the current text viewport to the text background colour. The parameters t1 and t2 indicate the base positions relating to the start and end of the block to be cleared respectively. The positions to which the values of t refer are shown below:

Value Position
t = 0 top left of viewport
t = 1 top of cursor column
t = 2 off top right of viewport
t = 4 left end of cursor line
t = 5 cursor position
t = 6 off right of cursor line
t = 8 bottom left of viewport
t = 9 bottom of cursor column
t = 10 off bottom right of viewport

The parameters x1, y1 and x2, y2 are the x and y displacements from the positions specified by t1 and t2 respectively. They determine the start and end of the block.

VDU 23,9,n|
VDU 23,10,n|

These set the durations for the first and second flashing colours respectively. The duration is set to n frame periods (1/50th of a second in the standard modes). For example, VDU 23,9,10| sets the duration of the first flash colour to 10/50 or 1/5 of a second. An alternative to the VDU command is *FX9 or *FX10 described in the appendix *FX commands.

VDU 23,11|

This sets the four-colour patterns to their default values. See the chapter entitled Graphic Patterns for more details.

VDU 23,12 to 15,n1,n2,n3,n4,n5,n6,n7,n8

These set up the simple colour patterns. A block of two-by-four pixels is defined using the eight parameters. Each pair of parameters corresponds to the colours of the pixels on a given row, n1 and n2 being the top row and n7 and n8 the bottom row. See the chapter entitled graphic patterns for more details.

VDU 23,16,n|

This alters the direction of printing on the screen.

Normally when a character has been printed, the cursor moves to the right by one place, and then to the start of the row below when a character is entered in the righthand column. This movement, however, can be altered so that, for example, the cursor moves down one row after each character, and moves to the top of the next column to the right when the bottom of the screen has been reached. This effect can by produced by typing

VDU 23,16,8|

The effect on cursor movement depends on the value n as shown below:

Value Effect
0 Positive X direction is right, positive Y direction is down
2 Positive X direction is left, positive Y direction is down
4 Positive X direction is right, positive Y direction is up
6 Positive X direction is left, positive Y direction is up
8 Positive X direction is down, positive Y direction is right
10 Positive X direction is down, positive Y direction is left
12 Positive X direction is up, positive Y direction is right
14 Positive X direction is up, positive Y direction is left

Altering the direction of cursor movement also affects the way in which the screen scrolls; so in the example above, when a character has been entered at the bottom righthand corner, the screen scrolls to the left by one column rather than scrolling up by one row as it usually does.

The following is the complete list of VDU commands for moving the cursor:

Command Movement
VDU 8 Moves the cursor one place in the negative X direction
VDU 9 Moves the cursor one place in the positive X direction
VDU 10 Moves the cursor one place in the negative Y direction
VDU 11 Moves the cursor one place in the positive Y direction
VDU 13 Moves the cursor to negative X edge
VDU 30 Moves the cursor to the negative X and Y edges (home)
VDU 31,x,y Moves the cursor to TAB(x,y)
VDU 127 Moves the cursor one place in the negative X direction, destructively

VDU 23,17,n,m|

If n = 0 to 3, this command sets the tint to the value m for the text foreground, text background, graphics foreground and graphics background colours respectively. It is equivalent to TINT n,m. See the chapter entitled Screen modes for more details.

If n = 4, this command chooses which set of default colour patterns is used. m = 0 gives the Master 128-compatible set; m = 1 gives the native set. See the chapter entitled graphic patterns for more details.

If n = 5, this command swaps the text foreground and background colours.

If n = 6, then the command has the format:

VDU 23,17,x;y;0;0

This is used to set the origin of colour patterns. By default, patterns are aligned so that the top left corner of the pattern coincides with the top left corner of the screen. Using this call, you can make the top left of the pattern coincide with any pixel on the screen, given by the coordinates (x,y).

If n = 7, then the command has the format:

VDU 23,17,7,flags,dx;dy;0;0

The bits in the flag byte have the following meanings:

Bit Meaning if set
0 Set VDU 4 character size from dx,dy
1 Set VDU 5 character size from dx,dy
2 Set VDU 5 character spacing from dx,dy

The bit 0 option is not implemented at present.

If bit 1 is set, then dx and dy give the size in pixels of characters plotted in VDU 5 mode. The standard size of 8 by 8, and double height, 8 by 16, are optimised. Other sizes use the scaled character option of the sprite module and are therefore somewhat slower.

Bit 2 set causes dx and dy to be used to set the amount by which the VDU driver moves after each VDU 5-mode character has been printed (dx) and the amount to move down for a line feed (dy). Usually these would be set to the same values as the character size (so you would set bit 1 and 2), but they can be set independently to allow, for example, narrower than usual spacing.

VDU23,18 to 24,n1,n2,n3,n4,n5,n6,n7,n8

These are reserved for future expansion.

VDU 23,25,n1,n2,n3,n4,n5,n6,n7,n8

VDU 23,25 is used for anti-aliased fonts. Use of these calls is now deprecated, and you should use the SWIs provided by the FontManager module. See the Programmer's Reference Manual for details.

VDU 23,26,h,s,p1,p2,s1,s2,0,0 <font name>

VDU 23,26 is used for anti-aliased fonts. Use of this call is now deprecated, and you should use the SWIs provided by the FontManager module. See the Programmer's Reference Manual for details.

VDU 23,7,m,n|

If m = 0, this command selects the sprite whose name is STR$n. It is equivalent to *SChoose n.

If m = 1, this command defines sprite n to contain the contents of the previously marked rectangle. It is equivalent to *SGET n.

VDU 23,28 to 30,n1,n2,n3,n4,n5,n6,n7,n8

These are reserved for use by applications programs.

VDU 23,32 to 255,n1,n2,n3,n4,n5,n6,n7,n8

These redefine the printable ASCII characters. The bit pattern of each of the parameters n1 to n8 corresponds to a row in the eight-by-eight grid of the character. See the chapter entitled outputting for more details.

VDU 24,x1;y1;x2;y2

VDU 24 defines a graphics viewport. The four parameters define the left, bottom, right and top boundaries respectively, relative to the current graphics origin.

The parameters may be sent as shown, with semicolons after them. This indicates that the values are each two bytes long. Alternatively, they can be sent as eight one-byte values separated as usual by commas. The first of each pair contains the low byte for the boundary; the second contains the high byte.

For example,

VDU 24,160;300;360;800;

is equivalent to

VDU 24,160,0,44,1,104,1,32,3.

See the chapter entitled viewports for more details.

VDU 25,k,x;y;

VDU 25 is a multi-purpose graphics plotting command. It is equivalent to PLOT k,x,y. See the chapter entitled complex graphics for more details.

VDU 26

VDU 26 returns the text and graphics viewports to their default states: full screen size. In addition, it resets the graphics origin to (0,0), moves the graphics cursor to (0,0), and moves the text cursor to its home position.

VDU 27

VDU 27 has no effect.

VDU 28,lx,by,rx,ty

VDU 28 defines a text viewport. The parameters specify the boundary of the viewport; the left-most column, the bottom row, the right-most column and the top row respectively. See the chapter entitled viewports for more details.

VDU 29,x;y;

VDU 29 moves the graphics origin. x and y specify the coordinates of the new position. Normally the origin is at the bottom left of the screen at (0,0): whenever a position is given as an absolute value, for example MOVE 20,80, the coordinates are taken as being relative to the graphics origin. This command, therefore, affects all movements of the graphics cursor and all subsequent graphics viewport commands. The position on the screen of any existing graphics viewport is not affected. This command is equivalent to ORIGIN x,y.

VDU 30

VDU 30 moves the text cursor to its home position.

VDU 31,x,y

VDU 31 moves the text cursor to a specified position on the screen. It is equivalent to PRINT TAB(x,y);.

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015