home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Basic / wst!blz1.dms / in.adf / docs / NeilsCIATrackerLib.doc < prev    next >
Encoding:
Text File  |  1994-09-05  |  12.4 KB  |  359 lines
  1. Library:
  2.   neilsciatrackerlib #56
  3.  
  4. Author:
  5.   Neil O'Rourke, 6 Victoria St, TAMWORTH, NSW 2340, AUSTRALIA
  6.  
  7. Overview:
  8.   Many thanks to Neil, from what I have seen on the net there are
  9.   already many BlitzUsers using this library to great success. I'm
  10.   trying to fit the example code on the disk as I type...
  11.  
  12. Commands:
  13.   LoadTrackerModule:   success=LoadTrackerModule(TrackerModule#,FileName$)
  14.   StartTracker:        success=StartTracker(TrackerModule#)
  15.   StopTracker:         StopTracker
  16.   SetDMAWait:          SetDMAWait value
  17.   FreeTrackerModule:   FreeTrackerModule TrackerModule#
  18.   SetTrackerModule:    SetTrackerModule TrackerModule#,ModuleAddress
  19.   GetTrackerSize:      trackerlength=GetTrackerSize(TrackerModule#)
  20.   GetTrackerLocation:  GetTrackerLocation (TrackerModule#)
  21.   GetTrackerEvent:     trackerevent=GetTrackerEvent
  22.   CheckTrackerEvent:   success=CheckTrackerEvent
  23.   WaitTrackerEvent:    WaitTrackerEvent
  24.   CheckTrackerModuleID:success=CheckTrackerModuleID(TrackerModule#)
  25.   GetTrackerVolume:    volume=GetTrackerVolume(TrackerChannel#)
  26.   GetTrackerNote:      note=GetTrackerNote(TrackerChannel#)
  27.   SetTrackerTempo:     SetTrackerTempo Tempo
  28.   GetTrackerInstrument:instrument=GetTrackerInstrument(TrackerChannel#)
  29.   GetPatternPosition:  PatPos=GetPatternPosition
  30.   GetSongPosition:     SongPos=GetSongPosition
  31.   SetSongPatternPosition:  SetSongPatternPosition Pattern#,Position#
  32.   GetSongLength:       NumPatterns=GetSongLength
  33.   SetTrackerMask:      SetTrackerMask Mask
  34.   GetTrackerNoteNumber:notenumber=GetTrackerNoteNumber(Channel#)
  35.   StartTrackerPatPos:  ret.l=StartTrackerPatPos(TrackerModule#,Pattern#,Position#)
  36.   PauseTracker:        PauseTracker
  37.   RestartTracker:      RestartTracker
  38.   PlayTrackerSample:   PlayTrackerSample Sample#,Period,Volume,Channel
  39.   InitTracker:         success=InitTracker(TrackerModule#)
  40.   GetSampleLocation:   location=GetSampleLocation(Sample#)
  41.   GetSampleLength:     length=GetSampleLength(Sample#)
  42.   GetSampleName:       name$=GetSampleName(Sample#)
  43.   GetTrackerName:      name$=GetTrackerName(TrackerModule#)
  44.  
  45. Author's Documentation:
  46.  
  47. CIATracker.lib Documentation
  48.  
  49. Neil O'Rourke
  50.  
  51. Version 1.6 (24/6/94)
  52.  
  53.  
  54. Introduction
  55. ~~~~~~~~~~~~
  56. The standard soundtracker replay routines supplied with Blitz Basic 2 have
  57. many faults, which this library attempts to overcome.  Some of the features
  58. are:
  59.  
  60.   - Plays all ST/NT/PT songs that utilise either the VBLANK timing or the
  61.     more recent CIA based timings
  62.   - Plays back correctly on 50/60Hz systems, running either PAL or NTSC
  63.   - Contains more specialised functions for advanced programmers
  64.   - Enables the programmer to syncronise graphics with their music
  65.  
  66.  
  67. Credits:
  68. ~~~~~~~~
  69. Original ProTracker playroutine by Amiga Freelancers, converted and
  70. enhanced for Blitz by Neil O'Rourke.  Naggings from Roy, Jeff and Richard.
  71.  
  72.  
  73. The 1.6 upgrade
  74. ~~~~~~~~~~~~~~~
  75. This is a maintenance upgrade, with some subtle (and not so subtle) bugs
  76. fixed or noted.
  77.  
  78. LoadTrackerModule no longer crashes the machine if the name was invalid.
  79.  
  80. SetTrackerMask has been removed for the moment (this was causing the
  81. TrackerEvent system to foul up)
  82.  
  83. WaitTrackerEvent has a nasty tendancy to lock the machine up.  Don't call
  84. this command, use While NOT CheckTrackerEvent:Wend to wait for an event if
  85. you must.  WaitTrackerEvent currently sits on the VBLANK interrupt, however
  86. I think the problem is due to the sheer bulk of ciaTrackerLib getting in
  87. the way of checking.  I think.
  88.  
  89. GetTrackerNoteNumber was found to be chewing up CPU time, and has been
  90. replaced by a new version that chews up 2K of ram extra.
  91.  
  92. I've found that if you have run errors enabled to bring up the requester,
  93. your module won't start sometimes.  Don't know what to do about this, as I
  94. don't know what causes it.
  95.  
  96.  
  97. Quick Usage:
  98. ~~~~~~~~~~~~
  99. First you must set the DMAWait time with the SetDMAWait command.  Then,
  100. enable all the channels with SetTrackerMask.  Load the module you want with
  101. the LoadTrackerModule command, and then either StartTrackerModule it, or
  102. InitTracker/RestartTracker later on.
  103.  
  104.  
  105. Basic Commands
  106. ~~~~~~~~~~~~~~
  107.  
  108. success=LoadTrackerModule(TrackerModule#,FileName$)
  109.  
  110. Loads the named module into chip ram, ready for playing.  This command can
  111. only be called in Amiga mode.  success is a boolean return code (true).  If
  112. the load fails for any reason, success returns the AmigaDOS error code.
  113.  
  114. Note that there is an implicit call to FreeTrackerModule for whatever
  115. module you are trying to load.  However, if you want to load another
  116. module, don't try to load it on top of the existing one that is playing.
  117. Use another TrackerModule# (you have from 0 to 8).  The results are
  118. unpredictable, and range from nothing to a system crash.  We can't call
  119. StopTracker, because this will stop everything.
  120.  
  121.  
  122. success=StartTracker(TrackerModule#)
  123.  
  124. Starts to play the requested module, stopping any modules already playing,
  125. or restarts the current module, and returns true.  Returns false if the
  126. module couldn't be started for some reason (like it isn't loaded).
  127.  
  128.  
  129. StopTracker
  130.  
  131. Stops the current module
  132.  
  133.  
  134. SetDMAWait value
  135.  
  136. This sets the DMA Wait for your machine.  On a standard 7.14MHz 68000 based
  137. machine, the value is the default (300).  However, faster machines can cause
  138. the replay routine to skip notes.  On a 25MHz 68030 machine, the suggested
  139. value is 900.  Set this as low as possible so that you still hear all the
  140. notes.  A future upgrade *may* do this automatically, but I have no
  141. intention of implementing it at this stage, as I don't know what DMAWait to
  142. set for different speed processors and version motherboards.
  143.  
  144. DMA wait is important.  Technically, when the replay routine loads the chip
  145. registers with the information about the current note (location, volume,
  146. pitch), a delay is needed to ensure that the chips actually get the data,
  147. which happens on the next DMA slot.  Since the CPU can be clocked
  148. independantly of the motherboard, we can't just delay by a set amount.  How
  149. this problem has been solved is a busy wait that simply loops around the
  150. number of times as specified by the DMAWait value.  A low value therefore
  151. lessens the load on the CPU but increases the chances of missing notes
  152. while playing a song.  Too high a value can bog the CPU down, and slow the
  153. song down as interrupts are missed.  
  154.  
  155.  
  156. FreeTrackerModule TrackerModule#
  157.  
  158. This frees a module loaded with LoadTrackerModule.  You cannot free a
  159. module that has been set up with SetTrackerModule (see below), but there is
  160. nothing to stop you trying.
  161.  
  162.  
  163. SetTrackerModule TrackerModule#,ModuleAddress
  164.  
  165. This sets an arbitary area of memory as a tracker module, useful if you
  166. have BLoaded a file and want to hear if it is a module. Caution: a
  167. non-module may crash the Amiga.
  168.  
  169.  
  170. trackerlength=GetTrackerSize(TrackerModule#)  GetTrackerLocation (TrackerModule#)
  171.  
  172. Both these functions return information about the module that has been
  173. loaded with LoadTrackerModule.  There should be no need to use this
  174. information, and these commands are only included because they served a
  175. purpose in debugging a long time ago, and to remove them would cause
  176. problems with the Blitz tokens
  177.  
  178.  
  179. trackerevent=GetTrackerEvent
  180.  
  181. This command is a customised extension to the ProTracker replay routine.  A
  182. "TrackerEvent" occurs when the replay routine comes across a $8xx command.
  183. This command is not defined in the command list, and many demos (eg Jesus
  184. on E's) use it to trigger effects.  This command gets the most recent
  185. TrackerEvent, so any program looking at this will have to compare the
  186. current value to the value that triggered the current effect.
  187.  
  188.  
  189. success=CheckTrackerEvent
  190.  
  191. This routine checks to see if a TrackerEvent has occured since the last
  192. time the routine was called, and returns True if it has.  Use
  193. GetTrackerEvent to determine what data the $8xx command had.
  194.  
  195.  
  196. WaitTrackerEvent
  197.  
  198. ** V1.6: DO NOT USE THIS COMMAND! **
  199.  
  200.  
  201. success=CheckTrackerModuleID(TrackerModule#)
  202.  
  203. This checks the module for the standard Pro/Noise/SoundTracker ID string
  204. "M.K." (or "M!K!" in the case of a 100 pattern PT module), and returns True
  205. if one of them is found.  This means that you can safely call StartTracker.
  206.  
  207. Note that there is no 100% guarenteed way of determining what is a module
  208. and what isn't.  Bit Arts, for example, remove the M.K. identifier to make
  209. it harder to rip modules, so if you're writing a module ripping program,
  210. you have to take this result with a grain of salt.
  211.  
  212.  
  213. volume=GetTrackerVolume(TrackerChannel#)
  214.  
  215. Returns the last volume set by a $Cxx command for the named channel, which
  216. are numbered from 0 to 3.  This is not the "real" volume of the sample that
  217. is currently playing.
  218.  
  219.  
  220. note=GetTrackerNote(TrackerChannel#)
  221.  
  222. Returns the note that the play routine has just played in the named
  223. channel.  This command is really only useful for graphic bars or simple
  224. syncronisation of graphics to the music, but for that purpose the
  225. TrackerEvent commands are far more flexable.  Note that the value returned
  226. is the period of the note.  You have to look up the note in a period table
  227. to find out what was actually being played.
  228.  
  229.  
  230. SetTrackerTempo Tempo
  231.  
  232. Sets the tempo of the current song.  Note that a tempo command ($Fxx) will
  233. override any value set by this command.  This command is really a stub to
  234. the actual $Fxx command in the playroutine, and has all the features
  235. associated with it.  Check your tracker docs for more details.
  236.  
  237.  
  238. instrument=GetTrackerInstrument(TrackerChannel#)
  239.  
  240. Gets the instrument that is playing in the channel.
  241.  
  242.  
  243. PatPos=GetPatternPosition
  244.  
  245. This returns the current position in the current pattern.
  246.  
  247.  
  248. SongPos=GetSongPosition
  249.  
  250. This returns the current pattern that is playing in the song
  251.  
  252.  
  253. SetSongPatternPosition Pattern#,Position#
  254.  
  255. This command sets what pattern to play, and from what position.  Use this
  256. while a song is playing to jump to another pattern (eg. a game over music).
  257. Call StartTrackerPatPos() to start a module from scratch.
  258.  
  259.  
  260. NumPatterns=GetSongLength
  261.  
  262. Returns the number of patterns in the current module.  Useful for displays
  263. like in IntuiTracker, where the title bar of the window gives a display
  264. that can be done like:
  265.   NPrint GetSongLength,":",GetSongPosition
  266.  
  267.  
  268. SetTrackerMask Mask
  269.  
  270. ** REMOVED IN V1.6 **
  271.  
  272.  
  273. notenumber=OldGetTrackerNoteNumber(Channel#)
  274.  
  275. This returns the number of the note played on the specified channel, with
  276. C-1 being note 1.  Of use really in creating "equalizer bars".
  277.  
  278. V1.6: This command has turned out to be a CPU-hog!  The new implementation
  279. will consume a lot of memory but will be much faster.  When you load your
  280. old programs, GetTracker... will be replaced by OldGetTracker..., so your
  281. code will continue to work.
  282.  
  283.  
  284. ret.l=StartTrackerPatPos(TrackerModule#,Pattern#,Position#)
  285.  
  286. This starts the named module at the requested pattern and position.  In all
  287. other respects it is the same as StartTracker.
  288.  
  289.  
  290. PauseTracker  RestartTracker
  291.  
  292. These commands allow you to stop a tracker module are restart it at a later
  293. time.
  294.  
  295.  
  296. PlayTrackerSample Sample#,Period,Volume,Channel
  297.  
  298. Plays a sample through the channel.  The module must not be running.
  299.  
  300.  
  301. success=InitTracker(TrackerModule#)
  302.  
  303. Identical to StartTracker, except that the module doesn't start, but is
  304. initialised.  Of use with the commands that use the current tracker module.
  305. Use ReStartTracker to start playing.
  306.  
  307.  
  308. location=GetSampleLocation(Sample#)
  309.  
  310. Returns the address in memory of the named sample in the current module.
  311.  
  312.  
  313. length=GetSampleLength(Sample#)
  314.  
  315. Returns the length in words of the named sample in the current module.
  316. Multiply by two to get the byte length.
  317.  
  318.  
  319. name$=GetSampleName(Sample#)
  320.  
  321. Returns the name of the sample in name$.
  322.  
  323.  
  324. name$=GetTrackerName(TrackerModule#)
  325.  
  326. Returns the name of the module in name$
  327.  
  328.  
  329. BuildNoteTable
  330.  
  331. This command builds a note table for use with GetTrackerNoteNumber.  It
  332. consumes 2K of memory for the look-up table.
  333.  
  334.  
  335. notenumber=GetTrackerNoteNumber(Channel#)
  336.  
  337. This returns the number of the note played on the specified channel, with
  338. C-1 being note 1.  Of use really in creating "equalizer bars".
  339.  
  340. For speed purposes, no error checking (like, has the note table been
  341. built?) is done.
  342.  
  343.  
  344. Notes:
  345. ~~~~~~
  346. Quite a number of these commands extract their data from the playroutine in
  347. real time; that is, around fifty times a second (depending upon the tempo).
  348. Therefore, the value your program receives could well be very different
  349. from what is actually happening in the song.
  350.  
  351.  
  352. Disclaimer:
  353. ~~~~~~~~~~~
  354. By installing this software on your system, you are agreeing that I have no
  355. liability as to the outcome of such use.  If, for example, you use a
  356. command as documented and a floppy disk is ejected from your disk drive
  357. with such force that it severs your head from your neck, tough.  Next time,
  358. duck.
  359.