home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Basic / bb_ext.dms / in.adf / LibsDev.lha / userlibdocs / XbonesCIATrkLib.doc < prev   
Encoding:
Text File  |  1995-11-11  |  14.5 KB  |  500 lines
  1. Library Name:
  2.   XbonesCIATrkLib #56
  3.  
  4. Authors:
  5.   Crossbones, Neil O'Rourke
  6.  
  7. OverView:
  8.   A nice soundtracker/protracker library 
  9.       
  10.  
  11. Authors Docs:
  12.  
  13.  
  14. VER: 1.0
  15. author "Crossbones"
  16. (c) "1995 Binary Assault"
  17.  
  18.  
  19.  
  20.                           CIA Protracker Library
  21.                               Blitz Basic II
  22.  
  23.                          Version 1.02a (11/11/95)
  24.  
  25.                                 Updated by:
  26.                          Crossbones/Binary Assault
  27.  
  28. Introduction:
  29. ~~~~~~~~~~~~~
  30. The standard soundtracker replay routines supplied with Blitz Basic 2 have
  31. many faults, which this library attempts to overcome.  Some of the features
  32. are:
  33.  
  34.   - Plays all PT songs that utilise either the VBLANK timing or the
  35.     more recent CIA based timings
  36.   - Plays back correctly on 50/60Hz systems, running either PAL or NTSC
  37.   - Contains more specialised functions for advanced programmers
  38.   - Enables the programmer to syncronise graphics with their music
  39.  
  40.  
  41. Credits:
  42.  
  43. Original ProTracker playroutine by Amiga Freelancers, converted and enhanced
  44. for Blitz by Neil O'Rourke.  Naggings from Roy, Jeff and Richard. Newer
  45. revisions and further enhancements by Crossbones/Binary Assault.
  46.  
  47.  
  48. NOTE:
  49.  
  50.  Neil stopped work on the library at version 1.6. Unfortunately, all the
  51. source code I've located of this library is only at version 1.3. This means
  52. that if you are fimiliar with the last version of his library, a few of the
  53. commands might not contain the same sytax or might not even be in this library
  54. any more.
  55.  
  56.  If you find that you simply can't live without a certain feature, you might
  57. try to contact me and coax me into providing the update you need.  I say
  58. *MIGHT* because there is no guarentee that I'll work on it.
  59.  
  60.  
  61.  
  62. Getting Started:
  63. ~~~~~~~~~~~~~~~~
  64. What you'll need:
  65.  
  66.  o Blitz Basic II version 1.8 or greater.
  67.  o An Amiga*
  68.  o Any music file in protracker format.
  69.  
  70.  
  71. Machine Requirements:
  72.  
  73.  o Kickstart 2.0x+
  74.  o At least 1 meg of chip ram.
  75.  o A kickin' stereo.
  76.  
  77.  
  78. Installing the library:
  79.  
  80.  First, remove any older version of this library you might have. Look for
  81. names such as "NeilsTrackerLib.obj" or "CiaTrackerLib.obj." Don't delete them,
  82. but move them out of the way for now, keeping them until you're sure you don't
  83. need them, or that you've found the correct library to remove.
  84.  
  85.  Now copy the included library into your blitzlibs:userlibs directory. Once
  86. copied, you'll need to recompile your DEFLIBS file to use it. (NOTE: Users of
  87. version 2.1 need not do this, according to Acid.)
  88.  
  89. * - I sincerely hope you have one of these. :)
  90.  
  91.  
  92.  
  93. List of Commands:
  94. ~~~~~~~~~~~~~~~~~
  95.                              LoadTrackerModule 
  96.                                StartTracker    
  97.                                 StopTracker    
  98.                                DecodeModule    
  99.                               GetTrackerSize   
  100.                             GetTrackerLocation 
  101.                              FreeTrackerModule 
  102.                               GetTrackerEvent  
  103.                              CheckTrackerEvent 
  104.                              WaitTrackerEvent  
  105.                               CheckTrackerID   
  106.                                ModuleToChip    
  107.                               GetModuleName$   
  108.                             ModulePositionJump 
  109.                              GetModulePosition 
  110.                                 PauseModule    
  111.                             ChangeTrackerVBLank
  112.                                 PlayTracker    
  113.                                TrackerVolume   
  114.                              ChangeTrackerMask 
  115.                                ModulePatterns  
  116.  
  117.  
  118. The Commands (Explained):
  119. ~~~~~~~~~~~~~~~~~~~~~~~~~
  120.                              LoadTrackerModule
  121.  
  122. Usage:
  123.  
  124. success=LoadTrackerModule(TrackerModule#,FileName$)
  125.  
  126. Comments:
  127.  
  128. Loads the named module into chip ram, ready for playing.  This command can
  129. only be called in Amiga mode.  success is a boolean return code (true).  If
  130. the load fails for any reason, success returns the AmigaDOS error code.
  131.  
  132. Note that there is an implicit call to FreeTrackerModule for whatever module
  133. you are trying to load.  However, if you want to load another module, don't
  134. try to load it on top of the existing one that is playing. Use another
  135. TrackerModule# (you have from 0 to 8).  The results are unpredictable, and
  136. range from nothing to a system crash.  We can't call StopTracker, because this
  137. will stop everything.
  138.  
  139.                                StartTracker
  140.  
  141. Usage:
  142.  
  143. success=StartTracker(TrackerModule#)
  144.  
  145. Comments:
  146.  
  147. Starts to play the requested module, stopping any modules already playing, or
  148. restarts the current module, and returns true.  Returns false if the module
  149. couldn't be started for some reason (like it isn't loaded).
  150.  
  151.                                 StopTracker
  152.  
  153. Usage:
  154.  
  155. StopTracker
  156.  
  157. Comments:
  158.  
  159. Stops the current module. Not much to it, really.
  160.  
  161.                                DecodeModule
  162.  
  163. Usage:
  164.  
  165. DecodeModule TrackerModule#,ModuleAddress
  166.  
  167. Comments:
  168.  
  169.  This sets an arbitary area of memory as a tracker module, useful if you have
  170. BLoaded/INCBIN'd a file and want to hear if it is a module. Caution:  a
  171. non-module may crash the Amiga when you try to play it.
  172.  
  173. NOTE: As of release 1.02a, the ModuleToChip command has been changed.
  174.       DecodeModule now does this for you automatically if the module that
  175.       is being decoded is in fast ram. The ModuleToChip command will still
  176.       tokenise though, to prevent problems that might occur to previous
  177.       users of this library.
  178.  
  179.                               GetTrackerSize
  180.  
  181. Usage:
  182.  
  183. trackerlength=GetTrackerSize(TrackerModule#)  
  184.  
  185. Comments:
  186.  
  187. Not really much of a useful command. Simply returns the size (in bytes) that
  188. the module is using in memory. There should be no need to use this
  189. information,  and these commands are only included because they served a
  190. purpose in debugging  a long time ago, and to remove them would cause problems
  191. with the Blitz tokens.
  192.  
  193.                               GetTrackerLocation
  194.  
  195. Usage:
  196.  
  197. trackerlength=GetTrackerLocation(TrackerModule#)  
  198.  
  199. Comments:
  200.  
  201. Not really much of a useful command. Simply returns the memory location that
  202. the module is occupying. There should be no need to use this information,  and
  203. these commands are only included because they served a purpose in debugging  a
  204. long time ago, and to remove them would cause problems with the Blitz tokens.
  205.  
  206.                              FreeTrackerModule
  207.  
  208. Usage:
  209.  
  210. FreeTrackerModule TrackerModule#
  211.  
  212. Comments:
  213.  
  214. This frees a module loaded with LoadTrackerModule.  You cannot free a module
  215. that has been set up with DecodeModule (see below), but there is nothing to
  216. stop you trying.
  217.  
  218.                               GetTrackerEvent
  219.  
  220. Usage:
  221.  
  222. trackerevent=GetTrackerEvent
  223.  
  224. Comments:
  225.  
  226. This command is a customised extension to the ProTracker replay routine.  A
  227. "TrackerEvent" occurs when the replay routine comes across a $8xx command.
  228. This command is not defined in the command list, and many demos (eg Jesus on
  229. E's) use it to trigger effects.  This command gets the most recent
  230. TrackerEvent, so any program looking at this will have to compare the current
  231. value to the value that triggered the current effect.
  232.  
  233.                              CheckTrackerEvent
  234.  
  235. Usage:
  236.  
  237. success=CheckTrackerEvent
  238.  
  239. Comments:
  240.  
  241. This routine checks to see if a TrackerEvent has occured since the last time
  242. the routine was called, and returns True if it has.  Use GetTrackerEvent to
  243. determine what data the $8xx command had.
  244.  
  245.                              WaitTrackerEvent
  246.  
  247. Usage:
  248.  
  249. Unknown
  250.  
  251. Comments:
  252.  
  253. ** V1.6: DO NOT USE THIS COMMAND! **
  254.  
  255. ** V1.0b: I haven't checked this. **
  256.  
  257.                                CheckTrackerID
  258.  
  259. Usage:
  260.  
  261. success=CheckTrackerID(TrackerModule#)
  262.  
  263. Comments:
  264.  
  265. This checks the module for the standard Pro/Noise/SoundTracker ID string
  266. "M.K." (or "M!K!" in the case of a 100 pattern PT module), and returns True if
  267. one of them is found.  This means that you can safely call StartTracker.
  268.  
  269. Note that there is no 100% guarenteed way of determining what is a module and
  270. what isn't.  Bit Arts, for example, remove the M.K. identifier to make it
  271. harder to rip modules, so if you're writing a module ripping program, you have
  272. to take this result with a grain of salt.
  273.  
  274.                                ModuleToChip
  275.  
  276.  
  277.  
  278. NOTE: This command is outdated as of this release. Even though the command
  279.       will tokenise, the command has no function. Please see the
  280.       DecodeModule command for more details.
  281.  
  282.                               GetModuleName$
  283.  
  284. Usage:
  285.  
  286. name$=GetModuleName$(TrackerModule#)
  287.  
  288. Comments:
  289.  
  290. Returns the name of the module in name$. Not too useful, but I made a little
  291. interface for workbench using the library, and needed a command like this.
  292.  
  293.                             ModulePositionJump
  294.  
  295. Usage:
  296.  
  297. ModulePositionJump(Position#)
  298.  
  299. Comments:
  300.  
  301.  This command tells the play routine to jump to the pattern requested in
  302. Position#.
  303.  
  304. NOTE: There is no error checking done at this time. It would be wise to know
  305.       where you're going.
  306.  
  307.                              GetModulePosition
  308.  
  309. Usage:
  310.  
  311. position=GetModulePosition
  312.  
  313. Comments:
  314.  
  315. This returns the current pattern the replay routine is playing.
  316.  
  317.                                 PauseModule
  318.  
  319. Usage:
  320.  
  321. PauseModule
  322.  
  323. Comments:
  324.  
  325. Stops the current module from playing, effectively pausing it. Use the command
  326. again to unpause it.
  327.  
  328.                             ChangeTrackerVBlank
  329.  
  330. Usage:
  331.  
  332. ChangeTrackerVBlank
  333.  
  334. Comments:
  335.  
  336. This command seems pretty useless, but there sure are alot of module players
  337. that offer vblank timing. Call the command before playing the module, then
  338. call the StartTracker command, so it knows which module to use. Then simply
  339. call the PlayModule command on every vblank.
  340.  
  341.                                 PlayModule
  342.  
  343. Usage:
  344.  
  345. PlayModule
  346.  
  347. Comments:
  348.  
  349.  This command is to be used if you use the ChangeTrackerVBlank command.
  350.  
  351.  To use this command, call ChangeTrackerVBlank first. Secondly, call the
  352. StartTracker command. At each vblank, you must then call PlayMoudule, which
  353. will keep the music playing.
  354.  
  355.                                TrackerVolume
  356.  
  357. Usage:
  358.  
  359. TrackerVolume [Volume Level]
  360.  
  361. Comments:
  362.  
  363.  What can be said? This command changes the volume level of the module. Note:
  364. this effects all the channels currently masked in. (Refer to the command
  365. ChangeTrackerMask for more information on this).
  366.  
  367.                              ChangeTrackerMask
  368.  
  369. Usage:
  370.  
  371. ChangeTrackerMask [NewMask]
  372.  
  373. Comments:
  374.  
  375.  For all intents and purposes, you might never need this command. This command
  376. allows you to tell the replay routine that it is not supposed to use a certain
  377. channel, or certain channels. This is useful if you want, for instance, a two
  378. channel module playing and sounds effects at the same time. The command wants
  379. to know what channels the replay routine CAN use.
  380.  
  381. How to figure out what channels to mask:
  382.  
  383.  This is fairly simple, and there are a couple of different ways to do this.
  384.  
  385.  1. ChangeTrackerMask %0000ABCD - Where ABCD represents channels 0-3.
  386.  
  387.     Channels to be used by the replay routine would be represented as
  388.     1's, and channels you wish to use for sound effects, etc., would be
  389.     represented as 0's.
  390.  
  391.     Example: ChangeTrackerMask %00001001 would play channels 0 and 3, while
  392.     channels 1 and 2 would be free for you to use.
  393.  
  394.  2. ChangeTrackerMask [DecimalValue] - Where decimal value represents:
  395.  
  396.     1 - Channel 0
  397.     2 - Channel 1
  398.     4 - Channel 2
  399.     8 - Channel 3
  400.  
  401.     Example: ChangeTrackerMask 9 would play channels 0 and 3, while channels
  402.     1 and 2 would be free for you to use.
  403.  
  404.                               ModulePatterns
  405.  
  406. Usage:
  407.  
  408. patt=ModulePatterns(Module#)
  409.  
  410. Comments:
  411.  
  412.  This command is kind of useless, but I wanted one so it's included. ;) All
  413. this command does is return the number of patterns used in the module.
  414.  
  415.  
  416.  
  417. Revision History:
  418. ~~~~~~~~~~~~~~~~~
  419. Pre 1.01B:
  420.  
  421.  -Original version by Neil updated to use a decent method of CIA timing. No
  422.   longer needs the crappy "SetDMA" command. :)
  423.  
  424. 1.01B:
  425.  
  426.  -Fixed problem with slots. (Was supposed to be able to allow 0-8, but was
  427.   only set only to keep track through 7.
  428.  -Added various commands in an attempt to get up to date with the commands
  429.   from Neil's last update. (Version 1.6)
  430.  -Added better run-time error checking (Limited edition version of 1.01B.)
  431.  
  432. 1.02 (Current):
  433.  
  434.  -Hoo boy! Did I ever screw up 1.01B. Good thing I didn't send it too much.
  435.   Seems that the run-time errors section REALLY made a mess of things.
  436.   Deleted them and rewrote the entire error checking system. MUCH better.
  437.  -I am now using the TrackerTester program on all versions of the library
  438.   ready for release. Since I have problems with beta testers offering to
  439.   help, then never saying a damn thing once they get the library, I figure
  440.   this is the next best thing. Checks all major commands for failure.
  441.   (NOTE: This program is now included in releases. Use it if you have
  442.   problems and report the errors/bugs to me for fixing.)
  443.  -Fixed small problem with LoadTrackerModule command. (1.02a)
  444.  -DecodeModule command changed to also include function from ModuleToChip.
  445.   ModuleToChip still tokenises, but performs no function. (1.02a)
  446.  -Repaired section that grabs the cia timer. This fixed the following
  447.   problems:
  448.   - Used to lose characters over the serial port when the player was active.
  449.   - Failed to play if one of the two cia timers was being used. (It only
  450.     was able to allocate one timer successfully, and failed on the other.)
  451.   These two should fix any problems the player had on specific machines.
  452.   (1.02a)
  453.  
  454.  
  455.  
  456. Bugs:
  457. ~~~~~
  458. Things I know about
  459.  
  460.  o Because of some unknown problem, the routine actually reserves 3 bytes of
  461.    memory (added to the actual module size.) Keep this in mind when calling
  462.    the function to find out the byte-size of a module.
  463.  
  464. Things I don't know about
  465.  
  466.  Well!?! If I don't know about them, I can't really put them here can I? ;)
  467.  
  468.                         How to Contact the Author:
  469.                             (This part's easy!)
  470.  
  471.                          Crossbones/Binary Assault
  472.                               aka Steve Flock
  473.  
  474.                                Via Internet
  475.                            sflock@comtch.iea.com
  476.  
  477.                               Via Snail-Mail
  478.                                 Steve Flock
  479.                             2421 west LaCrosse
  480.                             Spokane, Washington
  481.                                    99205
  482.  
  483. (Note: Please be sure that if you're contacting me via snailmail that you put
  484. the correct postage on the letter. If I have to pay to get the mail, chances
  485. are you won't get a reply.)
  486.  
  487.  
  488.  
  489.  
  490. People who have helped and deserve to be mentioned:
  491. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  492.  
  493.                              Ted Bailey
  494.                           Andrew (Defender)
  495.                            Richard Elmore
  496.  
  497.  
  498.  I know there are more, but I've forgotten your names. If you're seeing this
  499. and saying "Geez, and he forgot me!" then get ahold of me and let me know.
  500.