My STOS Falcon extension

My main programming project is an extension for STOS to allow it to take advantage of some of the features of the Falcon. Below is an HTML version of the read.me document.

Instructions for the Falcon Extension (v1.2)

Contents

Introduction

 This extension has been written to allow STOS to take advantage of the new facilities provided by the Atari Falcon. The current version only touches on some areas of the Falcons abilities very lightly. Future versions will hopefully go further, making programming the Falcon easier, without the need to resort to coding in assembler, or C.

To install the extension, simply copy the files FGRAPHIC.EXX and FAUDIO.EXY into the STOS folder, and FGRAPHIC.ECX, FAUDIO.EXY into the compiler directory.

When STOS initializes the graphics extension, it will select the correct Falcon resolution, so that STOS goes to a ST compatible screen rez, whatever you were in before running STOS. The initial resolution is not restored upon exit. In a screen mode where the vertical resolution is >=400 ST High will be chosen. Otherwise, ST Medium will be set. This will only be done on TOS 4 and above (- should TOS 5 every be released...).

This extension is SHAREWARE, so if you like it (or use it!!) then you should send me some money... See below for details.

Getting STOS to run on the Falcon.

Due to the way that STOS was originally written, STOS does not work correctly on the Falcon without patching. Even with patching, not all of the bugs can be removed. Some of the problems encountered are listed below, along with a sollution.

As you can see, STOS Fix is essential to use STOS on a Falcon. Remember that your compiled programs will suffer from the above problems unless they are also patched with STOS fix. I have found that if patched on TOS 4.04 they also work under TOS 4.01 and TOS 4.92a (hmmmm...). However, this should not be relied apon without further testing, and so, a note to this effect should be placed in the documentation of any released software.

STOS, will run under MultiTOS, so dont bother trying.... I have found, however, that compiled versions sometimes work...(to some extent) give 'em a go!

Registering.

This extension is shareware, and so, if you like it/use it, you owe me some money! As we all know, students are not the richest of people, so I can assure you that I could certainly use some cash...

I am only asking for 5 pounds (sterling), so it's not much....

If you register, you get a the latest version, along with a compiler that does not display the fact that you have not registered before running you program. I will also send you some example source code showing how to use some of the commands.

Registered users may write to me, with questions/requests and I will do my best to answer them. If you have internet access, I can send you all of the above via email (during the academic year), along with regular updates, if you want them...

If you dont feel that this extension is worth 5 pounds, write to me, telling me what is wrong with it (eg. commands/bugs etc), and I will try to fix it...

To register, simply send me 5 UK pounds (cheques payable to Anthony Jacques) at:

STOS Falcon Extension registrations,
70 West Avenue,
Oldfield Park,
Bath,
Avon.
BA2 3QD
ENGLAND

During the term-time of 95/96, I can be reached at:

25 Balleratt Street
Levenshulme
Manchester
M19 3DF
ENGLAND

Both addresses will reach me, but the Bath address may take longer during the accademic year, as it will be redirected by my parents. It should be noted that the Manchester address is ONLY for the accademic year - over holidays, mail will not be read/re-directed.

Frequently Asked Questions.

In this section, I shall answer some frequently asked questions about the extension. If you are having trouble, consult this section first, and if the answer to you question is not here, then email me...

SET VIDEO causes a bus error on my TOS 4.01/2 Falcon. Why?
Unfortunately, there seems to be a bug in these versions of the OS, which causes a bus error, when changing from an ST compatibility mode to a Falcon one. As STOS forces you into an ST compatibility mode on startup, this bug will crash your machine when you use this command. At the moment, the only way to successfully change mode on one of these machines is to use SET FV.
SET FV causes a division by zero error. Why?
For some reason, for a short period of time, one of the video registers becomes zero after being set. When this is used, it may be zero, causing the error. This error only occurs in versions < 1.1b, as from this version onwards, the extension pauses until the value is non-zero.
FALC CLS causes a bus error - why?
There is a bug in my code, which causes the vertical resolution to be incorrectly calculated (this is caused by the difference between RGB and VGA monitors) which causes FALC CLS to clear to large an area. If you experience this problem, please email me your version number, and the values returned by XRES, YRES and PLANES when in the selected video mode. A temporary solution is to use INIT VIRTUAL to set the width, and height explicitly....
Why dont FALC BOX etc. dont work correctly with SET FV?
This is a bug in my extension... At the moment, the number of bitplanes is not set by SET FV, and so the internal commands draw as if the number of planes is as the last video mode (often ST-med). This will be fixed soon (I hope)...
I have heard about another extension, by Anthony Hoskin. Is it compatible?
Yes and no. Unfortunately, we have both chosen to use the same letters for our extensions. If you rename them, you can have them both installed at the same time. The graphics commands are, at this time, incompatible (although I am working on that...). The audio commands are compatible though, from the testing that I have done...
Can this extension really be used to write full games?
Yes! Although the extension currently only has a small number of sprite commands, it is possible to write a game, running in true-colour using only this extension and STOS (and Spooky Sprites). I know of one game already in the pipeline, and an introduction to another game already written.

