home *** CD-ROM | disk | FTP | other *** search
-
- TrackerModule 5.12 (Sep 1994)
- --------------------------------
-
- This is the latest version of the Arc SoundTracker player written by
- Composite Reality of Archimedes Freelancers. It plays exclusively new-format
- modules, created using ArcProTracker, TechTracker or Tracker.
-
- This module can be found on the 'ST-00" disc as 'bin.prop'.
-
- CLI Commands offered
- --------------------
- The module implements the standard range of TrackerModule CLI commands
-
- -----------------------------------------------------------------------------
- *PlayMod <filename> - load and start to play SoundTracker module
- -----------------------------------------------------------------------------
-
- This command allocates space in RMA, loads the specified file and sets the
- player into play mode. Any previously playing tune is stopped as soon as the
- command is issued.
-
- -----------------------------------------------------------------------------
- *PlayStart - set player to play mode
- -----------------------------------------------------------------------------
-
- This command will start a tune playing that has previously been paused using
- SWI Tracker_Pause or *PlayPause. The tune will continue from exactly where
- it left off.
-
- -----------------------------------------------------------------------------
- *PlayPause - set player to pause mode
- -----------------------------------------------------------------------------
-
- This command will pause the currently playing SoundTracker module.
-
- -----------------------------------------------------------------------------
- *PlayStop - set player to stop mode
- -----------------------------------------------------------------------------
-
- This command will stop the currently playing tune and release all memory and
- verctors allocated to it. This command terminates a tune completely, and it
- cannot be restarted.
-
- -----------------------------------------------------------------------------
- *SetPlayPos - set position in sequence list
- -----------------------------------------------------------------------------
-
- This command will force the player to play the tune from the top of the
- pattern at the specified position in the sequence list.
-
- -----------------------------------------------------------------------------
- *PlayStatus - return useful textual information
- -----------------------------------------------------------------------------
-
- This command displays the tune name, author name, length (in positions and
- bytes), number of voices and the names of all samples in the tune.
-
- SWI COMMANDS
- ------------
- After seeing Matt Farrow's TrackerModule 4.00 SWI calls, I thought it would
- be a good idea if I included the same calls in TrackerModule 5.10 for
- compatability and also because they're genuinely useful!
-
- There are a few alterations to some data passed/returned to cater for the
- differeces in 4.00 and 5.12. However these differences just mean simpler
- results from the calls as this version isn't attempting to play old format
- tunes (as there's no point really - just convert it to the equivalent new
- format)
-
- Note: The SWI chunk base number is an officially recognised chunk base
- number supplied by Acorn!
-
- -----------------------------------------------------------------------------
- Tracker_Version (SWI &43200)
- -----------------------------------------------------------------------------
-
- No entry parameters
-
- On exit : R0 = version number × 100 (ie. for version 5.12 = 512)
-
- This call allows the TrackerModule version number to be ascertained.
- (Note: Only versions 4.00 upwards support this feature)
-
- -----------------------------------------------------------------------------
- Tracker_Load (SWI &43201)
- -----------------------------------------------------------------------------
-
- On entry: R0 = pointer to filename of SoundTracker module
-
- On exit : R0 preserved
-
- This call will load the specified SoundTracker module ready for playing.
- (Note: this call will set the player to pause mode. The Tracker_Play routine
- must be called, or a *PlayStart issued in order to start playing)
-
- -----------------------------------------------------------------------------
- Tracker_MemoryLoad (SWI &43202)
- -----------------------------------------------------------------------------
-
- On entry: R0 = pointer to start of SoundTracker module in memory
-
- On exit : R0,R1 preserved
-
- This call will setup the player to play the specified SoundTracker module at
- the memory location specified. This call is equivalent to Tracker_Load
- except that the tune is assumed to be already in memory.
- In this version, R1 need not be set to the tune length (in bytes) as this is
- automatically derived from the new format file.
-
- (Note: this call will set the player to pause mode. The Tracker_Play routine
- must be called, or a *PlayStart issued in order to start playing)
-
- -----------------------------------------------------------------------------
- Tracker_Play (SWI &43203)
- -----------------------------------------------------------------------------
-
- No entry parameters
-
- No exit parameters
-
- This call will restart a tune after it has been paused.
- Exactly eqivalent to *PlayStart
-
- -----------------------------------------------------------------------------
- Tracker_Stop (SWI &43204)
- -----------------------------------------------------------------------------
-
- No entry parameters
-
- No exit parameters
-
- This call will stop a tune, and release all memory/vectors. Exactly
- equivalent to *PlayStop
-
- -----------------------------------------------------------------------------
- Tracker_Pause (SWI &43205)
- -----------------------------------------------------------------------------
-
- No entry parameters
-
- No exit parameters
-
- This call will pause a tune. Exactly equivalent to *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,R1 preserved
-
- This performs the same actions as *SetPlayPos, except that the event within
- the pattern to start playing at can be specified. 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)
- -----------------------------------------------------------------------------
-
- No entry parameters
-
- 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 (music length)
-
- This call returns the current position, event in the current pattern, and
- the total music length.
-
- -----------------------------------------------------------------------------
- Tracker_PlayNote (SWI &43209)
- -----------------------------------------------------------------------------
-
- On Entry: R0 = Sound channel to sound note on (1-8)
- R1 = Note number (1-36) or period (100-1000)
- R2 = Sample to play (1-47 max)
- R3 = Volume (0-255) or -1 (use sample's default volume)
-
- 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.
-
- This call will play a sample at a given pitch and volume on a specified
- channel. Make sure first that the channel you intend to play the note on is
- attached to 'TrackerVox'. For instance if you are playing a 6 track tune,
- 8 tracks will be available (as always) but 7 and 8 will not be attached to
- anything. The first 6 channels as used by the tune can be used by this call
- as they are automatically attached to TrackerVox. Of course 7 and 8 are
- available and nothing is being played on them, so therefore these two
- channels can be used for sound effects. Attach them to TrackerVox using SWI
- Sound_AttachNamedVoice and then call SWI Tracker_PlayNote.
- Note that sample numbers outside the range offered by the module cannot be
- used. A module can contain any number of samples between 0 and 47.
-
- -----------------------------------------------------------------------------
- Tracker_TuneInfo (SWI &4320A)
- -----------------------------------------------------------------------------
-
- No entry parameters
-
- On Exit : R0 = Sequence table length/music length (1-128)
- R1 = Number of voices (1-8)
- R2 = Current speed (1-31) or tempo (32-255)
- R3 = Pointer to tune name (0 terminated, max length 32 chars)
- R4 = Pointer to author's name (0 terminated, max length 32 chars)
- 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.
- 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 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-47)
-
- On Exit : R0 preserved
- R1 = Pointer to sample name (0-terminated, max length 24 chars)
- R2 = Sample length (bytes)
- R3 = LSB - Sample volume (0-255) MSB - Finetune (0-15)
- 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.
-
- =============================================================================
-
- Errors
- ------
-
- The error numbers and messages which TrackerModule may generate:
-
- No tune loaded - An operation was attempted which requires a
- (&43200) tune to be loaded into memory beforehand
- using *PlayMod or SWI Tracker_Load.
-
- Sequence position out of range - The sequence position given with *SetPlayPos(&43201) or SWI Tracker_SetPos was higher than the
- tune's music length.
-
- No room for module - TrackerModule could not claim enough
- (&43202) RMA workspace to load the module. To get
- more memory quit 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 0 to the number of samples used for that
- particular tune.
-
- Volume out of range - The volume was not within the range of
- (&43206) 0-255, or -1.
-
- =============================================================================
-
- New features over previous new format players
- ---------------------------------------------
- New format modules to be played by 5.12 can include:
-
- * Finetune values
- * Restart position (as on NoiseTracker)
- * Sample zero
- * Any number of samples from 0-47
- * Samples upto 1Mb long
- * Secondary tempo commands
-
- -----------------------------------------------------------------------------