Appendix K - DesktopTracker Playmodule SWI list

44b40 - DeskTracker_PlayTune

Plays the tune from the beginning - MUST call DeskTracker_SetMemory and DeskTracker_SetHimem before calling.

44b41 - DeskTracker_SetMemory

On entry:

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.

44b42 - DeskTracker_PlayNote

On entry:

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.

44b43 - DeskTracker_ReadPosition

On exit:

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.

44b44 - DeskTracker_StopTune

IRQs are disabled

Stops the tune, and removes the sound driver.

44b45 - DeskTracker_ReadBars

On exit:

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)

44b46 - DeskTracker_SetVolume

On entry:

R0 = volume (-1 to read)

On exit:

R0 = old volume

Volume is from 0 to 127, with 127 being loud, 0 is "off".

44b47 - DeskTracker_SetClock

On entry:

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:

  1. Standard 24MHz clock (Monitor type 0)
  2. A5000 (3010 etc) and A540 25.175MHz clock (Monitor type 2)
  3. A5000 (3010 etc) and A540 36MHz clock (Monitor type 1)
  4. Auxiliary clock (commanded by bit 5 of latch A - VIDC Enhancer)
  5. Custom clock (commanded by the user)

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.

44b48 - DeskTracker_Control

On entry:

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:

BitMeaning when set
0Search line offset in pattern each time DTT needs it
1Search line offset in pattern next time DTT needs it
2Use Amiga volume
3Show time using colours
4Allow user to change number of voices
5Use Amiga period (Linear portamento)
6Use music length provided by SWI DeskTracker_SetMusicLength
7NOT USED (reserved as 0)
8Sound driver installed (Set on exit)
9Playing sound (Set on exit)
10Playing tune (Set on exit)
11..15NOT USED (reserved as 0)
16..17Clock control (see later)
20..22Clock value (#0 to #4)
23Use custom clock
24Control replay of voices 0 to 3
25Control replay of voices 4 to 7
26Control replay of voices 8 to 11
27Control 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:

  1. simple Archimedes, 24Mhz clock (Monitor type 0)
  2. VIDC+, or old VIDC enhancer (aux. port set to use new crystal)
  3. new VIDC enhancer (aux. port clear to use new crystal)
  4. uses latch C, to allow 25.175MHz and 36MHz crystals (A5000, A3010 etc, 540)
However, it is better to use bits 20-22 to read the clock value, as this corresponds to the DeskTracker_SetClock SWI.
R1 is the voice on/off flags

BitMeaning when set
0Voice 1 on
1Voice 2 on
......
14Voice 15 on
15Voice 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.

44b49 - DeskTracker_Pause

On entry:

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.

44b4a - DeskTracker_PlayPosition

On entry:

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.

44b4b - DeskTracker_TuneUp

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).

44b4c - DeskTracker_SetStereo

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.

44b4d - DeskTracker_SetMusicLength

On entry:

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.

44b4e - DeskTracker_SetHimem

On entry:

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.

44b4f - DeskTracker_GetEventsMemory

On exit:

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.

44b50 - DeskTracker_GetEventsLink

On exit :

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:

WordsDescription
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.
1Link to next routine, 0 if none (set it to 0 to start off with)
1EQUS "Link" - string.

.MyRoutine%
    x    Code

To 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

44b51 - DeskTracker_GetTiming

On exit:

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.

44b52 - DeskTracker_SetTempo

On entry:

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.

*Commands :

There is only 1 command -

*DTColours toggles control bit 3, so you can turn the colours on and off.

Wimp messages :

44b40 - DeskTracker_LosePlayer

If you receive this message, then it means that you have lost control of the player; another application is playing. There is nothing you can do about this. There is no data.

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

44b41 - DeskTracker_LosePlayerTimed

It tells you what tempo you were playing at, and the fact that you don't have control of the DeskTracker module. The method of transmission is similar:

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.

Other remarks:

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:

  1. Disable IRQs, and set bit 1 of the control register, or
  2. Set bit 0 of the control register, add or remove words, and then set bit 1 and clear bit 0 of the control register.

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.