SPECIAL CALLS (aka XIOs) for the VBXE BIOS

INDEX

I.   General functions: XIO 96, 111, 112, 113, 114
II.  Hardware specific functions: XIO 107, 108, 109
III. Terminal functions: XIO 97, 98, 99
IV.  Palette functions: XIO 100, 101, 102
V.   Drawing text in pixel modes: XIO 103, 104, 105

I. GENERAL FUNCTIONS
--------------------

a) XIO 96,#n,0,0,"S2:"

where "n" is a number of a closed IOCB channel.

If this call succeeds, and returns a value of 96 in the accumulator (or ICAX6), then the driver is present in the memory and the new functions are available.

In ICAX3/4 a pointer is returned that points to the internal function table (also pointed to by the symbol _RAWCON under SpartaDOS X):

+$00 - number of entries below (9):

+$01 - enable the display mode defined by ICAX1Z (attributes) and ICAX2Z (mode number).
+$03 - disable the mode.
+$05 - shut off the display temporarily.
+$07 - reactivate after a temporary shutoff.
+$09 - clear screen and reload colors from 709/710.
+$0b - reload colors only.
+$0d - get character from CRSCOL/CRSROW, return its value in A and store its color to 708.
+$0f - print char given in A at CRSCOL/CRSROW.
+$11 - call special operation (XIO) defined by parameters passed in ZIOCB.

The ENABLE function returns status in ICSTZ ($23). It not always was so, versions before 1.02 did not touch ICSTZ at all, so to avoid getting garbage there you should zero out ICSTZ before the call.

GET and PUT functions DO NOT automatically advance the cursor to next available position, nor they sanity-check given coordinates etc. These are simple, raw, lowest possible level GET and PUT functions (this is a BIOS, at last). It is programmer's responsibility to verify if the parameters passed to are valid, if they are not, there will be no errors, just a crash. So, contrary to the regular CIO calls, these two "unsafe". But they are also much faster.

ZIOCB parameters relevant to the last vector are the following locations:

* ICCOMZ $22 - opcode (e.g. 96 for XIO 96)
* ICAX1Z $2A - aux1 (3rd parameter for XIO)
* ICAX2Z $2B - aux2 (4th parameter for XIO)
* ICAX5Z $2E - aux5, IOCB number (only required for XIO 103 called this way).

When calling XIO via CIO, not via _RAWCON vector, you do not care about ZIOCB, just pass the parameters the usual way.

b) XIO 111,#n,0,0,"S2:"

This function is available as of driver version 1.01 (it is harmless to call it on older versions, where this opcode does nothing). In VBXE text mode, when called, it switches to a 'fast' text output routine. While in this mode, you cannot change fonts or change global colors of the screen. You still can change local character color though. In pixel modes this function does nothing.

The 'fast' mode may be disabled by re-enabling a VBXE text mode, or by calling XIO 112 (below).

c) XIO 112,#n,0,0,"S2:"

Disables the 'fast' text output mode previously enabled by XIO 111. In pixel mode this call does nothing.

d) XIO 113,#n,m,0,"S2:"

When m=0, loading a 256-character font will not switch the palette to 64 colors. When m=1 (default), it will.

e) XIO 114,#n,0,0,"S2:"

This call is available as of driver version 1.01. It will return (in ICAX2) a byte of information on the default size of a character cell, encoded as follows:

- bits 7-4: character width, less 2
- bits 3-0: character heigth, less 2

When any of the returned values is 0, the information is not available or not applicable. Values of $F are reserved. Therefore, the maximum character cell size possible here is 16x16 pixels.

This allows programs to select and load fonts depending on what is the character cell allowed by the video hardware. For example, the S_VBXE driver returns $66, for standard modes, which means that the character cell is 8x8 pixels (both sizes are decremented by 2), and $65 for "condensed" modes, where the character cell is 8x7. Software 80-column drivers may return 2x6 (character cell 4x8), and 64-column ones: 3x6 (character cell 5x8), and so on.

On loading fonts, see XIO 103.

II. HARDWARE SPECIFIC FUNCTIONS
-------------------------------

a) XIO 107,#n,0,0,"S2:"

returns the XDL address in ICAX3-5. You can then change or replace the default XDL in order to e.g. add an additional line to the screen or modify default in any other way.

Past the address pointed to by this address there is at least 512 bytes of free space for your XDL.

NOTICE: the value returned is NOT an Atari CPU address, it is an address inside the VBXE video RAM.

b) XIO 108,#n,v,p,"S2:"

ICAX1Z contains new VCTRL register value, ICAX2Z new overlay priority over ANTIC/GTIA display, as described in the VBXE programming manual (in the XDL section). The default priority is $00, VBXE display completely covered by ANTIC (which is kept off by the VBXE BIOS, by the way).

The new priority will immediately be taken into account. Old priority value is stored back in ICAX2, and old VCTRL in ICAX1 upon return of the call.

