home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / bbs / may94 / mus / play / delitracker.lha / DeliTracker / Files / developer.lha / Developer / Developer.doc next >
Text File  |  1994-04-15  |  31KB  |  761 lines
  1.  
  2.  
  3.                  $VER: Developer.doc V2.00 (10.04.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 ti