Difference between revisions of "VDU"

From BeebWiki
Jump to: navigation, search
(VDU 19 extra bytes)
m (Adjusted formatting.)
 
(3 intermediate revisions by the same user not shown)
Line 10: Line 10:
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
 
| rowspan="2" | [[BASIC metasyntax|Syntax]]
 
| rowspan="2" | [[BASIC metasyntax|Syntax]]
| BASIC I-III
+
| BASIC I-III
| <code>VDU</code> &lt;numeric&gt;{<code>,</code>&#124;<code>;</code>&lt;numeric&gt;}[<code>;</code>]
+
| <code>VDU</code> <numeric>{<code>,</code>&#124;<code>;</code><numeric>}[<code>;</code>]
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
| BASIC IV-V
+
| BASIC&nbsp;IV-V
 
| <code>VDU</code><numeric>{<code>,</code>&#124;<code>;</code>&#124;<code>&#124;</code><numeric>}<nowiki>
 
| <code>VDU</code><numeric>{<code>,</code>&#124;<code>;</code>&#124;<code>&#124;</code><numeric>}<nowiki>
 
</nowiki>[<code>;</code>&#124;<code>&#124;</code>]
 
</nowiki>[<code>;</code>&#124;<code>&#124;</code>]
Line 23: Line 23:
 
| Description
 
| Description
 
| BASIC I-V
 
| BASIC I-V
| Sends the &lt;numeric&gt; arguments as little-endian character pairs (if followed by <code>;</code>) <nowiki>
+
| Sends the <numeric> arguments as little-endian character pairs (if followed by <code>;</code>) <nowiki>
 
</nowiki>or single characters (otherwise) to [[OSWRCH]], thereby printing them.<br><nowiki>
 
</nowiki>or single characters (otherwise) to [[OSWRCH]], thereby printing them.<br><nowiki>
</nowiki>In BASIC V, a &lt;numeric&gt; followed by a vertical bar <code>&#124;</code> <nowiki>
+
</nowiki>In BASIC IV or later, a <numeric> followed by a vertical bar <code>&#124;</code> <nowiki>
 
</nowiki>prints the character followed by nine [[VDU 0|NUL]]s.  
 
</nowiki>prints the character followed by nine [[VDU 0|NUL]]s.  
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
Line 40: Line 40:
  
 
A <code>VDU</code> statement is equivalent to <code>[[PRINT]]</code>ing a
 
A <code>VDU</code> statement is equivalent to <code>[[PRINT]]</code>ing a
string of <code>[[CHR$]]</code> functions. The only exception is that
+
string of <code>[[CHR$]]</code> functions. The only exception is that
<code>PRINT</code> increases <code>[[COUNT]]</code> whereas <code>VDU</code>
+
<code>PRINT</code> increases <code>[[COUNT]]</code> and may insert NEWLINE if
does not.
+
WIDTH is active, whereas <code>VDU</code> does not.
  
 
All the facilities of <code>VDU</code> are available to machine code
 
All the facilities of <code>VDU</code> are available to machine code
 
programs as it is just a veneer for the MOS routine, [[OSWRCH]].
 
programs as it is just a veneer for the MOS routine, [[OSWRCH]].
  
<code>VDU</code> interprets each of the &lt;numeric&gt; values following the
+
<code>VDU</code> interprets each of the <numeric> values following the
 
keyword as an [[ASCII]] value.  Any value between 0 and 255 inclusive is
 
keyword as an [[ASCII]] value.  Any value between 0 and 255 inclusive is
accepted, and maps to a unique character. If the &lt;numeric&gt; is followed by a
+
accepted, and maps to a unique character. If the <numeric> is followed by a
 
semicolon <code>;</code> then the value is a little-endian ''word'' from 0
 
semicolon <code>;</code> then the value is a little-endian ''word'' from 0
 
to 65535 inclusive.  It is broken down into two ASCII values; first the word
 
to 65535 inclusive.  It is broken down into two ASCII values; first the word
Line 56: Line 56:
 
[[crunching BASIC programs]].
 
[[crunching BASIC programs]].
  
In BASIC IV onwards, if the &lt;numeric&gt; is followed by a vertical bar
+
In BASIC IV onwards, if the <numeric> is followed by a vertical bar
<code>&#124;</code> then the &lt;numeric&gt; is treated as a single ASCII
+
<code>&#124;</code> then the <numeric> is treated as a single ASCII
 
value, followed by nine ASCII values of zero.  This ensures that the current
 
value, followed by nine ASCII values of zero.  This ensures that the current
 
VDU sequence is completed as the longest sequence length is nine characters.  
 
VDU sequence is completed as the longest sequence length is nine characters.  
Line 85: Line 85:
 
{| class="wikitable"
 
{| class="wikitable"
 
|+ VDU commands
 
|+ VDU commands
! Hex !! Decimal !! CTRL !! ASCII abreviation !! Bytes extra !! Meaning
+
! Hex !! Decimal !! CTRL !! ASCII name !! Extra bytes !! Parameters !! Meaning
 
|-
 
|-
| &00 || [[VDU 0|0]] || @ || NUL || 0 || Does nothing
+
| &00 || [[VDU 0|0]] || @ || NUL || 0 || || Does nothing
 
|-
 
|-
| &01 || [[VDU 1|1]] || A || SOH || 1 || Send next character to printer only
+
| &01 || [[VDU 1|1]] || A || SOH || 1 || character || Send character to printer only
 
|-
 
|-
| &02 || [[VDU 2|2]] || B || STX || 0 || Start print job
+
| &02 || [[VDU 2|2]] || B || STX || 0 || || Start print job
 
|-
 
|-
| &03 || [[VDU 3|3]] || C || ETX || 0 || End print job
+
| &03 || [[VDU 3|3]] || C || ETX || 0 || || End print job
 
|-
 
|-
| &04 || [[VDU 4|4]] || D || EOT || 0 || Write text at text cursor
+
| &04 || [[VDU 4|4]] || D || EOT || 0 || || Write text at text cursor
 
|-
 
|-
| &05 || [[VDU 5|5]] || E || ENQ || 0 || Write text at graphics cursor
+
| &05 || [[VDU 5|5]] || E || ENQ || 0 || || Write text at graphics cursor
 
|-
 
|-
| &06 || [[VDU 6|6]] || F || ACK || 0 || Enable VDU drivers
+
| &06 || [[VDU 6|6]] || F || ACK || 0 || || Enable VDU drivers
 
|-
 
|-
| &07 || [[VDU 7|7]] || G || BEL || 0 || Make a short beep
+
| &07 || [[VDU 7|7]] || G || BEL || 0 || || Make a short beep
 
|-
 
|-
| &08 || [[VDU 8|8]] || H || BS || 0 || Backspace cursor one character
+
| &08 || [[VDU 8|8]] || H || BS || 0 || || Backspace cursor one character
 
|-
 
|-
| &09 || [[VDU 9|9]] || I || HT || 0 || Advance cursor one character
+
| &09 || [[VDU 9|9]] || I || HT || 0 || || Advance cursor one character
 
|-
 
|-
| &0A || [[VDU 10|10]] || J || LF || 0 || Move cursor down one line
+
| &0A || [[VDU 10|10]] || J || LF || 0 || || Move cursor down one line
 
|-
 
|-
| &0B || [[VDU 11|11]] || K || VT || 0 || Move cursor up one line
+
| &0B || [[VDU 11|11]] || K || VT || 0 || || Move cursor up one line
 
|-
 
|-
| &0C || [[VDU 12|12]] || L || FF || 0 || Clear text area (<code>[[CLS]]</code>)
+
| &0C || [[VDU 12|12]] || L || FF || 0 || || Clear text area (<code>[[CLS]]</code>)
 
|-
 
|-
| &0D || [[VDU 13|13]] || M || CR || 0 || Move cursor to start of current line
+
| &0D || [[VDU 13|13]] || M || CR || 0 || || Move cursor to start of current line
 
|-
 
|-
| &0E || [[VDU 14|14]] || N || SO || 0 || Page mode on
+
| &0E || [[VDU 14|14]] || N || SO || 0 || || Page mode on
 
|-
 
|-
| &0F || [[VDU 15|15]] || O || SI || 0 || Page mode off
+
| &0F || [[VDU 15|15]] || O || SI || 0 || || Page mode off
 
|-
 
|-
| &10 || [[VDU 16|16]] || P || DLE || 0 || Clear graphics area (<code>[[CLG]]</code>)
+
| &10 || [[VDU 16|16]] || P || DLE || 0 || || Clear graphics area (<code>[[CLG]]</code>)
 
|-
 
|-
| &11 || [[VDU 17|17]] || Q || DC1 || 1 || Define text colour (<code>[[COLOUR]] n</code>)
+
| &11 || [[COLOUR|17]] || Q || DC1 || 1 || colour || Select text colour (<code>[[COLOUR]] n</code>)
 
|-
 
|-
| &12 || [[VDU 18|18]] || R || DC2 || 2 || Define graphics colour (<code>[[GCOL]] a,n</code>)
+
| &12 || [[GCOL|18]] || R || DC2 || 2 || action, colour || Select graphics colour (<code>[[GCOL]] a,n</code>)
 
|-
 
|-
| &13 || [[VDU 19|19]] || S || DC3 || 5 || Define logical colour (<code>[[COLOUR]] l,p</code> and <code>[[COLOUR]] l,r,g,b</code>)
+
| &13 || [[VDU 19|19]] || S || DC3 || 5 || l,p,r,g,b || Define logical colour (<code>[[COLOUR]] l,p</code> and <code>[[COLOUR]] l,r,g,b</code>)
 
|-
 
|-
| &14 || [[VDU 20|20]] || T || DC4 || 0 || Restore default logical colours
+
| &14 || [[VDU 20|20]] || T || DC4 || 0 || || Restore default logical colours
 
|-
 
|-
| &15 || [[VDU 21|21]] || U || NAK || 0 || Disable VDU drivers or delete current line
+
| &15 || [[VDU 21|21]] || U || NAK || 0 || || Disable VDU drivers
 
|-
 
|-
| &16 || [[VDU 22|22]] || V || SYN || 1 || Select screen mode (<code>[[MODE]]</code>)
+
| &16 || [[VDU 22|22]] || V || SYN || 1 || mode || Select screen mode (<code>[[MODE]]</code>)
 
|-
 
|-
| &17 || [[VDU 23|23]] || W || ETB || 9 || Define display character and other commands <nowiki>
+
| &17 || [[VDU 23|23]] || W || ETB || 9 || n,a,b,c, d,e,f,g,h || Define display character and other actions <nowiki>
 
</nowiki>(used by <code>[[ON]]</code> and <code>[[OFF]]</code>)
 
</nowiki>(used by <code>[[ON]]</code> and <code>[[OFF]]</code>)
 
|-
 
|-
| &18 || [[VDU 24|24]] || X || CAN || 8 || Define graphics window
+
| &18 || [[VDU 24|24]] || X || CAN || 8 || l,l,b,b,r,r,t,t || Define graphics window
 
|-
 
|-
| &19 || [[VDU 25|25]] || Y || EM || 5 || <code>[[PLOT]] K,x,y</code> <nowiki>
+
| &19 || [[VDU 25|25]] || Y || EM || 5 || action,x,x,y,y || <code>[[PLOT]] K,x,y</code> <nowiki>
</nowiki>(used by <code>[[MOVE]]</code>, <code>[[DRAW]]</code> and other statements)
+
</nowiki>(used by <code>[[MOVE]]</code>, <code>[[DRAW]]</code> and other commands)
 
|-
 
|-
| &1A || [[VDU 26|26]] || Z || SUB || 0 || Restore default windows
+
| &1A || [[VDU 26|26]] || Z || SUB || 0 || || Restore default windows
 
|-
 
|-
| &1B || [[VDU 27|27]] || [ || ESC || 0 || Does nothing
+
| &1B || [[VDU 27|27]] || [ || ESC || 0 || || Does nothing
 
|-
 
|-
| &1C || [[VDU 28|28]] || \ || FS || 4 || Define text window
+
| &1C || [[VDU 28|28]] || \ || FS || 4 || l,b,r,t || Define text window
 
|-
 
|-
| &1D || [[VDU 29|29]] || ] || GS || 4 || Define graphics origin (<code>[[ORIGIN]]</code>)
+
| &1D || [[VDU 29|29]] || ] || GS || 4 || x,x,y,y || Define graphics origin (<code>[[ORIGIN]]</code>)
 
|-
 
|-
| &1E || [[VDU 30|30]] || ^ || RS || 0 || Home text cursor to top left
+
| &1E || [[VDU 30|30]] || ^ || RS || 0 || || Home text cursor to top left
 
|-
 
|-
| &1F || [[VDU 31|31]] || _ || US || 2 || Move text cursor to x,y (<code>[[PRINT]] [[TAB]](x,y);</code>)
+
| &1F || [[VDU 31|31]] || _ || US || 2 || x,y || Move text cursor to x,y (<code>[[PRINT]] [[TAB]](x,y);</code>)
 
|-
 
|-
| &7F || [[VDU 127|127]] || n/a || DEL || 0 || Backspace and delete
+
| &7F || [[VDU 127|127]] || n/a || DEL || 0 || || Backspace and delete
 
|}
 
|}
 +
 +
== VDU function ==
 +
Some BASICs implement VDU(n) as a function to read the VDU variables. What VDU(n) calls is dependant
 +
on the platform the BASIC is running on. On 8bit/16bit systems VDU(n) typically calls [[OSBYTE &A0]]
 +
and so the parameter is the OSBYTE &A0 number 0-127. On RISC OS it calls SWI OS_ReadVDUVariable 128-255.

Latest revision as of 13:22, 15 February 2024

VDU is a BASIC statement to send characters to the screen, printer, serial port or other output device. It is usually used to generate VDU sequences that control the display.

VDU
Availability Present in all original versions of BBC BASIC.
Syntax BASIC I-III VDU <numeric>{,|;<numeric>}[;]
BASIC IV-V VDU<numeric>{,|;||<numeric>} [;||]
Token (hex) BASIC I-V EF (statement)
Description BASIC I-V Sends the <numeric> arguments as little-endian character pairs (if followed by ;) or single characters (otherwise) to OSWRCH, thereby printing them.
In BASIC IV or later, a <numeric> followed by a vertical bar | prints the character followed by nine NULs.
Associated keywords CHR$

Description

VDU is a versatile statement to control features of the BBC Micro's display that do not have their own BASIC keywords -- and a few that do. It can also be used to send binary data to the printer, serial port, *SPOOL file or any other device attached to the output stream.

A VDU statement is equivalent to PRINTing a string of CHR$ functions. The only exception is that PRINT increases COUNT and may insert NEWLINE if WIDTH is active, whereas VDU does not.

All the facilities of VDU are available to machine code programs as it is just a veneer for the MOS routine, OSWRCH.

VDU interprets each of the <numeric> values following the keyword as an ASCII value. Any value between 0 and 255 inclusive is accepted, and maps to a unique character. If the <numeric> is followed by a semicolon ; then the value is a little-endian word from 0 to 65535 inclusive. It is broken down into two ASCII values; first the word value MOD 256, then its value DIV 256. This word syntax is useful for graphics coordinates or for crunching BASIC programs.

In BASIC IV onwards, if the <numeric> is followed by a vertical bar | then the <numeric> is treated as a single ASCII value, followed by nine ASCII values of zero. This ensures that the current VDU sequence is completed as the longest sequence length is nine characters. It is a useful shorthand to fill in the trailing zeroes of VDU 23 commands.

In each case, the ASCII value or values are sent to OSWRCH one at a time. From there they are delivered to the output device or devices. Beware as certain characters are blocked from going to the printer. See VDUCHR and OSBYTE &06.

VDU commands

The commands in the list below are provided by the MOS, not by BASIC. They are only of interest to VDUCHR, the screen driver routine that is part of OSWRCH. The attached printer or serial device may have its own meanings for these commands, although VDUCHR may still be listening and can affect the flow of characters to the printer.

VDUCHR parses the incoming characters looking for these commands. When it finds one it opens a VDU sequence or VDU queue to collect the required number of extra bytes (if any), then executes the command it forms. While a VDU queue is open, all incoming characters go into the queue and do not have their usual effect on the screen.

The table is based on the B+ User Guide:

VDU commands
Hex Decimal CTRL ASCII name Extra bytes Parameters Meaning
&00 0 @ NUL 0 Does nothing
&01 1 A SOH 1 character Send character to printer only
&02 2 B STX 0 Start print job
&03 3 C ETX 0 End print job
&04 4 D EOT 0 Write text at text cursor
&05 5 E ENQ 0 Write text at graphics cursor
&06 6 F ACK 0 Enable VDU drivers
&07 7 G BEL 0 Make a short beep
&08 8 H BS 0 Backspace cursor one character
&09 9 I HT 0 Advance cursor one character
&0A 10 J LF 0 Move cursor down one line
&0B 11 K VT 0 Move cursor up one line
&0C 12 L FF 0 Clear text area (CLS)
&0D 13 M CR 0 Move cursor to start of current line
&0E 14 N SO 0 Page mode on
&0F 15 O SI 0 Page mode off
&10 16 P DLE 0 Clear graphics area (CLG)
&11 17 Q DC1 1 colour Select text colour (COLOUR n)
&12 18 R DC2 2 action, colour Select graphics colour (GCOL a,n)
&13 19 S DC3 5 l,p,r,g,b Define logical colour (COLOUR l,p and COLOUR l,r,g,b)
&14 20 T DC4 0 Restore default logical colours
&15 21 U NAK 0 Disable VDU drivers
&16 22 V SYN 1 mode Select screen mode (MODE)
&17 23 W ETB 9 n,a,b,c, d,e,f,g,h Define display character and other actions (used by ON and OFF)
&18 24 X CAN 8 l,l,b,b,r,r,t,t Define graphics window
&19 25 Y EM 5 action,x,x,y,y PLOT K,x,y (used by MOVE, DRAW and other commands)
&1A 26 Z SUB 0 Restore default windows
&1B 27 [ ESC 0 Does nothing
&1C 28 \ FS 4 l,b,r,t Define text window
&1D 29 ] GS 4 x,x,y,y Define graphics origin (ORIGIN)
&1E 30 ^ RS 0 Home text cursor to top left
&1F 31 _ US 2 x,y Move text cursor to x,y (PRINT TAB(x,y);)
&7F 127 n/a DEL 0 Backspace and delete

VDU function

Some BASICs implement VDU(n) as a function to read the VDU variables. What VDU(n) calls is dependant on the platform the BASIC is running on. On 8bit/16bit systems VDU(n) typically calls OSBYTE &A0 and so the parameter is the OSBYTE &A0 number 0-127. On RISC OS it calls SWI OS_ReadVDUVariable 128-255.