Home XBIOSXBIOS xbios-trapxbios-trap CENTScreen XBIOS extensionCENTScreen XBIOS extension

4.5 Screen functions

Cursconf Changes or gets cursor display.
EgetPalette Reads colour palette.
EgetShift Reads shift mode register.
EsetBank Sets colour table.
EsetColor Sets colour table entry.
EsetGray Sets colour interpretation.
EsetPalette Loads colour palette.
EsetShift Sets shift mode register.
EsetSmear Sets colour smear.
Getrez Gets resolution.
Initmouse Initializes mouse pointer.
Logbase Gets address of the logical screen memory.
mon_type Gets monitor type.
Physbase Gets address of the physical screen memory.
Setcolor Sets colour.
Setpalette Selects colour palette.
Setscreen Sets the current screen resolution and base addresses.
ValidMode Validates a mode code.
VgetRGB Gets RGB-value of a colour.
VsetScreen Sets the screen resolution and base addresses.
VgetSize Gets size of the screen buffer.
VsetMask Sets transparency for True-Color.
VsetMode Sets video hardware register.
VsetRGB Sets RGB-value of a colour.
VsetSync Sets type of synchronisation for external video.
Vsync Gets vertical synchronisation signal.

4.5.1 Cursconf

Name: »cursor configuration« - Sets the working of the VT52 cursor
 
Opcode: 21
 
Syntax: int16_t Cursconf( int16_t func, int16_t rate );
 
Description: The XBIOS routine Cursconf alters the appearance and, if desired, the blink rate of the cursor. The parameter func can take the following values:
 
func Meaning
   
 0 Switch cursor off (hide it)
 1 Switch cursor on
 2 Enable cursor blink
 3 Disable cursor blink
 4 The blink rate of the cursors will be set to the value rate
 5 Returns the current blink rate

Note: The parameter rate should be used in steps of the screen repetition frequency.
 
Return value: The function only returns a defined result, namely the blink rate, if the number 5 was passed in the parameter func.
 
Availability: All TOS versions.
 
Group: Screen functions
 
See also: Binding
 

4.5.1.1 Bindings for Cursconf

C: #include <tos.h>
 
int16_t Cursconf( int16_t func, int16_t rate );
 
Assembler:
 
move.w    rate,-(sp)   ; Offset 4
move.w    func,-(sp)   ; Offset 2
move.w    #21,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #6,sp        ; Correct stack

4.5.2 EgetPalette

Name: »Get look up table registers« - Reads several entries from the colour table into a specified buffer.
 
Opcode: 85
 
Syntax: void EgetPalette( int16_t colorNum, int16_t count, int16_t *palettePtr );
 
Description: The XBIOS routine EgetPalette reads out a contiguous region from the TT colour registers.
 
Parameter Meaning
   
colorNum First colour register to be read out
count Number of colour registers to be read out
palettePtr Pointer to the colour palette to be transferred (this must be even)
Return value: The function does not return a result.
 
Availability: The function is available only in the TOS of the Atari TT.
 
Group: Screen functions
 
See also: Binding   EsetPalette
 

4.5.2.1 Bindings for EgetPalette

C: #include <tos.h>
 
void EgetPalette( int16_t colorNum, int16_t count, int16_t *palettePtr );
 
Assembler:
 
pea       palettePtr      ; Offset 6
move.w    count,-(sp)     ; Offset 4
move.w    colorNum,-(sp)  ; Offset 2
move.w    #85,-(sp)       ; Offset 0
trap      #14             ; Call XBIOS
lea       $A(sp),sp       ; Correct stack

4.5.3 EgetShift

Name: »Get current shift mode value« - Reads the shift mode register (the current mode of the video shifter).
 
Opcode: 81
 
Syntax: int16_t EgetShift( void );
 
Description: The XBIOS routine EgetShift reads out the shift mode register and returns the contents of the register.
 
Return value: The function returns the value of the register, with the following assignments:
 

Bit Meaning
0..3 Number of the colour register bank
8..10 Mode, according to Getrez
12 Hyper-mono (c.f. EsetGray)
15 Smear mode (c.f. EsetSmear)
Availability: The function is available only in the TOS of the Atari TT.
 
Group: Screen functions
 
See also: Binding   EsetShift
 

4.5.3.1 Bindings for EgetShift

C: #include <tos.h>
 
int16_t EgetShift( void );
 
Assembler:
 
move.w    #81,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #2,sp        ; Correct stack

4.5.4 EsetBank

Name: »Set color look up bank« - Sets the bank for the colour table from the 16 available.
 
Opcode: 82
 
Syntax: int16_t EsetBank( int16_t bankNum );
 
Description: The XBIOS routine EsetBank sets the bank number for the colour table of the TT to the value bankNum. The permitted value of bankNum lies between 0 and 15. If bankNum is negative, the current setting will not be altered.
 
Return value: The function returns the previous setting.
 
Availability: The function is available only in the TOS of the Atari TT.
 
Group: Screen functions
 
See also: Binding
 

4.5.4.1 Bindings for EsetBank

C: #include <tos.h>
 
int16_t EsetBank( int16_t bankNum );
 
Assembler:
 
move.w    bankNum,-(sp)  ; Offset 2
move.w    #82,-(sp)      ; Offset 0
trap      #14            ; Call XBIOS
addq.l    #4,sp          ; Correct stack

4.5.5 EsetColor

Name: »Set color entry« - Writes an entry into the colour table for an individual colour.
 
Opcode: 83
 
Syntax: int16_t EsetColor( int16_t colorNum, int16_t color );
 
