VDU 23

Description

Defines a character or performs various miscellaneous VDU functions. Unrecognised or unimplemented commands are passed to VDUV, on platforms where VDUV is implemented.

VDU 23

Syntax	VDU 23,<numeric>,<numeric>, <numeric>,<numeric>,<numeric>, <numeric>,<numeric>,<numeric>, <numeric> In BASIC IV onwards, | can be used to terminate a VDU sequence with 9 zeroes, eg VDU 23;<numeric>,<numeric>|
Character stream (hex)	17 <action> <param1> <param2> <param3> <param4> <param5> <param6> <param7> <param8>
Description	Defines a character or performs various miscellaneous VDU functions.

Summary

VDU 23,0 - CRTC register programming VDU 23,1 - Cursor control VDU 23,2 - Define ECF pattern 1 VDU 23,3 - Define ECF pattern 2 VDU 23,4 - Define ECF pattern 3 VDU 23,5 - Define ECF pattern 4 VDU 23,6 - Set dotted line pattern VDU 23,7 - Scroll rectangle on screen VDU 23,8 - Clear block VDU 23,9 - Set flash mark period VDU 23,10 - Set flash space period VDU 23,11 - Set default ECF patterns VDU 23,12 - Set simple ECF pattern 1 VDU 23,13 - Set simple ECF pattern 2 VDU 23,14 - Set simple ECF pattern 3 VDU 23,15 - Set simple ECF pattern 4

VDU 23,16 - Define cursor movement VDU 23,17 - Set subsidary colour effects VDU 23,18 - Set Teletext display characteristics VDU 23,19 - Unused VDU 23,20 - Unused VDU 23,21 - Unused VDU 23,22 - Select user defined screen mode VDU 23,23 - Set linedraw thickness VDU 23,24 - Set character spacing adjustment VDU 23,25 - Set anti-aliasing transfer function VDU 23,26 - Select font VDU 23,27 - Sprite operation VDU 23,28 - Reserved for user calls, passed to VDUV VDU 23,29 - Reserved for user calls, passed to VDUV VDU 23,30 - Reserved for user calls, passed to VDUV VDU 23,31 - Reserved for user calls, passed to VDUV VDU 23,32-255 - Define character

VDU 23,32-255 - Define character

VDU 23,32-255,row1,row2,row3,row4,row5,row6,row7,row8 (OS 0.10 onwards)

In this type of command, all nine parameters are used.

The first parameter selects the character to be defined, and the other eight encode an 8×8 monochrome bitmap that OSWRCH will print for that character in future (through VDUCHR).

The first byte of the bitmap (the second parameter) carries the top row of the bitmap. The most significant bit corresponds to the leftmost column. A binary 1 represents the foreground COLOUR (usually white), binary 0 the background COLOUR (usually black.)

For example, the stick figure character printed in the User Guide (and above) can be defined with the following sequence:

VDU 23,224,28,28,8,127,8,20,34,65

When the character is printed, such as by

VDU 224

the figure will typically appear in white on a black background, that is, in the negative compared to the image above.

Depending on the font explode state a number of other characters will simultaneously be assigned that bitmap. The font is not ordinarily transferred to the printer.

In MODE 7 the user defined character has no effect on the Teletext hardware, but the definition is stored for later use. In the bitmapped MODEs the new definition does not change the appearance of copies of that character already on screen; OSBYTE &87 will no longer recognise them as that character.

The character definition can be read with OSWORD &0A. Note that character 127 can be defined with VDU 23,127, but can never be printed. The definition can be read with OSWORD &0A.

VDU 23,0 - CRTC register programming

VDU 23,0,register,value,0,0,0,0,0,0 (OS 0.10 onwards)

In this command, VDU 23 programs the 6845 register <register> (or emulated register) with value <value>. For the functions of each register, see CRTC.

Platforms without a hardware 6845 CRTC, such as RISC OS and BBC BASIC for Windows, partly emulate the CRTC so that cursor appearance and screen interlace can be controlled with VDU 23. The statement VDU 23;8202;0;0;0; which appears in many BBC Micro programs, also turns the cursor off in RISC OS, as it expands to VDU 23,0,10,32;0;0;0.

