Instructions for the Falcon Extension (v1.1a) Contents * Introduction. o Introduction. o Getting STOS to run on the Falcon. o Registering this software. * Command descriptions :- o General + cache + cookie + falc help + jagpad + lfalc help + monitor + os version + set cache o Graphics + cycle + df video + falc bar + falc box + falc cls + falc colour + falc draw + falc ink + falc mkey + falc mouse off + falc mouse on + falc plot + falc set mouse + falc set zone + falc x mouse + falc y mouse + falc zone + fpal + gdos font + goraud + init goraud + init virtual + planes + quick fade + scrsize + set fpal + set fv + set video + st compat + tc collide + tc copy + tc fade + tc point + tc scrn fade + tc sprite + tc text + tga decode + tga height + tga width + virtual + xres + yres o Sound + dsp clear + dsp play + dsp process + dsp stop + dtm inst + dtm name + dtm play + dtm stop + dtm voices + falc freq + falc mic thru + falc sammde + falc sam play + falc sample + falc sampos + falc samstop + set gain / lgain / rgain + set volume / lvolume / rvolume + speaker on/off + tracker inst + tracker name * Commands in progress. * Version history. * Credits. 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. * Problem: The mouse does not respond. Solution: Use STOS Fix 3.0 or above to patch basic206.prg * Problem: The joysticks do not work. Solution: Use STOS Fix 3. * Problem: The keyclick goes wild. Solution: Use STOS Fix 3 (not BASICMJH.PRG) * Problem: Graphics functions dont work. Solution: Un-patched. Use graphics functions from an extension. (This one?) * Problem: Computer crashes apon quiting. Solution: Use STOS Fix 3. * Problem: Change mouse to user defined doesn't work. Solution: Un-patched. Use sprite x mouse,y mouse. * Problem: Palettes are not correctly set. Solution: try SET FPAL in this extension..... * Problem: Running STOS from >= 400 vertical resolution mode does not work. Solution: Install this extension! This will set it to ST High mode if this is the starting resolution. 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 do not try.... I have found, however, that compiled versions sometimes work... 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 or, during the 95/96 academic year, STOS Falcon Extension registrations, Anthony Jacques 25 Balleratt Street Levensulme Manchester England 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. On my TOS 4.04 Falcon the following addresses were found: (addresses as passed to instruction) * 6x6 - $e4afec * 8x8 - $e4b6c8 (This address is used by default) * 8x16- $e4d124 If a value of 0 is passed in ADDR, then the last address used will be retained. In my Falcon, if N is 1, and ADDR=8x8 font then the 8x16 is used.) 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. 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. 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: * 0 : Process audio through. Data is passed from the ADC -> DSP -> DAC, and so provides real-time processing. * 1 : Process audio record. Whenever FALC SAMPLE is called, the data is passed via the DSP, enabling filtering etc. to be performed at record time. * 2 : Process audio playback, Whenever FALC SAM PLAY is called, the sample is passed through the DSP, enabling effects to be performed on previously recorded data. 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. These will, in general, cause some kind of error (eg bus / syntax) if called (plus I dont tell you the necessary parameters ;-) I hope to replace all of the 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.... * tc alpha - make TC sprites translucent. * .AVR file support. * optimised bitplane graphics. * bitplane mode sprites. * falc draw. * Extension for registered users only. (watch out for more details...) 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 Future versions may include other commands, as I think of how to do them.... (such as more graphics functions; FLI player; d2d play and more...) Credits :- * True colour sprite routine : Johan Karlsson * True colour fade : Genie! of Network Trash * Goraud polygon : Griff * DTM replay code : Jaccard Emmanuel * DSP tracker code : bITmASTER of BSW * FV file format : Johan Karlsson 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... Anthony Jacques WWW: http://www.cs.mna.ac.uk/~jacquesa/ email: jacquesa@cs.man.ac.uk