This is the documentation for the 68000 asm API for Sona 0.50
To use it in your project, take all the *.68k files in api-asm and copy them
into your source code, then include them where most suitable (make sure that
sonadef.68k comes first).
Quick guide to get you started:
- Call Sona_Init when the program starts
- Call Sona_PlayBgm or Sona_PlaySfxEx to play sound
- Call Sona_StopAllSound if you need silence
NOTE: this is a "prerelease" version of Sona, this documentation does NOT
include anything that isn't ready to use yet (i.e. incomplete stuff). You've
been warned if you read the source code and decide to try using it anyway.
*** Initialization ***
Sona_Init
Call this to initialize the sound driver and hardware. This must be called
before doing anything else with Sona.
Sona_SetStereo
in d0.b -> 0 = mono, otherwise = stereo
Toggles stereo support (enabled by default). When disabled, it forces FM
channels to be mono regardless or panning commands. This is useful to
implement a mono/stereo option in a game.
There are currently some limitations that may be addressed later:
- Doesn't take effect immediately but only whenever a track changes panning
(for tracks that are already playing while this setting is changed)
- It doesn't compensate for the volume difference between panned sound and
mono, so "unpanned" sounds will come out louder.
- It forces output to both speakers regardless of pan setting, even when the
channel should have been muted instead (so don't use pan to mute a channel
from within a track)
Sona_SetSsgEg
in d0.b -> 0 = block SSG-EG, otherwise = allow SSG-EG
Toggles whether SSG-EG is supported or not (enabled by default). Some clones
(especially AtGames clones) have broken SSG-EG support to the point where it
turns into harsh noise, so this gives the option to disable it (which still
won't be correct but at least will be more acceptable).
This setting only takes effect when a FM instrument is loaded (it won't take
effect immediately on tracks that are currently playing). In practice this
shouldn't be an issue as you'd call it before playing any music.
*** Playing music ***
Sona_PlayBgm
in a0.l -> pointer to stream data (*.sona file)
in a1.l -> pointer to instrument list (see below)
in d0.b -> number of instruments
Tells Sona to play background music.
The instrument list is an array of pointers to each instrument used by the
track. Background music can use up to 160 unique instruments. The list looks
as follows (using example names):
InstrumentList:
dc.l PianoFm
dc.l SlapBassFm
dc.l SnareDrumPcm
...
Instruments should be aligned to 32 bytes (use the Sona_PadTo32 macro for
this). Instruments can be shared across tracks, just make sure that their
instrument lists point to the same instruments.
Sona_PadTo32
PianoFm: incbin "piano.spat"
SlapBassFm: incbin "slapbass.spat"
SnareDrumPcm: incbin "snare.swav"
...
Sona_PlaySfxEx
in a0.l -> pointer to stream data
in a1.l -> pointer to instrument list
in d0.b -> number of instruments
in d1.b -> sound effect priority (1..255)
in d2.b -> sound effect ID (0..2)
in d3.b -> (reserved)
in d4.b -> (reserved)
Plays a sound effect.
The first three arguments (a0,a1,d0) are the same as for Sona_PlayBgm. A
sound effect is allowed to use up to 32 instruments.
Priority is used to determine whether a sound effect can override another
one in the same ID, or separate sound effects trying to use the same sound
channel. Higher values will override lower ones. It MUST be between 1 and
255, if you try to pass 0 then Sona will explicitly ignore the sound effect.
Sona can play up to three independent sound effects at the same time, each of
them is assigned an "ID". For multiple sound effects to play they need to be
assigned different IDs, otherwise priority will apply.
d3 and d4 are intended for a feature that's currently incomplete. They can
be safely ignored for now.
Sona_StopAllSound
Stops everything currently playing (music and sound effects).
*** VM variables ***
Sona has the concept of "VM variables" which are 128 bytes worth of data for
use by the tracks. They can be used as a way to communicate between the track
currently playing and the 68000, allowing games to stay in sync with the music.
Sona_GetVariable
in d0.b -> variable ID (0..127)
out d0.b <- current value
Reads the current value of the specified VM variable. This can be used by
the track to report to the 68000 (e.g. to mark when it reached a certain
point so the game can do something in response, etc.).
Sona_SetVariable
in d0.b -> variable ID (0..127)
in d1.b -> new value
Changes the value of the specified VM variable. This can be used by the
68000 to tell the current track to do something (e.g. adjust volume of a
channel depending how far you're, etc.).
IMPORTANT NOTE: the value of a variable may be changed by a track between a
call to Sona_GetVariable and a call to Sona_SetVariable, potentially trashing
away the track's change. Make sure that only one side (track or 68000) can
modify a given variable.
*** Driver state ***
Sona_GetStatus
out d0.w <- Driver status (see below)
Returns a bitfield indicating the current status of the driver. Use the
BTST instruction with the following constants:
SONA_STATUS_BGM Background music is playing
SONA_STATUS_SFX1 Sound effect ID 0 is playing
SONA_STATUS_SFX2 Sound effect ID 1 is playing
SONA_STATUS_SFX3 Sound effect ID 2 is playing
SONA_STATUS_PCM1 1st PCM channel is playing
SONA_STATUS_PCM2 2nd PCM channel is playing
Bits other than the above are *undefined* and may contain garbage.
Do NOT rely on the value of undefined bits for forwards compatibility.
Sona_GetZ80Usage
out d0.b <- Z80 CPU usage
Returns how busy is the Z80, in case you want to know if the current track
is too heavy for the sound driver. Returned value is just for displaying and
not measured in any specific units, higher values mean more free Z80 time.
In extreme cases, it may even overflow and output an extremely low value when
nothing is going on.
*** Other definitions ***
The following stuff is defined in sonadef.68k (meaning it's only available
after it's included) and can be freely used by your program.
Sona_PadTo32 [macro]
Pads to the next 32 byte boundary.
Sona_RequestBus [macro]
Requests the Z80 bus and waits until Z80 is ready.
Sona_ReleaseBus [macro]
Releases the Z80 bus.
Sona_Z80BusReq [label]
Points to $A11100 (Z80 bus request control). Useful during DMA loops in
order to keep the Z80 away with as little overhead as possible.
Sona_Z80Reset [label]
Points to $A11200 (Z80/YM2612 reset control).
Sona_Z80Ram [label]
Points to $A00000 (beginning of Z80 RAM).