Note that this command can 'unprogram' the current MODE so that a full DRAM refresh is no longer performed. This coupled with a tight machine code loop erases most of the I/O processor's memory, with disastrous results.

Some BASIC programs contain embedded VDU 23 sequences in REM statements to protect themselves against being LISTed; for instance, Ducksoft's Tom Pinone Poker.

Some VDU drivers implement additional "pseudo" higher-numbered registers to implement additional functions.

VDU 23,1 - Cursor control

VDU 23,1,state,0,0,0,0,0,0,0 (OS 1.00 onwards)

This subcommand turns the cursor on or off. The defined values of <state> are:

0 - off 1 - on

2 - steady (MOS 3 onwards) 3 - flashing (MOS 3 onwards)

Note that the cursor will re-appear if cursor editing is used.

VDU 23,2-5 - Define ECF pattern

VDU 23,2-5,row1,row2,row3,row4,row5,row6,row7,row8 (GXR, MOS 3.00 onwards, not BBFW)

This defines Extended Colour Fill patterns (ECFs) 1 to 4. They are selectable for plotting with GCOL 16*ECF,0.

As the fill patterns are mapped to the pixel layout of each screen mode, they are defined differently for different colour depths. On RISC OS, ECF patterns can be defined in BBC/Master compatible mode or in RISC OS native mode. To change between the modes, VDU 23,17,4 is used.

Numbering the pixels of each row as 76543210 give the following arrangement:

• 2-colour modes: 7,6,5,4,3,2,1,0 (BBC) 0,1,2,3,4,5,6,7 (RISC OS)
• 4-colour modes: 73,62,51,40 (BBC) 10,32,54,76 (RISC OS)
• 16-colour modes: 7531,6420 (BBC) 3210,7654 (RISC OS)
• 256-colour modes: 76543210 (BBC) 76543210 (RISC OS)

The ECFs are readable with OSWORD 10,2-5.

VDU 23,6 - Set dotted line pattern

VDU 23,6,n1,n2,n3,n4,n5,n6,n7,n8 (GXR, MOS 3.00 onwards, not BBFW)

This sets the dotted line pattern used by dotted PLOT commands. The pattern length is set with *FX163,242. The default is &AA, length 8, as prior to MOS 3.00. The pattern is readable with OSWORD 10,6, and the repeat length is read with OSBYTE 163,242.

VDU 23,7 - Scroll rectangle on screen

VDU 23,7,extent,direction,movement,0,0,0,0,0 (OS 3.00 onwards)

This command will scroll the whole screen, or the current text window, in any direction.

extent=0 - scroll the current text window extent=1 - scroll the entire screen
direction=0 - scroll right direction=1 - scroll left direction=2 - scroll down direction=3 - scroll up	direction=4 - scroll in positive X direction direction=5 - scroll in negative X direction direction=6 - scroll in positive Y direction direction=7 - scroll in negative Y direction
movement=0 - scroll by 1 character cell movement=1 - scroll by 1 character cell vertically, or 1 byte horizontally (not BBFW)

When scrolling by a byte horizontally, the movement depends on the colour depth of the current mode:

8 pixels in 2-colour modes 4 pixels in 4-colour modes 2 pixels in 16-colour modes 1 pixel in 256-colour modes

Note that the cursor is never moved.

VDU 23,8 - Clear block

VDU 23,8,t1,t2,x1,y1,x2,y2,0,0 (OS 3.00 onwards, not BBFW)

This will clear a block of the current text window to the current text background colour.

• <t1> and <t2> define the type of block to be cleared
• <x1>,<y1> defines the start position of the block as specified by <t1>
• <x2>,<y2> defines the end position of the block as specified by <t2>

The <t1> and <t2> control bytes specify the location as:

0 - top left of text window 4 - left end of cursor line 8 - bottom left of text window

1 - top of cursor column 5 - cursor position 9 - bottom of cursor column

2 - off top right of text window 6 - off right of cursor line 10 - off bottom right of text window

Note that 'left', 'up', etc are dependent on the direction of cursor movement as defined with VDU 23,16.

<x1>,<y1>,<x2>,<y2> are from the positions specified by <t1> and <t2> and determine the start and end of the block to be cleared. If <t1> and <t2> are both 0, then <x1>,<y1>,<x2>,<y2> specify a block within the current text window in the same manner as VDU 28 defines the text window.