Command descriptions.

Following is a list of the instructions/functions, and what they do.

Some of these instructions assume a Falcon. If a falcon specific instruction is called on an ST, I do not know what will happen. (I would guess a bus error or illegal instruction). The user should test what machine the program is running on first (either using os version, or cookie).

General

x=cache

This function returns the current state of the '030 instruction and data caches. The result is represented by a sequence of bits. They are encoded in in the same way as in SET CACHE.

x=cookie(cook)

This function returns the value of the given cookie. If there is no cookie jar, or the cookie is not found, it returns a "Not Found" error.

eg.
10 print cookie("_MCH")

will print the value of the _MCH (machine) cookie. On a TOS 1.0 FM this will give the error message "Not Found in line 10."

A list of cookie ID's and the ascoiated meanings can be found on the WWW (email me for an address). The Atari cookies are also listed in Hisofts Modern Atari System Software - Appendix C.

falc help

This instruction displays on screen the syntax of each command available in this extension. This is designed to make it easier to use the commands.

As this is intended for editor use, this instruction cannot be compiled.

x=jagpad(port)

This function returns a binary value giving the state of each of the 21 keys on a Jaguar controller connected the the extended controller port PORT (0-1) The value returned allows the programmer to detect any combination of keys.

The bitwise representation of this value is :-

1 4 7 * 3 6 9 # 2 5 8 0 o p c b a r l d u

Where o = option, p = pause, a/b/c = fire buttons r/l/d/u=directions, and the others are keys on the "phone pad".

Each bit can be tested by anding with the bitwise value
ie
10 x=jagpad(0) : if (x and %10) then down
20 if (x and %1) then up

lfalc help

This instruction sends the help screen that is displayed by FALC HELP to the printer. This should be used if you do not intend to print out this manual.

As this is intended for editor use, this instruction cannot be compiled.

x=monitor

This returns the monitor type that is currently connected.

The form of x is :-
0 = ST mono monitor
1 = ST colour monitor
2 = (S)VGA monitor
3 = Television.

There is no method of distinguishing VGA and SVGA monitors. SVGA are capable of a wider range of frequencies and resolutions, but you will have to take the word of the user that their monitor can cope.

x=os version

This function returns the OS version. The radix point is not inserted, but is always two digits from the right. (eg. $404 = $4.04)

eg. 10 print hex$(os version)

set cache VALUE

This instruction sets the current state of the cache. VALUE is encoded in the following way:

x x x x x x x x x x x 
| | | | | | | | | | |__ Enable Intruction cache.
| | | | | | | | | ----- Freeze instruction cache.
| | | | | | | | ------- Clear instruction entry.
| | | | | | | --------- Clear instruction cache.
| | | | | | ----------- Instruction burst enable.
| | | | | --- Enable data cache.
| | | | ----- Freeze data cache.
| | | ------- Clear data entry.
| | --------- Clear data cache.
| ----------- Data burst enable.
------ Write allocate
As you can see, it is quite complex. However, for optimum speed, a value of 12561 should be passed.

NOTE: Encoding technique is likely to change (to simply on/off).

Graphics

cycle index,count

This instruction cycles COUNT palette entries starting from INDEX in the Falcons 256 colour palette.

All of the palette handling routines also apply to the NON-ST COMPATABILITY bit-plane based modes (ie. not true colour, or ST comp.)

df videl n,h,s,o,p,v,8,c

This instruction defines a video mode N, which can range from 1-9. This mode is defined by the remaining flags. The value of these flags does not matter (with the exception of c) To set a flag, give a non-zero value. The meanings of thes flags are :-

h - vertical height (double line / interlace)
s - ST compatibility mode
o - overscan (enabled)
p - PAL / NTSC (ie set = 50Hz, clear = 60 Hz)
v - VGA mode
8 - set 80 column mode
c - Number of colours. Valid values=2,4,16,256,65536. Other values give 2.

eg.
df video 1,1,0,0,0,1,0,65536 would set 320x240x65536 on a VGA monitor