The priority can be reset to defaults by calling the "S2:" device init vector, and this means that also hitting the RESET key will automatically restore default priority.

c) XIO 109,#n,lo,hi,"S2:"

XIO 109 allows to allocate VRAM. The values of lo and hi combine into parameter 'size' according to the following (and hardly surprising) formula:

size = lo + 256 * hi

In other words, lo is the low byte of size, and hi is the high byte of it. The size parameter itself specifies the amount of PAGES (256 bytes each) of video memory to allocate. If there is not enough memory to satisfy the request, error 147 is returned. Otherwise a pointer to the allocated block is returned in ICAX1/ICAX2 (low/high of the first allocated page number).

There are two special values of size:

$0000 - deallocates all the memory down to the default value. Notice that pixel modes allocate some amount of VRAM (up to 80 KB) for themselves. If a program requests the BIOS to deallocate memory, it will release everything that was allocated over the default amount. All the memory is released when a program changes the screen mode.

$FFFF - returns the current amount of free VRAM (counted in pages) in ICAX1/2.

NOTICE: the BIOS code resides in VRAM as well, therefore even if "nothing" is allocated, the total amount of free VRAM will be 16 KB smaller than expected.

NOTICE: in VBXE core "R" the amount of free VRAM may be yet smaller, it depends on the amount of extended RAM (which shares space with the upper 256 KB of VRAM) the DOS had allocated prior to loading VBXE BIOS. Therefore, if you use it with the VBXE core "R", load the VBXE BIOS last in your CONFIG.SYS.

III. TERMINAL FUNCTIONS
-----------------------

XIO f,#n,a,l,"S2:"

where:

- f is the function number:

97 - scroll one line up
98 - scroll one line down
99 - clear the specified line

- n is the channel number being in use for the VBXE text mode

- a is the I/O access code, it must be the same, as it was used to OPEN the screen for "S2:"

- l is the line number

XIO 97 & 98: The screen will scroll one line up (97) or down (98) starting at the top line number "l", and ending at the bottom line number contained in BOTSCR ($02BF or 703), less 1. BOTSCR normally contains a value of 24, so that if you give 0 as the "l" in the XIO 97 call, the entire screen will scroll one line up.

The driver uses the VBXE blitter to perform the operations so that they are rather fast.

These functions are primarily designed for text modes, but will also work in pixel modes. On that you can see how fast the VBXE blitter is: it takes it about 15325 CPU clocks to scroll the entire "standard" (320x192/256, 60 KB) display, which is 6,76 MB/s (yes, megabytes per second).

IV. PALETTE SUPPORT
-------------------

XIO f,#n,0,m,"S2:"

where:

f - is the function number:

100 - reset palette to default. "m" should be 0.

101 - write palette from Atari memory to VBXE. "m" is the high byte of the palette adress in Atari's memory.

102 - read palette from VBXE to Atari memory. "m" as above.

The palette format is 256 bytes of R, 256 bytes of G and 256 bytes of B on consecutive pages. The function 101 replaces the default colour palette, so that if you want the real default later, you must reload it back. So the best choice is to read the current palette first, load own one, and after you are done with the program, to reload the initial palette back before exiting.

The function 101 does not work in grayscale modes, as there is no real palette to replace in that mode.

V. DRAWING TEXT IN PIXEL MODES
------------------------------

XIO f,#n,a,b,"S2:"

where for f stands for the folowing:

103 - load font specified by "b". The "b" is CHBAS value for font stored in the memory. It works like CHBAS in character modes (see the main document for details). "a" should be 0. NOTE: this must be invoked AFTER the screen mode has been initialized (in other words: screen OPEN loads system font).

XIO 103 also works in text mode, and it is actually a preferred method of changing fonts which is "portable" across different video drivers - as not every driver/hardware combo is fast enough to make the CHBAS method available. See also XIO 114.

104 - reserved function.

105 - character specified by ASCII value "b" will be drawn at X/Y coordinates specified by CRSCOL and CRSROW (modified by POSITION keyword in BASIC or directly accessible in assembly). The color should be stored in FILDAT $02FD. "a" is mode:

- bits 0-2 specify the exact method of drawing, or blitmode, as defined in the VBXE programming manual. I guess you will find modes 0 and 1 most useful.

- bit 3 specifies printing mode: 0 normal, 1 proportional

- bits 4-7 define text attributes:

* 7 = 1 - inverse video (useful when your font contains 256 characters)
* 6 = 1 - underline (this adds one line to the char height)
* 5 = 1 - option bit:
          for proportional mode: print condensed
          for normal mode: reserved, does nothing
* 4 - reserved

After the character is drawn, its width is automatically added to the X coordinate, but the Y coordinate is unchanged: you have to decide yourself, what to do, when the text reaches the right margin. Remember that underlined text is 1 line higher than normal one.

Normally the text never wraps to the left margin, when it spans the right one: subsequent characters will be "drawn" off screen.