Values of <t1> and <t2> other than those listed produce undefined results.

No clearing will occur if the end point is before the start point.

VDU 23,9 - Set flash mark period

VDU 23,9,period,0,0,0,0,0,0,0 (OS 3.00 onwards, not BBFW)

Set flash mark period (the time the first flash colour is visible) in the number of VSyncs (usually 1/50s), as with *FX9. If the period is 0, the first flash colour is displayed continously.

VDU 23,10 - Set flash space period

VDU 23,10,period,0,0,0,0,0,0,0 (OS 3.00 onwards, not BBFW)

Set flash space period (the time the second flash colour is visible) in the number of VSyncs (usually 1/50s), as with *FX10. If the period is 0, the second flash colour is displayed continuously.

VDU 23,11 - Set default ECF patterns

VDU 23,11,0,0,0,0,0,0,0,0 (GXR, OS 3.00 onwards, not BBFW)

This command resets all the Extended Colour Fill (ECF) patterns to the default for the current screen mode.

VDU 23,12-15 - Set simple ECF pattern

VDU 23,12-15,a,b,c,d,e,f,g,h (GXR, OS 3.00 onwards, not BBFW)

Defines Extended Colour Fill (ECF) patterns 1 to 4 in a simpler manner than VDU 23,2-5. The ECF is defined as a repeated block of four lines of two repeated pixels.

The first pixel line uses alternative pixels of colours a,b; the second pixel line uses alternative pixels of colours c,b, etc.

VDU 23,16 - Define cursor movement

VDU 23,16,setting,mask,0,0,0,0,0,0 (OS 3.00 onwards)

This allows the direction the cursor moves after a character is printed to be specified. Normal cursor movement is to the right, and then wrapping off the edge of the screen or window and then downwards. VDU 23,16 changes these directions, and all other commands that move or set the position of the text cursor.

The new direction is specified with (old status AND mask) EOR setting, and the new status is interpreted as follows:

b7=0	normal value
b7=1	undefined
b6=0	In VDU 5 (text at graphics cursor) mode, movement beyond the edge of the window causes an implicit carriage return/linefeed to the next positive Y line.
b6=1	In VDU 5 (text at graphics cursor) mode, movement beyond the edge of the window causes no action, and the text 'continues' invisibly off the edge of the window.
b5=0	Cursor moves in positive X direction after a character is printed.
b5=1	Cursor does not move after a character is printed.
b4=0	Cursor movement in the positive Y direction past the bottom of the text window causes the text window to scroll in VDU 4 (text) mode, or moved to the opposite edge of the window in VDU 5 (text at graphics cursor) mode.
b4=1	Cursor movement in the positive Y direction past the bottom of the text window always causes the text cursor to be moved to the opposite edge of the window.

b3,b2,b1 define the cursor directon as follows:
0	0	0	X direction is right, Y direction is down
0	0	1	X direction is left, Y direction is down
0	1	0	X direction is right, Y direction is up
0	1	1	X direction is left, Y direction is up
1	0	0	X direction is down, Y direction is right
1	0	1	X direction is down, Y direction is left
1	1	0	X direction is up, Y direction is right
1	1	1	X direction is up, Y direction is left

b0=0

disables scroll protection, the text cursor moving off the positive edge of the window will always move directly to the next line, scrolling the window if neccessary.

b0=1

enables scroll protection, the text cursor moving off the positive edge of the window generates a pending newline, and waits at the edge of the window until the movement is needed. While the cursor is waiting, the cursor position returned by POS via OSBYTE &87 is the maximum column position plus one, ie the window width (eg 80 in MODE 0). If the cursor is moved elsewhere, the pending newline is abandoned, and no scrolling occurs.

VDU 23,17: Set subsidary colour effects

VDU 23,17,0-3: Set tint VDU 23,17,4: Set colour patterns VDU 23,17,5: Swap text colours

VDU 23,17,6: Set ECF origin VDU 23,17,7: Set character size

VDU 23,17,0-3: Set tint

VDU 23,17,action,tint,0,0,0,0,0,0 (Arthur 1.00 onwards, not BBFW)

