The Datafile PD-CD 5

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

/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / demos / incredemo / !IncreDemo / !S_Tracker / !Help < prev next >

Wrap

Text File | 1991-05-23 | 22.2 KB | 635 lines

!S/Tracker (Soundtracker/Tracker module music player) ----------------------------------------------------- Version 4.00 (23 May 1991) Originally written by Hugo Fiennes and Fabrice Mercier [(c) The Serial Port] SWI interface and other bits added by Matt Farrow You are allowed to use this module with any demos or p.d. stuff you write, but permission is required before you can use it in any commercial software. The !S/Tracker application may be freely copied if nothing more than the cost of a disc and a small amount for the trouble is charged, but it must be distributed with all the files complete and unchanged. DOCUMENTATION OF * COMMANDS AND SWI's ------------------------------------- *PlayMod - Loads into memory and starts to play the specified Tracker or Soundtracker module, determining automatically which format it is. Syntax: *PlayMod <filename> *PlayPause - Will pause the currently playing tune (kills all sound immed- iately) but retains the soundtracker/tracker module in memory. The tune can be restarted with a *PlayStart command. Syntax: *PlayPause *PlayStart - Will resume playing a tune after a *PlayPause command. Syntax: *PlayStart *PlayPos - Will set the current position in the sequence table, or if no parameter is given, will simply return the current position. Syntax: *PlayPos [<0-127>] *PlaySamples - Will list all the samples associated with the currently installed music module. Syntax: *PlaySamples *PlayStatus - Will print information about the current tune module loaded Syntax: *PlayStatus *PlayStereo - Controls the stereo settings while the older format sound- tracker modules are playing (the stereo is fixed on an Amiga), and will switch between five possible settings to cater for most configurations: 0 - Slightly off-centre left and right (normal) 1 - Fully left and right (amiga-style) 2 - Fully left 3 - Fully right 4 - Don't alter stereo settings (normally alters settings when a tune is loaded and when it plays a tracker stereo command - see SWI Tracker_Stereo) Syntax: *PlayStereo <0|1|2|3> *PlayStop - Will stop and kill the currently playing tune module, removing it from memory. Syntax: *PlayStop SWI COMMANDS ------------ Several SWI commands have been added to the module in order to simplify the task of adding soundtracker/tracker music to your demos etc. (especially multi-tasking situations). These provide all of the facilities offered by the various * commands, but also allow a more detailed control of some of the module's features. All the SWI's remain in SVC mode, and do not alter the interrupt status. I think most are re-entrant, except those which use system SWI's (load, play, stop etc.), so avoid calling them from interrupts if you can avoid it. The SWI chunk number given here (&43200) is an officially recognised chunk number issued by Acorn. ----------------------------------------------------------------------------- Tracker_Version (SWI &43200) ----------------------------------------------------------------------------- On Entry: - On Exit : R0 = version number*100 (ie. for V1.23 = 123) Use this call to ensure that the trackermodule installed is a recent enough version to support the SWI's you wish to use. Versions 4.00 onwards incorpor- ate the SWI's. ----------------------------------------------------------------------------- Tracker_Load (SWI &43201) ----------------------------------------------------------------------------- On Entry: R0 = pointer to filename of soundtracker/tracker module On Exit : R0 preserved This call will claim memory from the RMA and load the specified tune module, initialise the sound system, and set the playroutine in pause mode. You must then use the SWI Tracker_Play to start the tune playing. The command *PlayMod calls this routine, and then the SWI Tracker_Play. An error will be generated if the module cannot be loaded or not enough memory can be claimed. ----------------------------------------------------------------------------- Tracker_MemoryLoad (SWI &43202) ----------------------------------------------------------------------------- On Entry: R0 = pointer to first word of soundtracker/tracker module in memory (NB must be word-aligned) R1 = length of module in bytes On Exit : R0 and R1 preserved This call can be used by a non-multitasking application to specify an area of memory as a tune module, and thereby remove the need for a seperate file to hold a tune, and there is no need to claim a large amount of RMA space. Once this SWI is called, the module will be treated as if it was loaded in the module's own workspace. Important: You must tell the trackermodule to forget the module if the memory will be overwritten, otherwise the module may crash. (*PlayStop or Tracker_Stop SWI) NB This call will not work for programs running under the desktop if the module is loaded in user memory. When a soundtracker module is loaded, it is partially converted to an intermediate format between soundtracker and tracker to simplify the task for the playroutine. Once the module is loaded (by any method) it is permanently corrupted, and should not be re-saved. Tracker modules will be unchanged, however, and soundtracker modules should be converted fully into this format before being loaded to avoid this problem. ----------------------------------------------------------------------------- Tracker_Play (SWI &43203) ----------------------------------------------------------------------------- On Entry: - On Exit : - This call will restart a tune after it has been paused or loaded with the Tracker_Load SWI. ----------------------------------------------------------------------------- Tracker_Stop (SWI &43204) ----------------------------------------------------------------------------- On Entry: - On Exit : - This performs the same actions as *PlayStop Using *PlayStop or this SWI is the only way to get the trackermodule to release the memory taken up by the tune module, or to force it to forget the address of a module if it has been loaded with the 'Tracker_MemoryLoad' SWI. ----------------------------------------------------------------------------- Tracker_Pause (SWI &43205) ----------------------------------------------------------------------------- On Entry: - On Exit : - This performs the same actions as *PlayPause ----------------------------------------------------------------------------- Tracker_Stereo (SWI &43206) ----------------------------------------------------------------------------- On Entry: R0 = Stereo setting (0-4) On Exit : R0 preserved This performs the same actions as *PlayStereo, with R0 passed as a parameter. If R0 is set to 4 on entry, then the stereo settings will be unaltered whenever a module is loaded or killed, and disables any stereo commands in tracker modules. This is to allow interfacing programs to provide their own stereo options, or to allow adjustment to the stereo positions while tracker tunes are playing (which have default stereo settings stored as part of the tune). ----------------------------------------------------------------------------- Tracker_SetPos (SWI &43207) ----------------------------------------------------------------------------- On Entry: R0 = New sequence position (0-127 max) R1 = Event (0-63 max) On Exit : R0 preserved This performs the same actions as *PlayPos, except that the event with the pattern can be specified (0-63 normally). If an event number higher than the number of events in the current pattern is specified, the pattern will begin at event 0. If there is no tune currently loaded, an error is generated. ----------------------------------------------------------------------------- Tracker_ReadPos (SWI &43208) ----------------------------------------------------------------------------- On Entry: - On Exit : R0 = Current position in sequence table (0-127 max) R1 = Current position in pattern (0-63 max) R2 = Maximum position in sequence table This performs the same actions as *PlayPos with no parameters, but also returns the current position in the current pattern (in case some applic- ations need to synchronize events with the tune being played). ----------------------------------------------------------------------------- Tracker_PlayNote (SWI &43209) ----------------------------------------------------------------------------- On Entry: R0 = Sound channel to sound note on (1-8 max) R1 = Tracker format note number (1-36) R2 = Sample to play (1-36) R3 = Volume (0-255) On Exit : R0-R3 preserved If tune not paused then C flag set otherwise C flag cleared. If there is no tune loaded, an error will be generated. It plays one of the samples which are part of the paused tune at a given pitch (1=low, 36=high) and volume (0=silent, 255=loud). If any of the values are out of range, an error will be reported. The number of sound channels that can be used depends on the module loaded (soundtracker modules will always use 4 voices, whereas Tracker modules can use up to 8). Use the Tracker_TuneInfo SWI to find out the maximum number of voices if you intend to play more than one note at a time. NB This call should be avoided if possible, unless the purpose is to hear each sample seperately. ----------------------------------------------------------------------------- Tracker_TuneInfo (SWI &4320A) ----------------------------------------------------------------------------- On Entry: - On Exit : R0 = Sequence table length (1-128) R1 = Number of voices (1-8) R2 = Current speed (1-15) R3 = Pointer to tune name (terminated by 0, max length 32 chars) R4 = Pointer to author's name (0 terminated, max length 32 chars) or zero if soundtracker format module (not applicable) R5 = Address of currently loaded tune module If the tune is paused, the C flag is set, otherwise the C flag is cleared. If there is no tune loaded, R0 is set to zero, and R1-R5 are preserved. This call provides miscellaneous information about the tune currently loaded. You should not need to directly access the tune module (using the address passed in R5), because all information is available via the various SWI's, and soundtracker format modules will have been converted partially to Tracker format when loaded (and therefore in an unknown format). This information is provided if, for example, multi-tasking players/editors need to know if the tune currently playing is running from ordinary RMA, or the player's/editor's own workspace. ----------------------------------------------------------------------------- Tracker_SoundInfo (SWI &4320B) ----------------------------------------------------------------------------- On Entry: R0 = Pointer to word-aligned 256 byte block to hold sound data On Exit : R0 preserved if the tune is paused, the C flag will be set, otherwise the C flag will be cleared. If there is no tune loaded an error will be generated. This call is only provided for advanced uses of the trackermodule, and involves information of a highly technical nature. It is advised that you do not use this call if you can avoid it. The call will transfer the current contents of the sound voice info table to the location pointed to by R0. 256 bytes (64 words) will be transferred in total (8 words per sound channel), regardless of the number of voices actually active. When a note is played and then ends, word 6 of the appropriate channel is zeroed. The sound routines will only try and play the sample if this word is non-zero. When a tune is paused, the block is saved and overwritten with zeros. When the tune is restarted, the old contents are restored, so that the samples will continue to play from the same point. The format of the table is as follows:- Word Offset Sound channel 1... 0 +0 The current pitch accumulator. (shift right 16 bits to get the actual byte offset into the sample being played). 1 +4 The current pitch increment (added to accumulator after every byte filled). This is obtained using internal tables given the sample period (word 7) 2 +8 The sample loop offset (given in bytes). When the routine reaches the end of a sample or the sample length, the accumul- ator is loaded with this value shifted left 16 bits (ie. to give a byte offset). If this is a zero value, the sample will stop instead of looping. 3 +12 The sample length / repeat length (in bytes). The routine checks every 4 bytes filled to see if the current accumulator exceeds this value when shifted right 16 bits. (See above) 4 +16 The sample number (1-36). 5 +20 The current volume (0-255). This value is subtracted from every byte filled, therefore 0 = maximum volume and 255 = silent. NB This is the reverse of the normal volume command. 6 +24 This is the tracker format note number of the sample being played (1-36, 1=C octave 1 36=B octave 3). The arpeggio command makes use of this word. If this word is zero, no sound will be played. 7 +28 This is a copy of the sample period (from which the pitch increment value is calculated), and is used by the portamento commands. The range of the sample period is from 1 to hex &400 (although the portamento commands have smaller limits in practice). 8 +32 Word 0 of sound channel 2... 9 +36 Word 1 of sound channel 2... etc. -> word 8 of sound channel 8 ----------------------------------------------------------------------------- Tracker_ReadSampleTable (SWI &4320C) ----------------------------------------------------------------------------- On Entry: R0 = Sample number (1-36) On Exit : R0 preserved R1 = Pointer to sample name (0-terminated, max length 22 chars) R2 = Sample length (bytes) R3 = Sample volume (0-255, 255=maximum volume, 0=silent) R4 = Repeat offset (bytes) R5 = Repeat length (bytes) R6 = Address of raw sample data This call returns all relevant information about the specified sample. If there is no tune loaded, an error will be generated. ----------------------------------------------------------------------------- Tracker_Lock (SWI &4320D) ----------------------------------------------------------------------------- On Entry: R0 = locking code (passed in R4 to SWI's) On Exit : - This SWI and the corresponding Tracker_Unlock SWI are provided to prevent user intervention with any of the features of the module when this would be undesirable for any multi-tasking applications using the module (for example issuing a *PlayStop command). By calling this SWI, an applic- ation can gain complete control of the module, but as a result, this feature must be used carefully, because the module cannot then be unlocked unless the code specified in the lock SWI is known (and if not, the module must be re-initialised). When the module is locked, calling any commands or SWI's which alter anything (such as changing the current play position, loading or killing tunes, playing notes) will cause an error, but SWI's returning information will function as normal. For the application which is responsible for the locking to be able to use the affected SWI's, R4 must be set to the locking code (passed in R0) before any of the affected SWI's is called (no commands will work even if the locking code is known). If the trackermodule is already 'locked' when this SWI is called, an error will be generated. It is advisable to avoid using this call unless absolutely neccessary. The restricted commands are: *PlayMod, *PlayPause, *PlayStart, *PlayPos, *PlayStereo, *PlayStop. The restricted SWI's are: Tracker_Load, Tracker_MemoryLoad, Tracker_Play, Tracker_Stop, Tracker_Stereo, Tracker_SetPos, Tracker_PlayNote. ----------------------------------------------------------------------------- Tracker_Unlock (SWI &4320E) ----------------------------------------------------------------------------- On Entry: R0 = locking code (specified in Tracker_Lock) On Exit : - This SWI should be called to unlock the module after it has been locked with 'Tracker_Lock'. If the value passed in R0 is different to the locking code given in the lock SWI, or the module has not been locked, an error is generated. ============================================================================= Note translation table ---------------------- The tracker format note numbers and the notes they refer to are as follows: no. note sample period --- ---- ------------- 1 C -1 &358 2 C#-1 &328 3 D -1 &2FA 4 D#-1 &2D0 5 E -1 &2A6 6 F -1 &280 7 F#-1 &25C 8 G -1 &23A 9 G#-1 &21A 10 A -1 &1FC 11 A#-1 &1E0 12 B -1 &1C5 13 C -2 &1AC 14 C#-2 &194 15 D -2 &17D 16 D#-2 &168 17 E -2 &153 18 F -2 &140 19 F#-2 &12E 20 G -2 &11D 21 G#-2 &10D 22 A -2 &FE 23 A#-2 &F0 24 B -2 &E2 25 C -3 &D6 26 C#-3 &CA 27 D -3 &BE 28 D#-3 &B4 29 E -3 &AA 30 F -3 &A0 31 F#-3 &97 32 G -3 &8F 33 G#-3 &87 34 A -3 &7F 35 A#-3 &78 36 B -3 &71 ============================================================================= Errors ------ The error numbers and messages which the trackermodule may generate: No tune loaded (&43200) - an operation was attempted which requires a tune to be loaded into memory beforehand using *PlayMod or SWI Tracker_Load. Sequence position out of range - The sequence position given with *PlayPos (&43201) or SWI Tracker_SetPos was higher than the actual number of patterns in the song. No room for module (&43202) - The trackermodule could not claim enough RMA workspace to load the module. To get more memory, quit basic to the supervisor prompt, and retry. If you are using the desktop instead, remove an application and retry. Channel number out of range - The sound channel number was not a value (&43203) between 1 and the number of sound channels used for that particular tune. Note number out of range - The note number was not within the range of (&43205) 1-36. Sample number out of range - The sample number was not within the range (&43204) of 1-36. Volume out of range (&43206) - The volume was not within the range of 0-255 Module already locked (&43207) - Tracker_Lock was called when the module was already locked. The module can only be unlocked when the application in control of the module issues a Tracker_Unlock SWI. Unlock failed (&43208) - Tracker_Unlock was called but either the wrong locking code was specified, or the module was not locked at the time. TrackerModule in use (&43209) - An attempt was made to execute one of the restricted commands or SWI's while the module was locked (see Tracker_Lock) ============================================================================= This module was written for enthusiasts who wish to enjoy the benefits of the Archimedes sound system in a multi-tasking environment. Feel free to use this module in any p.d. demos or programs etc., but for any commercial use, please ask Hugo Fiennes for permission. (And upload any demos to his board [see below]) Versions 0.00 to 1.xx of the original module were written by Hugo Fiennes allowing the playing of any soundtracker tunes. Versions 2.00 to 2.xx were written by Fabrice Mercier and Hugo, playing any tracker tunes (with changes/improvements). Versions 3.00 to 4.00 were written (well, extended) by Matthew Farrow to allow the playing of soundtracker or tracker tunes, with the SWI extension from versions 4.00 onwards. You can contact Hugo in the following ways: Voice: UK (0749) 72234 (ask for Hugo) VodaFone: (0831) 444192 The World of Cryton (bbs) : UK (0749) 679794 (300-2400 - 1 line) : UK (0749) 670030 (300-HST/V32 - 2 lines) Mail: Prestel 045847608, CIX altman Burcott Manor, Wells, Somerset, BA5 1NH, UK Matt Farrow: Mail: Prestel 816706758, Arcade bbs (081-654 2212) as 'Matthew Farrow' 45 Alleyn Park, Dulwich, London SE21 8AT ============================================================================= Updates ------- Version 4.00 (from 3.04) - SWI interface added. - Volume translations for soundtracker modules performed correctly now (?) - Locking system introduced - Next pattern line played just after pattern position incremented, not just before (so the position doesn't appear to be ahead of the music). - Removal of more minor bugs..