Please make ALL programs both VGA and RGB compatible. There is a small enough user base, even without dividing it!!!

NOTE: 640x?x65536 is not a valid mode for a VGA monitor....

falc bar col,x1,y1,x2,y1,scr

This instruction draws a filled bar on the screen at address SCR. This screen is assumed to be of the resolution / colour depth as the current one. The co-ordinates of the bar are given by x1,y1,x2,y2 assuming the first pair to be the top left corner, and the second the bottom right.

It is drawn in the current colour.

falc box x1,y1,x2,y2,scrn

This instruction draws a hollow box on the screen at address SCR. The screen is assumed to be of the same dimensions/colour depth as the current screen. The top left corner is drawn at the point (x1,y1), and the bottom left corner at the co-ordinates (x2,y2).

It is coloured with the current colour.

falc cls scr_address

This instruction clears the screen at the given address. It uses the blitter in HOG mode, so do not use if another extension is utilising the BLiTTER in interleave mode. The entire screen (even with a virtual screen) is filled with colour 0.

There have been a couple of errors caused by this command... untraced...

falc colour index,red,green,blue

This instruction sets colour number INDEX in the palette to the colour made up of the components RED,GREEN and BLUE. Each of these can range from 0-63. So, white is defined as 63,63,63.

falc draw screen,x1,y1,x2,y2

This instruction will draw a line in the currently selected colour on the screen at address SCREEN from coordinates X1,Y1 to X2,Y2. At the moment, only horizontal and vertical lines will be drawn, and only in true-colour modes. This will change soon...

falc ink index

falc ink red,green,blue

This instruction sets the current colour for all (my) graphics routines. The value index is the 16-bit colour value when in true-colour mode, otherwise it is the index of the colour in the palette (0-255).

If the three value version is used in true colour mode, then the three values will be combined to make the 16-bit colour from the red,green and blue components. It should be noted that to ensure that the collision bit is not set, an even value should be passed for green.

n=falc mkey

This funtion returns the state of the mouse buttons when using the mouse routine from this extension. The value return is encoded in the same way as the equivelent STOS routine - ie : 0=none, 1=left, 2=right, 3=both.

falc mouse off

This instruction switches off the Falcon extension mouse command, and restores the STOS mouse routine.

falc mouse on

This instruction enables a mouse routine which is able to go beyond the screen size of ST-high. It takes the maximum dimension of the screen from the current dimensions. Thus, if using a 800x600 virtual screen, this is the range of the mouse co-ordinates.

It should be noted, that unlike the STOS mouse routines, a pointer is NOT displayed at the current postition of the screen. If this is desired, tc sprite/tc copy can be used in true-colour mode.

falc plot screen,x,y

This instruction plots point (x,y) on screen with the current colour. The routine is faster than the STOS 'PLOT' command, even though it supports 4/16/256 and true-colour modes!!

falc set mouse x,y

This instruction sets the current position of the mouse cursor to the coordinates (X,Y) as given.

falc set zone n,x1,y1,x2,y2

This instruction defines a zone which can be tested for the presence of the mouse. X1,Y1 is the co-ordinate pair of the top-left corner of the box to be defined. X2,Y2 is the co-ordinates of the bottom right hand corner. N is the number of the zone to be defined, and may range from 0 to 63

.

n=falc x mouse

This function returns the x co-ordinate of the mouse pointer when using the mouse routine in this extension.

n=falc y mouse

This function returns the y co-ordinate of the mouse pointer when using the mouse routine in this extension.

n=falc zone(m)

This function returns whether or not zone number M contains the mouse-pointer or not. The value returned is either TRUE (-1) or FALSE (0)

fpal adr,index,count

This instruction copies the palette to the memory starting at ADR. INDEX is the number of the first palette to store, and COUNT is the number to store. The data is stored in the same format as SET FPAL.

gdos font n,addr

This instruction sets which font will be used by tc text. ADDR holds the address of the font, and N is the number of the font in the data to use (More than once size may be held in one data-block).

Although the routine uses GDOS fonts, currently only the system font is supported. This will change very soon. This routine has been included at this stage as not all OS versions have the font at the same address.

To find the system font in memory, use a memory searcher program (such as MON from devpac) to search for the string "system", as this is in the font name. The data should say "8x8 system font" (or 6x6 or 8x16). This address-4 should be passed to this instruction.

Registered users have a piece of source code which actually searches for the fonts, and returns the relevent addresses... On my TOS 4.04 Falcon the following addresses were found: (addresses as passed to instruction)

goraud scr,col,x1,y1,i1,x2,y2,i2,x3,y3,i3