Sets the additional tint for the specified colour. COLOUR and GCOL can only specify 6-bit logical colours, so in 256-colour screen modes, VDU 23,17 is used to set the lowest two bits of the colour.

action=0 - sets tint for text foreground colour action=1 - sets tint for text background colour

action=2 - sets tint for graphics foreground colour action=3 - sets tint for graphics background colour

The tint is passed in the top two bits of tint (allowing a further six bits of colour depth), so the normal range is &00, &40, &80, &80 darkest to lightest.

The BASIC keyword TINT sends a VDU 23,17 sequence.

VDU 23,17,4: Select colour patterns

VDU 23,17,4,pattern,0,0,0,0,0,0 (Arthur 1.00 onwards, not BBFW)

Selects which colour patterns future VDU 23,2-5 calls use.

• pattern=0 - use BBC/Master compatible colour patterns
• pattern=1 - use native RISC OS colour patterns

VDU 23,17,5 - Swap text colours

VDU 23,17,5,0,0,0,0,0,0,0 (Arthur 1.00 onwards, not BBFW)

After this command, characters are effectively printed in inverse video. After repeating the command, characters are effectively printed back in normal video.

VDU 23,17,6: Set ECF origin

VDU 23,17,6,x;y;0,0,0 (Arthur 1.00 onwards, not BBFW)

Set Extended Colour Fill origin. By default, EFC patterns fill aligned with the bottom lefthand corner of the screen. This command changes this so that the bottom lethand pixel of the fill pattern is aligned with the specified point.

VDU 23,17,7: Set character size and spacing

VDU 23,17,7,flags,xsize;ysize;0,0 (Arthur 1.00 onwards, not BBFW)

This allows the character size and spacing of text printed in VDU 5 mode (text at graphics cursor) to be changed. If bit 1 of flags is set, the text size is changed, if bit 2 is set, the spacing is changed. xsize and ysize are specified in pixels.

VDU 23,18 - Set Teletext display characteristics

VDU 23,18,0: Teletext transparency VDU 23,18,1: Display update VDU 23,18,2: Reveal state

VDU 23,18,3: Control character extensions VDU 23,18,4: Font select VDU 23,18,16: Display characteristics

Some implementations implement VDU 23,18 as:

• VDU 23,18,setting,mode,mask,0,0,0,0,0
  

where the newmode = (oldmode AND mask) EOR mode, which is compatible with mask=0 to write the whole setting in one go.

VDU 23,18,0,mode,mask,0,0,0,0,0: Set Teletext transparency (RISC OS 5 onwards)
mode=0:	"Text" mode: the whole display is set opaque (default)
mode=1:	"Mix" mode: foreground colours, and both foreground and background of boxed text are opaque; non-boxed background colours are all transparent
mode=2:	"Box" mode: boxed regions are opaque, others are transparent
mode=3:	"TV" mode: the whole display is set transparent
VDU 23,18,1,flags,mask,0,0,0,0,0: Set Teletext display update (RISC OS 5 onwards, RISC OS Select 4 onwards, RISC OS Pyromaniac 7.47 onwards) This sets how often the teletext screen is updated. Two bits are currently defined:
bit 0 =	suspend all automatic display update
bit 1 =	update display after every character
VDU 23,18,2,flags,mask,0,0,0,0,0: Set Teletext reveal state (RISC OS 5 onwards, Brandy, RISC OS Select 4 onwards, RISC OS Pyromaniac 7.47 onwards)
bit 0 =	if set, any concealed text will be displayed. If cleared, concealed text is concealed.
VDU 23,18,3,enable,mask,0,0,0,0,0: Set Teletext control character extension (RISC OS 5 onwards, Brandy, BBC BASIC for SDL)
bit 0 =	0: &80/&90 do nothing, 1: &80 selects black text, &90 selects black graphics
bit 1 =	0: &8E/&8F do nothing, 1: &8E selects wide text, &8F selects wide X high text
VDU 23,18,4,fontLo,fontHi,0,0,0,0,0: Set Teletext font Selects teletext character font, numbering as for SAA505x series.
VDU 23,18,16,flags,mask,0,0,0,0,0: Set Teletext display characteristics (RISC OS 5 onwards, RISC OS Select 4 onwards, RISC OS Pyromaniac 7.47 onwards)
bit 0 =	render high quality text

