R0 = Tune address (or -1 to read the three values)
R1 = Pointer offset value
R2 = Task handle (or 0 if single tasking)
On exit:
R0 = Tune address
R1 = Pointer offset value
R2 = Task handle
IRQs are disabled
The Task handle is the handle of the application which owns the tune. You do not have to be this application. If you are multi-tasking, then a WIMP message must be sent, to tell the old task that you now have control. See later for details.
If the tune is playing, then this call will reset the addresses of the samples playing.
The Pointer offset value is the value to add to all the pointers in the tune. If you have just loaded the tune, with the pointers referring to file locations, then set R1=R0. If you have set up all the pointers yourself, then set R1=0.
R0 = sample (0=no new sample)
R1 = note (0=no new note, 1-36=note number, with C1 = 1)
R2 = voice (0 to 'Number of voices'-1), bit 31 clear
If bit 31 of R2 is set, then the registers have the following meaning:
R0 = sample (bits 0..5), note (bits 6..11), effect #0 (12..16),
effect #1 (17..20), effect #2 (22..26), effect #3 (27..31)
R1 = data #0 (0..7), data #1 (8..15), data #2 (16..23), data #3 (24..31)
R2 = voice, bit 31 set
IRQs are disabled
This plays any sample, at any note in any voice. If the sound driver is not installed, this SWI will install it.
R0 = current line number
R1 = current position
R2 = offset of line in current pattern
IRQs are disabled
If a pattern is looped (Pattern mode in DTT), bit 31 of R1 is set, and bits 0..7 hold the current pattern number.
Stops the tune, and removes the sound driver.
R0 points to note bars (36 bytes)
R1 points to voice bars (16 bytes)
These are in RMA space, and only change if the module's workspace is relocated (*RMTidy)
R0 = volume (-1 to read)
On exit:
R0 = old volume
Volume is from 0 to 127, with 127 being loud, 0 is "off".
R0 = clock number (1-5)
R1 = VIDC DMA period (-1 to read)
R2 = clock frequency (-1 to read)
On exit:
R0 preserved
R1 = previous DMA
R2 = previous clock
IRQs are disabled
This SWI allows you to set the period of the DMA for each VIDC clock. The clock numbers are:
The VIDC DMA is in µs, and the clock frequency is the value in MHz, multiplied by 2^24, so a 30MHz clock is set by using the value 30*2^24, or &1E000000. The frequency for clock 1 cannot be set.
If you are using a custom clock, you must tell the module by setting bit 23 of the control register in the SWI DeskTracker_Control.
R0 = new control register (-1 to read)
R1 = voices on/off (-1 to read)
R2 = number of voices (-1 to read)
R3 = maximum bar height (-1 to read)
On exit:
R0 = previous control register
R1 = previous voices on/off
R2 = previous number of voices
R3 = previous bar height
The control register is:
| Bit | Meaning when set |
| 0 | Search line offset in pattern each time DTT needs it |
| 1 | Search line offset in pattern next time DTT needs it |
| 2 | Use Amiga volume |
| 3 | Show time using colours |
| 4 | Allow user to change number of voices |
| 5 | Use Amiga period (Linear portamento) |
| 6 | Use music length provided by SWI DeskTracker_SetMusicLength |
| 7 | NOT USED (reserved as 0) |
| 8 | Sound driver installed (Set on exit) |
| 9 | Playing sound (Set on exit) |
| 10 | Playing tune (Set on exit) |
| 11..15 | NOT USED (reserved as 0) |
| 16..17 | Clock control (see later) |
| 20..22 | Clock value (#0 to #4) |
| 23 | Use custom clock |
| 24 | Control replay of voices 0 to 3 |
| 25 | Control replay of voices 4 to 7 |
| 26 | Control replay of voices 8 to 11 |
| 27 | Control replay of voices 12 to 16 |
If a bit 24 to 27 is set, then DeskTracker will play any note on the channels, without volume and pitch control. The replay rate is the same as the sample rate. This allows, for example, a 4 track tune, with another 4 voices dedicated to sound effects (useful in games, demos...)
For speed test purposes, DeskTracker can display the time used as a colour on the screen. It uses logical colour 0, and if it is red, DeskTracker is remapping VIDC, and calculating pitch. If it is yellow, then it is filling the sound buffer. Otherwise it is white.
The clock control is as follows:
| Bit | Meaning when set |
| 0 | Voice 1 on |
| 1 | Voice 2 on |
| ... | ... |
| 14 | Voice 15 on |
| 15 | Voice 16 on |
The number of voices can be set, if bit 4 is set. This immediately changes the number of voices, provided it is greater or equal to the number of voices in the current tune. You can set it to 4, 8, 12 or 16 voices. The tune "width" remains at the number of voices in the tune; the other voices can be used for sound FX, or more music.
The maximum bar height is used in the SWI DeskTracker_ReadBars. When a note is played, its corresponding bar is set to the maximum height.
R0 = 0 to pause the tune
R1 = -1 to continue
On exit:
R0 = 0 if tune is playing (was paused)
R1 = -1 if tune is paused (was playing)
This allows you to pause or continue the tune. The exit is defined, so that you can easily use a procedure to swap the state, for example:
DEFPROCswap SYS "XDeskTracker_Pause",pause% TO pause% ENDPROC
If pause% is -1, then the tune is paused.
R0 = position (from 0 to "music length"-1), bit 31 clear
pattern number, bit 31 set
If bit 31 is clear, the tune plays from the specified position, at the current tempo, unless the position is 0, when it plays at the initial tempo. If it is clear, the tune is looped at the specified pattern number. This is like "Pattern mode" in Desktop Tracker.
On entry:
R0 = tuning factor, multiplied by 2^24 (normal = 1, or &01000000)
On exit:
R0 = old factor
This allows the tuning of the samples. To increase the pitch by 1 tone, use
SYS "DeskTracker_TuneUp",2^(1/6)*(1<<24)
To accept fine precision, the tuning is done by the difference between 1, so the value is coded (tuning-1), if tuning is greater than 1, or (1-tuning), if tuning is less than 1.
Tuning factor is from 0 to 2 (infinitely lower, to 1 octave higher).
On entry:
R0 = voice number (from 0 to 'number of voices'-1)
R1 = stereo position (1-7), or -1 to read
On exit:
R0 preserved
R1 = old stereo position
This SWI allows you to set the stereo position of the voices. Note that in 9 to 12 voices, voices 0,4,8 have the same stereo position; 1,5,9 also have the same stereo position, as do 2,6,10 and 3,7,11. In 13 to 16 voices, voice pairs (0,8), (1,9), (2,10), and up to (7,15) have the same stereo position.
R0 = new music length, or -1 to read
On exit:
R0 = old music length
This SWI allows the music length to be explicitly defined. In Desktop Tracker, the music length in the tune header is defined to be 4096, while the actual music length is set using this command. Bit 6 in the control register must be set in order to use this SWI.
WARNING - This MUST be numerically equal to the length of the position array.
R0 = new himem, or -1 to read
On exit:
R1 = current himem
This SWI allows you to set the top of memory. It MUST be called before calling DeskTracker_SetMemory. It can be set as the pointer to the end of the module. In an editor, such as Desktop Tracker, this call must be issued every time a Wimp_Slot is called.
R0 = pointer to 16 bytes
This SWI can be used to read the address of the event &1Fxy. When this instruction is reached in a tune, the address R0+x is set to the nibble y.
For example:
R0 is &1832410. The tune reaches effect &1F2B. The address &1832412 is set to &0B.
The main aim of this is to allow light patterns to be defined in the music. With a suitable piece of hardware, and software, the lights will flash in time with the music! It can be put to your own use, however.
R0 = pointer to the first routine
When an event &1Fxy is called, a chain of machine code routines can be called. This means you do not have to set up an interrupt routine to monitor all the addresses; you can just set up the code, and DeskTracker will call it when event &1F occurs. You can then do with it what you wish.
To link a piece of code, first set up the following block:
| Words | Description |
| 2 | "Application" name. This needs to be allocated from Leading Edge, if you want to use it in a commercial program, otherwise the string ”User????•, where ”????• is your initials can be used. |
| 1 | Link to next routine, 0 if none (set it to 0 to start off with) |
| 1 | EQUS "Link" - string. |
.MyRoutine%
x CodeTo add a routine use:
SYS "DeskTracker_GetEventsLink" TO Ptr% WHILE Ptr%!-8<>0 Ptr%=Ptr%!-8 ENDWHILE Ptr%!-8=MyRoutine%
To remove the routine, use:
SYS "DeskTracker_GetEventsLink" TO Ptr% WHILE Ptr%!-8<>MyRoutine% Ptr%=Ptr%!-8 ENDWHILE Ptr%!-8=MyRoutine%!-8
The routine must be in RMA if you are multitasking, otherwise it does not matter.
On entry (to routine):
R0 = pointer to music module (unmapped)
R1 = reserved
R2 = data byte of the effect (ie. &xy)
R3 = pointer to 16 "addresses"
R13 = FD stack
R14 = return link register
To return, use the following:
LDR R4,MyRoutine%-8 MOVEQ PC,R14 MOVNE PC,R4
Warning : Do NOT use MOVS PC,R14
R0 = percentage of time used by the last 16 interrupts
R1 = percentage of time used by the last interrupt
This allows you to measure the performance of the module. The percentage is from 0 (0%) to &7FFFFFFF (100%). The module reads the 100Hz clock, and timer 0 to calculate the time used. The resulting percentage is the bandwidth of the processor left, so it is dependant on which mode you are in.
R0 = speed value (or -1 to read)
R1 = fine tempo value (or -1 to read)
On exit:
R0 = speed
R1 = fine tempo
This allows you to set the tempo explicitly. It is used in Desktop Tracker to return the tempo to the old speed after another application has used the module to play tunes.
*DTColours toggles control bit 3, so you can turn the colours on and off.
To tell another task that it has lost control, use the following, BEFORE calling DeskTracker_SetMemory:
SYS "DeskTracker_SetMemory",-1 TO ,,OldTask% IF OldTask%<>MyTask% THEN !Message%=20 : REM message% is DIMmed memory Message%!4=MyTask% Message%!8=0 Message%!12=0 Message%!16=&44b40 : REM DeskTracker_LosePlayer SYS "Wimp_SendMessage",16,Message%,OldTask% ENDIF
SYS "DeskTracker_SetMemory",-1 TO ,,OldTask% IF OldTask%<>MyTask% THEN SYS "DeskTracker_SetTempo",-1,-1 TO OldTempo%,OldFineTempo% !Message%=28 : REM Message% is DIMmed memory Message%!4=MyTask% Message%!8=0 Message%!12=0 Message%!16=&44b41 : REM DeskTracker_LosePlayerTimed Message%!20=OldTempo% Message%!24=OldFineTempo% SYS "Wimp_SendMessage",16,Message%,OldTask% ENDIF
More WIMP notes :
When you want to regain the DeskTracker player, as well as telling other tasks that you've got it, you must reset all the control registers you were using, such as voice on/off, stereo positions, number of voices and music length. The corresponding flags in the DeskTracker module must also be set/cleared. Also the tempo must be restored to the old values. Desktop Tracker will tell your application what tempo it was playing at, by using the DeskTracker_LosePlayerTimed message. If you receive that, then you can read the tempo from the message block:
MyTempo%=Message%!20
MyFineTempo%=Message%!24
If you receive a DeskTracker_LosePlayer, you will not know what the tempo is/was. DO NOT ATTEMPT TO READ IT YOURSELF - a tune may already be playing.
When you want to regain control, set the tempo by using:
SYS "DeskTracker_SetTempo",MyTempo%,MyFineTempo%
!DTTSounds sends the DeskTracker_LosePlayer, because the tempo is not changed in this application.
DMA Period - Period*Number of voices must be less that 256. There is no check for it, so be careful.
Changing music data -
If you want to add or remove words in a pattern:
If you want to change words in the sample info (including sample pointer) :
Disable IRQ, call DeskTracker_SetMemory, and enable IRQ
If you want to change a position in the sequence:
Disable IRQ, read position. If this is not the current playing position, set new position and enable IRQ. Otherwise, stop tune, set the new position, release IRQ, and play from new position, using DeskTracker_PlayPosition.
If you want to increase the number of samples, you can do it at any time.
If you want to decrease the number of samples :
Disable IRQ, change the number of samples, call DeskTracker_SetMemory and release IRQs.
If you want to change the number of patterns :
Disable IRQs. Read position, then the pattern playing. If the pattern is outside the new number of patterns, stop the tune. Change the number of patterns (and the various arrays). Call DeskTracker_SetMemory (and SetHimem?), and restart tune if wanted. Release IRQs.
If you want to change anything else, you can do so at any time.