This instruction draws a goraud shaded triangle on a true colour screen at address SCR. x1-x3 and y1-y3 are the co-ordinates of each of the three corners. i1-i3 are the relative inensities of the three points. This may range from 0 to $7fff.

The corners should be specified in a clock-wise direction.

COL determines the colour. The valid values are :-
0 - Red
1 - Green
2 - White
3 - Brown/orange

If the colour is anything other than these, it will be assumed to be the address of the colour table. The colour table consists of 32 words, each a true colour value. word no. 0 is the darkest and word no. 31 the brightest. This must be followed by 16 empty words.

NOTE: CANNOT BE COMPILED.

init goraud

This instruction sets up various parameters for the Goraud routine (see above). This MUST be called before goraud.

NOTE: CANNOT BE COMPILED.

init virtual xres,yres

This command initialises a virtual screen of dimensions XRES by YRES. The actual resolution of the screen / number of colours is determined by the current screenmode. Calling setvideo 0 will restore the screen.

x=planes

This function returns the number of bit-planes in the current screenmode. The values returned are 1,2,4,8 and 16.

x=quick fade(colour)

This function fades a 256 colour palette to the given colour. The colour is stored as a 18-bit number, where the top 6 bits represent the Red component, the next 6 are the Green component, and the bottom 6 bits are the Blue component.

The returned value, x is the number of palette entries changed.

NOTE: There seems to be some inteference at the top of the screen ?!?

x=scrsze(videomode)

This function returns the amount of memory taken for a given screenmode. The value VIDEOMODE is the number (0-9) of the defined video mode.

This function does not take account of any virtual screen, or expanded screen (using set fv)

set fpal addr,index,count

This instruction sets the Falcons 256 colour palette. ADDR stores the address at which the first palette entry is held. INDEX stores the first register to change, and count is the number of colour registers to change.

The data is stored longwords in the XRGB format of the XBIOS. An array can be used to hold the palette data, with the address passed using varptr.

eg.
set fpal VARPTR(MYPAL(0)),0,256

set fv addr

This command allows the use of non-standard screen resolutions by setting the video registers to those specified in a FV (version 2) file. The address of the start of this file is passed in the parameter ADDR.

Note that FV files are, by their very nature, dangerous, as setting the registers to incorrect values could be harmful to your monitor. I take no responsibility for any problems caused by using this command. Having said this I have synced my SVGA up to 100Hz, and have had no adverse effects...

set video n

This instruction sets the video mode to a previously defined mode. N may range from 0-9. Video mode 0 is set to the video mode which is chosen at boot-up of STOS (ie ST Medium / ST High) - and is changed by the ST COMPAT command to the new default resolution.

On TOS < 4.04, when changing from an ST mode, a bus error / illegal instructions are caused by the operating system. Unfortunately, as STOS forces the Falcon into an ST mode, every time this instruction is executed on < TOS 4.04 it will crash your machine. If compatibility is essential, then use set fv to change the video mode.

st compat n

This command switches the video mode from one ST screen mode to another. It initialises both this extensions graphics commands, and the STOS routines for the new mode. N may range from 0 to 2, where 0 is ST Low and 2 is ST High.

The command should work on an ST (although cannot switch to ST High).

At this time, it is neccesary to use the DEFAULT command after this instruction as It does not completely re-initalise STOS. I hope to remove this problem.

tc alpha mask

This function sets a mask which is used for allowing only certain bits to be effected by sprite commands. The value MASK is a 16-bit value, which indicates which bits of the background colour are overwriten, and which are not. If a bit has a 1, the value of that bit in the sprite is used - a value of 0 causes the backgound pixels bit to be used.

eg:

10 if monitor=2 then df video 1,1,0,0,0,1,0,65536 : else df video 1,0,0,0,1,0,0,65536
20 reserve as work 1,scrsize(1) : bload "backgrnd.bld",1
30 reserve as work 2,10000 : bload "sprites.trs",2
40 physic=start(1) : set video 1
:  :
100 tc alpha %1111100000011111
110 tc sprite X,Y,0,physic,start(1)
This will display only the red and blue components of the sprite, with the green component as it was in the background before the sprite was placed. A mask of $FFFF (all sixteen bits set) will give the sprite, unchanged. A value of 0 would not display the sprite at all (although the colision test would still be performed.)

This can be used to provide semi-transparent sprites, such as the mouse pointer in Moonspeeder's menu. To get a feel for how to use it, just play arround with different values...

x=tc collide

