home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / AMP / !Amp / Docs / TimGuide < prev    next >
Text File  |  1999-02-22  |  32KB  |  1,046 lines
  1.  
  2. ————————————————————————————————————————————————————————————————————————————————
  3.                  TimPlayer v0.88, © André Timmermans 1996-1998
  4. ————————————————————————————————————————————————————————————————————————————————
  5.  
  6. Introduction
  7. ————————————
  8.  
  9.   TimPlayer is a RISC OS soundtrack player that supports the following formats:
  10.  
  11.   - Standard MODs.
  12.   - PC MODs (with more than 4 channels, I even found a 28 channels one).
  13.   - Multi Tracker Modules (MTM).
  14.   - ScreamTracker 3 Modules (S3M): ADPCM samples and adlib samples not
  15.     supported, but I have never found a file which used them.
  16.   - Fast Tracker 2 Modules (XM).
  17.   - Impulse Tracker Modules (IT), including support for packed samples and
  18.     virtual channels.
  19.  
  20.   You are free to use this module with in own applications (or demos) as long
  21.   as users are able to replace the module with more recent versions in case
  22.   the current version fails to work on new hardware or new version of RISC OS.
  23.  
  24.   The main features are turned toward sound quality rather than speed:
  25.  
  26.   - 32-bit internal precision for mixing, dithered to 8-bit or 16-bit.
  27.  
  28.   - In 8-bit mode, the logarithmic buffers are generated using a linear to
  29.     logarithmic translation table with 12 significant bits instead of the
  30.     usual 8-bit table found in most players (quiet sounds are much clearer).
  31.  
  32.   - Linear interpolation is used for resampling.
  33.  
  34.   - Dynamic Gain Control allows to boost the volume level of songs with many
  35.     channels while ensuring that no clipping occurs.
  36.  
  37.   - Volume scaling is done with multiplications, not approximated by shifts.
  38.  
  39.   - Volume ramping: instead of jumping from one note volume to the other, the
  40.     player will use a volume ramp of a few ms at the start of every frame,
  41.     which will remove most of the pops and clicks in the sound.
  42.  
  43.   - Supports multiple effects on the same channel.
  44.  
  45.   - Provides timing (in ms) of song position and the song duration.
  46.  
  47.   - Accept Surround effect (not Prologic) which sends the sound to the tiny
  48.     lateral amplifiers instead of the big ones of your HiFi installation.
  49.  
  50.   - Performs a limitation of the note polyphony when the CPU usage becomes too
  51.     high, to prevent freezing the computer. When a song requests to play more
  52.     notes than allowed by the note polyphony, the mixing routines will only
  53.     play the notes with the highest volume.
  54.  
  55.  
  56. Hardware requirements
  57. —————————————————————
  58.  
  59.   - An A5000 is enough for 4 channels MODs, a StrongARM is required for songs
  60.     with 64 channels.
  61.  
  62.   - Either the original 8-bit sound or a 16-bit card.
  63.  
  64.  
  65. Contacts
  66. ————————
  67.  
  68.   You can contact me using email at:
  69.  
  70.     tim@swn.sni.be (which I can only access between Monday and Thursday).
  71.  
  72.   or using smail address:
  73.  
  74.     Timmermans André
  75.     Rue du Vert Coron, 17
  76.     7600 Péruwelz
  77.     Belgium
  78.  
  79.  
  80. Sound quality setup
  81. ———————————————————
  82.  
  83.   All the parameters controlling the sound output are tuned using:
  84.  
  85.     SYS "TimPlayer_Configure", param id, param value
  86.  
  87.   The following parameters are currently defined:
  88.  
  89.   * Mixing quality:
  90.     This is the duration (in microseconds) a digital sample value is maintained
  91.     on the DAC (Digital/Analog Converter) that produces the sound. The smaller
  92.     this duration is, the faster it will be possible to change the output signal
  93.     and the better the higher frequencies in the signal will be reproduced.
  94.     For example a value of 24 µs will allow the signal to change at 41666 Hz.
  95.  
  96.   * Sample interpolation:
  97.     This defines the way you play samples which have a frequency which differs
  98.     from the output frequency defined by the mixing quality. If for example you
  99.     which to play a sample defined at 20833 Hz with an output frequency of
  100.     41666 Hz, you will have to feed the DAC with 2 times (41666/20833) the
  101.     number of values defined in the sample. The simple way to is to feed the DAC
  102.     twice with the same sample value, but we can as well interpolate between the
  103.     successive values. In our example I could feed the DAC with the following
  104.     sequence: value 0, mean of value 0 & 1, value 1, mean of value 1 & 2, ...
  105.     There are many forms of interpolation but I defined only the one which takes
  106.     the less processing power, linear interpolation.
  107.  
  108.   * Balance:
  109.     This defines the balance between the left and right speakers and allows you
  110.     to offset the produced signal to the left or the right.
  111.  
  112.   * Stereo separation:
  113.     This defines the rate at which a signal moves from a central position to the
  114.     left or the right. Increasing the rate will produce "spatial" sound,
  115.     dropping to zero will produce a mono signal and negative rate will invert
  116.     the stereo.
  117.  
  118.   * Volume ramping:
  119.     You may have noticed that sometimes while playing the speakers produces pops
  120.     or clicks. This is produced by brutal changes in the signal received by
  121.     the speakers and has various causes. The most obvious cause is the use of
  122.     samples which contains such brutal changes and composers quickly learn to
  123.     avoid such samples but otherwise not much can be done to avoid the noises.
  124.     The other cause is changing the volume at which a note is played when using
  125.     a volume effect or a note cut (and playing a new note in a channel usually
  126.     cuts the previous note) but here instead of changing the volume in one go
  127.     we can use a ramp of a few milliseconds to smooth the change and that way
  128.     avoid generating pops and clicks.
  129.  
  130.  
  131. Current limits
  132. ——————————————
  133.  
  134.   - 64 logical channels.
  135.   - 255 samples.
  136.   - 255 instruments.
  137.   - 256 rows in a pattern.
  138.   - Unlimited number of patterns and sequence length.
  139.   - Note range from C-0 to B-9.
  140.  
  141.  
  142. Not implemented
  143. ———————————————
  144.  
  145.   - MOD effect EF (invert loop).
  146.   - IT flag 'link E|F and G memory'.
  147.   - IT usage of a different memory for volume slides in volume column.
  148.   - IT volume and panning swing.
  149.   - IT filters.
  150.   - IT MIDI parameters.
  151.  
  152.  
  153. Timing explained
  154. ————————————————
  155.  
  156.   Due to the nature of soundtracks, timing is not a straightforward issue.
  157.   So first let me explain briefly how a soundtrack is played:
  158.  
  159.   1. A song is composed of a sequence of patterns which are played in turn.
  160.      Example the sequence 1-3-5-1-1-2 means play pattern nr 1, then pattern
  161.      nr 3 then nr 5, then nr 1 again, etc.
  162.  
  163.   2. Each pattern is divided in n rows (64 usually) which are played in turn.
  164.      A row contains information to apply to each defined channel: instrument,
  165.      note to play, volume, panning, commands (effects) to apply. When a row is
  166.      played, first the row is decoded, then commands are applied and the note
  167.      is maintained for a given duration called a frame (or sometimes a tick).
  168.      Then commands are re-applied and the note is maintained for the same
  169.      duration. Then ...
  170.  
  171.      The duration of a row is determined by two parameters:
  172.      - the Tempo or number of beats per minutes (125 by default)
  173.        and the relation: nr of frames/sec = 0.4 * tempo.
  174.      - the Speed or number of frames per row (6 by default).
  175.  
  176.   So, the duration of a song could simply be:
  177.  
  178.     sum for each pattern in the sequence of "nr of rows * speed * 0.4 * tempo".
  179.  
  180.   The problem is the existence of special commands that interferes with this,
  181.   such as:
  182.  
  183.   - Set Tempo, to alter the tempo
  184.   - Set Speed, to alter the speed
  185.   - Pattern break, to stop playing the current pattern and to go in row x
  186.     of the next pattern in the sequence
  187.   - Sequence Jump, to stop playing current pattern and to go in row 0
  188.     of pattern at sequence index x.
  189.   - Loop, to loop x times on a set of rows.
  190.  
  191.   The best way I have found is to perform the song without actually playing
  192.   but applying only the above commands, adding together the resulting frame
  193.   durations and storing this time index at the start of each position in the
  194.   pattern sequence until I reach a the end of a sequence or I branch to
  195.   a sequence position I have already timed.
  196.  
  197.   As this may not cover all the positions in the sequence (for example all the
  198.   songs in the game Lemmings are stored in the same soundtrack and are played
  199.   by moving to different looping sequence fragments) I then move to the first
  200.   untimed sequence position and continue the timing from that point. And again
  201.   and again until every sequence position is timed. The final timing obtained
  202.   is the song duration reported by TimPlayer_SongInfo.
  203.  
  204.   During real playback I maintain a timer that can be obtained on return of
  205.   TimPlayer_SongPosition. The timer is reset at every sequence position change
  206.   to the time index store for that position, then time is added normally
  207.   while the pattern is played.
  208.  
  209.   Those of you with some knowledge of how soundtracks works will noticed
  210.   immediately the remaining problems:
  211.  
  212.   - by combining Pattern Break and Sequence Jumps it is possible to perform 2
  213.     or more sets of different rows of the same pattern position (and I have
  214.     only timed one of them) or to perform the same set with different
  215.     tempo/speed settings.
  216.  
  217.   - when the user decide to skip a part of the song he may bypass some
  218.     Set Tempo/Set Speed, which means that the song will then continue
  219.     to play with abnormal tempo/speed settings.
  220.  
  221.  
  222. TroubleShooting
  223. ———————————————
  224.  
  225.   * Processing power:
  226.     Those with less faster machine should be warned that the CPU usage can be
  227.     quite high: at 24 µs, above 1% of CPU per channel on my SA RPC
  228.                 at 72 µs, Cache off, 4 channels grabs 60% of CPU
  229.  
  230.     As a result playing songs with many channels on slow machines would result
  231.     in grabbing 100% of the CPU, you would never have the control back and be
  232.     forced to reset the machine. To prevent this the player is timing the mixing
  233.     routines and when it detects that it's taking more time to fill the sound
  234.     DMA buffers than the duration they represent, the note polyphony is
  235.     decreased to reduce the processor usage.
  236.  
  237.     When a song requests to play more notes than allowed by the note polyphony,
  238.     the mixing routines will choose to play only the notes with the highest
  239.     volume.
  240.  
  241.     Basically on a ARM 6 machine, with a mixing quality of 24 µs you cannot go
  242.     above a polyphony of 11-12 notes.
  243.  
  244.   * One possible problem is that I use the IOCTimer1 so it may conflict with
  245.     Acorn's TimeCode module and a few others.
  246.  
  247.   * Bangs when starting to play, pausing or stopping a song:
  248.     I have noticed that altering the stereo position of hardware channels tends
  249.     to produce noises on 8-bit hardware, which often leads to a small bang when
  250.     at song startup I switch from 1 to 2 channels and reconfigure the stereo
  251.     positions. As anyone found a way to avoid it?
  252.  
  253.  
  254. ————————————————————————————————————————————————————————————————————————————————
  255.                                  SWI Interface
  256. ————————————————————————————————————————————————————————————————————————————————
  257.  
  258.   The SWI interface as been partially rewritten (I told you it was still subject
  259.   to change without notice). From version 0.86, changes to the interface are
  260.   done without introducing incompatibilities.
  261.  
  262.   In all the following commands every numbering (patterns, rows, ...) usually
  263.   starts at value 0. The only exceptions are:
  264.  
  265.   1) Samples/instruments where 0 means no sample/instrument, so numbering starts
  266.      with 1.
  267.  
  268.   2) Note values cover 10 octaves and each octave is divided equally
  269.      in 12 semitones. The semitones in increasing order of frequency
  270.      are noted: C  C# D  D# E  F  F# G  G# A  A# B
  271.      The note C of octave 5 (C-5) is the central note i.e. is the
  272.      one which plays the sample at its default frequency and was given
  273.      the number 64. This gives a valid range of 4 (C-0) to 123 (B-9).
  274.    
  275.   Warning: on SWI exit flags are corrupted
  276.  
  277.  
  278. TimPlayer_Version &51380
  279. ————————————————————————
  280.  
  281.     Returns the current version of the player.
  282.  
  283.   On entry
  284.  
  285.     -
  286.  
  287.   On exit
  288.  
  289.     R0 = version * 100
  290.  
  291.  
  292. TimPlayer_Configure &51381
  293. ——————————————————————————
  294.  
  295.     Reads or alters the player's configuration.
  296.  
  297.   On entry
  298.   
  299.     R0 = configuration code
  300.     R1 = configuration value
  301.  
  302.   On exit
  303.   
  304.     R1 = current configuration value
  305.  
  306.   Use
  307.   
  308.     * Mixer configuration codes:
  309.     0 - R1 = mixing quality in µs [24, 32, 40, 48, 46, 64, 72], -1 to read
  310.     1 - R1 = interpolation, 0 off, 1 linear, -1 read
  311.     2 - R1 = balance [left 0, right 255], -1 to read
  312.     3 - R1 = stereo separation [-1024,1024], 256 is normal, 1<<31 to read
  313.     4 - R1 = force usage of the 8-bit sound system, 0 off, 1 on, -1 read
  314.              (not for normal use, provided mainly for tests)
  315.  
  316.     * Tracker configuration codes:
  317.     256 - R1 = volume ramping, 0 off, 1 on, -1 read
  318.     257 - R1 = ignore loops in last pattern, 0 off, 1 on, -1 read
  319.     258 - R1 = ignore end of sequence markers, 0 off, 1 on, -1 read
  320.  
  321.  
  322. TimPlayer_SongLoad &51382
  323. —————————————————————————
  324.  
  325.     Loads a soundtrack file in memory, sets the playback position to the start
  326.     of first pattern in the sequence and returns an logical handle for the song.
  327.     
  328.   On entry
  329.  
  330.     R1 = filename pointer
  331.  
  332.   On exit
  333.   
  334.     R0 = song handle
  335.  
  336.   Use
  337.   
  338.     Up to now the player only supports one loaded song at a time and replaces
  339.     any previously loaded song in memory by the new one. However this behaviour
  340.     may change in the future and you should always use TimPlayer_SongUnload
  341.     to remove a song from memory instead of expecting TimPlayer_SongLoad to
  342.     do it for you.
  343.  
  344.   Related SWIs
  345.  
  346.     TimPlayer_SongUnload
  347.  
  348.  
  349. TimPlayer_SongUnload &51383
  350. ———————————————————————————
  351.  
  352.     Removes a song from memory.
  353.  
  354.   On entry
  355.  
  356.     R0 = song handle
  357.  
  358.   On exit
  359.  
  360.     -
  361.  
  362.   Related SWIs
  363.  
  364.     TimPlayer_SongLoad
  365.  
  366.  
  367.  
  368.  
  369. TimPlayer_SongPlay &51388
  370. —————————————————————————
  371.  
  372.     Resumes the playback from the current playback position.
  373.  
  374.   On entry
  375.   
  376.     R0 = song handle
  377.  
  378.   On exit
  379.   
  380.     -
  381.  
  382.   Related SWIs
  383.  
  384.     TimPlayer_SongPause, TimPlayer_SongStop
  385.  
  386.  
  387. TimPlayer_SongPause &51389
  388. ——————————————————————————
  389.  
  390.     Pauses the playback of the song.
  391.  
  392.   On entry
  393.  
  394.     R0 = song handle
  395.  
  396.   On exit
  397.  
  398.     -
  399.  
  400.   Related SWIs
  401.  
  402.     TimPlayer_SongPlay, TimPlayer_SongStop
  403.  
  404.  
  405. TimPlayer_SongStop &5138A
  406. —————————————————————————
  407.  
  408.     Stops the playback of the song, reset all global and channel parameters
  409.     and sets the playback position to the start of the first pattern in the
  410.     sequence.
  411.  
  412.   On entry
  413.  
  414.     R0 = song handle
  415.  
  416.   On exit
  417.  
  418.     -
  419.  
  420.   Related SWIs
  421.  
  422.     TimPlayer_SongPlay, TimPlayer_SongPause
  423.  
  424.  
  425. TimPlayer_SongPosition &5138B
  426. —————————————————————————————
  427.  
  428.     Reads or alter the playback position of the song.
  429.  
  430.   On entry
  431.  
  432.     R0 = song handle
  433.     R1 = new position in the sequence [0, nr of orders[, -1 to read
  434.  
  435.   On exit
  436.  
  437.     R1 = current position in the sequence [0, nr of orders[
  438.     R2 = current row in pattern [0, pattern length[
  439.     R3 = current pattern [0, nr of patterns[
  440.     R4 = number of rows in the current pattern [0, 255]
  441.     R5 = time index (in ms)
  442.  
  443.  
  444. TimPlayer_SongVolume &5138C
  445. ———————————————————————————
  446.  
  447.     Reads or alter the volume level of the song.
  448.  
  449.   On entry
  450.  
  451.     R0 = song handle
  452.     R1 = new volume [0, 256], -1 to read
  453.  
  454.   On exit
  455.  
  456.     R1 = current volume [0, 256]
  457.  
  458.  
  459.  
  460.  
  461.  
  462. TimPlayer_SongInfo &51390
  463. —————————————————————————
  464.  
  465.     Provides general information on the song.
  466.  
  467.   On entry
  468.  
  469.     R0 = song handle
  470.  
  471.   On exit
  472.  
  473.     R1 = number of channels [0, 64]
  474.     R2 = number of orders in sequence [0, ]
  475.     R3 = pointer to sequence table (4 bytes values)
  476.     R4 = number of patterns [0, ]
  477.     R5 = number of instruments [0, 255]
  478.     R6 = number of samples [0, 255]
  479.     R7 = flags
  480.            song_flag_linear        * &00000001
  481.            song_flag_instruments   * &00000002
  482.  
  483.  
  484. TimPlayer_SongTexts &51391
  485. ——————————————————————————
  486.  
  487.   Provides general textual information on the song.
  488.  
  489.   On entry
  490.  
  491.     R0 = song handle
  492.  
  493.   On exit
  494.  
  495.     R1 = song title, pointer to a 0 terminated string.
  496.     R2 = song author, pointer to a 0 terminated string.
  497.     R3 = song type, pointer to a 0 terminated string.
  498.     R4 = length of the song comments.
  499.     R5 = song comments, pointer to a sequence of control terminated lines.
  500.  
  501.  
  502. TimPlayer_SongInitialSettings &51392
  503. ————————————————————————————————————
  504.  
  505.     Provides the initial settings of the song's general parameters.
  506.  
  507.   On entry
  508.  
  509.     R0 = song handle
  510.  
  511.   On exit
  512.  
  513.     R1 = initial speed [1, 31]
  514.     R2 = initial tempo [32, 255]
  515.     R3 = initial global volume [0, 256]
  516.          Do not confuse it with the volume set with TimPlayer_SongVolume!
  517.     R4 = restart position [0, nr of orders[
  518.  
  519.  
  520. TimPlayer_ChannelInitialSettings &51393
  521. ———————————————————————————————————————
  522.  
  523.     Provides the initial settings of a song channel.
  524.  
  525.   On entry
  526.  
  527.     R0 = song handle
  528.     R1 = channel number [0, nr of channels[
  529.  
  530.   On exit
  531.  
  532.     R2 = volume [0, 256]
  533.     R3 = panning [0, 255], 256 is surround
  534.  
  535.  
  536. TimPlayer_SongPlayInfo &51394
  537. —————————————————————————————
  538.  
  539.   On entry
  540.  
  541.     R0 = song handle
  542.  
  543.   On exit
  544.  
  545.     R1 = min pitch (defined once and for all by the soundtrack type)
  546.     R2 = max pitch (defined once and for all by the soundtrack type)
  547.     R3 = corrupted
  548.     R4 = Time Length (in ms)
  549.     R5 = Current max nr of playing channels seen.
  550.          This can be greater than nr of channels for ITs using
  551.          instruments with New Note Action != 'note cut'.
  552.  
  553.  
  554.  
  555.  
  556.  
  557. TimPlayer_SampleInfo &513A0
  558. ———————————————————————————
  559.  
  560.     Reads a sample's general information.
  561.  
  562.   On entry
  563.  
  564.     R0 = song handle
  565.     R1 = sample nr [1, nr of samples]
  566.  
  567.   On exit
  568.  
  569.     R2 = sample size (in values, not bytes)
  570.     R3 = sample data pointer
  571.     R4 = sample flags
  572.            smp_type_unsigned       * &00000001 (converted to signed on loading)
  573.            smp_type_stereo         * &00000002 (not supported)
  574.            smp_type_16bit          * &00000004
  575.            smp_type_loop           * &00000008
  576.            smp_type_loop_bidi      * &00000010
  577.            smp_type_sustain        * &00000020
  578.            smp_type_sustain_bidi   * &00000040
  579.            smp_type_set_panning    * &00000080
  580.            smp_type_surround       * &00000100
  581.     R5 = sample name, pointer to 0 terminated string
  582.     R6 = sample filename, pointer to 0 terminated string
  583.  
  584.  
  585. TimPlayer_SampleMisc &513A1
  586. ———————————————————————————
  587.  
  588.     Reads various parameters of a sample.
  589.  
  590.   On entry
  591.  
  592.     R0 = song handle
  593.     R1 = sample nr [1, nr of samples]
  594.  
  595.   On exit
  596.  
  597.     R2 = sample default volume [0, 256]
  598.     R3 = sample scale volume [0, 256]
  599.     R4 = sample panning [0, 255]
  600.            used only if smp_type_set_panning is on
  601.            and smp_type surround is off
  602.     R5 = sample frequency (Hz)
  603.     R6 = sample finetune
  604.     R7 = sample relative tone (in semitones)
  605.  
  606.  
  607. TimPlayer_SampleLoops &513A2
  608. ————————————————————————————
  609.  
  610.    Reads a sample's looping information.
  611.  
  612.   On entry
  613.  
  614.     R0 = song handle
  615.     R1 = sample nr [1, nr of samples]
  616.  
  617.   On exit
  618.  
  619.     R2 = sample loop start
  620.     R3 = sample loop end
  621.     R4 = sample sustain loop start
  622.     R5 = sample sustain loop end
  623.  
  624.     The values returned are logical offset from the start of the sample.
  625.  
  626.  
  627. TimPlayer_SampleVibrato &513A3
  628. ——————————————————————————————
  629.  
  630.     Reads a sample's auto-vibrato parameters.
  631.  
  632.   On entry
  633.  
  634.     R0 = song handle
  635.     R1 = sample nr [1, nr of samples]
  636.  
  637.   On exit
  638.  
  639.     R2 = sample vibrato type
  640.            cmd_vibrato_type_sin         * &0
  641.            cmd_vibrato_type_square      * &1
  642.            cmd_vibrato_type_rampdown    * &2
  643.            cmd_vibrato_type_rampup      * &3
  644.            cmd_vibrato_type_random      * &4
  645.     R3 = sample vibrato depth [0, 255]
  646.     R4 = sample vibrato speed [0, 255]
  647.     R5 = sample vibrato rate  [0, 255]
  648.  
  649.  
  650.  
  651.  
  652.  
  653. TimPlayer_InstInfo &513A8
  654. —————————————————————————
  655.  
  656.     Reads an instrument's general information.
  657.  
  658.   On entry
  659.  
  660.     R0 = song handle
  661.     R1 = instrument nr [1, nr of instruments]
  662.  
  663.   On exit
  664.  
  665.     R2 = name, pointer to 0 terminated string
  666.     R3 = filename, pointer to 0 terminated string
  667.     R4 = note mapping table 128 byte pairs (note, sample nr)
  668.     R5 = flags
  669.            inst_flag_set_panning   * &1
  670.            inst_flag_surround      * &2
  671.     R6 = New note action
  672.            note_action_cut      * 0
  673.            note_action_off      * 1
  674.            note_action_fade     * 2
  675.            note_action_continue * 3
  676.     R7 = Duplicate check type
  677.            inst_DCT_off         * 0
  678.            inst_DCT_note        * 1
  679.            inst_DCT_sample      * 2
  680.            inst_DCT_instrument  * 3
  681.     R8 = Duplicate note action
  682.            see R4
  683.  
  684.  
  685. TimPlayer_InstVolume &513A9
  686. ———————————————————————————
  687.  
  688.     Reads an instrument's volume information.
  689.  
  690.   On entry
  691.  
  692.     R0 = song handle
  693.     R1 = instrument nr [1, nr of instruments]
  694.  
  695.   On exit
  696.  
  697.     R2 = scale volume [0, 256]
  698.     R3 = fadeout volume [0, 65536]
  699.     R4 = swing
  700.  
  701.  
  702. TimPlayer_InstPanning &513AA
  703. ————————————————————————————
  704.  
  705.     Reads an instrument's panning information.
  706.  
  707.   On entry
  708.  
  709.     R0 = song handle
  710.     R1 = instrument nr [1, nr of instruments]
  711.  
  712.   On exit
  713.  
  714.     R2 = panning [0, 255]
  715.     R3 = swing
  716.     R4 = pitch-pan separation [0, 128]
  717.     R5 = pitch-pan central note [4 (C-0), 123 (B-9)]
  718.  
  719.  
  720. TimPlayer_InstVolumeEnvelope &513AC
  721. ———————————————————————————————————
  722.  
  723.     Reads an instrument's volume envelope.
  724.  
  725.   On entry
  726.  
  727.     R0 = song handle
  728.     R1 = instrument nr [1, nr of instruments]
  729.  
  730.   On exit
  731.  
  732.     R2 = nr of points
  733.     R3 = pointer to table of 2bytes pairs (frame nr, volume)
  734.     R4 = flags
  735.            envelope_flag_on        * 1
  736.            envelope_flag_sustain   * 2
  737.            envelope_flag_loop      * 4
  738.     R5 = loop start point
  739.     R6 = loop end point
  740.     R7 = sustain start point
  741.     R8 = sustain end point
  742.  
  743.   Use
  744.  
  745.     The volume envelope modulates the instrument's volume in the frames that
  746.     follows the start of a note. It is described graphically as a sequence
  747.     of lines segments from one point to the following. Volume values are in
  748.     range [0, 256] and values for frames between points are calculated by using
  749.     linear interpolation.
  750.  
  751.  
  752. TimPlayer_InstPanningEnvelope &513AD
  753. ————————————————————————————————————
  754.  
  755.     Reads an instrument's panning envelope.
  756.  
  757.   On entry
  758.  
  759.     R0 = song handle
  760.     R1 = instrument nr [1, nr of instruments]
  761.  
  762.   On exit
  763.  
  764.     R2 = nr of points
  765.     R3 = pointer to table of 2bytes pairs (frame nr, panning)
  766.     R4 = flags
  767.            envelope_flag_on        * 1
  768.            envelope_flag_sustain   * 2
  769.            envelope_flag_loop      * 4
  770.     R5 = loop start point
  771.     R6 = loop end point
  772.     R7 = sustain start point
  773.     R8 = sustain end point
  774.  
  775.   Use
  776.  
  777.     The panning envelope modulates the instrument's panning in the frames that
  778.     follows the start of a note. It is described graphically as a sequence
  779.     of lines segments from one point to the following. Panning values are in
  780.     range [0, 255] and values for frames between points are calculated by using
  781.     linear interpolation. Values are then applied using the following formula:
  782.  
  783.     panning = panning + (128 - abs(panning - 128)) * (envelope value - 128)/128
  784.  
  785.     which means that the variation is not applied at full scale but is
  786.     proportional to the distance between the note's panning and the nearest
  787.     extremity (left or right).
  788.  
  789.  
  790. TimPlayer_InstPitchEnvelope &513AE
  791. ——————————————————————————————————
  792.  
  793.     Reads an instrument's pitch envelope.
  794.  
  795.   On entry
  796.  
  797.     R0 = song handle
  798.     R1 = instrument nr [1, nr of instruments]
  799.  
  800.   On exit
  801.  
  802.     R2 = nr of points
  803.     R3 = pointer to table of 2bytes pairs (frame nr, pitch offset)
  804.     R4 = flags
  805.            envelope_flag_on        * 1
  806.            envelope_flag_sustain   * 2
  807.            envelope_flag_loop      * 4
  808.     R5 = loop start point
  809.     R6 = loop end point
  810.     R7 = sustain start point
  811.     R8 = sustain end point
  812.  
  813.   Use
  814.  
  815.     The pitch envelope modulates the instrument's pitch in the frames that
  816.     follows the start of a note. It is described graphically as a sequence
  817.     of lines segments from one point to the following. Pitch values are in
  818.     range [-64, 64] and values for frames between points are calculated by
  819.     using linear interpolation.
  820.  
  821.  
  822.  
  823.  
  824.  
  825. TimPlayer_SongParams &513B8
  826. ———————————————————————————
  827.  
  828.     Reads the current song global playback parameters.
  829.  
  830.   On entry
  831.  
  832.     R0 = song handle
  833.  
  834.   On exit
  835.  
  836.     R1 = current speed [0, 31]
  837.     R2 = current tempo [32, 255]
  838.     R3 = current global volume [0, 256]
  839.  
  840.  
  841. TimPlayer_ChannelParams &513B9
  842. ——————————————————————————————
  843.  
  844.     Reads a song channel playback parameters.
  845.  
  846.   On entry
  847.  
  848.     R0 = song handle
  849.     R1 = channel nr [0, nr of channels[
  850.     R2 = 16-bit buffer pointer or 0
  851.     R3 = buffer len (bytes)
  852.  
  853.   On exit
  854.  
  855.     R2 = instrument nr (0 if nothing played)
  856.     R3 = pitch in 1/65536 of default pitch (0 if nothing played)
  857.     R4 = if R2 != 0 on input
  858.            buffer peak value [0,&7FFF]
  859.          else
  860.            note volume [0, &10000]
  861.     R5 = if R2 != 0 on input
  862.            buffer mean value [0,&7FFF]
  863.          else
  864.            note volume [0, &10000]
  865.     R6 = panning [0 (left), 255 (right)], 256 for surround
  866.     
  867.  
  868. TimPlayer_VChannelParams &513BA
  869. ———————————————————————————————
  870.  
  871.     Reads a virtual channel playback parameters.
  872.  
  873.   On entry
  874.  
  875.     R0 = song handle
  876.     R1 = vchannel nr
  877.     R2 = 16-bit buffer pointer or 0
  878.     R3 = buffer len (bytes)
  879.  
  880.   On exit
  881.  
  882.     R2 = instrument nr
  883.     R3 = pitch in 1/65536 of default pitch
  884.     R4 = if R2 != 0 on input
  885.            buffer peak value [0,&7FFF]
  886.          else
  887.            note volume [0, &10000]
  888.     R5 = if R2 != 0 on input
  889.            buffer mean value [0,&7FFF]
  890.           else
  891.            note volume [0, &10000]
  892.     R6 = panning [0, 255], 256 for surround
  893.     R7 = channel nr on which the note was started,
  894.          bit 31 is also set if it is a 'past note'
  895.          -1 if not playing
  896.  
  897.  
  898. TimPlayer_ChannelStatus &513BB
  899. ——————————————————————————————
  900.  
  901.   On entry
  902.  
  903.     R0 = song handle
  904.     R1 = channel nr [0, nr of channels[
  905.     R2 = actions
  906.            channel described in R1
  907.              bit 0: alter status: 1 yes, 0 no
  908.              bit 1: new status: 1 play, 0 mute
  909.            channels other than the one described in R1
  910.              bit 2: alter status: 1 yes, 0 no
  911.              bit 3: new status: 1 play, 0 mute
  912.  
  913.   On exit
  914.  
  915.     R3 = channel status (1 play, 0 mute)
  916.  
  917.  
  918. ————————————————————————————————————————————————————————————————————————————————
  919.                                     History
  920. ————————————————————————————————————————————————————————————————————————————————
  921.  
  922. 16-04-98 Reset song parameters at restart pos or pos 0
  923. 18-04    IT packed samples decoding is working 8)
  924. 19-04    Inverted effects of linear pitch slide up/down
  925.          Modified Note Off fadeout conditions
  926.          Moved all XM notes one halftone down
  927. 29-04    IT effect V as range 0-128 instead of 0-64!
  928.          Modified Note Off fadeout conditions once again
  929.          Some trials to speed up things on non-SA
  930. 03-05    Incorrect test, never played last defined instrument !!!
  931.          Support of XM command L: set envelope pos
  932. 10-05    IT envelope flags loop and sustain were inverted
  933. 24-05    IT virtual channels
  934. 30-05    support for 1/4 stereo pairs
  935. 05-06    support for 16-bit hardware
  936. 06-06    Bug in IT volume command M.
  937. 08-06    option to disable interpolation
  938.  
  939. Version 0.81
  940. ————————————
  941. 10-06-98 Big bug introduced the 08-06
  942.  
  943. Version 0.82
  944. ————————————
  945. 13-06-98 Corrected arpeggio (1 octave too high)
  946. 15-06    S3M files: pattern parapointer of 0 means empty pattern of 64 rows
  947.          16-bit hardware, stereo was inverted
  948. 16-06    MOD files loading: if byte &3B7 value is not 127
  949.          search highest pattern nr from defined sequence only
  950.          and not the whole 128 bytes
  951.          MOD: Problems of cmd F00 with multiple F on a row
  952.  
  953. Version 0.83
  954. ————————————
  955. 17-06-98 S3M/IT: J00 is repeat last arpeggio
  956. 20-06    IT effect SAy (set sample high offset)
  957.          IT surround: play note as central pan but invert right buffer.
  958.          Another correction for Note Off.
  959. 21-06    Notes which go beyond the maximum allowed pitch must be cut
  960. 27-06    Yet another correction for Envelopes (Grrr).
  961. 01-07    XM: incorrect correction on 19-04, actually there was
  962.              a 1 haltone offset in instrument note mappings
  963.  
  964. Version 0.84
  965. ————————————
  966. 06-07-98 Tone portamento must not be applied on frame 0 for MOD, XM
  967. 07-07    Vibrato must not be applied on frame 0 except for IT with old flags
  968. 09-07    MOD files loading: byte &3B7 is restart pos, value 127
  969.          means not used. Scanning for highest pattern modified as follows:
  970.          nr of patterns = (file size - header - samples) DIV pattern size
  971.          if (nr of pat <= highest pat in seq) nr of pat = highest pat
  972.          if (nr of pat > highest pat of 128 bytes seq) nr of pat = highest pat
  973.          I hope this is now correct because I really start to hate
  974.          that stupid file format.
  975. 11-07    Linear pitch handler could be called after amiga one
  976. 15-07    06-07 change extended to S3M/IT
  977. 17-07    IT global volume slides should be twice finer
  978. 21-07    Envelopes with loops: do not play position of last env. point
  979.          but restart loop (I_can_fly.xm).
  980.  
  981. Version 0.85
  982. ————————————
  983. 05-08-98 Added support for MTMs.
  984. 06-08    Store name and filename of every samples and instruments.
  985. 07-08    Reorganised the SWIs and added a whole new batch of them
  986.          to provide access to every bit of information on the song.
  987. 12-08    Use now dynamic areas for memory management
  988. 18-08    Corrected error in sample autovibrato
  989. 18-08    Corrected error sample sustain loop
  990.  
  991. Version 0.86
  992. ————————————
  993. 23-08-98 Recoded set envelope pos effect which was totally incorrect
  994.          (not sure yet if it's 100% as it should be)
  995. 24-08    Implemented limitation of the number of mixing notes when CPU usage
  996.          gets to high (I use IOCTimer1 so Acorn's TimeCode may not like it).
  997. 30-08    Correction: keep only the latest jump/pattern break on a row
  998.          instead of the latest jump and the latest pattern break
  999. 30-08    Volume ramping option implemented, and instead of jumping from one
  1000.          volume to the other, the player will use a volume ramping at the start
  1001.          of every frame, which will remove some of the pops and clicks
  1002.          in the sound.
  1003. 06-09    Yet another little (but noisy) bug in set envelope pos effect.
  1004. 18-09    Should not try to process envelope when use envelope is set
  1005.          but no envelope is actually defined.
  1006. 25-09    Removed another bug in autovibrato.
  1007. 05-10    Volume ramping extended to fade cut notes.
  1008. 25-10    Read IT volume envelopes for v < 2.00
  1009. 28-10    Added Balance and Stereo Separation.
  1010. 01-11    Removed Precalculated Gain Control which was both time consuming
  1011.          at song loading and inefficient for amplifying songs with a large
  1012.          number of channels. Automatic Gain Control in Modplug style replaces
  1013.          it: pre-amplification according to the number channels and dynamic
  1014.          attenuation when required to avoid clipping.
  1015. 11-11    Added Configuration code 4 to be able to force usage of the 8-bit sound
  1016.          system for 2 reasons:
  1017.          - be able to check 8-bit mode without the need to remove my Mozart card
  1018.            or hacking the module.
  1019.          - prevent someone I know to do the same hack.
  1020.  
  1021. Version 0.87
  1022. ————————————
  1023. 20-11-98 Maximum wave amplitude for Gain Control was not updated on volume
  1024.          changes during playback.
  1025. 27-11    Bug in handling of envelopes which could return values out of range
  1026.          if an instrument is replaced by another one during a tone portamento.
  1027. 02-12    Mixing routines did not work in 16-bit mode on an ARM6.
  1028. 03-12    Dynamic Gain Control muted sound definitely in volume was set to 0
  1029.          then restored.
  1030.  
  1031. Version 0.88
  1032. ————————————
  1033. 18-12-98 Removed infinite loop in corrupted MOD loading.
  1034. 25-12-98 Keep 'end of sequence markers' into account.
  1035.          Implemented Configure codes 257, 258.
  1036. 02-01-99 Yet another correction in autovibrato.
  1037.          In XM, remove as many unused samples as possible to fit in the 255
  1038.          samples limit (cf. "Pools of Poison").
  1039. 03-01-99 Corrected bug in Set Past/New Note Action commands.
  1040. 10-01-99 Recoded some parts so that in the future more than one song may be
  1041.          loaded (or even played at the same time).
  1042. 18-01-99 Split notes and channels in nearly independent entities, virtual
  1043.          channels support is completely rewritten as a consequence.
  1044. 21-01-99 Note related effects are now processed even if no note is playing
  1045.          to ensure effects memory is up to date.
  1046. 12-02-99 Slight bug implementation of 18-01.