Difference between revisions of "BIOS Sound Functions"

Revision as of 01:20, 22 April 2021

Output to Sound Queue

 BCAA SOUND_QUEUE (output sound) ;in: HL=data ;ch,env,ent,freq(lo,hi,noise),vol,len(lo,hi)

In: HL=Pointer to 9-byte Data Block

 0  Channel (Bit0-2=ChannelA-C, Bit3-5=RendevousA..C, Bit6=Hold, Bit7=Flush)
 1  ENV Volume Envelope (1..15, or 0=none)
 2  ENT Tone Envelope   (1..15, or 0=none)
 3  Tone Frequency, lower 8bit (000h=none)
 4  Tone Frequency, upper 4bit
 5  Noise Frequency (01h..1Fh, or 00h=none)  ;shared for all 3 channels
 6  Volume (00h..0Fh)
 7  Duration, lower 8bit (in 1/100 seconds)  ;\0=endless/until end of ENV?
 8  Duration, upper 8bit                     ;/negative=repeat ENV -N times?

Out: CY=1=okay, CY=0=Queue Full. Equivalent to BASIC's "SOUND".

Set Volume Envelope

 BCBC SOUND_SET_ENV

In: A=Envelope number (1..15), HL=Pointer to Data (must be >3FFFh) The data block starts with a header byte:

 bit7    envelope type (0=software, 1=hardware)
 bit6-0  number of following 3-byte parameters (1..5)

The following 3-byte parameters can be (when Byte 0, Bit7=0):

 Byte 0  Number of steps (01h..7Fh)
 Byte 1  Step (-80h..+7Fh) (of which, only -0Fh..+0Fh makes sense)
 Byte 2  Duration per step (in 1/100 seconds) (01h..FFh, or 00h=100h)

Or, using the (less comfortable) hardware envelope (when Byte 0, Bit7=1):

 Byte 0  PSG Envelope Shape (00h..0Fh), plus 80h ;PSG Register 0Dh
 Byte 1  PSG Envelope Frequency, upper 8bit      ;PSG Register 0Ch
 Byte 2  PSG Envelope Frequency, lower 8bit      ;PSG Register 0Bh

Equivalent to BASIC's "ENV". The initial sound volume is SOUND_QUEUE's [HL+6]. Note that the step is added to the sound volume (there's NO separate envelope volume register, multiplied with the sound volume). Take care that the volume doesn't overflow/underflow.

Set Tone Envelope

 BCBF SOUND_SET_ENT

In: A=Envelope number (1..15), HL=Pointer to Data (must be >3FFFh) The data block starts with a header byte:

 bit7    repeat flag (0=one shot, 1=repeat envelope)
 bit6-0  number of following 3-byte parameters (1..5)

The following 3-byte parameters can be (when Byte 0 is <F0h):

 Byte 0  Number of steps (01h..EFh)
 Byte 1  Step (-80h..+7Fh)
 Byte 2  Duration per step (in 1/100 seconds) (01h..FFh, or 00h=100h)

Or, setting the frequency directly, non-relative (when Byte 0 is >=F0h):

 Byte 0  Upper 4bit of frequency, plus F0h       ;PSG Register 01h,03h,05h
 Byte 1  Lower 8bit of frequency                 ;PSG Register 00h,02h,04h
 Byte 2  Duration (in 1/100 seconds) (01h..FFh, or 00h=100h)

Equivalent to BASIC's "ENT".

Sound Reset

 BCA7 SOUND_RESET

Reset and mute sound output.

Sound Check

 BCAD SOUND_CHECK

In: A=channel mask, Out: A=channel status.

Sound Event

 BCB0 SOUND_ARM_EVENT

In: A=channel mask, HL=event block. Equivalent to BASIC's "ON SQ GOSUB". Triggers when the channels queue is not full?

Sound Release

 BCB3 SOUND_RELEASE

In: A=channel mask. Starts pending sounds (which did have the "Hold" bit set; ie. Bit6 of Byte0 passed to SOUND_QUEUE). Equivalent to BASIC's "RELEASE".

Sound Pause/Unpause

 BCB6 SOUND_PAUSE  ;Out: CY=1=okay, CY=0=nothing to do.
 BCB9 SOUND_UNPAUSE

Freezes/unfreezes sound output.

Get Envelope

 BCC2 SOUND_GET_ENV
 BCC5 SOUND_GET_ENT

In: A=Envelope number (01h..0Fh), Out: HL=16-byte block, CY=1=okay.

Machine Pack

 BD34 MC_SOUND_REGISTER  ;in: A=PSG index, C=PSG data

Directly writes to a PSG register (this would conflict with the other SOUND functions).