This command returns a value to indicate whether or not a collision occured during the previous sprite plot. A value of 0 is returned if no collision occured, or 1 if a collision was detected.

Unlike the STOS collide routine, this is pixel perfect - ie the object may be any shape, with only one pixel overlapping, and a collision will be detected. However, for this to work, somewhere the sensative parts of the screen (for backgrounds may also be sensative) must be stored. I have chosen to store this information in bit 5 (The LSB of the green part of the colour). This is because this bit does not make a noticable difference in colour, and it is used for other things (such as the genlock alpha channel).

The test is performed on any part of the sprite being ploted (non see-though) to test whether bit 5 is set in the background.

If using this command in conjunction with tc alpha, then ensure that bit 5 is not masked out by the alpha command. if you wish your sprites to be sensative to each other...

tc copy scr1,x,y,w,h,scr2,x2,y2

This instruction copys a block of width W and Height H from the point (X,Y) on the screen at address SCR1 to the screen at address SCR2, with the top left corner at the point (X2,Y2). This instruction uses the BLiTTER chip in HOG mode to perform the operation, so do not use the blitter extension to start a copy in shared mode and then call this instruction.

NOTE: Dont pass -ive width and height parameters! I tried this, and it caused my machine to reboot, and trashed the NVRAM !!!!!

x = tc fade(length,address)

This function fades a True Colour screen towards the currently selected colour. The ADDRESS is the start of the screen to fade. LENGTH is the length of the part to fade. (ie the length of 1 screen if the whole screen is to be faded.)

The returned value is the number of pixels that were faded. When this value is zero, the whole screen has be faded to the given colour.

z=tc point screen,x,y

This returns the RGB value z, of the pixel on screen at coordinate (x,y) in True Colour mode. This command has the same purpose as the STOS command point.

tc scrn fade screen1,screen2,length

This instruction fades one True Colour screen into another. Simply pass the addresses of the screens as parameters, and the length.Both screens must be of the same size.

tc sprite x,y,n,scr,spr

This instruction draws a sprite created with Spooky Sprites (by Johan Karlsson - d92jk@efd.lth.se ) in true colour mode. X and Y are the co-ordinates at which to plot the sprite. N is the number of the sprite to draw. SCR is the address of the screen, and SPR is the address of the sprite bank.

Currently, clipping is only supported vertically on UNPACKED sprites. However, further support is on the way...

tc text screen,x,y,string$

This instruction will print the string stored in STRING$ on the screen at address SCREEN at coordinates X,Y. It will be printed in the current font (not the STOS one) The text is plotted in the currently set colour, using FALC COLOUR.

Future versions (very soon) will support GDOS fonts, stored at the given address. However, only fonts with the data in motorola format will be supported as I dont want to slow the printing down by supporting both Intel and Motorola formats.

INFO: Motorola / Intel format:
Motorola format is where 2 byte values are stored HIGH BYTE | LOW BYTE. (ie with the bits from left to right decreasing in significance.)

Intel format is where 2 byte values are stored LOW BYTE | HIGH BYTE. Thus, to convert from one format to the other requires that the two bytes are switch order. I will supply a STOS program which will detect whether it is a motorola or intel font, and to convert an intel format one into a motorola. You are free to use it in any program you like to allow all GDOS (not Speedo) fonts to be used by you programs.

tga decode tga_addr,dest_addr

This instruction will decode a type 2 targa (.TGA) picture. The targa should be at the address TGA_ADDR, and the destination screen should be at DEST_ADDR. The screen is assumed to be of the correct size for the targa, and is assumed to be a true-colour screen.

To ensure that you reserve enough memory for the decoded picture, the size can be calculated by:

width * height * 2

The source and destination addresses should be different, as corruption will occur in most pictures - only those stored left-to-right and top-to-bottom will not be corrupted by decompressing over the original file.

The decode routine only supports type 2 targas. These are by far the most common type, and are uncompressed true colour images. (15/16/24/32 bit). The routine does however support any of the four orientations in which the picture may be stored.

x=tga height(addr)

This function returns the height in pixels of the targa at ADDR. This is useful for calculating the amount of space required for the picture.

x=tga width(addr)

This function returns the width in pixels of the targa at ADDR. This is useful for calculating the amount of space required for the picture.

virtual x,y,screen

This command positions the view-port in a virtual screen. The virtual screen should start at SCREEN, and X,Y should be the co-ordinates of the top-left pixel to be displayed on screen.

Currently in bit-plane modes, only screens with X a multiple of 16 will be displayed correctly. In true-colour mode, X must be a multiple of 2.