Description: The XBIOS routine EsetColor sets the colour entry colorNum (0..255) in the colour table to the value color; a negative value does not alter the entry.
 
Return value: The function returns the previous setting.
 
Availability: The function is available only in the TOS of the Atari TT.
 
Group: Screen functions
 
See also: Binding   Setcolor
 

4.5.5.1 Bindings for EsetColor

C: #include <tos.h>
 
int16_t EsetColor( int16_t colorNum, int16_t color );
 
Assembler:
 
move.w    color,-(sp)     ; Offset 4
move.w    colorNum,-(sp)  ; Offset 2
move.w    #83,-(sp)       ; Offset 0
trap      #14             ; Call XBIOS
addq.l    #6,sp           ; Correct stack

4.5.6 EsetGray

Name: »Set/clear gray mode« - Switches on or off the colour interpretation in the video shifter.
 
Opcode: 86
 
Syntax: int16_t EsetGray( int16_t switch );
 
Description: The XBIOS routine EsetGray switches on (1) or off (0) the colour interpretation in the colour table as a greytone. A negative value returns the grey bit of the video shifter but does not alter the setting.
 
In greytone mode one can select from a palette of 256 greytones (0-255) instead of 4096 colours (RGB 0-15).
 
Return value: The function returns the previous value of the video shifter's grey bit.
 
Availability: The function is available only in the TOS of the Atari TT (when the high word of the '_VDO' cookie has the value of 2).
 
Group: Screen functions
 
See also: Binding
 

4.5.6.1 Bindings for EsetGray

C: #include <tos.h>
 
int16_t EsetGray( int16_t switch );
 
Assembler:
 
move.w    switch,-(sp) ; Offset 2
move.w    #86,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #4,sp        ; Correct stack

4.5.7 EsetPalette

Name: »Set palette registers« - Sets several entries in the colour table from the specified buffer.
 
Opcode: 84
 
Syntax: void EsetPalette( int16_t colorNum, int16_t count, int16_t *palettePtr );
 
Description: The XBIOS routine EsetPalette sets count colour entries from colorNum on in the colour table to the values in array palettePtr.
 
Return value: The function has no return.
 
Availability: The function is available only in the TOS of the Atari TT.
 
Group: Screen functions
 
See also: Binding   EgetPalette
 

4.5.7.1 Bindings for EsetPalette

C: #include <tos.h>
 
void EsetPalette( int16_t colorNum, int16_t count, int16_t *palettePtr );
 
Assembler:
 
pea       palettePtr      ; Offset 6
move.w    count,-(sp)     ; Offset 4
move.w    colorNum,-(sp)  ; Offset 2
move.w    #84,-(sp)       ; Offset 0
trap      #14             ; Call XBIOS
lea       $A(sp),sp       ; Correct stack

4.5.8 EsetShift

Name: »Set shift mode register« - Sets the shift mode registers of the video shifter.
 
Opcode: 80
 
Syntax: int16_t EsetShift( int16_t shftMode );
 
Description: The XBIOS routine EsetShift writes to the shift mode register of the TT the value shftMode. shftMode is a bit array with the following assignments:
 

Bit Meaning
0..3 Number of the colour register bank
8..10 Mode according to Getrez
12 Hyper-mono (c.f. EsetGray)
15 Smear mode (c.f. EsetSmear)
Return value: The function returns the previous value of the register.
 
Availability: The function is available only in the TOS of the Atari TT.
 
Group: Screen functions
 
See also: Binding   EgetShift
 

4.5.8.1 Bindings for EsetShift

C: #include <tos.h>
 
int16_t EsetShift( int16_t shftMode );
 
Assembler:
 
move.w    shftMode,-(sp)  ; Offset 2
move.w    #80,-(sp)       ; Offset 0
trap      #14             ; Call XBIOS
addq.l    #4,sp           ; Correct stack

4.5.9 EsetSmear

Name: »Set/clear video smear mode« - Switches on (1) or off (0) the smear mode of the video shifter.
 
Opcode: 87
 
Syntax: int16_t EsetSmear( int16_t switch );
 
Description: The XBIOS routine EsetSmear permits switching of the smear mode of the TT video shifter. In smear mode, the last displayed pixel colour is drawn in each case instead of the background colour (colour 0).
 

switch Meaning
<0 Obtain existing value
0 Smear mode off
>0 Smear mode on
Return value: The function returns the existing setting.
 
Availability: The function is available only in the TOS of the Atari TT.
 
Group: Screen functions
 
See also: Binding
 

4.5.9.1 Bindings for EsetSmear

C: #include <tos.h>
 
int16_t EsetSmear( int16_t switch );
 
Assembler:
 
move.w    switch,-(sp)  ; Offset 2
move.w    #87,-(sp)     ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #4,sp         ; Correct stack

4.5.10 Getrez

Name: »get resolution« - Return current screen resolution code.
 
Opcode: 4
 
Syntax: int16_t Getrez( void );
 
Description: The XBIOS routine Getrez obtains the current resolution of the screen.
 
Return value: The function returns the following values:
 

Value Meaning
0  320*200 (4 planes)
1  640*200 (2 planes)
2  640*400 (one plane)
4  640*480 (4 planes, TT only)
6 1280*960 (one plane, TT only)
7  320*480 (8 planes, TT only)

All other values are reserved for future extensions.
 
Note: For the sake of clean programming this function should not be used, as it is very dependent on the hardware; particularly when graphics cards are in use, it has practically no meaning. Instead, the screen resolution should be obtained via the VDI function (v_opnvwk).
 
