-
Notifications
You must be signed in to change notification settings - Fork 2
/
ptplayer.readme
181 lines (140 loc) · 7.27 KB
/
ptplayer.readme
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
Short: ProTracker 2.3B replayer with support for external sound fx
Author: Frank Wille
Uploader: [email protected]
Type: mus/play
Version: 5.0
Requires: Assembler
Achitecture: m68k-amigaos
While developing the games Sqrxz and Solid Gold I needed a Protracker
player which can insert sound effects from the game into the current song.
I ended up in writing a completely new player based on the original
replayer source which came with ProTracker 2.3.
This player is quite optimized and has some useful features for game
developers:
- Insert external sound effects into the replayed module.
- Can also play sound effects while music is stopped or not even initialized.
- A fast master volume for the replayed music.
- No busy waiting. DMA and repeat pointers are set with timer interrupts.
- E8 command can be used as a trigger for your main program.
- Lots of tables for best performance. No multiplications or divisions.
The sound fx system gives you the possibility to play samples on a channel
of your choice or on the channel which the player thinks is the best one.
It may be a channel which is currently not replaying music and/or has
the longest period of silence ahead. This has the effect that the replayed
song is often not disturbed at all.
Up to four sound effects can be played at the same time and any of them
has its own priority, which is especially useful when trying to play
several sounds on the same channel. You may for example define that a
shooting-sound has a higher priority than a jumping-sound.
For automatic channel selection you can additionally reserve specific
channels for music only, or define the maximum number of channels which
may be used for sound effects at once.
The master volume is always applied to the music, but does not affect
external sound effects at all.
Selecting the data model:
ptplayer.asm can be configured to support two data models:
1. By default ptplayer.asm assembles into a single code section. The
interface functions set up a local base register to access data.
This requires a working RS directive, which is provided by many
assemblers, like e.g. vasm, PhxAss, Devpac, Basm, AsmOne, SNMA.
2. By defining the SDATA symbol ptplayer.asm assembles into a code
section and a small-data section (called __MERGED). All interface
functions require that the base register A4 is set up with the
small-data base pointer (provided by the linker through _LinkerDB).
It uses the NEAR directive, which might work with vasm and PhxAss only.
Exported functions:
(CUSTOM is the custom-chip register set base address $dff000.)
_mt_install_cia(a6=CUSTOM, a0=AutoVecBase, d0=PALflag.b)
Install a CIA-B interrupt for calling _mt_music or mt_sfxonly.
The music module is replayed via _mt_music when _mt_Enable is non-zero.
Otherwise the interrupt handler calls mt_sfxonly to play sound
effects only.
_mt_remove_cia(a6=CUSTOM)
Remove the CIA-B music interrupt and restore the old vector.
_mt_init(a6=CUSTOM, a0=TrackerModule, a1=Samples|NULL, d0=InitialSongPos.b)
Initialize a new module.
Reset speed to 6, tempo to 125 and start at the given position.
Master volume is at 64 (maximum).
When a1 is NULL the samples are assumed to be stored after the patterns.
_mt_end(a6=CUSTOM)
Stop playing current module.
_mt_soundfx(a6=CUSTOM, a0=SamplePointer,
d0=SampleLength.w, d1=SamplePeriod.w, d2=SampleVolume.w)
Request playing of an external sound effect on the most unused channel.
This function is for compatibility with the old API only!
You should call _mt_playfx instead.
_mt_playfx(a6=CUSTOM, a0=SfxStructurePointer)
Request playing of a prioritized external sound effect, either on a
fixed channel or on the most unused one.
Structure layout of SfxStructure:
APTR sfx_ptr (pointer to sample start in Chip RAM, even address)
WORD sfx_len (sample length in words)
WORD sfx_per (hardware replay period for sample)
WORD sfx_vol (volume 0..64, is unaffected by the song's master volume)
BYTE sfx_cha (0..3 selected replay channel, -1 selects best channel)
BYTE sfx_pri (unsigned priority, must be non-zero)
When multiple samples are assigned to the same channel the lower
priority sample will be replaced. When priorities are the same, then
the older sample is replaced.
The chosen channel is blocked for music until the effect has
completely been replayed.
_mt_musicmask(a6=CUSTOM, d0=ChannelMask.b)
Set bits in the mask define which specific channels are reserved
for music only. Set bit 0 for channel 0, ..., bit 3 for channel 3.
When calling _mt_soundfx or _mt_playfx with automatic channel selection
(sfx_cha=-1) then these masked channels will never be picked.
The mask defaults to 0.
_mt_mastervol(a6=CUSTOM, d0=MasterVolume.w)
Set a master volume from 0 to 64 for all music channels.
Note that the master volume does not affect the volume of external
sound effects (which is desired).
_mt_music(a6=CUSTOM)
The replayer routine. Is called automatically after mt_install_cia().
Exported byte-sized variables:
_mt_Enable
Set this byte to non-zero to play music, zero to pause playing.
Note that you can still play sound effects, while music is stopped.
_mt_E8Trigger
This byte reflects the value of the last E8 command.
It is reset to 0 after mt_init().
_mt_MusicChannels
This byte defines the number of channels which should be dedicated
for playing music. So sound effects will never use more
than 4 - _mt_MusicChannels channels at once. Defaults to 0.
History:
3.0:
- Try not to break channels with sound effects, which are currently
playing a looped sample.
- Sound effects can also be started when the music is not playing
(mt_Enable=0).
3.1:
- Do not trash d2/a2 in mt_init().
- Unused samples with length 0 are played like a 1-word null-sample,
for compatibility with other players.
- Make sure all samples start with two zero-bytes.
4.0:
- For better maintenance there is only a single source text now. The
default is a PC-relative, single-section version, which uses a local
base register. Small data mode can be enabled by defining SDATA.
- mt_install_cia() also initializes the channel structures, like mt_init()
does. So it should be possible to play sound effects without loading
a tracker module.
- New sound effects system, which truly supports playing multiple sound
effects per frame (e.g. stereo). It also supports priorities and
channel selection.
- New exported function mt_playfx() which passes a pointer to an sfx
structure, includes the new parameters like channel and priority.
The old API through mt_soundfx() is still supported and emulated by
mt_playfx().
- New exported function mt_musicmask() defines which specific channels
are dedicated for music and won't be used for sound effects.
- New exported variable mt_MusicChannels defines a limit for the
maximum number of channels to be used for sound effects in parallel.
5.0:
- Only few assemblers support the BASEREG directive, so I decided
to rework the code and make it more portable. This version is tested
with Devpac, vasm, PhxAss, Barfly-Asm, SNMA, AsmOne, AsmPro.
- All exported symbols (functions and variables) have got a leading
underscore now, to make them directly accessible to C programs.
So in assembler you have to call _mt_init now, while in C you can
call mt_init().