The virtual screen is achieved through the 'Hardware Scrolling' hardware, and so can be used to implement infinite scrollers...

X=xres

This function returns the horizontal resolution in pixels. This includes any virtual screen that is in use, and will take account of unusual modes defined with a .FV file.

Y=yres

This function returns the vertical resolution in pixels. This includes any virtual screen that is in use, and will take account of unusual modes defined with a .FV file.

Sound

dsp clear

This command can be used to reset the entire sound sub-system. It does this using the XBIOS call Sndstatus, however, it does not perform exactly as the system call.

The command flushes the DSP of all subroutines, and then tri-states it (disconnecting it from the sound-system). All DSP interupts are disabled, and all conections (not just the DSP) in the sound system are disconected. The sample playback resolution is set to 8-bit stereo, and all DMA transfers are halted.

However, unlike the XBIOS, the gain and attenuation (volume) settings are not cleared, and the PSG and the Matrix are both connected to the audio output.

This command should be used to clear the sound-system if an error occurs, or to remove a DSP routine which has been loaded in (either with TRAP or with the DSP PROCESS command).

All internal flags are cleared, and so, any play routines will not need the corresponding stop. (eg DTM PLAY start(14),155555 : DSP CLEAR would not need a DTM STOP command, as DSP CLEAR would do this.)

dsp play modaddress

This instruction plays a 4-track mod file on the DMA sound system using the DSP. This causes little slowdown, unlike other replay routines.

Due to a bug in part of the code (not by me), the file "dspmod.bsw" must be loaded each time a module is played. This file is read by the extension from the current directory. If the file could not be found, the "Not done" error will be returned.

(for those who wish to know why, the code cannot be run twice, as it seems to modify itself {or a variable} causing an illegal instruction.)

modaddress is the address at which the module can be found. If this is a memory bank, it must be specified as start(10), not as 10.

eg.
10 reserve as work 15,195636 : load "bubleman.mod",15 : dsp play

dsp process file$,buffer,mode

This instruction allows you to process audio data with the DSP. The DSP load file (.LOD) FILE$ is loaded into the dsp with the DSP_LoadProg call. BUFFER should point to an area of space which can be used to process the .LOD file. The size of this area is "3 * (length of program / data words + (3 * no of blocks in program))".

MODE is a value which indicates what you wish to be processed. There are currently 3 modes. These are:

A forth mode may be added, which takes a sample in memory, processes it, and places it back in memory. This would allow perminant processing.

For further details, see the example .LOD files, and related documentation.

dsp stop

This instruction stops the dsp module that currently is playing. If the mod is left playing, and the memory is re-allocated (eg exiting STOS), the code will cause a bus error (probably...)

X$=dtm inst (number,addr)

This function returns the name of instrument no. NUMBER in the DTM module at address ADDR. The name is returned in the form of a string. The instrument name is often used to store information about the module, writen by the composer.

eg.

10 reserve as work 10,355000 : bload "test.dtm",10
20 i$=dtm inst(1,start(10)) : print i$

will print the name of the first instrument in the DTM module TEST.DTM.

x$=dtm name(addr)

This function returns a string containing the name of a DTM module at address ADDR.

eg.

10 reserve as work 10,355000 : bload"test.dtm",10

20 i$=dtm name(start(10)) : ? i$

will print the name of the module TEST.DTM

dtm play dtmaddr,length

This instruction plays a Digital Tracker Module using the DSP and the Audio sub-system. The address of this module should be passed in the dtmaddr parameter, and also the LENGTH of the file.

When reserveing the space for the module, you must reserve an extra 200000 bytes, as this is used as temporary storage by the player routine.

The current version of the player only supports 8-bit mono samples, and only modules with an even number of voices (up to 32 tracks!!!)

NOTE: CANNOT BE COMPILED

dtm stop

This instruction stops a piece of DTM tracker music.

NOTE: CANNOT BE COMPILED

X=dtm voices addr

This function returns an the number of voices (or tracks) that the DTM module at address ADDR uses. This command can be used to test that the module uses an even number of tracks, as the current replay routine does not support modules with an odd number of tracks.

falc freq value

