The Complete STOS Reference

pre-release 0.2 Edited By Dr Phibes

STOS Manual: APPENDIX E Traps

The Stos Basic Traps
The Window Functions (Trap 3)

The Sprite Functions (Trap 5)
Floating Point Extension Library

The Music Generator
The Music Traps (Trap 7)

The Stos Basic Traps

Stos basic was written in a very modular way. Each separate group of basic functions was implemented using a special set of 68000 TRAPs, placed on the STOS system disc. The TRAPs can be found in the files:

WINDOWS.BIN (TRAP 3)
SPRITES.BIN (TRAP 5)
FLOAT.BIN (TRAP 6)
MUSIC.BIN (TRAP 7)

These files are installed by STOS basic into memory whenever it is loaded. The advantage of this approach is to allow the machine code programmer unprecedented access to the heart of the STOS basic system. You can call up most of the more interesting features of the package such as sprites or music directly from assembly language. Note that it is advisable NOT to call up these functions from machine code whilst they are being used from basic.

The Window Functions (Trap 3)

The function number is stored in register D7 and any additional data is loaded into D0-D1 and A0. If the function returns any results, these will be passed to your program in either A0 or D0. WARNING ! Some of these functions automatically redraw all the sprites on the screen. You can avoid this by using the UPDATE OFF command from basic before executing machine code.Here is a list of the various functions.

no.     name            action                                          parameters
0       CHROUT          print a character in charactercurrent window    D0=output
1       PRINT STRING    prints a string of characters in window         A0=pointer to string,string is terminated by 0
2       LOCATE          move text cursor                                D0=X coordinate (text)D1=Y coordinate. See LOCATE
3       SET PAPER       set paper colour                                D0=colour index of paper
4       SET PEN         set text colour                                 D0=colour number of pen
5       TEST SCREEN     find character at cursor Returns with character in D0
6       INIT WINDOW     initialize a window      
7       STOP INTER      stop window interrupts                          DO NOT CALL !
8       WINDON          activate window                                 D0=window number
9       DEL WINDOW      delete window                                   D0=window number
10      INIT MODE       initialise a screen in a new resolution  
11      GET BUFFER      get address of keyboard buffer                  D0=length: A0=address
12      WINDCOPY        print current window on printer  
13      GET CURRENT     get current window no.  returned in D0
14      FIX CURSOR      change size of cursor                           D0=top:D1=bottom:D2=0
15      START INTER     start window interrupts                         DO NOT USE !
16      QWINDOW         activate window quickly                         D0=window number
17      GET CURSOR      get position of text cursor                     D0 top byte=X coordinate D0 bottom byte=Y coordinate
18      CENTRE          prints centred text string on the screen        A0=address of string to be printed
19      SET BACK        change address of sprite background             A0=address of new background
20      AUTO INS        opens a space in the line and places a character in it  D0=character to be output
21      JOIN            joins current line with the following line       
22      SMALL CURSOR    displays a small cursor  
23      TALL CURSOR     displays a thick cursor  
24      MOVE WINDOW     move a window to a new position                 D0=window number D1=X coord, D2=Y coord(text)
26      SET ICON ADR    set address of icons                            A0=address of icon bank
28      GET CHARSET     get address of character set                    D0=set number returns address in D0
29      SET CHARSET     set new address of a character set              D0=set number A0=address of new set
30      BORDER          change current window border                    D0=new border(0-16)
31      TITLE           add a title to the current window               A0=address of a string for title (terminated with a 0)
32      AUTOBACK ON     identical to Basic version      
33      AUTOBACK OFF    identical to Basic version      
35      XGRAPHIC        convert X coordinate from text to graphic       D0=text coordinate returns coordinate in D0 
36      YGRAPHIC        as for XGRAPHIC but for Y coordinate     
37      XTEXT           converts X coordinate from graphic to text      D0=graphic coordinate returns text coordinate in D0
38      YTEXT           as for XTEXT but for Y coordinate        
39      SQUARE          draws a square at the current cursor position   D0=border (0-16) D1=width (minimum 3) D2=height (minimum 3)

The Sprite Functions (Trap 5)

These take the function number in register D0, and read the various parameters in the other registers. Note that only registers D0-D1 and A0 are modified by this TRAP. Here is a list of the fuctions:

no      name            action  parameters
1       INIT MODE       initialise the sprite generator to a new resolution     
2       CHANGE BANK     change the address of the bank                  A0=address of new sprite sprite bank
3       CHANGE LIMITS   change limits of the display area used by the sprites   D1=X coord of leftmost limit D2=X coord of right limit (called by LIMIT SPRITE) D3=Y coord of top limit D4=Y coord of bottom limit
4       SYNCHRO         turns on/off synchronisation of sprites and background  D1=1 for SYNCHRO ON D1=0 for SYNCHRO OFF
5       PRIORITY        switch between normal and Y coordinate priority D1=1 for PRIORITY ON D1=0 for PRIORITY OFF
6       POS SPRITE      get position of sprite                          D1=sprite number returns: X coord in D0:Y coord in D1
7       SPRITES ON/OFF  redraw or remove ALL sprites on screen          D2=1 for redraw D2=0 for erase
8       SPRITE ON/OFF   redraw or remove ONE sprite on screen           D2=1 redraw:d2=0 erase D1=sprite number
9       SPRITE          draws a sprite                                  D1=sprite number D2=X coordinate of sprite D3=Y coordinate of sprite D4=image number of sprite
10      MOVES ON/OFF    starts or stops ALL sprite movements            D2=0 for stop :D2=2 for start D2=1 for freeze
11      MOVE ON/OFF     starts or stops ONE sprite movement             D2 as for MOVES ON/OFF D1=sprite number
12      MOVE INIT       defines a sprite movement equivalent to MOVE X and MOVE Y       A0=address of sprite movement string terminated by a zero (in same format as basic) D1=sprite number D2=0 for MOVE X:D2=1 MOVE Y
13      ANIMS ON/OFF    same as function 10 but for animations  
14      ANIM ON/OFF     same as function 11 but for animations  
15      INIT ANIM       define an animation sequence                    A0=address of animation string terminated by a zero (in same format as basic) D1=sprite number
16      UPDATE          redraw any sprites which have changed since last update 
17      SHOW            show mouse                                      D1=0 SHOW ON :D1=1 SHOW
18      HIDE            hide mouse                                      D1=0 HIDE ON :D1=1 HIDE
19      CHANGE MOUSE    changes mouse image                             D1=number of new image
20      MOUSE           get mouse coordinates returns D0=X coord:D1=Y coord
21      MOUSEKEY        get mouse button returns status in D0
22      SCREEN TO BACK  copies physical screen to sprite background     
23      BACK TO SCREEN  copies sprite background to physical screen     
24      DRAW MOUSE      redraw mouse on screen  
25      SET ZONE        set test zone                                   D1=number of zone D2=leftmost limit in X D3=rightmost limit in X D4=top limit in Y D5=bottom limit in Y
26      ZONE            test zone                                       D1=sprite to be tested returns 0/zone number in D0
27      CHANGE BACK     change sprite background address                A0=new address
28      STOP MOUSE      stop the mouse moving on the screen     
29      DRAW SPRITES    redraws all the sprites on the screen              
30      START INTER     start sprite interrupts DO NOT USE !
31      STOP INTER      stop sprite interrupts  DO NOT USE !
32      LIMIT LOUSE     limit mouse to an area on the screen            D1=X coord of left corner D2=Y coord of left corner D3=X coord of right corner D4=Y coord of right corner
33      SCREEN COPY     as STOS basic                                   A0=address of source screen A1=address of dest screen D1/D2=(X,Y) of rectangle to be copied D3/D4=(X,Y) of destination D5/D6=(W,H)of zone to copy
34      ICON            put sprite                                      D1=X coord of sprite D2=Y coord of sprite D3=number of icon address of sprite data
35      PUT SPRITE      puts sprite in background screen providing it's already displayed       D1=number of sprite
36      INIT ZONE       initialise test zones   
37      GET SPRITE      equivalent to the basic instruction             D1=X coord of new sprite D2=Y coordinate D3=pointer to sprite to copy D4=mask
38      REDUCE          reduces a screen        A0=address of source screen A1=address of destination D1=X coord of reduced screen D2=Y coord of reduced screen D3=width of reduced screen D4=height of reduced screen
39      INIT FLASH      initialise colour flashes       
40      FLASH           set up a flash sequence D1=number of colour flash A0=flash string terminated by a 0 (see FLASH from basic)
42      ZOOM            enlarges a section of screen                    A0=address of source screen A1=address of destination D1=X coord of top left corner D2=Y coord of top left corner D3=width of the section D4=length of the section D5/D6=coordinates of dest A2/A3=size in X and Y of dest
43      APPEAR          fades between two screens                       A0=address of source screen A1=address of dest screen D1=type of fade (1-80)
44      MOVE MOUSE      changes the coordinates of the mouse            D1=new X coordinate D2=new Y coordinate
45      MOVEON          checks whether sprite is in motion              D1=number of sprite Returns:- D1=0 stationary:D1=1 moving
46      SHIFT           shifts the palette of colours                   D1=speed in 50ths of a second D2=colour the rotation to be started at     
47      REDRAW          identical to the basic function

Floating Point Extension Library

This gives the programmer access to a wide variety of floating point operations and uses numbers in the IEEE 64-bit format between 10-307 to 10+308 These routines corrupt registers D0-D4 and A0-A1. As before, the function number is loaded into D0 before calling the appropriate routine.The first parameter should always be placed in registers D1-D2 (with D1 containing the bottom half of the number, and D2 holding the top half). If a second parameter is required, this should be put into registers D3-D4 using the same format. You can now execute the function using the TRAP 6 instruction

