BBC BASIC Host VDU Interface Specification ========================================== This document specifies how a compliant BBC BASIC implementation interfaces with the VDU system of the platform it is running on. Failure to implement the functionality as specified will result in a broken, non-compliant implementation. Definitions =========== MUST the implementation is required to do this, failure to do so is a MUST ALWAYS broken implementation. MUST NOT the implementation is required to not do this, failure is a broken MUST NEVER implementation. SHOULD the implementation is not required to do this, but it is recommended to do so. Failure to do so is not a broken implementation, but SHOULD will usually be qualified by MUST and/or MUST NOT to specifiy how the functionality is required to be implemented. MAY the implementation may optionally do this, neither implementing or not implementing the feature results in a broken implementation, though MAY will usually be qualified with MUST and/or MUST NOT to specify how the optional functionaly is required to be implemented. VDU Commands ============ BASIC MUST translate all VDU commands to the following sequences of characters sent to the VDU. BASIC does not know and is not able to know what interpretation the VDU driver may put on any particular VDU sequence. BASIC MUST NOT impose any interpretation on any commands and MUST NOT impose any expectations of what the VDU driver's actions may or may not be. It is SOLELY the responsibility of the VDU driver to determine if any particular VDU sequence is supported and what functions any sequences perform. VDU Command - Required Functionality ----------------------------------------------- CLS - VDU 12 CLG - VDU 16 GCOL n opt - VDU 18, 0, n GCOL m,n - VDU 18, m, n COLOUR n - VDU 17, n COLOUR l,p opt - VDU 19, l, p, 0, 0, 0 COLOUR l,r,g,b opt - VDU 19, l,16, r, g, b if l>=0 COLOUR l,r,g,b opt - VDU 19, l,24, r, g, b if l<0 MODE n - VDU 22, n MOVE x,y - VDU 25, 4, x AND 255, x DIV 256, y AND 255, y DIV 256 DRAW x,y - VDU 25, 5, x AND 255, x DIV 256, y AND 255, y DIV 256 PLOT x,y opt - VDU 25, 69,x AND 255, x DIV 256, y AND 255, y DIV 256 PLOT k,x,y - VDU 25, k, x AND 255, x DIV 256, y AND 255, y DIV 256 TAB(x,y) - VDU 31, x, y VDU arguments - VDU arguments Those listed as 'opt' are optional additional syntax, with their required functionality. An implementation MAY generate an error instead of implementing them. If an implementation wishes to not pass any non-optional commands to the VDU driver it SHOULD parse all the parameters and then give an error. For example: PLOT 69,1/0,10 SHOULD give 'Divide by zero' rather than 'Unsupported'. MODE MAY interrogate the VDU driver to check if program memory would be used by the new screen mode, and disallow it by generating the 'Bad MODE' (ERR 25) error instead of issuing the VDU sequence. Note, this is BASIC doing the enquiry and generating a local error, NOT the VDU driver. The VDU driver MUST select whatever MODE it has been instructed to, falling back to an alternative MODE if the requested MODE is unavailable. The VDU driver MUST NOT generate any errors. The following are optional commands, if they are implemented they MUST be translated to the listed VDU sequences. VDU Command - Required Functionality ----------------------------------------------- OFF - VDU 23, 1, 0, 0, 0, 0, 0, 0, 0, 0 ON - VDU 23, 1, 1, 0, 0, 0, 0, 0, 0, 0 ORIGIN x,y - VDU 29, x AND 255, x DIV 256, y AND 255, y DIV 256 MOVE BY x,y - PLOT 0 ,x,y DRAW BY x,y - PLOT 1 ,x,y PLOT BY x,y - PLOT 65,x,y CIRCLE x,y,r - MOVE x,y:PLOT 145,r,0 CIRCLE FILL x,y,r - MOVE x,y:PLOT 153,r,0 ELLIPSE x,y,a,b - MOVE x,y:PLOT 0,a,0:PLOT 193,0,b ELLIPSE FILL - MOVE x,y:PLOT 0,a,0:PLOT 201,0,b FILL x,y - PLOT 133,x,y FILL BY x,y - PLOT 129,x,y LINE x1,y1,x2,y2 - MOVE x1,y1:DRAW x2,y2 RECTANGLE x,y,w - MOVE x,y:PLOT 13,x+w,y:PLOT 13,x+w,y+w:PLOT 13,x,y+w:PLOT 13,x,y RECTANGLE x,y,w,h - MOVE x,y:PLOT 13,x+w,y:PLOT 13,x+w,y+h:PLOT 13,x,y+h:PLOT 13,x,y RECTANGLE FILL x,y,w - MOVE x,y :PLOT 101,x+w,y+w RECTANGLE FILL x,y,w,h - MOVE x,y :PLOT 101,x+w,y+h RECTANGLE x1,y1,w TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+w:PLOT 190,x2,y2 - copy area RECTANGLE x1,y1,w,h TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+h:PLOT 190,x2,y2 - copy area RECTANGLE FILL x1,y1,w TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+w:PLOT 189,x2,y2 - move area RECTANGLE FILL x1,y1,w,h TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+h:PLOT 189,x2,y2 - move area RECTANGLE MOVE x1,y1,w TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+w:PLOT 189,x2,y2 - move area RECTANGLE MOVE x1,y1,w,h TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+h:PLOT 189,x2,y2 - move area RECTANGLE SWAP x1,y1,w TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+w:PLOT 191,x2,y2 - swap area RECTANGLE SWAP x1,y1,w,h TO x2,y2 - MOVE x1,y1:MOVE x1+w,y1+h:PLOT 191,x2,y2 - swap area TINT a,t - VDU 23,17,a,t,0,0,0,0,0,0 COLOUR c TINT t - VDU 17,c, 23,17,0+(c DIV 128),t,0,0,0,0,0,0 GCOL c TINT t - VDU 18,0,c,23,17,2+(c DIV 128),t,0,0,0,0,0,0 GCOL a,c TINT t - VDU 18,a,c,23,17,2+(c DIV 128),t,0,0,0,0,0,0 VDU Driver ========== It is SOLELY the responsibility of the VDU driver to determine what VDU sequences mean, what are supported, and to translate them into whatever is required for the host system to perform the required actions. BASIC does not impose any expectation on what any VDU sequences does, and has no ability to know what they do. The expectations of any particular actions are those of the programmer writing a BASIC program, NOT the BASIC interpreter itself. The VDU driver MUST NOT generate any errors. Anything unsupported MUST simply be swallowed and ignored. Fundamental core level ---------------------- VDU 10,13 MUST move the cursor to column zero of the next line. VDU 13,10 MUST move the cursor to column zero of the next line. CHR$32-CHR$95 MUST be standard ASCII printable characters. Basic level ----------- VDU 0 MUST be ignored. VDU 8 MUST move the text cursor backwards, unless at the start of the line. If at the start of the line it SHOULD wrap to the end of the next line above. If it wraps, wrapping from the top line SHOULD cause the display to scroll downwards. VDU 9 MUST move the text cursor forwards, unless at the end of the line. If at the end of the line it SHOULD wrap to the start of the next line below. If it wraps, wrapping from the bottom line MUST cause the display to scroll upwards. VDU 10 SHOULD cause the text cursor to move directly down to the next line without changing the text column. If doing so and moving down from the bottom line it MUST cause the display to scroll upwards. VDU 11 SHOULD cause the text cursor to move directly up to the previous line without changing the text column. If doing so and moving up from the top line it SHOULD cause the display to scroll downwards. VDU 12 SHOULD cause the display to clear and if it does so it MUST leave the cursor at (0,0) in the top lefthand corner. VDU 13 MUST move the cursor to column 0 of the current line. VDU 27 MUST be ignored and passed to the underlying system to allow it to implement CSI escape sequences. VDU 30 SHOULD move the cursor to (0,0) at the top lefthand corner. VDU 31,x,y SHOULD move the cursor to (x,y) counting from (0,0) at the top lefthand corner. VDU 127 SHOULD move the cursor left, removing the displayed character. Full text implementation ------------------------ VDU 0 MUST be ignored. VDU 6 MUST enable all VDU actions. VDU 8 MUST move cursor left. VDU 9 MUST move cursor right. VDU 10 MUST move cursor down. VDU 11 MUST move cursor up. VDU 12 MUST clear the display, leaving the cursor at (0,0). VDU 13 MUST move to column 0 on the same line. VDU 17,n MUST select text colour n. VDU 20 MUST select default colours. VDU 21 MUST temporarily halt all VDU actions except VDU 6. VDU 22,n SHOULD select a new screen mode and MUST clear the display, reset colours, reset windows, reset axes, turn cursor on, end paged mode. VDU 26 MUST reset all windows if VDU 28 or VDU 24 are implemented. VDU 27 MUST be ignored and passed directly to the underlying system. VDU 28,l,b,r,t SHOULD define a text window. VDU 30 MUST move the cursor to (0,0). VDU 31,x,y MUST move the cursor to (x,y). VDU 127 MUST move left, removing the displayed character. Full graphics implementation ---------------------------- VDU 16 MUST clear the graphics window. VDU 18,a,c MUST set the graphics colours. VDU 19,l,p,r,g,b MUST set the palette if a palette exists. VDU 24,xl,xh,bl,bh,rl,rh,tl,th SHOULD define a graphics window. VDU 25,k,xl,xh,yl,yh MUST perform a PLOT action. VDU 29,xl,xh,yl,yh MUST set the graphics origin. Other ----- VDU 1,n Send n to the printer driver. VDU 2 Start a print job, all following 8-13, 32+ echoed to printer. VDU 3 End a print job. VDU 4 Text is displayed at text cursor. VDU 5 Text is displayed at graphics cursor. VDU 7 Generate a BELL sound. VDU 14 Start 'paged' mode. VDU 15 End 'paged' mode. VDU 23,n,a,b,c,d,e,f,g,h Define character or control functions. VDU 23,1,n,x,x,x,x,x,x,x Turn cursor off (n=0) or on (n=1). VDU 1, 2 and 3 are normally implemented by the output stream handler, not the VDU driver itself which is called by the output stream handler. Some implementations use VDU 1,n to pass the character n to the underlying display handler, bypassing the VDU driver. Colours ======= If there is no palette, VDU 17 (COLOUR) and VDU 18 (GCOL) MUST select physical colours using physical colour numbers, and VDU 19 MUST be ignored. If there is a palette, VDU 17 and VDU 18 MUST select logical colours, and VDU 19 MUST be used to select the physical colours they are displayed as. These notes do not cover colour selection in screen modes with 256 or more colours as they are difficult to control purely through the VDU stream. Physical colours are a 6-bit number which MUST be the closest match to RGB numbering. * VDU 19 uses the 6-bit physical colour number and MUST ignore b6 and b7 of the passed value. * VDU 17 (COLOUR) and VDU 18 (GCOL) use the 6-bit physical colour number with control values in bit 6 and bit 7. The 8-bit physical colour number is a bitmap which MUST be of the following format: +-+-+-+-+-+-+-+-+ |L|D|E|F|I|B|G|R| +-+-+-+-+-+-+-+-+ | | | | | | | +-Red | | | | | | +---Green | | | | | +-----Blue | | | | +-------Intensity or Flash | | | +---------Flash | | +-----------Extension 0 0-------------Select foreground colour 0 1-------------Extension 1 0-------------Select background colour 1 1-------------Select border colour where supported On systems where Bright is selectable, bit 3 MUST select Intensity and bit 4 MUST select Flash (eg ANSI, ZX Spectrum). On systems with Flash but no Bright, bit 3 is Flash (eg BBC, RISC OS). Extensions are implementation specific. For examples, the ZX Spectrum uses bit 5 and 6 to independently select Flash/Bright and RGB, and ANSI drivers select underline and inverse. On systems with Bright selectable (eg ANSI, ZX Spectrum), "Dim White" and "Bright Black" are types of grey, the greyscale colours MUST be: 0:Black, 8:Dim Gray, 7:Bright Grey, 15:White On some systems the hardware is not capable of Bright Black. This ordering means that the greyscale progression remains consistant: 0:Black, 8:Black, 7:Bright Grey, 15:White Where COLOUR 192+n is supported, that sets the border colour to n. The BBC and RISC OS uses b3=flash, whereas all other platforms use b4=flash. For visual compatibility, programs should use 0-7 for non-flashing colours and 24-31 for flashing colours. On the BBC/RISC OS these will be standard intensity flashing colours, on other platforms these will be bright flashing colours where supported. Where individual control is needed in platform-independent code, the following coding method should be used: os% set from OSBYTE 0 IF os%<8 THEN flash%=8:bright%=16 ELSE flash%=16:bright%=8 COLOUR n :REM select the specified colour COLOUR bright%+n :REM select a bright colour COLOUR flash%+n :REM select a flashing colour COLOUR flash%+bright%+n :REM select a bright flashing colour PLOT numbers ============ The PLOT action used by VDU 25 is a bitmap which MUST be of the following format: +-+-+-+-+-+-+-+-+ |7|6|5|4|3|2|1 0| +-+-+-+-+-+-+-+-+ | | | | | | | | | | | | | | +-+---00 Move | | | | | | 01 Plot with foreground GCOL colour and action | | | | | | 10 Plot in inverse colour, as though using GCOL 4 | | | | | | 11 Plot with background GCOL colour and action | | | | | +------- 0 Relative coordinates | | | | | 1 Absolute coordinates | | | | +--------- 0 Last point not omitted | | | | 1 Last point omitted | | | +----------- 0 Solid line | | | 1 Dot-dash line | | +------------- 0 First point not omitted | | 1 First point omitted +-+---------------00 Draw line 01 Plot points and areas 1x Fill and other actions VDU 25 MUST implement PLOT &04 (MOVE), PLOT &05 (DRAW) and PLOT &45 (plot a point). PLOT &F0-&FF MUST ALWAYS be available for the user program, the VDU driver MUST NEVER do anything with them. Coordinate system ================= The text coordinate system MUST be numbered from (0,0) in the top lefthand corner of the screen or text window. The coordinates MUST be (x,y) with x incrementing to the right and y incrementing downwards. A single character unit is a single increment in coordinates. The VDU driver MAY implement the VDU 23 sequences that redefine the directions of "up", "down", "left" and "right" for the text coordinate system. If it does so, VDU 22 (MODE) MUST reset the coordinate system to their natural directions for English text and maths graphics. The graphics coordinate system MUST be numbered from (0,0) in the bottom lefthand corner of the screen or graphics window. The coordinates MUST be (x,y) with x incrementing to the right and y incrementing upwards. The graphics coordinates use logical pixels regardless of the number of physical pixels or colour depth, the VDU driver MUST translate those logical pixels to the physical coordinate addressing required for the underlying system. The logical- to-physical pixel addressing MUST use shifts, and MUST NOT use divides. For example, a 60x24-character screen MUST have 60<=&300 gfX%=gfW%:REPEAT:gfX%=gfX%*2:UNTIL gfX%>=&400 : Examples: Text Physical Logical Text Physical Logical Columns Pixels Pixels Rows Pixels Pixels 20 160 1280 16 128 1024 32 256 1024 24 192 768 40 320 1280 25 200 800 if not striped 64 512 1024 25 250 1000 if striped 80 640 1280 32 256 1024 132 1056 2112 64 512 1024 80x32 characters -> 640 x 256 physical pixels -> 1280 x 1024 logical pixels 80x25 characters -> 640 x 200 physical pixels -> 1280 x 800 logical pixels 80x24 characters -> 640 x 192 physical pixels -> 1280 x 768 logical pixels 40x32 characters -> 320 x 256 physical pixels -> 1280 x 1024 logical pixels 40x25 characters -> 320 x 200 physical pixels -> 1280 x 800 non-striped pixels 40x25 characters -> 320 x 200 physical pixels -> 1280 x 1000 striped pixels 40x24 characters -> 320 x 192 physical pixels -> 1280 x 768 logical pixels 64x24 characters -> 512 x 192 physical pixels -> 1024 x 768 logical pixels 32x24 characters -> 256 x 192 physical pixels -> 1024 x 768 logical pixels 32x16 characters -> 256 x 128 physical pixels -> 1024 x 512 logical pixels Known exceptions ---------------- RISC OS MODE 22 fails to use a logical pixel mapping that matches this formula. The BBC BASIC for Windows VDU driver is subtly different. If your VDU driver uses the BBC BASIC for Windows scheme your host MUST return (INKEY-256 AND &DB)=&53 as TRUE, if your host returns (INKEY-256 AND &DB)=&53 as TRUE then your VDU driver MUST use the BBC BASIC for Windows scheme. The normal case is not to use the BBC BASIC for Windows scheme, and your host MUST return (INKEY-256 AND &DB)=&53 as FALSE. Reading VDU state ================= The following functions call the VDU driver to read various information. BASIC MUST implement the functions, BASIC MUST NOT generate an error if they are used. The VDU driver MUST NOT generate any errors, the VDU driver MAY return null values if they are unsupported. VDU Function - Required Functionality ----------------------------------------------- POS - Returns text column counting from 0, or 0 if unimplemented VPOS - Returns text row counting from 0, or 0 if unimplemented POINT(x,y) - Returns the colour at the graphics point (x,y): the logical colour on paletted systems, or: the physical colour on non-paletted systems, or: -1 if the point is off the screen or outside the graphics window, or: -1 if the call is unsupported. BASIC MAY generate an error if the following functions are not implemented. If they are implemented they MUST perform the listed actions. The VDU driver MUST NOT generate an error when the function is called, the VDU driver MAY return null values if the function is not implemented. VDU Function - Required Functionality ----------------------------------------------- MODE - Returns the current screen MODE, such that MODE MODE reselects the current screen MODE. TINT(x,y) - Returns the tint at the graphics point (x,y) VDU offset - Returns the VDU variable at offset. Text and graphics windows ========================= Text at graphics cursor =======================