VDU 23,19-21 - Unused

VDU 23,19-21,a,b,c,d,e,f,g,h

Reserved for future expansion, passed to VDUV.

VDU 23,22 - Select user defined screen mode

VDU 23,22,xpixels;ypixels;xchars,ychars,colours,flags (BBFW, BBCSDL, Brandy (without flags))

This command selects a specified user-defined mode. Flags specified the following:

• b0-b3=0 - ANSI character set
• b0-b3=1 - OEM (IBM PC) character set
• b0-b3=8 - UTF-8 (Unicode) character set
• b7=0 - white text on black background
• b7=1 - black text on white background

VDU 23,23 - Set linedraw thickness

VDU 23,23,t,0,0,0,0,0,0,0 (BBFW, BBCSDL)

This command sets the width in pixels of lines drawn with PLOT commands.

VDU 23,24 - Set character spacing adjustment

VDU 23,24,a,0,0,0,0,0,0,0 (BBCSDL)

Adjusts the character spacing when a TTF or OTF font has been selected. The parameter is a signed number of pixels, negative values reduce the character spacing and positive values increase the character spacing.

VDU 23,25 - Anti-aliasing functions

VDU 23,25,0-4 - Set anti-aliasing transfer function

VDU 23,25,bitsperpixel,threshold1,...,theshold7 (Communicator, Arthur 1.00 onwards, not BBFW)

bitsperpixel specify the number of bits per pixel to use when anit-alising fonts. threshold1 to threshold7 are used to decide which output bits are produced from the original values (0 to 15). There are either one, three or seven of them depending on the number of bits per pixel. For example:

 VDU 23,25,3,2,4,6,8,10,12,14

translates the values 0-15 to 0,0,1,1,2,2,3,3,4,4,5,5,6,6,7,7.

VDU 23,25,&80+ - Set anti-aliasing pallette

VDU 23,25,&80+logical background colour,logical foreground colour,start R,start G,start B,end R,end G,end B (Communicator, Arthur 1.00 onwards, not BBFW)

This command sets the physical colour range to use when anti-aliasing between the two specified logical colours.

VDU 23,25,&FF - Set anti-aliasing pallette in 256-colour modes

VDU 23,25,&FF,logicalcolour,start R,start G,start B,end R,end G,end B (Communicator, Arthur 1.00 onwards, not BBFW)

This command sets the physical colour range to use when anti-aliasing between the background and the specified logical foreground colour in 256-colour screen modes.

VDU 23,26 - Select font

VDU 23,26,fontnumber,size,xppi,yppi,xscale,yscale,0,0,fontname,13 (Communicator, Arthur 1.00 onwards, not BBFW)

This selects the name font at the specified size for future use when selecting font fontnumber. The font name is sent as a CR-terminated sequence immediately after the VDU 23 sequence.

• fontnumber - the font handle that will be used to select the specified font
• size - font size in points
• xppi - if nonzero, specifies the number of horizontal pixels per inch
• yppi - if nonzero, specifies the number of vertical pixels per inch
• xscale - if nonzero, multiplier for font size width
• yscale - if nonzero, multiplier for font size height

xscale and yscale allow non-integer font sizes to be selected, and allow the horizontal and vertical font sizes to be different. For example, using VDU 23,26,fontnumber,1,xppi,yppi,10,12,0,0,fontname,13 will set the horizontal point size to 1*10 and the vertical font size to 1*12.

VDU 23,27 - Sprite operation

VDU 23,27,m,n,0,0,0,0,0,0 (GXR, SpriteROM, Arthur 1.00 onwards, not BBFW)

This command performs various sprite operations, depending on the value of m.

If m=0, then sprite n is selected to be plotted by subsequent PLOT &EC+k commands.

If m=1, then the rectangular area between the last two graphics points is uses to define sprite n.

VDU 23,28-31 - User calls

VDU 23,28-31,a,b,c,d,e,f,g,h (OS 0.10 onwards)

Reserved for user calls. These are defined to vector through VDUV, and will never be used for inbuilt functions.