no name description
$00 ADFL Adds two floating point numbers together first no in D1-D2
$01 SBFL Subtract one floating point number from another as for ADFL
$02 MLFL Multiply two floating point numbers
$03 DVFL Divide two floating point numbers
$04 SINFL Takes the SIN of the number in D1-D2 and places it in D0-D1
$05 COSFL Takes the COS of the number in D1-D2 and places it in D0-D1
$06 TANFL Takes the TAN of the number in D1-D2 and places it in D0-D1
$07 EXPFL Takes the EXP of the number in D1-D2 and places it in D0-D1
$08 LOGFL Takes the LN of the number in D1-D2 and places it in D0-D1
$09 LOG10FL Takes the LOG of the number in D1-D2 and places it in D0-D1
$0A SQRFL Takes a number in D1-D2 and returns the SQR of it in D0-d1
$0B ATOFL Takes an Ascii string pointed to by A0 and converts it to a number in F.P. format in D0-D1.
$0C FLTOA Takes a number in D1-D2 and converts it to an Ascii string. input params: D1-D2=the floating point number to be converted. D3=a digit representing the number of digits after the decimal point in Ascii. A0=the pointer to a buffer for the string. output params The length of the Ascii string (not including the final 0) A0=a pointer to the string of Ascii characters terminated by a zero.
$0D FLTOIN Convert a FP number in D1-D2 into an integer in D0.
$0E INTOFL Convert an integer in D1 into a FP number in D0-D1.
$0F EQFL Compares the two numbers in D1-D2 and D3-D4. If they are equal then D0 contains 1, else it contains 0.
$10 NEFL Compares the two numbers in D1-D2 and D3-D4. If they are not equal then D0 contains a 1, else it contains a 0.
$11 GTFL Compare two numbers and return 1 in D0 if the first is greater than the second.
$12 GEFL Test if greater than or equal.
$13 LTFL Test if less than.
$14 LEFL Test if less than or equal.
$15 ASINFL Calculate ARC SIN of number in D1-D2 and return in D0-D1
$16 ACOSFL Calculate the ARC COS
$17 ATANFL Calculate the ARC TAN
$18 SINHFL Calculate the hyperbolic SIN
$19 COSHFL Calculate the hyperbolic COS
$1A TANHFL Calculate the hyperbolic TAN
$1B INTFL Get the integer part of D1-D2 and place result in D0-D1.
$1C POWFL Calculate X^Y where X is in D1-D2 and Y is in D3-D4. As usual the result is returned in D0-D1.

The Music Generator

Like the sprite definer, there is also a special music generator which functions completely independently of the rest of STOS basic. This can be called from any of your machine code programs by using a TRAP 7 instruction. To access these routines, place the function number in D0. Note that only registers D0 and A0 are modified by these commands.

The Music Traps (Trap 7)

)

no      name            action                                          parameters
0       INIT SOUND      resets the sound generator and kills music.     
1       START MUSIC     starts playing some music                       A0=address of music
2       STOP VOICE      stops the music played on a single voice        D1=number of voice
3       RESTART VOICE   resumes playing a single voice stopped by STOP VOICE    D1=number of voice
4       FREEZE  freezes some music      
5       UNFREEZE        resumes some music frozen with FREEZE   
6       CHANGE TEMPO    change speed of music                           D1=new speed (0-100)
7       START INTER     start music interrupts                          DO NOT USE !
8       STOP INTER      stop music interrupts                           DO NOT USE !
9       TRANSPOSE       change pitch of music by a number of semi tones D1=number of semi tones
10      GET VOICE       get position of tune in a voice D1=number of voice D0 returns position in tune

PSG(r)=x

r is the register number to be modified with the data x. The value of r can range between 0 and 13 (for the 14 psg registers). As soon as an array element is changed it is automatically loaded into the appropriate register. USE CAREFULLY!! IT CAN CRASH THE COMPUTER OR CORRUPT DISCS!!

reg     function

0       bits 0-7 set the pitch in units of single step for voice 1.

1       bits 0-3 set the size of each frequency step.

2       fine control for voice 2. Format as for register 0.

3       coarse control for voice 2. Format as for register 1.

4       controls pitch of voice 3. Format as register 0

5       coarse control of the pitch of voice 3.

6       bits 0-4 control the pitch of the noise generator. The higher the value the lower the tone.

7       bit: control register for sound chip.

        bit 0: play pure note on voice 1. 1 for on, 0 for off

        bit 1: voice 2 tone on/off

        bit 2: voice 3 tone on/off

        bit 3: play noise on voice 1. 1 for on, 0 for off

        bit 4: voice 2 noise on/off

        bit 5: voice 3 noise on/off

8       bits 0-3 control volume of voice 1. If bit 4 is set then the envelope generator is being used, and the volume bits are ignored. Since this corresponds to a volume of 16, this explains why you need to set VOLUME to 16 before you can use the ENVEL command.

9       as register 8, but for voice 2.

10      as register 8, but for voice 3.

11      bits 0-8 provide fine control of the length of the envelope

12      provides coarse control of the length of the envelope.

13      bits 0-3 choose which of the 16 envelope types to be used.