VDUVars160  0.03 (16 Jun 2021)   nemo 2020-2021

This module provides a full implementation of OS_Byte,160 - the BBC MOS method
for reading VDU Variables. Arthur (and therefore RISC OS) only implemented the
first 16 Beeb VDU Vars, omitting many useful variables that in some cases can
not be read by any other official RISC OS API. Notably this includes the VDU
writing direction as set by VDU23,16.

There were some changes to the Vars between the Beeb and the Master. This
module implements the Master Vars as standard, but the Beeb versions are also
available - R1b31 selects the Beeb version (for example, subtract 256 from the
Var number). Otherwise only b0-7 of R1 are checked, and Vars &10-&7F are
implemented or simulated by this module.

e.g. Once you have loaded the module, you can read the VDU write direction:

  SYS"OS_Byte",160,&66 TO D%: D%=D%AND14

The VDU Vars

&10     Graphics cursor X
&11     Graphics cursor X MSB
&12     Graphics cursor Y
&13     Graphics cursor Y MSB
&14     Previous cursor X
&15     Previous cursor X MSB
&16     Previous cursor Y
&17     Previous cursor Y MSB

    These are better read using OS_ReadVduVariables.

&18     Output cursor X
&19     Output cursor Y

    Not useful inside a TaskWindow due to its lazy implementation.
    
&1B     VDU queue 0
&1C     VDU queue 1
&1D     VDU queue 2
&1E     VDU queue 3
&1F     VDU queue 4
&20     VDU queue 5
&21     VDU queue 6
&22     VDU queue 7
&23     VDU queue 8

    The VDU queue depth is read using OS_Byte,218, and again is useless inside
    a TaskWindow because it doesn't try very hard.

&24     Graphics cursor X
&25     Graphics cursor X MSB
&26     Graphics cursor Y
&27     Graphics cursor Y MSB
&4A     Text cursor address
&4B     Text cursor address MSB
&4C     Text window byte width
&4D     Text window byte width MSB

    As with all MSB pairs, the intention is to read the first and hence also
    get the "MSB" in R2, which for compatibility reasons should be combined
    with ORR R1,R1,R2,LSL#8 - but note that this implementation returns the
    full value for the first anyway, which is why they are not labelled "LSB".

&4E     Start of screen memory MSB

    LSB is always zero.

&4F     Bytes per character
&50     Start of display memory
&51     Start of display memory MSB
&52     Bytes per character row
&53     Bytes per character row MSB

    Although the distribution of bytes within a character row is very
    different on RISC OS, the total number of bytes is the same.

&54     Screen size MSB
&55     Current screen MODE

    Like OS_Byte,135, the screen MODE has not been a byte since RISC OS 3.50.

&57     Text foreground colour
&58     Text background colour

The following two Vars vary between the Beeb and the Master, we simulate the
M128 version despite them not being very useful:

&59     Graphics background flag
&5A     Graphics action

    On the Beeb these were the graphics foreground and background colours,
    which moved to &6D and &6E on the Master:

&59+b31 (-167) Graphics foreground colour
&5A+b31 (-166) Graphics background colour

These vars are common:

&5B     Graphics foreground action
&5C     Graphics background action
&5D     VDU address (JVec)
&5E     VDU address (JVec) MSB
&5F     Previous VDU23,0,10

    This returns the default cursor start line for the current MODE, taking
    into account Teletext modes, so can be used for resetting the cursor. It
    does not keep a record of the actual previous value. Note that RISC OS
    uses a slightly different value in MODE7 than the earlier machines.

&60     Maximum logical colour
&61     Maximum pixel in byte (or 0)
&62     Left pixel mask
&63     Right pixel mask

    For compatibility with the Beeb, these masks are BYTES for 1-8bpp, but
    words otherwise.

&64     Text input cursor X
&65     Text input cursor Y

Vars &66-&6E changed from the Beeb to the Master, first the M128 vars:

&66     VDU23,16 (and cursor) flags

    This returns the full 32bit CursorFlags (which can also be read by the
    undocumented call OS_Word,10,[11]).

&67     Dot pattern

    This returns the first four bytes of the dot pattern set by VDU23,6, which
    was only a byte on the M128.

&68     Dot pattern state

    The second four bytes of the dot pattern. On the M128 this was the previous
    byte rotated by the number of bits used so far, which is not as useful.
    The dash pattern can also be read by OS_Word,10,[6].

&69     ECF flag
&6A     Foreground ECF flag
&6B     Background ECF flag

    These bytes are non-zero if an ECF has been selected. In fact they're the
    ECF number<<4.

&6C     Column 81

    This returns the top bit of CursorFlags in b7, which is set if a newline
    is pending.

&6D     Graphics foreground colour
&6E     Graphics background colour

    These were at &59 and &5A on the Beeb, so can also be read as -167 and -166.

Now the Beeb versions of those Vars. These are read if R1 b31 is set, ie R1 is
negative. If so, the bottom 8 bits are the Var number as normal. It is easier
to use negative numbers (shown in parentheses):

&66+b31 (-154) Teletext copy cursor chr
&67+b31 (-153) Font expansion state

    Always 127 and 255 respectively on RISC OS.

&68+b31 (-152) Font expansion 32-63 MSB
&69+b31 (-151) Font expansion 64-95 MSB
&6A+b31 (-150) Font expansion 96-127 MSB
&6B+b31 (-149) Font expansion 128-159 MSB
&6C+b31 (-148) Font expansion 160-223 MSB
&6D+b31 (-147) Font expansion 224-239 MSB
&6E+b31 (-146) Font expansion 240-255 MSB

    Unfortunately due to an ill-considered change in RISC OS 4.33-4.39 the "MSB"
    is insufficient on RISC OS. Var &7F has been introduced as the expansion
    LSB for this reason. So the address of chr 128 is Var(-149)*256+Var(127).
    The Beeb and Master return 0 for Var &7F, so this is backwards-compatible.

The remaining Vars are the same on all OSes:

&6F     Palette colour 0
&70     Palette colour 1
&71     Palette colour 2
&72     Palette colour 3
&73     Palette colour 4
&74     Palette colour 5
&75     Palette colour 6
&76     Palette colour 7
&77     Palette colour 8
&78     Palette colour 9
&79     Palette colour 10
&7A     Palette colour 11
&7B     Palette colour 12
&7C     Palette colour 13
&7D     Palette colour 14
&7E     Palette colour 15

    Only (potentially) useful in 4bpp and below, these return colours 0-15 for
    Beeb-compatible definitions, or 16 for steady and 17 for flashing colours.

&7F     Font expansion LSB (new!)

    The LSB for the Font Expansion MSBs in Vars &68-&6E. The Beeb and Master
    return 0 for this var.

The Beeb Vars that cannot be provided or reasonably simulated return 0:

&1A     offset into current chr cell (not applicable)
&28-49  general scratch space (not useful)
&56     screen memory type (not applicable)

Versions
--------
0.01 (24 Oct 2020)  Working
0.02 (24 May 2021)  Correction to text colours and added Var &7F
0.03 (16 Jun 2021)  Recognition of TTL colours

 nemo 2020-2021