Maximum MODS

home *** CD-ROM | disk | FTP | other *** search

/ Maximum MODS / MaximumMODS.iso / amiga / delitracker_1.36 / docs / delitracker.doc next >

Wrap

Text File | 1996-01-23 | 54KB | 1,399 lines

*************************************************************************** * DeliTracker * *************************************************************************** ⌐ 1992 by Delirium $VER: V1.36 (07.01.1993) 1. CONTENTS 1.CONTENTS 2.LICENSING AND DISTRIBUTION 3.INTRODUCTION 3.1 What is DeliTracker ? 3.2 Why use DeliTracker ? 4. GETTING STARTED 4.1 System requirements 4.2 Starting from CLI/Shell 4.3 Starting from Workbench 4.4 Installation 5. BASICS 5.1 Player 5.2 Packed modules 5.3 Options 5.4 Configuration files 6. HOW TO CONTROL DELITRACKER 6.1 The main window 6.1.1 Gadgets 6.1.2 Menus 6.1.3 Shortcuts 6.1.4 Appwindow 6.2 The preferences window 6.2.1 Gadgets 6.2.2 Shortcuts 6.3 ARexx 6.4 Commodities 7. TROUBLESHOOTING 8. EXTERNAL PLAYER PROGRAMMING INTERFACE 8.1 The external player interface 8.1.1 The structure of external players 8.1.2 The structure of custom modules 8.2 How to build external players 8.2.1 Playerheader 8.2.2 Modulerecognicion 8.2.3 Interrupts 8.3 Tags 8.4 DeliTracker support functions 8.5 Hints and Tips 9. ACKNOWLEDGEMENTS 2. LICENSING AND DISTRIBUTION DeliTracker (c) 1991 - 1993 by Peter Kunath and Frank Riffel. This Program is Shareware. If you like this program and use it frequently, we encourage you to register. The shareware fee is $US 20 or 20 DM. You may send CASH or EUROCHEQUE's. We cannot accept any other cheques cause it is not possible for us to cash foreign checks without having to pay substantial fees to the bank. Registered users will be shipped a disk with the latest release version of DeliTracker. By cooperating with this concept you help to ensure continued development of this product. Please send your registration card (Orderform) and the money to: Frank Riffel Merkstr. 27 8129 Wessobrunn Germany You may send bug reports, remarks, and suggestions to this address as well. If you have written a new soundsystem and you wish to adapt your replay-routine to DeliTracker, contact us. We will help you. DeliTracker may be distributed on public-domain, shareware disks, and electronic networks such as the Internet as longs as the followings conditions are fulfilled: ░ all files must be kept together. You can find a list of all files in 'Distribution'. ░ no part of the distribution may be changed in any way. The only exception is archiving (e.g. with LhA), but the original files must be 100% restoreable. ░ The price of a disk that contains DeliTracker must be less than US $6 or 8.- DM. The same is the maximum price that networks may charge from their users for downloading DeliTracker. ░ For use in commercial products the permission of the authors is required. DeliTracker was developed and tested very carefully. Nevertheless the Authors are not responsible for any damages that are caused by DeliTracker. Use at your own risk. 3.INTRODUCTION 3.1 What is DeliTracker ? DeliTracker is a soundplayer which supports several soundformats; some are SoundTracker 15 inst., SoundTracker 31 inst., NoiseTracker, ProTracker, StarTrekker without AM sounds and CustomPlay. Since these types are so common, their replay routines are built within DeliTracker itself. Additional players are loaded from disk, meaning that you can very easily add/update players by placing them into the DeliPlayers directory. DeliTracker is NOT a Songeditor, MIDIsequencer or Digitizer. It is only meant to play music modules in a comfortable way. 3.2 Why use DeliTracker ? There are many reasons for using DeliTracker; here is only a small list: ░ system friendly and multitasks happily ░áallocates the soundchannels ░ correct playspeed in PAL/NTSC (uses timerinterrupts) ░ works well with serial.device ░ supports xpkmaster.library for decrunching ░ásupports up to 64 players ░áruns fine with 680x0 ░ ARexx support ░ has a configfile ░ enforcer and mungwall proof ░ supports full CLI or Workbench (ToolTypes) environment ░áeasy to use & looks good ░áhas Volume/Balance sliders ░ resident cli startup ░ásupports multiselect ░ PubScreen support ░ hotkey (Commoditiy) ░ modules can be played by simply dropping the moduleicon into the mainwindow (Appwindow). ░áwritten in 100% Assembler 4. GETTING STARTED 4.1 System requirements As of version 1.31 and beyond DeliTracker requires at least Workbench and Kickstart 2.0 (aka V37). We recomend the usage of Workbench 2.1 (or 3.0), because the ASL Filerequester of V38 and above is much faster and supports multiselect. If you want to use packed modules, the 'xpkmaster.library' and the corresponding sublibraries must be installed. Make sure that you use V2 of XPK! V1 is NOT sufficient. DeliTracker requires at least 70KB of memory. Additional memory is needed for every loaded player, for the current modulelist and the decrunched module. Of course your System should be equiped with a Monitor that has speakers or even better with a HiFi system. 4.2 Starting from CLI/Shell Open a Shell or CLI window and CD to the directory where DeliTracker is located. Now you can type 'DeliTracker' followed by none/one/more options explained in 5.4. The options and arguments should be separated by spaces. DeliTracker automatically detatches from the CLI and you may close the CLI window. If a wrong arument is supplied DeliTracker quits with a short helptext. Example: 'DeliTracker config DT.config volume 32 filter 0' Starts DeliTracker with 'DT.config' as configuration file, turns the lowpass filter off (not on A1000's) and sets the volume to 32. 4.3 Starting from Workbench Open the drawer that contains DeliTracker and start it with a double click. All options can be set as ToolTypes by using the 'Info' item from the Workbench. The options must be separated by an '=' from the arguments. Invalid Tooltypes are ignored. DeliTracker can be used as a 'Default Tool' for automatic playing of modules. Example: Config=DT.config PrefWinXY=0/11 Volume=43 CX_Popup=NO If DeliTracker is started with these tooltypes, it loads 'DT.config' as the configuration file and sets the volume to 43. 4.4 Installation If you already use an older version of DeliTracker, please delete all files of the old distribution and your configuration files before you install this version. Copy DeliTracker in a directory of your choosing. Now copy the whole 'DeliPlayers' directory into this place. We strongly suggest that you move seldom used players from DeliPlayers/ to DeliPlayers/PlayerStore/. If you don't do this you waste memory! When DeliTracker is started every player in the 'DeliPlayers' drawer will be loaded. Note: any loaded player will stay in memory until the user unloads it or DeliTracker is exited. If you have packed modules you must install the XPK libraries. A double click on the CopyLibs icon will launch a script that will install the powerpacker.library and the XPK libraries in LIBS:. 5. BASICS 5.1 Player With DeliTracker it is possible to load single players. If such a player is loaded DeliTracker will recognize and play modules of this type. Currently a maximum of 64 external players may be loaded. This should be sufficient for awhile. When DeliTracker is started all players in the 'DeliPlayers' directory or the specified playerpath e.g. tooltypes or in the configfile are loaded. The player concept is one of the strong points in DeliTracker. It has the advantage that you may only load the players that you need (= efficient memoryusage). Of course you may unload any player at any time. Another drawback is that you only need to know the 'DeliTracker-player' rather than every single player. Multimedia applications in conjunction with ARexx greatly benefit from this (e.g. You may play any Module in an AmigaVision(TM) presentation). Another major advantage is that the player interface is very flexible so everyone may easily enhance/update/adapt or write players. DeliTracker has the most common players built in. These are: StarTrekker without AM sounds, SoundTracker15, SoundTracker31, NoiseTracker and ProTracker. There is another player called 'CustomPlay'; this is a special player that was created to play special modules that contain their own replay code. These 'modules' may not be crunched, because they are loaded via LoadSeg() to allow relocation. All external players are listed in the 'Players.doc'. For details on programming players read the includefile and 'Programming.doc'. 5.2 Packed modules If xpkmaster.library V2 or higher is installed DeliTracker will use the library for decrunching. Certain players do NOT support module packing! This is due to the fact that those players load the module by themselves rather than using the internal LoadFile() function. If the player-info field for a particular player shows 'Packable....NO' you are not allowed to crunch modules of this player. NOTE: Don't pack custommodules because they are loaded and RELOCATED via LoadSeg()! The only way to get around this is to use the XFH filehandler. 5.3 Options To allow an easy and flexible configuration, DeliTracker uses the following options. These options are used as KEYWORDS in Tooltypes, Configurationfiles and CLI templates. The options are not case sensitive! Option Default value and description -------------------- ----------------------------- cx_priority <pri> 0 (default priority) Sets the commodities priority. Valid values are -128 to 127. cx_popup <yes|no> yes (window opened) Defines if the control window should be opened at startup. If it is set to 'no', the main window will not be opened. It may be opened via hotkey, Commodities Exchange or with an ARexx command. cx_popkey <string> "" (no hotkey) This defines the hotkey that is used to open or close the main window. If the mainwindow is closed via hotkey the prefs window is closed as well -- the same applies to Hide Interface. To disable the hotkey use the INACTIVE option of the Commodities Exchange Program. config <file> "ENV:DeliTracker.config" Loads the specified file as a configuration file. Note: This option may not be specified in a configuration file! module <file> No file, empty module list. Adds the <file> to the module list. pubscreen <Screen> "", default PubScreen (usually Workbench). Let you specify the name of the public screen where DeliTracker should pop up. If the given screen is not available (e.g. does not exist), DeliTracker opens its windows on the default public screen. Note: Screen names are case sensitive! playerpath <path> "DeliPlayers" Sets the path where DeliTracker loads the external players. windowxy<XPos>/<YPos> 0/0 Attempts to open the mainwindow at the given position. If this fails the window will be opened at 0/0. prefwinxy<XPos>/<YPos> 0/1 Attempts to open the prefs window at the given position. If this fails the window will be opened at 0/1. volume <volume> 64 (maximal volume) Sets the volume to <volume>. Where volume can range from 0 to 64. balance <balance> 0 Sets the balance to <balance>. Where balance can range from -64 (left channels only) to 64 (right channels only). reqlines <lines> 0 (requester internal default setting). Specifies the filerequester height in lines. subsong <number> 0 (first subsong) Sets the subsong counter to <number> if the player for the first module in the soundlist supports subsongs. playing <yes|no> yes (first module is playing) Defines if the first module in the soundlist should be loaded, when DeliTracker is started. filter <yes|no> no (filter off) Switches the internal lowpass filter on or off. An advantage of having the filter off is that frequencies over 7kHz are not cut off. This has the effect that most modules will sound much better. Note: On A1000 this switch has no effect. quick <yes|no> yes (module is played immediately after loading) Defines if a loaded module should begin to play immediately after loading or if the module is in a paused state. This option is meant for synchronization purposes in ARexx scripts. random <yes|no> no (sequential order) Lets you specify whether a Next/Prev-Song event should take a randomly picked or the following (preceeding) list entry for loading. Once a module has been played it won't be reselected until other selected modules have been played. This behaviour is also known as 'Shuffleplay'. This option only works if there are more than 2 entries in the modulelist. append <yes|no> no (replace modulelist with new selection) Lets you specify whether the soundlist should be appended at the end or replaced by the current selection. If this option is set, multiselect of modules from different directories is possible. fadeout <yes|no> no (don't fade) Lets you specify whether the song should be faded out on a eject event or if no smooth transition should be done. This feature is only available for players that support volume changing. songend <yes|no> no (ignore songend signals) Lets you specify whether songend events should be ignored or not. SOME players support a notification of the song end. If this option is set, DeliTracker will pause the module and load the next module in the list. If only one module is in the soundlist then it is paused after the song has played once. timeout <secs> 0 (no timeout) Lets you specify the amount of time (in secs) after that DeliTracker will cause a Next-Song event. A value of 0 disables timeout. 5.4 Configuration files A Configuration file contains one or more options with the appropriate arguments. The only option that is not possible is the 'config' option. Only one option per line is allowed. DeliTracker can create configfiles with the save functions from the prefs window. Another way is to create a config file by your own with an editor or automatically by using the following NewList alias: 'alias ModList NL -hTigfsF "module=\'%P\'" []'. Only redirect the output to a file. Example of a configfile: windowxy=473/15 random=yes songend=yes timeout=300 reqlines=50 subsong=2 playerpath="Data:DeliPlayers" module="Data:Modules/SonicArranger/MF__Slowmotion1.3.pp" module="Data:Modules/FutureComposer13/hidden part.pp" Tooltypes and CLI options have a higher priority over the options in a configfile. This means they can override config file settings. At startup DeliTracker tries to open 'ENV:DeliTracker.config' as the default configfile. If this file can be opened, DeliTracker uses all settings that are contained therein. After this DeliTracker loads the external players and plays the first module. If the Configfile is not present, DeliTracker tries to load all external players that are located in the 'Deliplayers' directory on the current path. 6. HOW TO CONTROL DELITRACKER 6.1 The main window The main window is the central part of the DeliTracker. All module specific things may be controlled with this panel. 6.1.1 Gadgets This is a overview of the functions of the gadgets. If a gadget is drawn ghosted then this option is not accessible for this player. Two reasons why this is so: First, the soundsystem does not have this feature at all (e.g. SoundTracker has no SubSongs), or second, the player is not perfectly adapted (which is more likely). +---------+-+------------------------------------------------+-+ | | | [] | | [15] [1] | ? + +------------------------------------------------+ + | | | [] | | [14] +---+-----+-+--+-----+-----+-----+----+-----+-----+-----+----+-+ [2] | + | | | | | | | | | | |»»\ | +---+ |< | < | << | |> | >> | > | >| | [] | ^ | | | | [3] | - | | | | | | | | | - | +--+ | +---+-----+----+-----+-----+-----+----+-----+-----+-----+------+ [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [1] opens or closes the Prefs-Window [2] Faster: plays song a little faster [3] Slower: plays song a little slower [4] Prev Song: play the previous song. This gadget is only enabled if more than one file was selected. If Randomplay is selected this button picks a random module. See also Randomplay. [5] Prev Pattern: Jumps to the previous pattern. If the current pattern is the first, the counter is set to the last pattern. [6] Prev SubSong: Jumps to the previous sub-song (if available). [7] Play/Pause: Plays a paused sound or pauses a playing sound. [8] Forward: Jumps to the next pattern in the module. If the current pattern is the last, the counter is set to the first pattern. [9] Next Song: This button loads the next module form the selected Soundlist. If the last module of the list is playing and you press this button the first module of the list will be played (cyclic list). If Randomplay is selected this button has the same function as the Prev Song button. [10] Next SubSong: Plays the next SubSong of a module. This function allows you to select other melodies in the module. Not every Soundsystem provides you this feature. One of the most common Soundsystems that provide multi-modules is TFMX. [11] Stop Song: This button resets the patterncounter and the speed to the initial default value. [12] Kill Song: stops the actual module and removes it from memory. [13] Load Song: Opens the filerequester and lets you select one or more modules for playing. The first selected module is loaded and played. If enough memory is available, DeliTracker will use double buffering. This means that the actual song continues playing until the next song is loaded. [14] Balance Control: Let you change the Volume. [15] Volume Control: Let you change the Balance 6.1.2 Menus Project Load Module <A> L .........Open the filerequester. Play/Pause .........Play or pause a module. Stop Playing .........Stopt the actual module. Eject Module .........Stop playing and remove the actual module from memory. ================= Prefs ... .........Open prefs window ================= About ... <A> ? .........Open 'About' requester. ================= Quit <A> Q .........Quit DeliTracker. Control Faster .........Increase Playspeed. Slower .........Decrease Playspeed. Forward .........Jump one Pattern forward. Backward .........Jump one Pattern back. Next SubSong .........Play next Subsong. Prev Subsong .........Play previous Subsong. Next Module .........Load the next module in the Soundlist. See also Randomplay. Prev Module .........Load previous module. 6.1.3 Shortcuts All functions of the mainwindow can although be reached with shortcuts. To make them easy to remember we decided to order them hirarchically on the nummeric keypad. In additon you may specify a HotKey for opening and closing of the mainwindow (refer to cx_hotkey). * and <A> L open the filerequester for moduleselection. / open or close the prefs window. ] and ) play next song in the modulelist (only if more files are selected). [ and ( play previous song (same as above). 8 play next subsong. 7 play previous subsong. 5 step to next pattern. 6 skip one pattern back. + increase playspeed. - decrese playspeed. 1 stop song (stop playing, reset patterncunter). 0 play/pause (toggles between playing and paused). . stop song and remove it from memory (eject). 9 decreases the volume (besides -). 6 increases the volume (besides +). 2 changes the balance (decreases the volume of the right channels). 3 changes the balance. (increases the volume of the right channels) <A> ? opens the 'About' requester. <A> Q quits DeliTracker. 6.1.4 Appwindow To make the module selection even more comfortable icons from modules and module drawers may be dropped on the control window. The modules will be handled as if they were selected with the file requester. If a drawer is dropped all files will be scanned and added to the module list. Only files that are obviously not module files (e.g .info files) will be skipped. Subdirectorys are not scanned. To use this feature the control window of DeliTracker must be opened on the workbench screen. 6.2 The preferences window The preferences window is for seting all global and player specific options. To open the prefs window you may either select the 'Prefs ...' menu or the '?'-Gadget of the mainwindow. Of course, there is a short cut ('/') and an arexx-command ('openprefswin'), too. To activate a player select it from the player requester. After selecting a player, all informations about the player is shown beside it in the player information field. 6.2.1 Gadgets ADD Load an external player and set the playerpath. If a player with the same name is already loaded, the player with the lower version number will be expunged. DEL Deletes the selected player. This means the player is unloaded. Internal players may be deleted too, but the memory is not freed. Filter Refer to 5.4 filter option. Quick Refer to 5.4 quick option. Random Refer to 5.4 random option. Songend Refer to 5.4 songend option. Append Refer to 5.4 append option. Fadeout Refer to 5.4 fadeout option. Time Refer to 5.4 timeout option. Load Config Load a saved configuration and set all values. Save Config Save all actual settings and the current module list to a configuration file. Save List Only save the module list to a configuration file. Config If the player provides a player specific configuration routine this routine will be called. OK Close the preferences window. You can set the playerdirectory by typing the path into the stringgad (on the lefthand of the ADD gadget) or using the filerequester (ADD). 6.2.2 Shortcuts To make the shortcuts easy to remember we decided to use the first letter of the function (if not already used) as shortcuts. Shortcuts may be entered either in lower or upper case. a <A>dd (Filerequester for loading players). d <D>el (delete selected player). l <L>oad (Load a config file). s <S>ave (Save a config file). c <C>onfig (configure selected player). o <O>k (Close preference window). q <Q>uick (toggle quick). f <F>ilter (toggle filter). r <R>andom (toggle random). p A<P>pend (toggle append). e Song<E>nd (toggle songend detection). u Fadeo<U>t (toggle fadeout). t <T>ime(out) (activate timeout gadget). 6.3 ARexx Nearly every function of DeliTracker may be controlled with ARexx. This is very nice if you are using other ARexx aware software like AmigaVision(TM). DeliTracker is addressed as a function host with the name "rexx_DT". DeliTracker provides the following commands: quit Leave DeliTracker. filter <yes|no> yes: Switch filter on. no: Switch filter off. quickstart <yes|no> yes: Turn quick on. no: Turn quick off. random <yes|no> yes: Turn Randomplay on. no: Turn Randomplay off. songend <yes|no> yes: Recognize songend signals. no: Ignore songend events. append <yes|no> yes: Activate append mode. no: Deactivate Append mode. fadeout <yes|no> yes: Activate fadeout mode. no: Deactivate fadeout mode. timeout <SECS> Set timeout to given number of seconds (SECS) If SECS = 0 the timeout function is disabled. volume <VOL> Set volume to <VOL> (Range VOL: 0 to 64). balance <BAL> Set balance to <BAL>, 0 is default, -64 left only, 64 right only (Range BAL: -64 to 64). forward Play next pattern. backward Play previous pattern. nextsong Play next song (module). prevsong Play previous song (module). nextsubsong Play next subsong. prevsubsong Play previous subsong. faster Increase playspeed. slower Decrease playspeed. loadconfig [FILE] Load configfile [FILE] if [FILE] was specified, else pop filerequester up. saveconfig [FILE] Save configfile [FILE] if [FILE] was specified, else pop filerequester up. savelist [FILE] Save module list to [FILE] if [FILE] was specified, else pop filerequester up. loadplayer [PLAYER] Load the [PLAYER] if specified, else open loadplayer requester. deleteplayer <NUMBER> Remove player number <NUMBER> from memory. Note: all modules of this player won't be recognized any longer. configplayer <NUMBER> Call the configuration routine of the player <NUMBER>. playpause Play/Pause song. stop Stop song. playmod [MODULE] play [MODULE] if [MODULE] was specified else pop requester up. eject Remove active module from memory. makelist [MODULE] if [MODULE] is supplied, the given modulename is appended to an internal module list. If [MODULE] is ommited the current module list is rebuild and the internal list is cleared. Depending on the append flag the current list is either overwritten or expanded with the internal list. playlist <NUMBER> Play the module with the list position <NUMBER>. pubscreen <SCREEN> Closes all DeliTracker windows and tries to open the mainwindow on the pubscreen <SCREEN>. openmainwin Open and/or activate mainwindow. closemainwin Close mainwindow. openprefswin Open and/or activate prefs window. closeprefswin Close the prefs window. status <group> <dependent> Returns the actual status. This funtion is divided into three different groups: global settings (g), player specific settings (p) and module dependent settings (m). Additional arguments are specified after the group. <group> = g : Global <dependent> = <cmd> <cmd> description returnvalue ver DeliTracker version number dir playerdir string num players number led filter <yes|no> qst quickstart <yes|no> rnd random <yes|no> app append <yes|no> fad fadeout <yes|no> end songend <yes|no> tim timeout in seconds number mwi mainwindow closed/open <yes|no> pwi prefswindow closed/open <yes|no> vol current volume number bal current balance number ply paused or playing <yes|no> pub prefered pubscreen string <group> = m : Module <dependent> = <cmd> <cmd> description returnvalue dir moduledir string fil filename string pnr actual PlayerNr number max selected modules number num actual position in list number <group> = p : Player <dependent> = <playernum> <cmd> <cmd> description returnvalue nam name string cre creator string ver player version number vol volume <yes|no> bal balance <yes|no> jmp patternjump <yes|no> spd playspeed <yes|no> sub subsong <yes|no> cfg config <yes|no> pck packable <yes|no> Square brackets [...] mark arguments that may be omitted. Arguments in angle brackets <...> must be supplied. Note: For almost any command example scripts are available. All commands may be entered in lower and upper case. 6.4 Commodities DeliTracker is a Commodity, therefore some typical things may be controled from the Commodies Exchange Program. First select 'DeliTracker' in the 'Available Commodities' box. The cycle gadget shows you if the hotkey for opening/closing the mainwindow is enabled or not. Click once to change this. 'Show Interface' will open and activate the mainwindow. 'Hide Interface' will close all DeliTracker windows. Finally a click on the 'Remove' button will quit DeliTracker. As usual for commodities a click on the close gadget only closes the window, but doesn't quit the program. 7. TROUBLESHOOTING Preferences window can't be opened: Check the screen height. It must be at least 190 Pixels + Barheight. The Barheigth depends on the screenfont height. Try to use a smaller font (topaz 8). Some external players have trouble with >68010 or SuperHires; these problems often can't be fixed. The cause of this lies in the coding style (e.g. the player is part of the module and contains modulespecific code/data) of these players. Many players are hitting at the basic principles of programming on the Amiga. Such things as poking directly into processor vectors or working with nullpointers are often seen. Don't be astonished if enforcer hits occur. These hits are only from external players and *not* from DeliTracker itself!! Usually the playspeed of the players are the same on PAL/NTSC machines, because a CIA, rather than a VBlank IRQ is used. Since some players essentially need a VBlank interrupt, these players have different playspeeds depending on the selected video mode (PAL/NTSC/Productivity). Some players dont take notice of the VBR (on >68000) and write directly to the interrupt vector table ($70 Vector/Audio-DMA-End). This may have the effect that you won't hear anything when VBR is nonzero. Those players are marked in the player documentation. For Modem users: All players that use the DeliTracker internal timer Interrupt should now work well with serial transfers. Players that generate their own timer interrupt will probably not(!). This is due to the fact that instead of executing the actual playroutine in the timer interrupt itself, we cause a SoftInt (so that the real routine executes in a lower interrupt priority than the RFB interrupt). 8. EXTERNAL PLAYER PROGRAMMING INTERFACE DeliTracker supports so called external players. These are executables in a special format so that they can be loaded from DeliTracker. 8.1 The external player interface External Players are executables (object files) which means they are relocated. At the start of an external player you can find the characteristic playerstructure. This structure is generated with a macro that can be found in 'misc/deliplayer.i'. There are two kinds of players: normal players and custom modules. 8.1.1 The structure of external players Normal players can distinguished from custom modules by the existence of a check routine and the lack of the DTP_CustomPlayer tag. { player header } identifies the objectfile as player. { tag array } description of the playerfuntions. { interfacecode } playername/registerconversion/checkcode... { replaycode } replay code itself { optional data } optional data 8.1.2 The structure of custom modules These are not modules in the conventional meaning. They are more like external players, the difference is that custom modules contain the player and the module. With the custom module interface you can adapt almost every module. If you have more modules with the same replay routine we suggest to write an own player for this moduleformat. { player header } identifies the objectfile as player. { tag array } description of the playerfuntions. { interfacecode } playername/registerconversion/checkcode... { replaycode } replay code itself { optional data } optional data { SOUND DATA } music data (the module) 8.2 How to build external players It is not difficult to adapt a player if you have the replayroutine. You only need to write some interfacecode. DeliTracker has some helpful builtin routines that will make this job a lot easier. To adapt a new soundsystem you need the replayroutine of that soundsystem, and at least 5 modules for testing the adaption. 8.2.1 Playerheader The PLAYERHEADER macro generates the header that identifies the file as a valid external player for DeliTracker. This macro must exist and the player must begin with the macro. The only parameter you must supply is a pointer to a Tag Array that contains all functions that the external player supports. In all calls to player functions (except the interrupt routine) a5 will contain the address to the global player datastructure (Base). For more about this structure read 'misc/deliplayer.i'. In your routines (except in DTP_Interrupt) you may trash all registers. PLAYERHEADER <tagarray> tagarray Pointer to a tag array, terminated with TAG_DONE. 8.2.2 Modulerecognicion In order to recognize the different moduleformats every player contains a specific routine, that tells DeliTracker if the player can play this module or not. This routine has the task to check certain positions in the module that are identical in every module (like 'M.K.' at offset $438 in NoiseTracker modules) or significant assembler instructions (if the module contains the player). Testing against one or two branches or jumps is NOT enough, cause many modules with player have branchtables at the beginning of the module. If the player recognizes the wrong module, a system crash will be the result! So be careful with the Ckeckroutine. As you can see the playerstructure has two checkfunctions but the player must use exactly one check routine. This leads to two basic player types: a) Type one Player Here the Check1 function is implemented. Advantage: You can implement players that can load the module by itself. Disadvantage: No Packsupport, more complex. This type should only be used if you REALLY need to load the module by yourself! (e.g. FTM, IFF-8SVX player that loads the sample while playing, ...) b) Type two Player - the easier way Here the Check2 function is implemented. Advantage: The module may be packed and DeliTracker handles the loading and allocation of the module for you. Disadvantage: The module is completely loaded into CHIP-Memory. Regardless of the playertype the checkfunction must return d0.l=0 if the player can handle this module or d0.l<>0 if not. 8.2.3 Interrupts Players can be divided in two categories: a) Player that uses the internal timer interrupt from DeliTracker Advantage: The player is independent from the selected videomode The player has automatically the faster/slower function. No expense for interrupthandling (interrupt structure and the insert/remove code). Compatible with the serial.device. Disadvantage: The interrupt is not synchronous to the VBlank (This leads to problems only in certain cases). b) Player that generates their own interrupt Advantage: You can use other interrupt sources (like AudioIRQ) Disadvantage: You have to handle the interrupts by yourself, and if you use VBlank the player is not independent to the videomode. If you use your own timerinterrupt you should allocate CIAB because under 2.x the CIAA is used by the system. Do not to run the soundcode directly in the timerinterrupt. Instead you should Cause() a SoftInt in the timer interrupt and execute the routine in the SoftInt. This is to assure maximum compatibility for modem users because the SoftInt has a lower priority thant the RBF interrupt. Beware of writing directly to the 680x0 intvectors! You should use AddIntServer() or SetIntVector() from the OS. 8.3 Tags In addition to the system tags (TAG_DONE, TAG_IGNORE, TAG_MORE, TAG_SKIP) this tags may be used: DTP_CustomPlayer (BOOL) - this tag identifies a player as customplayer. If this tag is used the following tags are ignored: DTP_PlayerVersion DTP_PlayerName DTP_Creator DTP_Check1 DTP_Check2 DTP_ExtLoad DTP_Config DTP_UserConfig DTP_RequestDTVersion (WORD) - only if the DeliTracker version is greater than or equal to the requested version (ti_Data) will DeliTracker accept the player. If your player uses functions that were introduced in later revisions of DeliTracker you must set this tag according to the version that introduced this function. DTP_RequestV37 (BOOL) - if this tag is set, only the Kick 2.0 version of DeliTracker will load the player. (dtg_GadToolsBase is valid) DTP_PlayerVersion (WORD) - Tag that contains the revision number of the player. If there are two players with same name the player with the higher version is used. DTP_PlayerName (STRPTR) - ti_Data contains a pointer to the playername. This string may be as long as you wish, but only the first 24 chars are actually used. This tag must exist ! DTP_Creator (STRPTR) - pointer to the author/adaptor name. This string is visible in the prefs window if the player is selected. The string may contain $A as line separator. DTP_Check1 (FPTR) - pointer to a module identification routine. This routine is called after the first 1024 bytes of the module are loaded. If the module is shorter, the rest will contain zero. If the routine recognizes the moduleformat it must return d0=0 else d0<>0. DTP_Check2 (FPTR) - pointer to a module identification routine. This routine is called after the complete module is loaded (and decrunched). If the routine recognizes the module it must return d0=0 else d0<>0. DTP_Extload (FPTR) - pointer to a optional loadroutine for modules. If an error occurs return d0<>0 else d0=0. Please remember to free all allocated resources (memory, locks,...), because no further player function is called. DTP_Interrupt (FPTR) - pointer to a interruptroutine. This routine is called every 1/50 sec. via a timerinterrupt. Note: your interruptroutine is not executed in the timerinterrupt itself. This is the standard method for gaining the correct playspeed regardless of the videomode. If the DTP_Faster/DTP_Slower pointers are not supplied, DeliTracker emulates this by changing the interrupt frequency. If this tag doesn't exist, you must supply DTP_StartInt/DTP_StopInt. DTP_Stop (FPTR) - pointer to optional stop routine. If this tag does not exist, DeliTracker uses the following standard method: stop interrupt (DTP_StopInt) cleanup sound (DTP_EndSnd) reinitialize the song (DTP_InitSnd) This routine will stop playing the song, reset the 'patterncounter' to the begin and change the playspeed to default. This means that the interrupt is started again and the song should begin to play from the beginning. DTP_Config (FPTR) - pointer to an optional initialising routine. This routine is only called once after the player is loaded. Purpose: The player could load a specific configfile. DTP_UserConfig (FPTR) - pointer to a optional initialising routine. This routine is called if the user selects the 'Config' button in the prefswindow. Purpose: The player could open a player specific configwindow for setting special options (e.g instrumentpath for a sonix player) and saving them into a configfile. DTP_SubSongRange (FPTR) - This tag should be supplied if the player supports multimodules. ti_Data points to a function that returns in d0 the minimum and in d1 the maximum subsong number. DTP_InitPlayer (FPTR) - pointer to an initialising routine, that is called if a module is loaded successfully. Must return d0=0 if all is ok else d0<>0. The audioallocation must be done here. (DeliTracker has a function that does the allocation.) If the player supports subsongs it has to set dtg_SndNum(a5) to the first subsongnumber. If a routine for DTP_SubSongRange exists, DeliTracker performs this for you and you may omit the initialization for dtg_SndNum(a5). DTP_EndPlayer (FPTR) - pointer to a cleanuproutine, that is called if the module is removed from memory. Audiochannels have to be freed here. (Use the DeliTracker internal supportroutine) DTP_InitSound (FPTR) - pointer to an optional initialising routine. This routine has the task to (re)initialize the module. If the interrupt is started the song should begin to play at the beginning. DTP_EndSound (FPTR) - pointer to an optional cleanuproutine. For example it can be used to reset the volumeregister or the audiodma. DTP_StartInt (FPTR) - pointer to an initialising routine, that must exist if DTP_Interrupt doesn't exist. It has the task to start the sound. DTP_StopInt (FPTR) - pointer to a cleanuproutine, that must exist if DTP_Interrupt doesn't exist. It has the task to stop the sound. DTP_Volume (FPTR) - pointer to function that sets the volume. This function is called every time the volume is changed (via arexx or slider) and once at the initialising phase of the module (before DTP_InitSnd is called). The mastervolume can be found in dtg_SndVol(a5). The mastervolume is the highest volume allowed. The effective volume can be calculated using the following formula: VOL_eff=( ( MASTERVOLUME*modulevolume ) >>6 ). See also the example sources. DTP_Balance (FPTR) - pointer to a function that sets the balance. This function is called every time the balance is changed (via arexx or slider) and once at the initialising phase of the module (before tf_InitSnd is called). The balance for the left channel can be found in dtg_SndLBal(a5), for the right channel in dtg_SndRBal(a5). Note: All players that support balance are capable of volume too! Then you must use the same routine for both operations. The mastervolume for the left channels can be calculated with this formula: LeftMaster =( ( dtg_Volume(a5)*dtg_SndLBal(a5) ) >>6 ). For the right channels the formula is similar. DTP_Faster (FPTR) - pointer to a function that increases the playspeed. DTP_Slower (FPTR) - pointer to a function that decreases the playspeed. DTP_NextPatt (FPTR) - pointer to a function that increases the patternpointer. DTP_PrevPatt (FPTR) - pointer to a function that decreases the patternpointer. DTP_NextSong (FPTR) - pointer to a function that increases the subsongcounter (only if the subsong exists). DTP_PrevSong (FPTR) - pointer to a function that decreases the subsongcounter (only if the subsong exists). DTP_SubSongTest (FPTR) - (till version 1.35) The tag is only evaluated if DTP_SubSongRange exits too. ti_Data points to a routine that returns a boolean value. This indicates if the subsong number dtg_SubNum(a5) is valid (d0=0) or not (d0<>0). This tag is only necessary for players where not every subsong in the subsong range is existant. 8.4 DeliTracker support functions DeliTracker provides some support functions that can be called from the external player. Every function is called like this: move.l dtg_XXX(a5),a0 ; a5 must contain the base jsr (a0) All functions (exept dtg_SongEnd/dtg_SetTimer) use d0/d1/a0/a1 as scratch register. A5 must contain the base (exept dtg_SongEnd/dtg_SetTimer). Currently the following functions are available: dtg_GetListData SYNOPSIS memory size = dtg_GetListData(number) a0 d0 d0.l FUNCTION Returns the address and the length of a file that was loaded with dtg_LoadFile(). INPUTS number - number of the file beginning with 0 for the file that was selected by the user. RESULT memory - startaddress of the files in memory, if error 0. size - length of the loaded file in bytes or 0 in case of an error dtg_LoadFile SYNOPSIS success = dtg_LoadFile(name) FUNCTION Loads and decrunches the specified file to chipmemory. Note: this function automatically adds '.pp' to the filename. INPUTS name - store the filename in the internal buffer (dtg_PathArray contains a pointer to this buffer) RESULT success - success d0.l=0, else d0.l<>0. dtg_CopyDir SYNOPSIS dtg_CopyDir() FUNCTION Copies the directory of the selected file at the end of the string, that dtg_PathArray points to. dtg_CopyFile SYNOPSIS dtg_CopyFile() FUNCTION Copies the filename of the selected file at the end of the string, that dtg_PathArray points to. dtg_CopyString SYNOPSIS dtg_CopyString(string) a0 FUNCTION a0 contains the address of a string, which is copied at the end of the string that dtg_PathArray points to. INPUTS string - a0 contains the pointer to the string dtg_AudioAlloc SYNOPSIS success = dtg_AudioAlloc() FUNCTION Allocates the audiochannels RESULT success - if we got them: d0.l=0, else d0.l<>0. dtg_AudioFree SYNOPSIS dtg_AudioFree() FUNCTION Frees the audiochannels that were allocated with dtg_AudioAlloc. dtg_StartInt SYNOPSIS dtg_StartInt() FUNCTION Starts the soundinterrupt. If DTP_Interrupt exists, DeliTracker starts the internal timerinterrupt, else DTP_StartInt is called. dtg_StopInt SYNOPSIS dtg_StopInt() FUNCTION Stops the soundinterrupt. If DTP_Interrupt exists, DeliTracker stops the internal timerinterrupt, else DTP_StopInt is called. dtg_SongEnd SYNOPSIS dtg_SongEnd() FUNCTION Signals DeliTracker, that the module was played once. This function doesn't change any registers and is save to call from interrupts. dtg_CutSuffix SYNOPSIS dtg_CutSuffix() FUNCTION removes the suffix '.pp', '.im', '.xpk' at the end of the string, that dtg_PathArray points to. dtg_SetTimer SYNOPSIS dtg_SetTimer() FUNCTION programs the CIA-timer with the value that is stored in dtg_Timer(a5). This function doesn't change any registers and is save to call from interrupts. 8.5 Hints and Tips The player should not change the LED condition because DeliTracker will handle it. This is a small list that you should match when you create your own player or custom module. [ ] checkroutine exact enough ? [ ] audiochannels allocated/freed correctly ? [ ] all allocated memory freed after playing? [ ] all locks unlocked after playing ? [ ] enforcer and mungwall proof ? [ ] viable error handling path taken for all possible errors ? [ ] player tested under 1.3 and 2.0 ? [ ] does the player work correct in all videomodes ? Problems Symptom possible source elimination crash a5 trashed, other registers not saved, wrong stack usage initialization wrong or too late module too new for the replayroutine better check module sounds audio data not in chipmem wrong wrong initialization module too new for the replayroutine player needs some special values in some registers extra init code wrong videomode no sound Audio-DMA off :-) >68000 player writes directly to processor use OS routines to intvectors and VBR is not 0. set IntVectors no free wrong interrupt handling VBlank-IRQ: CPU-time Z-Flag must be set at the end of the interruptroutine. 9. ACKNOWLEDGEMENTS Our special thanks go to the following people: Our betatesters Stefan, Daniel, B÷rnie and Manfred for their bugreports and ideas. Armin Sander (Oktalyzer) and Carsten Schlote (Sonic Arranger) for creating DeliPlayers for their soundsystems. J÷rg W. Schmidt for the source code of PlayFTM. Tomas Partl for his player. DoIO for modules, demos and diskmag advertisement. All on IRC #amiga (Internet Relay Chat) Markus Illenseer and Christian Rattei for the correction of the german docs. Kevin Dackiw for the enhancement of the NoisePacker players and the correction of the english doc files. [Hope it is a little clearer...8-) -- KD] Florian Vorberger for many nice Modules and the enhancement of various players. U. Dominik Mⁿller for XPK. Colin Fox and Bruce Dawson for the incredibile req.library. Eric Kennedy for TstApp.rexx. and all others, who have send replays, modules or registrations.