Availability: All TOS versions.
 
Group: Screen functions
 
See also: Binding   v_opnvwk
 

4.5.10.1 Bindings for Getrez

C: #include <portab.h>
#include <tos.h>
 
int16_t Getrez( void );
 
Assembler:
 
move.w    #4,-(sp)     ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #2,sp        ; Correct stack

4.5.11 Initmouse

Name: »initialize mouse« - Initializes the mouse handler.
 
Opcode: 0
 
Syntax: void Initmouse( int16_t type, MOUSE *par, void (*mousevec)() );
 
Description: Initmouse is a XBIOS routine for low-level initialization of the mouse. The parameter type sets the working mode of the mouse. The following apply:
 

type Meaning
0 Disable mouse
1 Enable mouse in relative mode
2 Enable mouse in absolute mode
3 Unused
4 Enable mouse in key-code mode

The bytes from 4 to 11 of the parameter par are only used when the mouse is to work in absolute mode. With mousevec you can set a new mouse interrupt vector. The vector will reset if you disable the mouse (type=0).
 
Return value: The function return -1 if it OK or 0 if no error has occurred.
 
Availability: All TOS versions.
 
Group: Screen functions
 
See also: Binding   MOUSE
 

4.5.11.1 Bindings for Initmouse

C: #include <tos.h>
 
void Initmouse( int16_t type, MOUSE *par, void (*mousevec)() );
 
Assembler:
 
pea       mousevec     ; Offset 8
pea       par          ; Offset 4
move.w    type,-(sp)   ; Offset 2
move.w    #0,-(sp)     ; Offset 0
trap      #14          ; Call XBIOS
lea       12(sp),sp    ; Correct stack

4.5.12 Logbase

Name: »logical screen RAM base« - Returns a pointer to the logical start address of the video memory.
 
Opcode: 3
 
Syntax: void *Logbase( void );
 
Description: The XBIOS routine Logbase obtains the logical start address of the RAM region currently being used for the video memory.
 
Return value: The function returns the start address of the logical screen memory.
 
Availability: All TOS versions.
 
Group: Screen functions
 
See also: Binding   Physbase   Setscreen
 

4.5.12.1 Bindings for Logbase

C: #include <tos.h>
 
void *Logbase( void );
 
Assembler:
 
move.w    #3,-(sp)     ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #2,sp        ; Correct stack

4.5.13 mon_type

Name: »mon_type« - Identify the monitor type.
 
Opcode: 89
 
Syntax: int16_t mon_type( void );
 
Description: The XBIOS function mon_type identifies the type of monitor connected, based on pin 18(M1) and 19(M0) of the video port. A 0-bit means ground at the corresponding pin, a 1-bit means no connection.
 
Return value: The function returns the type of monitor connected. The following applies:
 

Value Meaning Pin
0 ST monochrome monitor M1:0 M0:0
1 ST colour monitor M1:0 M0:1
2 VGA monitor M1:1 M0:0
3 TV devicet M1:1 M0:1
4 LCD  
5 DVI  

Value four and five only available with ct60 and Radeon driver.
 
Availability: The function is only available on computers of the Falcon series.
 
Group: Screen functions
 
See also: Binding   VsetSync   VsetMode   VgetSize   VgetRGB   VsetRGB   VsetMask
 

4.5.13.1 Bindings for mon_type

C:
 
int16_t mon_type( void );
 
Assembler:
 
move.w    #89,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #2,sp        ; Correct stack

4.5.14 Physbase

Name: »physical screen ram base« - Returns the physical start address of the video memory.
 
Opcode: 2
 
Syntax: void *Physbase( void );
 
Description: The XBIOS routine Physbase returns the physical start address of the RAM region currently being used for the video memory.
 
Return value: The function Physbase returns the start address of the physical screen memory.
 
Availability: All TOS versions.
 
Group: Screen functions
 
See also: Binding   Logbase   Setscreen
 

4.5.14.1 Bindings for Physbase

C: #include <tos.h>
 
void *Physbase( void );
 
Assembler:
 
move.w    #2,-(sp)     ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #2,sp        ; Correct stack

4.5.15 Setcolor

Name: »Setcolor« - Sets one of 16 colours.
 
Opcode: 7
 
Syntax: int16_t Setcolor( int16_t colornum, int16_t color );
 
Description: The XBIOS routine Setcolor obtains the value of a colour register or sets this to a new value. The following apply:
 

