Extensions to the MOS API called by BBC BASIC
---------------------------------------------
These are defined extensions, some may or may not be included in Brandy.


INKEY(&FF00+nn)  - BBC keyscan (standard)
INKEY(&FE00+nn)  - DOS keyscan
INKEY(&FC00+nn)  - SDL keyscan
INKEY(&8000+nn)  - 16-bit INKEY

ADVAL(n)         - read I/O device (standard)
ADVAL(-n)        - test buffer contents (standard)
ADVAL(128-n)     - low-level read of buffer n
ADVAL(128-1)     - fetch untranslated entry from keyboard buffer, 16-bit GET

BPUT#0           - VDU
BGET#0           - GET
EOF#0            - input pending, soft key being expanded or key in keyboard
                   buffer (contrast with ADVAL(-1) which only tests keyboard
                   buffer)
PTR#0
EXT#0


COLOUR &00+n              - foreground colour (standard)
COLOUR &40+n              - reserved (various functionality)
COLOUR &80+n              - background colour (standard)
COLOUR &C0+n              - border colour

VDU 19,<128,p,r,g,b       - set logical colour
VDU 19,-1  ,p,r,g,b       - set border colour (-1 is sent as CHR$255)

VDU 19,l,  0+RGB   ,r,g,b - steady physical colour (standard)
VDU 19,l,  8+RGB   ,r,g,b - flashing or bright physical colour (standard)
VDU 19,l, 16+action,r,g,b - RGB colour (standard extension)
VDU 19,l, 32+RGB   ,r,g,b - first flashing physical colour
VDU 19,l, 48+RGB   ,r,g,b - second flashing physical colour
VDU 19,l, 64+action,r,g,b - reserved
VDU 19,l,128+y     ,z,x,x - CPC: 5-bit physical colours y and z
VDU 19,l,255       ,r,g,b - DOS: 6-bit RGB colour

VDU 23,18,n,setting,mask|  - teletext display settings, new setting =
                             (old setting AND mask) EOR setting
VDU 23,18,0,display,mask|  - set mix/box display mode
                              b1-b0=text/mix/box/TV
VDU 23,18,1,update,mask|   - set update type
                              b0=suspend all automatic display upate
                              b1=update display after every character
VDU 23,18,2,reveal,mask|   - reveal concealed display
                              b0=reveal concealed characters
VDU 23,18,3,enable,mask|   - enable extended control characters
                              b0=black foreground enabled (CHR$&80, CHR$&90)
                              b1=double width enable (CHR$&8E, CHR$&8F)
                              b7-b2=reserved for eg Level 3 features
VDU 23,18,4,fontLo,fontHi| - select teletext font as per SAA505x series.
VDU 23,18,16,quality,mask| - select character display quality
                              b0=render high quality text
VDU 23,18,255,width|       - Set Teletext character cell width.

VDU 23,22 - define screen mode (BBCSDL)
VDU 23,23 - set line thickness (BBCSDL)
VDU 23,24 - set character spacing (BBCSDL)
VDU 23,31 - reset VDU system (internal to BBCSDL)

GCOL 0,c  GCOL 1,c  GCOL 2,c - standard GCOL commands
GCOL 3,c  GCOL 4,c
GCOL 5,c                   - on-screen colour not changed (RISC OS)
GCOL 6,c                   - on-screen colour = c AND NOT on-screen colour (RISC OS)
GCOL 7,c                   - on-screen colour = c OR NOT on-screen colour (RISC OS)
GCOL 8+n,c                 - GCOL n with transparent background (RISC OS)
GCOL 16*p+n,c              - Use extended colour pattern p for p=1..4
                             (GXR, MOS 3) or giant pattern for p=5 (RISC OS)
GCOL 96+,c                 - reserved


Extensions to BBC BASIC
-----------------------
BPUT#n,byte             - put single byte (standard)
BPUT#n,string[;]        - put string (standard extension)
BPUT#n,byte[,byte....]  - put multiple bytes

BGET#n                  - get single byte (standard)
GET$#n                  - get string (standard extension)

COLOUR l,p              - do VDU 19,l,p,0,0,0
COLOUR l,r,g,b          - do VDU 19,l,16,r,g,b or VDU 19,l,24,r,g,b if l<0
GCOL c                  - do GCOL 0,c
PLOT x,y                - do PLOT 69,x,y
=COLOUR(r,g,b)          - MODE-dependent colour number closest matching RGB.
=CHR$(x,y)              - read character from screen at x,y
SOUND ON                - turn sound on (*FX210,0)
SOUND OFF               - turn sound off (*FX210,1)
&o                      - octal constant, eg &o107
%                       - binary constant, eg %100111 (standard extension)
%%                      - Variable suffix, to denote a 64-bit integer.
&                       - Variable suffix, to denote unsigned 8-bit integer.
]                       - 64-bit unary indirection.

DIM HIMEM               - A Basalt extension, use to define arrays outside
                          of heap space using malloc(). Byte arrays defined
                          this way can be de-allocated by re-DIMming to -1.

CLEAR HIMEM [<array()>] - Deallocate off-heap arrays allocated using DIM HIMEM.
                          This does not deallocate memory blocks.


Notes on ADVAL(-1) and EOF#0
----------------------------
ADVAL(-1) returns how many entries are in the keyboard buffer, EOF#0 - where
implemented - returns whether the next GET or INKEY will return immediately.
These are two slightly different concepts.

If the current input stream is an EXEC file, ADVAL(-1) does not tell you if
tell you if there is a byte to read from GET/INKEY.

If the current input stream is the serial port, ADVAL(-1) does not tell you
if there is a byte to read from GET/INKEY, the serial input buffer is
ADVAL(-2).

Subtly, soft keys can give unexpected results. Consider the case where you
have:
*KEY 0 "hello"
*KEY 1 ""

Assuming the keyboard buffer is empty, if f0 is pressed, ADVAL(-1) will
return 1. GET/INKEY will fetch the "h" character, but thereup ADVAL(-1) will
return 0 - as there is now nothing in the keyboard buffer. However, there
are still four characters that can be fetched as there is a soft key being
expanded. You can see this with this bit of code, press f0 and only a single
character will be displayed:

REPEAT
  IF ADVAL(-1) THEN VDU GET
UNTIL FALSE

Now assume that f1 has been pressed. ADVAL(-1) will again return 1 as there
is one entry in the keyboard buffer. However, GET will wait forever, as it
will fetch the one entry from the keyboard buffer, find it is a soft key,
find that the soft key defintion is a null string, and loop back waiting for
something to enter the keyboard buffer. Again, with the same sample code,
pressing f1 will cause the program to wait forever - or until another key is
pressed.


If EOF#0 is implemented, it should do its best to examine the system and
only return zero if and only if the next GET/INKEY will immediately return
with no waiting, so the following code will work:

REPEAT
  IF NOT EOF#0 THEN VDU GET
UNTIL FALSE

In general, if you can it is better to write code in the form:

key%=INKEY(time):IF key%<>-1 THEN ....

