home *** CD-ROM | disk | FTP | other *** search
/ AMIGA PD 1 / AMIGA-PD-1.iso / Programme_zum_Heft / Anwendungen / Kurztests / DeliTracker / Files / developer.lha / Developer / Developer.doc next >
Text File  |  1994-07-24  |  31KB  |  760 lines
  1.  
  2.  
  3.                  $VER: Developer.doc V2.07 (24.07.1994)
  4.                    Copyright 1994 by Delirium Softdesign
  5.                       (Peter Kunath and Frank Riffel)
  6.  
  7.                   DeliTracker Development Documentation
  8.  
  9.  
  10.   1.OVERVIEW
  11.  
  12.   2.PLAYERS
  13.    2.1 Normal Players
  14.    2.2 Custom Modules
  15.    2.3 Interrupts
  16.  
  17.   3.GENIES
  18.    3.1 Generic Kind
  19.    3.2 Converter
  20.    3.3 Decruncher
  21.    3.4 NotePlayer
  22.  
  23.   4.TAGS
  24.  
  25.   5.DELITRACKER SUPPORT FUNCTIONS
  26.  
  27.  
  28.   1.OVERVIEW
  29.  
  30.   DeliTracker can be extended with external code. From DOS sight external
  31.   code for DeliTracker is nothing else than an executable object file
  32.   that contains a characteristic structure at the beginning of first code
  33.   hunk. When DeliTracker has loaded such external code it evaluates this
  34.   structure. It consists of three parts: one longword of code, two longs
  35.   used as identifier and at last a pointer to a taglist. The first long
  36.   usually contains a moveq #-1,d0 and a rts instruction. This prevents a
  37.   system crash if a user accidentally tries to run a normal genie or player
  38.   from shell. To get a program that works without DeliTracker, too, you
  39.   can change this to a bra.w to your own startup code. You should use the
  40.   PLAYERHEADER macro from 'deliplayer.i' to create this structure. It has
  41.   two parameters: a pointer to the tag array and a pointer to the optional
  42.   startupcode.
  43.  
  44.     PLAYERHEADER <tagarray>,[startup]
  45.  
  46.         tagarray        Pointer to a tag array, terminated with TAG_DONE.
  47.         startup         Pointer to optional startup code. Only set if you
  48.                         need to make the code run without DeliTracker.
  49.                         Note: In case the startup code is called you have
  50.                         to do anything by your own! The startup option
  51.                         does not make sense in most cases. Use rarely.
  52.  
  53.   This taglist contains all informations that DeliTracker must know. We
  54.   have choosen to use a tag array because it is extremely flexible and
  55.   extensible. For the other direction the external code has the limited
  56.   ability to check the internal program state by looking at the DeliTracker
  57.   Global structure. It can also take advance of inbuild support functions.
  58.   At the moment DeliTracker knows two different types of external code:
  59.  
  60.         1) Players they have the task to identify and play a modules.
  61.  
  62.         2) Genies can perform several other things. This includes module
  63.            conversion, extended decrunch support and information display.
  64.  
  65.   Both forms can run synchronusly or asynchronusly. The term synchronuns
  66.   means that the player or the genie is not running as seperate task.
  67.   DeliTracker will communicate with the genie or player using real fuction
  68.   calls (jsr). In asynchronus mode DeliTracker will spawn an own process
  69.   for the player or genie. Now DeliTracker uses a message based interface
  70.   to "call" the functions of the external code. In general genies tend to
  71.   run asynchronus whereas player run synchronous. If a player or genie is
  72.   running asynchronously a CTRL-C signal must terminate it. As you see
  73.   DeliPlayers and DeliGenies are very similiar. Indeed DeliTracker handles
  74.   them in the same way but of course in two sperate lists. All external
  75.   code that has set the DTP_CustomPlayer, DTP_Check1 or DTP_Check2 tag is
  76.   a player. The rest is threated as genie.
  77.  
  78.   If a player or genie has a GUI it should offer the following menu items:
  79.  
  80.         Project
  81.                 About      A ?  Displays a short info
  82.                 ==============
  83.                 Save Prefs A S  Save the current settings as default
  84.                 ==============
  85.                 Hide       A H  Hide the GUI
  86.                 ==============
  87.                 Quit       A Q  Remove the Player/Genie (same as CTRL-C)
  88.  
  89.         Settings
  90.                 Activate   A A  Activates the window if the GUI is opened
  91.                 Popup      A P  Opens the GUI after loading
  92.                 ==============
  93.                 Other settings  Other genie specific settings, see the
  94.                 ··············  particular genie documentation.
  95.  
  96.   Some general things:
  97.  
  98.   A good point to start with is to read the supplied example sources. To
  99.   get an idea how DeliTracker calls the player routines see 'Testplayer.s'.
  100.   Configuration files should not be saved to ENV:. Instead they should be
  101.   stored in DeliTracker's default configuration directory. The path of this
  102.   directory can be found in the 'DeliConfig' ENV-Variable. If this variable
  103.   is not set the configuration should be saved to 'PROGDIR:DeliConfig'.
  104.   Your player should not change the LED (Filter) state because DeliTracker
  105.   will handle this. Besides the interrupt routine any other subroutine may
  106.   trash any register. When DeliTracker calls a player function (exept the
  107.   interrupt routine) a5 will contain the address to the global player data
  108.   structure (Base).
  109.  
  110.  
  111.   2.PLAYERS
  112.  
  113.   It is not difficult to adapt a player if you have the replayroutine.
  114.   You only need to write some interfacecode. DeliTracker has some helpful
  115.   builtin routines that will make this job a lot easier. To adapt a new
  116.   soundsystem you need the replayroutine of that soundsystem, and some
  117.   modules for testing the adaption. At the beginning of an external
  118.   player you can find the characteristic playerstructure. DeliTracker
  119.   distinguishes between two kinds: normal players and custom modules.
  120.  
  121.     2.1 Normal Players
  122.  
  123.     Normal players identify and play modules. They must allways have a
  124.     check routine. This is the schematic structure of a normal player:
  125.  
  126.         { player header }       identifies the objectfile
  127.         { tag array     }       description of the playerfuntions.
  128.         { interfacecode }       playername/registerconversion/checkcode...
  129.         { replaycode    }       replay code itself
  130.         { optional data }       optional data
  131.  
  132.     In order to recognize different moduleformats every player must contain
  133.     a specific routine, that tells DeliTracker if the player can play this
  134.     module or not. This routine has the task to check certain positions in
  135.     the module that are identical in every module (like 'M.K.' at offset
  136.     $438 in NoiseTracker modules) or significant assembler instructions (if
  137.     the module contains the player). Testing against one or two branches or
  138.     jumps is NOT enough, cause many modules with player have branchtables at
  139.     the beginning of the module. If the player recognizes a wrong module, it
  140.     is likely that a system crash will result! So be very careful with the
  141.     ckeck routine. There are two different types of check functions but your
  142.     player must use exactly one check routine.
  143.  
  144.     a) DTP_Check1: The check function is called after DeliTracker has
  145.     loaded 1K of the file. This has the advantage that you can implement
  146.     players that can load the module by itself. The disadvantage is that
  147.     you don't profit from the internal packsupport and of course it is
  148.     more complex to write such players. Use this type only where you must
  149.     load the module by yourself!
  150.  
  151.     b) DTP_Check2: The check function is called after the module is loaded
  152.     and decrunched. This is the easy way. All memory allocation, loading
  153.     and decrunching is done by DeliTracker.
  154.  
  155.     Regardless of the playertype the checkfunction must return d0.l=0 if
  156.     the player can handle this module or d0.l<>0 if not.
  157.  
  158.  
  159.     2.2 Custom modules
  160.  
  161.     This is a very special thing: Custom modules contain replay and sound
  162.     data, both relocatable. They don't contain a check routine. With the
  163.     custom module interface you can adapt almost every module. If you have
  164.     more modules with the same replay routine we suggest to write an own
  165.     player for this moduleformat.
  166.  
  167.         { player header }       identifies the objectfile
  168.         { tag array     }       description of the playerfuntions.
  169.         { interfacecode }       playername/registerconversion/checkcode...
  170.         { replaycode    }       replay code itself
  171.         { optional data }       optional data
  172.         { SOUND DATA    }       music data (the module)
  173.  
  174.  
  175.     2.3 Interrupts
  176.  
  177.     Players can be divided in two categories:
  178.  
  179.     a) Player that uses the internal timer interrupt from DeliTracker
  180.  
  181.      Advantage: The player is independent from the selected videomode
  182.         The player has automatically the faster/slower function. No expense
  183.         for interrupthandling (interrupt structure and the insert/remove
  184.         code). Compatible with the serial.device.
  185.  
  186.     b) Player that generates their own interrupt
  187.  
  188.      Advantage: You can use other interrupt sources (like AudioIRQ)
  189.  
  190.      Disadvantage: You have to handle the interrupts by yourself, and if
  191.         you use VBlank the player is not independent to the videomode.
  192.  
  193.     If you use your own timerinterrupt you should allocate CIAB because
  194.     under 2.x the CIAA is used by the system. Do not to run the soundcode
  195.     directly in the timerinterrupt. Instead you should Cause() a SoftInt in
  196.     the timer interrupt and execute the routine in the SoftInt. This is to
  197.     assure maximum compatibility for modem users because the SoftInt has a
  198.     lower priority thant the RBF interrupt. Beware of writing directly to
  199.     the 680x0 intvectors! You should use AddIntServer() or SetIntVector()
  200.     from the OS.
  201.  
  202.  
  203.   3.GENIES
  204.  
  205.   As said Genies can 'help' DeliTracker to perform different tasks. At the
  206.   moment four different functionalitys are distinguished: output of notes
  207.   (not to be mixed up with players), decrunching and conversion of Modules
  208.   and finaly acting on the current module.
  209.  
  210.     3.1 Generic Kind
  211.  
  212.     This kind of genie can do many things (e.g display informations). Of
  213.     course neither the module nor DeliTracker's global structure may be
  214.     changed to obtain the desired informations. Usually this type will use
  215.     DTP_InitPlay/DTP_EndPlay to get notified when the module changes.
  216.  
  217.     3.2 Converter
  218.  
  219.     This genie has the task to change a module. E.g. it can convert one
  220.     format into another or change the size of the module. It is identified
  221.     by the special tag DTP_Convert. This tag contains the address of the
  222.     conversion function. DeliTracker will call this function at the right
  223.     time.
  224.  
  225.     3.3. Decruncher
  226.  
  227.     This kind of genie enhances DeliTracker's dtg_LoadFile() function.
  228.     The calling interface is not documented yet beacuse this part may
  229.     still change.
  230.  
  231.     3.4 Noteplayer
  232.  
  233.     This genie type will convert/redirect 'Notes' to the actualy used
  234.     audiohardware. The interface is not documented yet beacuse this
  235.     part is still under development.
  236.  
  237.  
  238.   4.TAGS
  239.  
  240.   In addition to the system tags (TAG_DONE, TAG_IGNORE, TAG_MORE, TAG_SKIP)
  241.   this tags may be used:
  242.  
  243.   DTP_CustomPlayer (BOOL) - this tag identifies a player as customplayer.
  244.                 If this tag is used the following tags are ignored:
  245.                                 DTP_PlayerVersion
  246.                                 DTP_PlayerName
  247.                                 DTP_Creator
  248.                                 DTP_Check1
  249.                                 DTP_Check2
  250.                                 DTP_ExtLoad
  251.                                 DTP_Config
  252.                                 DTP_UserConfig
  253.  
  254.   DTP_RequestDTVersion (UWORD) - only if the DeliTracker version is greater
  255.                 than or equal to the requested version (ti_Data) will
  256.                 DeliTracker accept the player. If your player uses
  257.                 functions that were introduced in later revisions of
  258.                 DeliTracker you must set this tag according to the version
  259.                 that introduced this function.
  260.  
  261.   DTP_RequestKickVersion (ULONG) - set this tag to the required OS version.
  262.  
  263.   DTP_PlayerVersion (ULONG) - Tag that contains the version (high word) and
  264.                 revision number (low word) of the player. If there are two
  265.                 players with same name the player with the higher version
  266.                 is used.
  267.  
  268.   DTP_PlayerName (STRPTR) - ti_Data contains a pointer to the playername.
  269.                 This string may be as long as you wish, but only the first
  270.                 24 chars are actually used. This tag must exist !
  271.  
  272.   DTP_Creator (STRPTR) - pointer to the author/adaptor name. This string
  273.                 is visible in the prefs window if the player is selected.
  274.                 The string may contain $A as line separator.
  275.  
  276.   DTP_Check1 (FPTR) - pointer to a module identification routine. This
  277.                 routine is called after the first 1024 bytes of the module
  278.                 are loaded. If the module is shorter, the rest will contain
  279.                 zero. If the routine recognizes the moduleformat it must
  280.                 return d0=0 else d0<>0.
  281.  
  282.   DTP_Check2 (FPTR) - pointer to a module identification routine. This
  283.                 routine is called after the complete module is loaded (and
  284.                 decrunched). If the routine recognizes the module it must
  285.                 return d0=0 else d0<>0.
  286.  
  287.   DTP_Extload (FPTR) - pointer to a optional loadroutine for modules. If
  288.                 an error occurs return d0<>0 else d0=0. Please remember to
  289.                 free all allocated resources (memory, locks,...), because
  290.                 no further player function is called.
  291.  
  292.   DTP_Interrupt (FPTR) - pointer to a interruptroutine. This routine is
  293.                 called every 1/50 sec. via a timer.device. Note: your
  294.                 interruptroutine is not executed in the timerinterrupt
  295.                 itself. This is the standard method for gaining the
  296.                 correct playspeed regardless of the videomode. If the
  297.                 DTP_Faster/DTP_Slower pointers are not supplied,
  298.                 DeliTracker emulates this by changing the interrupt
  299.                 frequency. If this tag doesn't exist, you must supply
  300.                 DTP_StartInt/DTP_StopInt.
  301.  
  302.   DTP_Stop (FPTR) - pointer to optional stop routine. If this tag does not
  303.                 exist, DeliTracker uses the following standard method:
  304.                         stop interrupt (DTP_StopInt)
  305.                         cleanup sound (DTP_EndSnd)
  306.                         reinitialize the song (DTP_InitSnd)
  307.                 This routine will stop playing the song, reset the
  308.                 'patterncounter' to the begin and change the playspeed
  309.                 to default. This means that the interrupt is started
  310.                 again and the song should begin to play from the
  311.                 beginning.
  312.  
  313.   DTP_Config (FPTR) - pointer to an optional initialising routine. This
  314.                 routine is only called once after the player is loaded.
  315.                 Purpose: The player could load a specific configfile.
  316.                 Must return d0=0 if all is ok else d0<>0. In case of an
  317.                 error DeliTracker will remove this player.
  318.  
  319.   DTP_UserConfig (FPTR) - pointer to a optional initialising routine. This
  320.                 routine is called if the user selects the 'Config' button
  321.                 in the prefswindow. Purpose: The player could open a player
  322.                 specific configwindow for setting special options (e.g
  323.                 instrumentpath for a sonix player) and saving them into a
  324.                 configfile.
  325.  
  326.   DTP_SubSongRange (FPTR) - Obsolete, please use DTP_NewSubSongRange!
  327.                 This tag should be supplied if the player supports
  328.                 multimodules. ti_Data points to a function that returns
  329.                 in d0 the minimum and in d1 the maximum subsong number.
  330.  
  331.   DTP_InitPlayer (FPTR) - pointer to an initialising routine, that is
  332.                 called if a module is loaded successfully. Must return
  333.                 d0=0 if all is ok else d0<>0. The audioallocation must be
  334.                 done here. (DeliTracker has a function that does the
  335.                 allocation.) If the player supports subsongs it has to set
  336.                 dtg_SndNum(a5) to the first subsongnumber. If a routine
  337.                 for DTP_SubSongRange exists, DeliTracker performs this for
  338.                 you and you may omit the initialization for dtg_SndNum(a5).
  339.  
  340.   DTP_EndPlayer (FPTR) - pointer to a cleanuproutine, that is called if the
  341.                 module is removed from memory. Audiochannels have to be
  342.                 freed here. (Use the DeliTracker internal supportroutine)
  343.  
  344.   DTP_InitSound (FPTR) - pointer to an optional initialising routine. This
  345.                 routine has the task to (re)initialize the module. If the
  346.                 interrupt is started the song should begin to play at the
  347.                 beginning.
  348.  
  349.   DTP_EndSound (FPTR) - pointer to an optional cleanuproutine. For example
  350.                 it can be used to reset the volumeregister or the audiodma.
  351.  
  352.   DTP_StartInt (FPTR) - pointer to an initialising routine, that must exist
  353.                 if DTP_Interrupt doesn't exist. It has the task to start
  354.                 the sound.
  355.  
  356.   DTP_StopInt (FPTR) - pointer to a cleanuproutine, that must exist if
  357.                 DTP_Interrupt doesn't exist. It has the task to stop the
  358.                 sound.
  359.  
  360.   DTP_Volume (FPTR) - pointer to function that sets the volume. This
  361.                 function is called every time the volume is changed (via
  362.                 arexx or slider) and once at the initialising phase of the
  363.                 module (before DTP_InitSnd is called). The mastervolume can
  364.                 be found in dtg_SndVol(a5). The mastervolume is the highest
  365.                 volume allowed. The effective volume can be calculated
  366.                 using the following formula:
  367.                         VOL_eff=( ( MASTERVOLUME*modulevolume ) >>6 ).
  368.                 See also the example sources.
  369.  
  370.   DTP_Balance (FPTR) - pointer to a function that sets the balance. This
  371.                 function is called every time the balance is changed (via
  372.                 arexx or slider) and once at the initialising phase of the
  373.                 module (before tf_InitSnd is called). The balance for the
  374.                 left channel can be found in dtg_SndLBal(a5), for the right
  375.                 channel in dtg_SndRBal(a5). Note: All players that support
  376.                 balance are capable of volume too! Then you must use the
  377.                 same routine for both operations. The mastervolume for the
  378.                 left channels can be calculated with this formula:
  379.                     LeftMaster =( ( dtg_Volume(a5)*dtg_SndLBal(a5) ) >>6 ).
  380.                 For the right channels the formula is similar.
  381.  
  382.   DTP_Faster (FPTR) - pointer to a function that increases the playspeed.
  383.  
  384.   DTP_Slower (FPTR) - pointer to a function that decreases the playspeed.
  385.  
  386.   DTP_NextPatt (FPTR) - pointer to a function that increases the
  387.                 patternpointer.
  388.  
  389.   DTP_PrevPatt (FPTR) - pointer to a function that decreases the
  390.                 patternpointer.
  391.  
  392.   DTP_NextSong (FPTR) - pointer to a function that increases the
  393.                 subsongcounter (only if the subsong exists).
  394.  
  395.   DTP_PrevSong (FPTR) - pointer to a function that decreases the
  396.                 subsongcounter (only if the subsong exists).
  397.  
  398.   ;--- tags in revision 14 or higher (distributed as Release 1.35) ---
  399.  
  400.   DTP_SubSongTest (FPTR) - The tag is only evaluated if DTP_SubSongRange
  401.                 exits too. ti_Data points to a routine that returns
  402.                 a boolean value. This indicates if the subsong number
  403.                 dtg_SubNum(a5) is valid (d0=0) or not (d0<>0). This tag
  404.                 is only necessary for players where not every subsong
  405.                 in the subsong range is existant.
  406.  
  407.   ;--- tags in revision 16 or higher (distributed as Release 2.00) ---
  408.  
  409.   DTP_NewSubSongRange (APTR) - enhanced replacement for DTP_SubSongRange.
  410.                 This tag should be supplied if the player supports
  411.                 multimodules. ti_Data is  a pointer to an array of three
  412.                 WORDs: The first word contains the default subsong that
  413.                 should be played at first. The second contains the minimum
  414.                 and the third the maximum subsong number. In most cases
  415.                 the first and the second word will be equal.
  416.  
  417.   DTP_DeliBase (APTR) - the address of a pointer where DT will
  418.                 store a pointer to the DeliGlobals
  419.  
  420.   DTP_Flags (ULONG) - contains various Flags.
  421.                 Currently the following flags are defined:
  422.                 PLYF_CUSTOM     - player is a customplayer
  423.                 PLYF_SONGEND    - this player supports songend
  424.  
  425.   DTP_CheckLen (ULONG) - Length of the check Code. Set this tag only if
  426.                 the check code is PC-relative and reentrant! If set this
  427.                 enables DeliTracker to swap out the player code.
  428.  
  429.   DTP_Description (APTR) - Pointer to a string that describes what this
  430.                 player/genie does and what special features it has. The
  431.                 string may contain $A as line separator.
  432.  
  433.   DTP_Decrunch (FPTR) - private, still under development!
  434.  
  435.   DTP_Convert (FPTR) - pointer to a module conversion routine. This routine
  436.                 is called after a module has been loaded and decrunched. It
  437.                 has the task to convert the module from one to another
  438.                 module format. The conversion routine works usually the
  439.                 following way:  1) recognize source format
  440.                                 2) allocate memory for target format with
  441.                                 dtg_AllocListData().
  442.                                 3) convert source to target format
  443.                 This routine returns NULL if a conversion took place
  444.                 (success) and -1 in any other case (error). Make sure that
  445.                 the conversion routine does not change the source module!
  446.                 Note: for temporary memory allocations you can use the
  447.                 exec memoryhandling functions as well. But be aware that
  448.                 memory of the final converted module must be allocated with
  449.                 DeliTracker's dtg_AllocListData()!
  450.  
  451.   DTP_NotePlayer (APTR) - private, still under development!
  452.  
  453.   DTP_NoteStruct (APTR) - private, still under development!
  454.  
  455.   DTP_NoteInfo (APTR) - private, still under development!
  456.  
  457.   DTP_NoteSignal (FPTR) - private, still under development!
  458.  
  459.   DTP_Process (FPTR) - pointer to process entry code. If this tag is set
  460.                 DeliTracker will start the player or genie as seperate
  461.                 process
  462.  
  463.   DTP_Priority (BYTE) -  priority of the created process. Only in
  464.                 conjunction with DTP_Process possible.
  465.  
  466.   DTP_StackSize (ULONG) - stack size of the created process. Only in
  467.                 conjunction with DTP_Process possible.
  468.  
  469.   DTP_MsgPort (APTR) - address of a pointer where DT will store the port
  470.                 address to which DT will send it's messages. Only in
  471.                 conjunction with DTP_Process useful.
  472.  
  473.   DTP_Appear (FPTR) - pointer to a routine that opens/activates the genie
  474.                 or player GUI. Returns the old window state (<>0 if the
  475.                 window was already opened else 0). Note: Make sure that
  476.                 you open on the right screen! See dtg_LockPubScreen() and
  477.                 dtg_UnLockPubScreen().
  478.  
  479.   DTP_Disappear (FPTR) - pointer to a routine that closes the GUI. This
  480.                 routine must return the old window state (0 if the window
  481.                 was already closed or <>0 if it was open).
  482.  
  483.   DTP_ModuleName (APTR) - address of a pointer to the real module name.
  484.                 The string must be null terminated. This Tag is for
  485.                 players only and is evaluated after InitPlay().
  486.  
  487.   DTP_FormatName (APTR) - address of a pointer to the real format name.
  488.                 The string must be null terminated. This Tag is for
  489.                 convert genies only and is evaluated after the Convert()
  490.                 function has been called.
  491.  
  492.  
  493.  
  494.   5.DELITRACKER SUPPORT FUNCTIONS
  495.  
  496.   DeliTracker provides some support functions that can be called from genies
  497.   and players. Every function is called like this:
  498.  
  499.         move.l  dtg_XXX(a5),a0          ; a5 must contain the base
  500.         jsr     (a0)
  501.  
  502.   All functions (exept dtg_SongEnd/dtg_SetTimer) use d0/d1/a0/a1 as scratch
  503.   register. A5 must contain the base (exept dtg_SongEnd/dtg_SetTimer).
  504.   Currently the following functions are available:
  505.  
  506.  
  507.   dtg_GetListData
  508.  
  509.         SYNOPSIS
  510.                 memory size = dtg_GetListData(number)
  511.                 a0     d0                     d0.l
  512.  
  513.         FUNCTION
  514.                 Returns the address and the length of a file that was
  515.                 loaded with dtg_LoadFile().
  516.  
  517.         INPUTS
  518.                 number - number of the file beginning with 0 for the file
  519.                          that was selected by the user.
  520.  
  521.         RESULT
  522.                 memory - startaddress of the files in memory, if error 0.
  523.                 size - length of the loaded file in bytes or 0 in case of
  524.                        an error
  525.  
  526.  
  527.   dtg_LoadFile
  528.  
  529.         SYNOPSIS
  530.                 success = dtg_LoadFile(name)
  531.  
  532.         FUNCTION
  533.                 Loads and decrunches the specified file to chipmemory.
  534.                 Note: this function automatically adds '.pp' to the
  535.                       filename.
  536.  
  537.         INPUTS
  538.                 name - store the filename in the internal buffer
  539.                        (dtg_PathArray contains a pointer to this buffer)
  540.  
  541.         RESULT
  542.                 success - success d0.l=0, else d0.l<>0.
  543.  
  544.  
  545.   dtg_CopyDir
  546.  
  547.         SYNOPSIS
  548.                 dtg_CopyDir()
  549.  
  550.         FUNCTION
  551.                 Copies the directory of the selected file at the end
  552.                 of the string, that dtg_PathArray points to.
  553.  
  554.  
  555.   dtg_CopyFile
  556.  
  557.         SYNOPSIS
  558.                 dtg_CopyFile()
  559.  
  560.         FUNCTION
  561.                 Copies the filename of the selected file at the end
  562.                 of the string, that dtg_PathArray points to.
  563.  
  564.  
  565.   dtg_CopyString
  566.  
  567.         SYNOPSIS
  568.                 dtg_CopyString(string)
  569.                                a0
  570.  
  571.         FUNCTION
  572.                 a0 contains the address of a string, which is copied at
  573.                 the end of the string that dtg_PathArray points to.
  574.  
  575.         INPUTS
  576.                 string - a0 contains the pointer to the string
  577.  
  578.  
  579.   dtg_AudioAlloc
  580.  
  581.         SYNOPSIS
  582.                 success = dtg_AudioAlloc()
  583.  
  584.         FUNCTION
  585.                 Allocates the audiochannels
  586.  
  587.         RESULT
  588.                 success - if we got them: d0.l=0, else d0.l<>0.
  589.  
  590.  
  591.   dtg_AudioFree
  592.  
  593.         SYNOPSIS
  594.                 dtg_AudioFree()
  595.  
  596.         FUNCTION
  597.                 Frees the audiochannels that were allocated with
  598.                 dtg_AudioAlloc.
  599.  
  600.  
  601.   dtg_StartInt
  602.  
  603.         SYNOPSIS
  604.                 dtg_StartInt()
  605.  
  606.         FUNCTION
  607.                 Starts the soundinterrupt. If DTP_Interrupt exists,
  608.                 DeliTracker starts the internal timer interrupt,
  609.                 else DTP_StartInt is called.
  610.  
  611.  
  612.   dtg_StopInt
  613.  
  614.         SYNOPSIS
  615.                 dtg_StopInt()
  616.  
  617.         FUNCTION
  618.                 Stops the soundinterrupt. If DTP_Interrupt exists,
  619.                 DeliTracker stops the internal timerinterrupt, else
  620.                 DTP_StopInt is called.
  621.  
  622.  
  623.   dtg_SongEnd
  624.  
  625.         SYNOPSIS
  626.                 dtg_SongEnd()
  627.  
  628.         FUNCTION
  629.                 Signals DeliTracker, that the module was played once.
  630.                 This function doesn't change any registers and is save
  631.                 to call from interrupts.
  632.  
  633.  
  634.   dtg_CutSuffix
  635.  
  636.         SYNOPSIS
  637.                 dtg_CutSuffix()
  638.  
  639.         FUNCTION
  640.                 Removes the suffix '.pp', '.im', '.xpk' at the end of the
  641.                 string, that dtg_PathArray points to.
  642.  
  643.  
  644.   ;------ extensions in revision 14 (distributed as Release 1.34)
  645.  
  646.   dtg_SetTimer
  647.  
  648.         SYNOPSIS
  649.                 dtg_SetTimer()
  650.  
  651.         FUNCTION
  652.                 Programs the timer with the value that is stored in
  653.                 dtg_Timer(a5). This function doesn't change any
  654.                 registers and is save to call from interrupts.
  655.  
  656.  
  657.  
  658.   ;------ extensions in revision 15 (distributed as Release 1.37)
  659.  
  660.   dtg_WaitAudioDMA
  661.  
  662.         SYNOPSIS
  663.                 dtg_WaitAudioDMA()
  664.  
  665.         FUNCTION
  666.                 Waits a particular amount of time before returning.
  667.                 This amount of time is enough for the audio hardware
  668.                 to set new values. This function is only allowed if
  669.                 the internal timer-interrupt is used. Use it instead
  670.                 of the usual dbra or rasterline dma wait's in the
  671.                 replayer's interruptcode. This function doesn't change
  672.                 any registers.
  673.  
  674.   ;------ extensions in revision 16 (distributed as release 2.00)
  675.  
  676.   dtg_LockScreen
  677.  
  678.         SYNOPSIS
  679.                 screen = dtg_LockScreen()
  680.                 (d0)
  681.  
  682.         FUNCTION
  683.                 Try to lock the screen on which DeliTracker is running.
  684.                 This is allways a pubscreen.
  685.  
  686.         RESULT
  687.                 Screenpointer in d0 or NULL on failure.
  688.  
  689.  
  690.   dtg_UnlockScreen
  691.  
  692.         SYNOPSIS
  693.                 dtg_UnlockScreen()
  694.  
  695.         FUNCTION
  696.                 this function unlocks DeliTracker's screen. Note: do not
  697.                 unlock a screen more times than you have locked it!
  698.  
  699.  
  700.   dtg_NotePlayer
  701.  
  702.         SYNOPSIS
  703.                 dtg_NotePlayer()
  704.  
  705.  
  706.         FUNCTION
  707.                 this call plays the notes specified in the current NoteStruct
  708.                 structure. This function call is not allowed if the active
  709.                 player doesn't have a valid NotePlayer structure.
  710.                 Note: This call is guaranteed to preserve all registers. It
  711.                 is save to call from interrupt, if the interrupt level is 4
  712.                 or lower.
  713.  
  714.         INPUTS
  715.                 current NoteStruct.
  716.  
  717.  
  718.   dtg_AllocListData
  719.  
  720.         SYNOPSIS
  721.                 memory = dtg_AllocListData(byteSize,Flags)
  722.                 (d0)                      (d0.l) (d1.l)
  723.  
  724.  
  725.         FUNCTION
  726.                 This is the memory allocator function for module specific memory
  727.                 to be used by all players and genies. It provides a means of
  728.                 specifying that the allocation should be made in a memory area
  729.                 accessible to the chips, or accessible to shared system memory.
  730.                 If the allocation is successful, DeliTracker will keep track of
  731.                 the new block and dtg_GetListData()) will return the location and
  732.                 size of this block.
  733.  
  734.  
  735.         INPUTS
  736.                 byteSize - the size of the desired block in bytes.
  737.  
  738.                 Flags - flags that are passed through to AllocMem().
  739.  
  740.         RESULT
  741.                 A pointer to the newly allocated memory block is returned in d0.
  742.                 If there are no free memory regions large enough to satisfy the
  743.                 request, zero will be returned. The pointer must be checked
  744.                 for zero before the memory block may be used!
  745.  
  746.  
  747.   dtg_FreeListData
  748.  
  749.         SYNOPSIS
  750.                 dtg_FreeListData(memoryBlock)
  751.                                   (a1)
  752.  
  753.         FUNCTION
  754.                 Free a region of memory allocated with AllocListData(),
  755.                 returning it to the system pool from which it came.
  756.  
  757.         INPUTS
  758.                 memoryBlock - pointer of the memory block to free, may be NULL.
  759.  
  760.