Parameter Meaning
colornum Number of the colour register (0..15)
color New colour value (-1 = don't alter)
Return value: The function returns the old value of the colour register.
 
Availability: All TOS versions.
 
Group: Screen functions
 
See also: Binding   Setpalette
 

4.5.15.1 Bindings for Setcolor

C: #include <tos.h>
 
int16_t Setcolor( int16_t colornum, int16_t color );
 
Assembler:
 
move.w    color,-(sp)    ; Offset 4
move.w    colornum,-(sp) ; Offset 2
move.w    #7,-(sp)       ; Offset 0
trap      #14            ; Call XBIOS
addq.l    #6,sp          ; Correct stack

4.5.16 Setpalette

Name: »set palette« - Selects 16 colours.
 
Opcode: 6
 
Syntax: void Setpalette( void *pallptr );
 
Description: The XBIOS routine Setpalette permits the passing of a new colour palette to the video hardware.
 
The parameter pallptr points to a table of sixteen 16-bit words that contain the new palette. The lowest 12-bits are used here for the RGB values. pallptr must point to an even address.
 
As the function's data are not processed immediately, one has to ensure that the pointer pallptr still points to something sensible in the next vertical blank.
 
Note: It is better to make use of the corresponding functions of the VDI.
 
Return value: The function does not return a value.
 
Availability: All TOS versions.
 
Group: Screen functions
 
See also: Binding
 

4.5.16.1 Bindings for Setpalette

C: #include <tos.h>
 
void Setpalette( void *pallptr );
 
Assembler:
 
pea       pallptr      ; Offset 2
move.w    #6,-(sp)     ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #6,sp        ; Correct stack

4.5.17 Setscreen

Name: »set screen« - Initializes the screen.
 
Opcode: 5
 
Syntax: void Setscreen( void *laddr, void *paddr, int16_t rez );
 
Description: The XBIOS routine Setscreen serves to alter the screen resolution and screen memory addresses. The following apply:
 

Parameter Meaning
laddr Address of the logical screen memory
paddr Address of the physical screen memory
rez 0 = ST Low
    1 = ST Medium
    2 = ST High

A value of -1 here means that the corresponding address or resolution will not be altered.
 
Note: One should always check whether possible changes were really performed successfully. During resolution changes the VT52 emulator is automatically initialized.
 
Under some circumstances there is an extended version of this function (VsetScreen).
 
Return value: The function does not return a result.
 
Availability: All TOS versions.
 
Group: Screen functions
 
See also: Binding   Physbase   Logbase   Getrez
 

4.5.17.1 Bindings for Setscreen

C: #include <tos.h>
 
void Setscreen( void *laddr, void *paddr, int16_t rez );
 
Assembler:
 
move.w    rez,-(sp)    ; Offset 10
move.l    paddr,-(sp)  ; Offset  6
move.l    laddr,-(sp)  ; Offset  2
move.w    #5,-(sp)     ; Offset  0
trap      #14          ; Call XBIOS
lea       $C(sp),sp    ; Correct stack

4.5.18 Setscreen, Milan

Name: »set screen« - Initializes the screen.
 
Opcode: 5
 
Syntax: void Setscreen( void *par1, void *par2, int16_t rez, int16_t command );
 
Description: This XBIOS routine corresponds to the Setscreen function with additional parameters, and serves for altering the screen resolution and screen memory addresses.
 

Parameter Meaning
par1 Depending on function - see below
par2 Depending on function - see below
rez always 0x4D49 (MI_MAGIC)
command Command

The following values are defined for command:
 
CMD_GETMODE (0)

Getting current mode
 
int32_t mode;
Setscreen(-1, &mode, MI_MAGIC, CMD_GETMODE);
 

CMD_SETMODE (1)

Set new graphic mode
 
int32_t mode=0x1023 /* 800*608*16 */
Setscreen(-1, mode, MI_MAGIC, CMD_SETMODE)
 
BIOS and VDI will be initialised. Not the AES.
 

CMD_GETINFO (2)

Get screen info structure for mode
 

SCREENINFO si;
/* Structure size has to be set         */
si.size=sizeof(SCREENINFO);
/* ID of the mode or 0 for current mode */
si.devID=0x1023;
/* status of the operation              */
si.scrFlags=0;
Setscreen(-1, &si, MI_MAGIC, CMD_GETINFO);
if(si.scrFlags & SCRINFO_OK)
  puts("OK");
else
  puts("Error");

CMD_ALLOCPAGE (3)

Allocate 2nd screenpage
 

int32_t adr=0;      /* Frame address or -1 */
Setscreen(&adr, mode, MI_MAGIC, CMD_ALLOCPAGE);
if(adr)
  puts("OK");
else
  puts("Error");

This only allocates one page. A further call will only return the frame address.
 

CMD_FREEPAGE (4)

Release 2nd screenpage
 
Setscreen(-1, -1, MI_MAGIC, CMD_FREEPAGE)
 
The graphics card memory will be released again. If the second page had still been active the call will switch back to the first page with Logbase and Physbase set.
 

CMD_FLIPPAGE (5)

Switch to 2nd screenpage
 
Setscreen(-1, -1, MI_MAGIC, CMD_FLIPPAGE)
 
Will switch to the second screenpage. Logbase and Physbase will be set.
 

CMD_ALLOCMEM (6)

Allocate memory on the graphics card
 

SCRMEMBLK blk;

blk.size=sizeof(SCRMEMBLK);
/* alloc a block of 200 lines*/
blk.blk_y=200;

Setscreen(-1, &blk, MI_MAGIC, CMD_ALLOCMEM);
if(blk.blk_start)
  puts("OK");
else
  puts("Out of memory");

The width of the block is currently always the width of the virtual screen. For the hardware functions this block will be like a screen (0,0,blk_w,blk_h), the coordinates start in the top left corner (0,0). It will be internally recalculated.
 

CMD_FREEMEM (7)

Release graphics card memory
 
Setscreen(-1, &blk, MI_MAGIC, CMD_FREEMEM)
blk of the block to be released.
 

CMD_SETADR (8)

Set screen to fixed address
 

/* logical address or -1  */
int32_t logbase=blk.blk_start;
/* physical address or -1 */
int32_t physbase=blk.blk_start;

Setscreen(logbase, physbase, MI_MAGIC, CMD_SETADR);

CMD_ENUMMODES (9)

Requests all available modes, since 13.01.2000
 

int32_t cdecl enumfunc(SCREENINFO *inf,int32_t flag)
{
  printf("%s\n",inf->name);
  return ENUMMODE_CONT;
}

Setscreen(-1, &enumfunc, MI_MAGIC, CMD_ENUMMODES);

The function "enumfunc" will be called once for every available mode. ENUMMODE_EXIT (0) will cancel CMD_ENUMMODES. ENUMMODE_CONT (1) will continue. The parameters are handed over to the stack using the C standard.
 

CMD_TESTMODE (10)

This function only exist inside the ct60 with internal TOS Radeon driver.
 

Return value: Return value undefined.
 
Availability: The function is available from the MilanTOS 4.08 onwards.
 
Group: Screen functions
 
See also: Setscreen   VsetScreen   Setscreen, ct60
 

4.5.19 Setscreen, ct60

Name: »set screen« - Initializes the screen
 
Opcode: 5
 
Syntax: void Setscreen( void *par1, void *par2, int16_t rez, int16_t command );
 
Description: This XBIOS routine corresponds to the Setscreen function with additional parameters, and serves for altering the screen resolution and screen memory addresses.
 

Parameter Meaning
par1 Depending on function - see below
par2 Depending on function - see below
rez Always 0x564E ('VN' for VsetScreen New)
command Command

The following values are defined for command:
 
CMD_GETMODE (0)

Getting current mode
 
int32_t mode;
Setscreen(-1,&mode,0x564E,CMD_GETMODE);
 

CMD_SETMODE (1)

Set new graphic mode
 
int32_t mode=0x1023 /* 800*608*16 */
Setscreen(-1,mode,0x564E,CMD_SETMODE)
 
This function is identical to VsetScreen(0, 0, 3, modecode);
BIOS and VDI will be initialised. Not the AES.
 

CMD_GETINFO (2)

Get screen info structure for mode
 

SCREENINFO si;
/* Structure size has to be set         */
si.size=sizeof(SCREENINFO);
/* ID of the mode or 0 for current mode */
si.devID=0x1023;
/* status of the operation              */
si.scrFlags=0;
Setscreen(-1,&si,0x564E,CMD_GETINFO);
if(si.scrFlags & SCRINFO_OK)
  puts("OK");
else
  puts("Error");

CMD_ALLOCPAGE (3)

Allocate screenpage
 

/* Frame address or -1 */
int32_t adr=0;
Setscreen(&adr,mode,0x564E,CMD_ALLOCPAGE);
if(adr)
  puts("OK");
else
  puts("Error");

This only allocates one page. A further call will only return the frame address.
 

CMD_FREEPAGE (4)

Release screenpage
 
Setscreen(-1,-1,0x564E,CMD_FREEPAGE)
 
The graphics card memory will be released again. If the second page had still been active the call will switch back to the first page with Logbase and Physbase set.
 

CMD_FLIPPAGE (5)

Switch to screenpage
 
Setscreen(-1,-1,0x564E,CMD_FLIPPAGE)
 
Will switch to the second screenpage. Logbase and Physbase will be set.
 

CMD_ALLOCMEM (6)

Allocate memory on the graphics card
 

SCRMEMBLK blk;

blk.size=sizeof(SCRMEMBLK);
/* alloc a block of 200 lines*/
blk.blk_y=200;

Setscreen(-1,&blk,0x564E,CMD_ALLOCMEM);
if(blk.blk_start)
  puts("OK");
else
  puts("Out of memory");

The width of the block is currently always the width of the virtual screen. For the hardware functions this block will be like a screen (0,0,blk_w,blk_h), the coordinates start in the top left corner (0,0). It will be internally recalculated.
 

CMD_FREEMEM (7)

Release graphics card memory
 
Setscreen(-1,&blk,0x564E,CMD_FREEMEM)
blk of the block to be released.
 

CMD_SETADR (8)

Set screen to fixed address
 

/* logical address or -1  */
int32_t logbase=blk.blk_start;
/* physical address or -1 */
int32_t physbase=blk.blk_start;

Setscreen(logbase,physbase,0x564E,CMD_SETADR);

CMD_ENUMMODES (9)

Requests all available modes
 

int32_t cdecl enumfunc(SCREENINFO *inf,int32_t flag)
{
  printf("%s\n",inf->name);
  return ENUMMODE_CONT;
}

Setscreen(-1,&enumfunc,0x564E,CMD_ENUMMODES);

The function "enumfunc" will be called once for every available mode. ENUMMODE_EXIT (0) will cancel CMD_ENUMMODES. ENUMMODE_CONT (1) will continue. The parameters are handed over to the stack using the C standard.
 

CMD_TESTMODE (10)

Test a graphic mode
 

/* 800*600*16M */
int32_t modecode=VESA_600+HORFLAG2+VGA+COL80+BPS32;
Setscreen(-1,modecode,0x564E,CMD_TESTMODE);

Only the BIOS is initialised, and a screen test arrives with colored wide lines.
 
This function not exist inside the MilanTOS.
 

CMD_COPYPAGE (11)

Copy screenpage
 

VsetScreen(-1,0,0x564E,CMD_COPYPAGE);
Copy first screenpage to second screenpage
VsetScreen(-1,1,0x564E,CMD_COPYPAGE);
Copy second screenpage to first screenpage

This function not exist inside the MilanTOS.
 

CMD_FILLMEM (12)

Fill memory on the graphics card
 

SCRFILLMEMBLK blk;
blk.size=sizeof(SCRFILLMEMBLK);
blk.blk_op = BLK_COPY;
blk.blk_color = 0x112233;  /* background fill color */

VsetScreen(-1,&blk,0x564E,CMD_SETMEM);
if(blk.blk_status == BLK_OK)
  puts("OK");

Fill a block with a color with the GPU at (blk_x, blk_y), size is blk_w, blk_h.
Note that this structure has the same size and same entry the the structure SCRMEMBLK for the entry for size, blk_status, blk_x, blk_y, blk_y, blk_w and blk_h for use the allocated structure with a cast.
 
This function exists since the version 0x0101 of the video XBIOS and is not inside the MilanTOS.
 

CMD_COPYMEM (13)

Copy memory on the graphics card
 

SCRCOPYMEMBLK blk;
blk.size=sizeof(SCRCOPYMEMBLK);

VsetScreen(-1,&blk,0x564E,CMD_COPYMEM);
if(blk.blk_status == BLK_OK)
  puts("OK");

Copy a block with the GPU at (blk_src_x, blk_src_y) to (blk_dst_x, blk_dst_y), size is blk_w, blk_h.
Note that this structure has the same size and same entry the the structure SCRMEMBLK for the entry for size, blk_status, blk_x, blk_y, blk_y, blk_w and blk_h for use the allocated structure with a cast when blk_x is blk_dst_x and blk_y is blk_dst_y.
 
This function exists since the version 0x0101 of the video XBIOS and is not inside the MilanTOS.
 

CMD_TEXTUREMEM (14)

Put texture in memory on the graphics card
 

SCRTEXTUREMEMBLK blk;
blk.size=sizeof(SCRTEXTUREMEMBLK);

VsetScreen(-1,&blk,0x564E,CMD_TEXTUREMEM);
if(blk.blk_status == BLK_OK)
  puts("OK");

Copy a 65K texture from CPU local area to a 65K screen or an ARGB texture to a 32M screen pixel format multiple times (best results are with little source texture and big screen for destination).
 
This function need a texture support inside the TOS.
This function exists since the version 0x0101 of the video XBIOS and is not inside the MilanTOS.
 

CMD_GETVERSION (15)


 

/* if the function is not implemented, 0x0100 is the first release */
long version = 0x0100;
VsetScreen(-1,&version,0x564E,CMD_GETVERSION);

Return the version of the video XBIOS.
 
This function exists since the version 0x0101 of the video XBIOS and is not inside the MilanTOS.
 

CMD_LINEMEM (16)

Draw line on the graphics card
 

SCRLINEMEMBLK blk;
blk.size=sizeof(SCRLINEMEMBLK);
blk.blk_fbcolor = 0x112233;  /* foreground fill color */
blk.blk_bgcolor = 0;  /* background fill color */
blk.blk_pattern = 0xffffffff;  /* solid line */

VsetScreen(-1,&blk,0x564E,CMD_LINEMEM);
if(blk.blk_status == BLK_OK)
  puts("OK");

Draw a line with colors with the GPU at (blk_x1, blk_y1) to (blk_x2, blk_y2).
 
This function exists since the version 0x0101 of the video XBIOS and is not inside the MilanTOS.
 

CMD_CLIPMEM (17)

Set clipping rectangle on the graphic card
 

SCRCLIPMEMBLK blk;
blk.size=sizeof(SCRCLIPMEMBLK);
blk.blk_clip_on = 1; /* clipping flag 1:on,
                                      0:off */

VsetScreen(-1,&blk,0x564E,CMD_CLIPMEM);
if(blk.blk_status == BLK_OK)
  puts("OK");

Enable or diable clipping rectange at (blk_x, blk_y), size is blk_w, blk_h.
 
This function exists since the version 0x0101 of the video XBIOS and is not inside the MilanTOS.
 

CMD_SYNCMEM (18)

Wait an empty GPU fifo for sync the drawing engine with the memory.
 

VsetScreen(-1,-1,0x564E,CMD_SYNCMEM);

This function exists since the version 0x0101 of the video XBIOS and is not inside the MilanTOS.
 

CMD_BLANK (19)

Blank / unblank screen.
 

int32_t blank = 1; /* (0): unblank
                      (1): blank normal
                      (2): VSYNC suspend
                      (3): HSYNC suspend
                      (4): powerdown */
VsetScreen(-1,blank,0x564E,CMD_BLANK);

This function exists since the version 0x0101 of the video XBIOS and is not inside the MilanTOS.
 

Return value: Nothing (or current modecode in TOS mode)
 
Availability: Only valid with internal TOS Radeon driver (PCI.HEX) for the ct60 (2007-01-24).
 
Group: Screen functions
 
See Also: Setscreen   VsetScreen   Setscreen, Milan
 

4.5.20 ValidMode

Name: «ValidMode» - Validates a mode code.
 
Opcode: 95
 
Syntax: int16_t ValidMode( int16_t mode );
 
Description: The XBIOS function ValidMode returns a valid version of the specified mode code, depending on the monitor that is connected. The bits of the parameter mode have the following meaning:
 

Bit Meaning
0-2 Number of colour planes:
  0 = 1 plane 2 colours
  1 = 2 planes 4 colours
  2 = 4 planes 16 colours
  3 = 8 planes 256 colours
  4 = 16 planes 65536 colours
   
3 Set: Image width at least 640 pixels (80 columns)
  Cleared: Image width 320 pixels (40 columns)
   
4 Set: VGA mode
  Cleared: TV mode (also Atari SC monitors)
   
5 Set: PAL mode
  Cleared: NTSC mode
   
6 Set: Overscan active (not valid for VGA)
7 Set: ST-compatible graphics
8 Set: Interlace mode (on colour monitor or
  double-line mode (on VGA monitor) active

Note: This function is not officially documented and some development tools may also call it Validmode or VcheckMode.
 
Return value: The function returns a valid mode code.
 
Availability: The function is only available on computers of the Falcon series, Milan and CT60.
 
Group: Screen functions
 
See also: Binding   mon_type   VsetSync   VgetSize VgetRGB   VsetRGB   VsetMask   VsetMode
 

4.5.20.1 Bindings for ValidMode

C: int16_t ValidMode( int16_t mode );
 
Assembler:
 
move.w    mode,-(sp)    ; Offset 2
move.w    #95,-(sp)     ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #4,sp         ; Correct stack

4.5.21 VgetRGB

Name: »VgetRGB« - Obtain the RGB values of a colour palette.
 
Opcode: 94
 
Syntax: void VgetRGB( int16_t index, int16_t count, int32_t *array );
 
Description: The XBIOS function VgetRGB obtains the RGB values for count colours starting from the colour index index. The resulting values are stored in array.
 
Note: One should not try to backup more color than supported by the video mode.
 
Return value: The function does not return a result.
 
Availability: The function is only available on computers of the Falcon series.
 
Group: Screen functions
 
See Also: Binding   mon_type   VsetMode   VsetSync   VgetSize   VsetRGB   VsetMask
 

4.5.21.1 Bindings for VgetRGB

C: #include <tos.h>
 
void VgetRGB( int16_t index, int16_t count, int32_t *array );
 
Assembler:
 
move.l    array,-(sp)  ; Offset 6
move.w    count,-(sp)  ; Offset 4
move.w    index,-(sp)  ; Offset 2
move.w    #94,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
lea       $A(sp),sp    ; Correct stack

4.5.22 VsetScreen

Name: »set screen« - initializes the screen.
 
Opcode: 5
 
Syntax: void VsetScreen( void *laddr, void *paddr, int16_t rez, int16_t mode );
 
Description: The XBIOS routine VsetScreen corresponds to the Setscreen function with an additional parameter, and serves for altering the current screen resolution and screen memory addresses.
 

Parameter Meaning
laddr Address of the logical screen memory
paddr Address of the physical screen memory
rez 0 = ST Low
    1 = ST Medium
    2 = ST High
    3 = Resolution used, from mode
mode modecode (see VsetMode)

A value of -1 here means that the corresponding address or resolution will not be altered.
 
Note: One should always check whether possible changes were really performed successfully. During resolution changes the VT52 emulator is automatically initialized.
 
The additional parameter mode is only available if the cookie '_VDO' has the value 0x00030000 or greater.
 
For the TOS of the Milan there is an additional function for Setscreen, entsprechendes gilt auch für den ct60.
 
Return value: The function does not return a result.
 
Availability: The function is only available on computers of the Falcon series.
 
Group: Screen functions
 
See also: Binding
 

4.5.22.1 Bindings for VsetScreen

C: #include <tos.h>
 
void VsetScreen( void *laddr, void *paddr, int16_t rez, int16_t mode );
 
Assembler:
 
move.w    mode,-(sp)   ; Offset 12
move.w    rez,-(sp)    ; Offset 10
move.l    paddr,-(sp)  ; Offset  6
move.l    laddr,-(sp)  ; Offset  2
move.w    #5,-(sp)     ; Offset  0
trap      #14          ; Call XBIOS
lea       14(sp),sp    ; Correct stack

4.5.23 VgetSize

Name: »VgetSize« - Return the size of the screen buffer.
 
Opcode: 91
 
Syntax: int32_t VgetSize( int16_t mode );
 
Description: The XBIOS function VgetSize returns the size of the screen buffer in bytes for the graphic mode mode.
 
Return value: The function returns the size of the screen buffer in bytes.
 
Availability: The function is only available on computers of the Falcon series.
 
Group: Screen functions
 
See also: Binding   mon_type   VsetMode   VsetSync   VgetRGB   VsetRGB   VsetMask
 

4.5.23.1 Bindings for VgetSize

C: #include <tos.h>
 
int32_t VgetSize( int16_t mode );
 
Assembler:
 
move.w    mode,-(sp)    ; Offset 2
move.w    #91,-(sp)     ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #4,sp         ; Correct stack

4.5.24 VsetMask

Name: »VsetMask« - Set transparency for TrueColor.
 
Opcode: 150
 
Syntax: void VsetMask( int32_t ormask, int32_t andmask, int16_t overlay );
 
Description: The XBIOS function VsetMask sets masks that are used to modify the colours set by the VDI function vs_color. vs_color obtains for its parameter an RGB value. This is ORd bitwise with ormask and ANDed with andmask. Thus colours may appear as transparent in TrueColor mode. If overlay is non-zero a switch is made into the overlay mode, or if zero switched back out of it.
 
Return value: The function does not return a result.
 
Availability: The function is only available on computers of the Falcon series.
 
Group: Screen functions
 
See also: Binding   mon_type   VsetMode   VsetSync   VgetSize   VgetRGB   VsetRGB
 

4.5.24.1 Bindings for VsetMask

C: #include <tos.h>
 
void VsetMask( int32_t ormask, int32_t andmask, int16_t overlay );
 
Assembler:
 
move.w    overlay,-(sp) ; Offset 10
move.l    andmask,-(sp) ; Offset 6
move.l    ormask,-(sp)  ; Offset 2
move.w    #150,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
lea       12(sp),sp     ; Correct stack

4.5.25 VsetMode

Name: »VsetMode« - Set video hardware registers.
 
Opcode: 88
 
Syntax: int16_t VsetMode( int16_t mode );
 
Description: The XBIOS function VsetMode programs the video hardware register of the Falcon computer. The bits of the parameter mode have the following meaning:
 

Bit Meaning
0-2 Number of colour planes:
  0 = 1 plane 2 colours
  1 = 2 planes 4 colours
  2 = 4 planes 16 colours
  3 = 8 planes 256 colours
  4 = 16 planes 65536 colours
   
3 Set: Image width at least 640 pixels (80 columns)
  Cleared: Image width 320 pixels (40 columns)
   
4 Set: VGA mode
  Cleared: TV mode (also Atari SC monitors)
   
5 Set: PAL mode
  Cleared: NTSC mode
   
6 Set: Overscan active (not valid for VGA)
7 Set: ST-compatible graphics
8 Set: Interlace mode (on colour monitor or
  double-line mode (on VGA monitor) active

If VM_INQUIRE (-1) is passed as mode one will get the current resolution without changing anything.
 
Note: There is no check of the correctness of the coding for the connected monitor.
 
Return value: The function returns the old contents of the video hardware register.
 
Availability: The function is only available on computers of the Falcon series.
 
Group: Screen functions
 
See also: Binding   mon_type   VsetSync   VgetSize VgetRGB   VsetRGB   VsetMask
 

4.5.25.1 Bindings for VsetMode

C: #include <tos.h>
 
int16_t VsetMode( int16_t mode );
 
Assembler:
 
move.w    mode,-(sp)    ; Offset 2
move.w    #88,-(sp)     ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #4,sp         ; Correct stack

4.5.26 VsetRGB

Name: »VsetRGB« - Set the RGB value of a colour.
 
Opcode: 93
 
Syntax: void VsetRGB( int16_t index, int16_t count, int32_t *array );
 
Description: The XBIOS function VsetRGB sets the RGB values for count palette entries starting from the palette index index. The colour values are stored in array.
 
Note: One should not try to restore more colors than supported by the video mode.
 
Return value: The function does not return a result.
 
Availability: The function is only available on computers of the Falcon series.
 
Group: Screen functions
 
See also: Binding   mon_type   VsetMode   VsetSync   VgetSize   VgetRGB   VsetMask
 

4.5.26.1 Bindings for VsetRGB

C: #include <tos.h>
 
void VsetRGB( int16_t index, int16_t count, int32_t *array );
 
Assembler:
 
move.l    array,-(sp)  ; Offset 6
move.w    count,-(sp)  ; Offset 4
move.w    index,-(sp)  ; Offset 2
move.w    #93,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
lea       $A(sp),sp    ; Correct stack

4.5.27 VsetSync

Name: »VsetSync« - Sets the type of external synchronisation.
 
Opcode: 90
 
Syntax: void VsetSync( int16_t flag );
 
Description: The XBIOS function VsetSync determines how the video is to be synchronized. The parameter flag is coded as follows:
 

Bit Meaning for set bits
0 Use external clock
1 Use external vertical sync
2 Use external horizontal sync
Return value: The function does not return a result.
 
Availability: The function is only available on computers of the Falcon series.
 
Group: Screen functions
 
See also: Binding   mon_type   VsetMode   VgetSize   VgetRGB   VsetRGB   VsetMask
 

4.5.27.1 Bindings for VsetSync

C: #include <tos.h>
 
void VsetSync( int16_t flag );
 
Assembler:
 
move.w    flag,-(sp)   ; Offset 2
move.w    #90,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #4,sp        ; Correct stack

4.5.28 Vsync

Name: »vertical sync« - Hold process until next vertical sync signal.
 
Opcode: 37
 
Syntax: void Vsync( void );
 
Description: The XBIOS routine Vsync holds up program execution until the next screen refresh (vertical blank interrupt). This makes it possible to synchronize screen operations with the operating system.
 
Note: For time-critical operations (scrolling) it is better to have recourse directly to the line counter in the Shifter.
 
Return value: The function does not return a result.
 
Availability: All TOS versions.
 
Group: Screen functions
 
See also: Binding
 

4.5.28.1 Bindings for Vsync

C: #include <tos.h>
 
void Vsync( void );
 
Assembler:
 
move.w    #37,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #2,sp        ; Correct stack

4.5.29 Constants for the Falcon's video hardware

To simplify programming of the video hardware register of the Falcon with the function VsetMode, the following constants are defined in the header file tos.h, which can be combined with | :

    #define VERTFLAG  0x0100  /* Activate interlace                */
    #define STMODES   0x0080  /* ST-compatible graphics            */
    #define OVERSCAN  0x0040  /* Activate overscan                 */
    #define PAL       0x0020  /* PAL mode                          */
    #define FALC_VGA  0x0010  /* VGA mode                          */
    #define TV        0x0000  /* TV mode                           */

    #define COL80     0x0008  /* Picture width at least 640 pixels */
                                                      (80 columns) */
    #define COL40     0x0000  /* Picture width 320 pixels (40 col.)*/

    #define BPS16     4       /* 16 colour planes: 65536 colours   */
    #define BPS8      3       /*  8 colour planes:   256 colours   */
    #define BPS4      2       /*  4 colour planes:    16 colours   */
    #define BPS2      1       /*  2 colour planes:     4 colours   */
    #define BPS1      0       /*  1 colour plane:      2 colours   */

With the following constant the number of colour planes can be masked out:

    #define NUMCOLS   7       /* if (( mode & NUMCOLS ) == 0 ) */
                              /*   puts( "monochrome mode" );  */

Home XBIOSXBIOS xbios-trapxbios-trap CENTScreen XBIOS extensionCENTScreen XBIOS extension