This instruction selects what frequency should be used for DMA sound (ie for DSP PROCESS, and FALC SAMPLE / SAMPLAY. The change will only take effect when the next command using the DMA is called.

There are 8 different frequencies available. These are coded in the following way:


  1 = 49170 Hz          5 = 16390 Hz
  2 = 32780 Hz          7 = 12292 Hz
  3 = 24585 Hz          9 =  9834 Hz
  4 = 19668 Hz         11 =  8195 Hz
All other values will give a MUTE condition (ie it wont play....).

NOTE: The frequency encoding is likely to change, to allow for 50, 25.5 and 12.5 Khz freqencies also supported by the DMA.

Falc mic thru

This instruction toggles the microphone through, and the PSG output. Both are mixed with the output of the matrix (ie DMA/DSP). This can be used to allow the output of an external device such as a walkman through you Falcons speakers.

Falc sammde x

This instruction sets the resolution of sample playback. The value X gives the mode. Valid modes are :-

0 - 8 bit stereo
1 - 16 bit stereo
2 - 8 bit mono
This call does not effect recording mode - all recording is done at 16 bit stereo.

Falc samplay start,end,loop

Using this command a sample starting at address START and ending at END can be played on the Falcons DMA sound-system. The sample is played at the currently selected frequency.

The value LOOP indicates whether or not the sample should be looped. If the value is zero, the sample will not be looped, otherwise, it will be.

There are 8 different frequencies available. These are coded in the following way:


  1 = 49170 Hz          5 = 16390 Hz
  2 = 32780 Hz          7 = 12292 Hz
  3 = 24585 Hz          9 =  9834 Hz
  4 = 19668 Hz         11 =  8195 Hz
All other values will give a MUTE condition (ie it wont play....).

NOTE: The frequency encoding is likely to change, to allow for 50, 25.5 and 12.5 Khz freqencies also supported by the DMA.

Falc sample start,end

This command uses the Falcons 16-bit sampling hardware to record a sample into memory starting at START. END is the end of the record buffer, and the sample will not exceed this buffer. Although it doesn't pass the end, sound can still be heard even when the buffer is full. Stop this with FALC MIC THRU.

The sample is recorded at the current frequency. Remember that all recording is done in 16-bit stereo, whatever mode has been set.

X=Falc sampos(mode)

This function returns the address of the current sample being played or recorded. Which is returned is determined by the value MODE. If mode=0, then the record pointer will be returned, otherwise, the playback pointer is returned.

There are two uses for this instruction. One to find the end of a sample.

Eg.
10 falc samplay strt,end,freq
20 repeat
30 until (falc sampos(0)>end)
40 falc samstop

This program would stop the sample when it reaches the end.

Or, alternatively, it can be used to find the current samples value.
Eg.
10 falc sammde 0
20 falc samplay strt,end,freq
30 repeat
40 plot x,100 : x=peek(falc sampos(0)) : plot x,100
50 until (falc sampos(0)>end)
60 falc samstop

This program would play an 8-bit mono sample, and plot a single point on its waveform. This could be used to constuct an osciliscope display. If the sample is stereo, the right sample comes imedately after the left.

Falc samstop

This instruction halts all DMA sound interupts (both record and playback). Note that this does not disconnect the microphone throughput, or stop any PSG based sound.

set gain l,r / x=lgain / x=rgain

LGAIN and RGAIN return the left and right input gains. Set gain, sets the left and right gains to L and R. All values range from 0 to 15. Each step is a gain of 1.5 dB.

This is done with the XBIOS command (not using the memory location.)

set volume l,r / x=lvolume / x=rvolume

LVOLUME and RVOLUME return the left and right output volumes. Set volume sets the left and right volumes to L and R. All values range from 0 to 15. Each step is a decrease of 1.5 dB.

speaker on / speaker off

These two instructions switch on/off the internal speaker.

programs should give the user the choice of having it on/off, since not all users have external speakers, and VGA monitors do not include speakers.

X$=tracker inst (number,addr)

Like the command DTM INST, this function returns the name of instrument No. NUMBER in the .MOD module at the address ADDR.

tracker name (addr)

This command is similar to DTM NAME, and performs the same task - returning the name of a module at address ADDR, but for a .MOD module. The name is returned in the form of a string, which is never over 20 characters in length.

Instructions in progress

In the current version of this extension, incomplete instructions are included, as you may know if you use the extension selector... You are welcome to try and get these to work, but if they are not documented, they are not finished - ie dont work...

I hope to replace all of the remaining TC commands with a FALC version. This will detect the current screenmode, and draw etc. in the correct way. TC GORAUD may be an exception to this....

comming soon....

Version history :-

 Work for this extension began on 10 December 94 (I think).

V0.1
First interpreter extension code (ever!!!)
With instructions - set fv, get fv, cookie and speaker on / off, goraud (not working).
V0.2
Added gain, attenuation, jagpad (not working), dsp play, dsp stop.
Installed start-up code.
V0.3
Removed set fv, get fv.
Added set videl, videl, monitor, os version.
Fixed DSP play.
V0.4
Added tc fde, tc scrn fde, my fde, tc plt, tc pnt, scrsze.
Fixed start-up for RGB (I think - not tested)
Changed gain etc. to use XBIOS calls, rather than memory location.
V0.4a
Fixed scrsze (typo), and added checking to DSP play/stop to prevent errors due to the other not being called ( ie DSP stop with no play) Finally coded jagpad (why did Atari make it so complex?!?)
Completed quick fade,tc point and tc plot.
V0.5a
Started cycle, and started falc play.
Fixed gain/attenuation to accept variables.
Started DTM play / stop.
Replaced set l/r atten with set volume.
Replaced video mode routines
V0.5b
Complete re-write from v0.3 ish due to source code being wiped.
Added TC sprite and falc sammde.
TC FADE/TC SCRN FADE/TC PLOT/TC POINT no longer work....
V0.5c
Fixed the above (TC) routines.
Fixed sprite/graphics routines to work with all resolutions.
V0.6
Fixed start-up for RGB. Fixed DSP play bug.
Completed goraud / init goraud / dtm play / dtm stop.
Added TC bar / TC box.
Started virtual/init virtual.
V0.7
Added TC copy / set fpal / fpal.
Completed cycle.
Changed quick fade to 18-bit parameter, from palette form. Compiler now coming on-line.....
- TC BOX/TC BAR/TC PLOT/TC POINT/DF VIDEO/SET VIDEO/ OS VERSION/COOKIE/LVOLUME/RVOLUME/SET VOLUME/LGAIN/ RGAIN/SET GAIN/TC FADE/TC SCRN FADE/QUICK FADE/ TC SPRITE/SPEAKER ON/SPEAKER OFF/MONITOR/SAM MODE and SCR SZE all now work compiled.....
V0.8
Added falc mic thru / falc samplay / falc samstop / falc sampos.
Added falc sample / set fv
Added above commands to compiler.
Added FPAL/SET FPAL/CYCLE to compiler.
Fixed set video for TOS 4.02 (I HOPE!!!!! - NO. Try again....)
V0.9
Split extension into 2 parts - due to limit of size.
Added dtm name, tracker name, dtm voices, dtm inst, tracker inst to both Compiler and Interpreter extensions.
Fixed goraud for any polygon (not just trianges).
Added dsp process and dsp clear, falc freq, falc ink
Fixed dtm play/dsp play clash.
V0.9a
Fixed a few Compiler bugs.
Completed falc cls. Finished init virtual/virtual
Fixed tc box bug.
Started bitplane mode graphics routines...
V0.9b
Completed bitplane graphics for 4/16/256 colours.
Fixed compiler DSP play.
Added set cache,cache.
Added st compat
V1.0
Goraud polygon back to only triangles (so that it actually works!!)
Added falc colour
Various bug-fixes
Example code for registered version available.
Un-registered compiler extension now has start up message.
Added falc help and lfalc help.
Added xres,yres and planes.

V1.0a
Added tga width, tga height and tga decode.
Fixed yres
Fixed falc mouse clipping.
Falc mouse now compiles.
Finally fixed setvideo for TOS 4.02 (OS bug...)
Fixed TC sprite for compiler

V1.1
Added tc text and tc collide
Fixed a couple of minor bugs.
Started tc alpha.
Started .AVR reading code.
Started falc draw

V1.1a
Added gdos font
Fixed bugs in tc text
Added collide to compiler
Falc draw partially implemented
Made mouse routine more stable in editor

V1.1b Fixed bug in yres calculation (caused bus error in falc cls)
Fixed (?) bug in set fv

V1.1c
Fixed bug in FALC INK's alternative parameters (compiler only)
Fixed another bug in set fv - number of planes was not set...

V1.2
FLI Player code coming on-line...
Completed TC ALPHA
improved compatibility with Anthony Hoskins' extension.

Just a little note... Recently, there have been more a/b/c releases. These are in response to bug reports from users... (eg. if a registered user finds a bug, I will try to track it down, and squash it quickly ...) These releases are not placed in FTP sites, just my WWW page, and UUE'd to registered users...

Future versions may include other commands, as I think of how to do them.... (such as more graphics functions; d2d play and more...)

Credits :-

All the rest is by me (Anthony Jacques)

Cheers to RiCH Davey for testing/suggesting commands, and Les Greenhalgh for the tips on extension writing... and of course, to all registered users...

Back to the Atari page...

Anthony Jacques :- jacquesa@cs.man.ac.uk