Old PSG sound driver APIs

Old PSG sound driver APIs. More...

Collaboration diagram for Old PSG sound driver APIs:

Data Structures
struct	sound_fragment
	The sound fragment structure. More...
struct	sound_clip
	The sound clip structure. More...

Macros
#define	SOUND_CHANNEL_A   (1 << 0)
	The bit-mask to specify PSG channel A.
#define	SOUND_CHANNEL_B   (1 << 1)
	The bit-mask to specify PSG channel B.
#define	SOUND_CHANNEL_C   (1 << 2)
	The bit-mask to specify PSG channel C.
#define	SOUND_CHANNEL_ALL   (SOUND_CHANNEL_A | SOUND_CHANNEL_B | SOUND_CHANNEL_C)
	The bit-mask to specify all PSG channels.
#define	SOUND_SPEED_1X   (4)
	The value of the playback speed multiplier for 1.0x speed.
#define	SOUND_SPEED_MIN   (1)
	Minimum value of playback speed multiplier.
#define	SOUND_SPEED_MAX   (8)
	Maximum value of playback speed multiplier.

Functions
void	sound_init (void)
	MSX This function initializes the PSG and the sound driver.
void	sound_set_speed (uint8_t multiplier)
	MSX Sets the playback speed multiplier for background music.
void	sound_set_volume (uint8_t volume)
	MSX Set main volume level.
void	sound_set_repeat (bool repeat)
	MSX Turn on/off the auto-repeat of the BGM.
void	sound_set_mute (uint8_t mute)
	MSX Mute/unmute for each sound channel.
void	sound_effect (const struct sound_clip *s)
	MSX Plays the specified music clip as sound effect.
void	sound_set_bgm (const struct sound_clip *s)
	MSX Sets the specified music clip as BGM in the sound driver.
void	sound_start (void)
	MSX Start the BGM.
void	sound_stop (void)
	MSX Stop the BGM.
void	sound_pause (void)
	MSX Pause the BGM.
void	sound_player (void)
	MSX Main routine of the sound driver.

Detailed Description

Old PSG sound driver APIs.

---

Data Structure Documentation

sound_fragment

struct sound_fragment

The sound fragment structure.

The sound fragment structure represents a section of music. It is used to define reusable sections of music, such as intros, choruses, outros, etc.

The sound fragment structure holds a list of pointers to the sound data stream for each channel.

Each sound data stream shall be in the following format.

Note

The format of the sound data stream is described in the extended BNF format as follows:

• The term x* means zero or more x.
• The term x+ means one or more x.
• If a term ends with b (e.g. 1111b), it means a binary number.
• A - in a binary number means an unused bit.
• If a term ends with :y (e.g. foo:5), it means that the term is a binary number with y bits.

stream = chunk* eom
chunk  = header body
body   = command+
eom    = 1111b 1111b
 
header  = len:3 duration_hi:5 duration_lo:8
command = keyon
        | tone
        | keyoff
        | volume
        | software_envelope_pattern
        | envelope_pattern
        | envelope_cycle
        | envelope_pattern_and_cycle
        | noise
        | mixer
 
keyon  = 0000b tone_fdr_hi:4 tone_fdr_lo:8
tone   = 1110b tone_fdr_hi:4 tone_fdr_lo:8
keyoff = 0001b ----b
noise  = 001b noise_fdr:5
mixer  = 0111b ----b --b NC:1 NB:1 NA:1 TC:1 TB:1 TA:1
volume = 1000b vol:4
software_envelope_pattern
       = 1100b pat:4
envelope_pattern
       = 1001b pat:4
envelope_cycle
       = 0100b 0000b cycle_hi:8 cycle_lo:8
envelope_pattern_and_cycle
       = 1101b pat:4 cycle_hi:8 cycle_lo:8

The structure of chunk:

+-----------------------+  -----
| len:3 | duration_hi:5 |    |
|-----------------------|  header (2 bytes)
|     duration_lo:8     |    |
|-----------------------|  -----
|       body[0]:8       |    |
|-----------------------|    |
|       body[1]:8       |    |
|-----------------------|  body (`len` bytes)
|         ...           |    |
|-----------------------|    |
|     body[len-1]:8     |    |
+-----------------------+  -----
The body is a sequence of one or more commands.

Definition at line 152 of file sound.h.

Data Fields
uint8_t *	streams[3]	A list of pointers to the sound data stream for each channel.

sound_clip

struct sound_clip

The sound clip structure.

The sound clip structure is a list of sound fragments. It represents the entire logical data stream of music.

This structure also stores the priority order when the sound clip is used as a sound effect. (If the sound clip is to be used as background music, its priority has no meaning and will be ignored.)

Definition at line 168 of file sound.h.

Collaboration diagram for sound_clip:

Data Fields
uint16_t	priority	Priority for using this sound clip as a sound effect.
size_t	num_fragments	Number of sound fragments.
struct sound_fragment **	fragments	Pointer to an array of pointers to sound fragments. The pair of fragments and num_fragments represent a list of sound fragments, where the list represents the entire logical data stream of the music.

Macro Definition Documentation

SOUND_CHANNEL_A

#define SOUND_CHANNEL_A   (1 << 0)

The bit-mask to specify PSG channel A.

Definition at line 41 of file sound.h.

SOUND_CHANNEL_B

#define SOUND_CHANNEL_B   (1 << 1)

The bit-mask to specify PSG channel B.

Definition at line 46 of file sound.h.

SOUND_CHANNEL_C

#define SOUND_CHANNEL_C   (1 << 2)

The bit-mask to specify PSG channel C.

Definition at line 51 of file sound.h.

SOUND_CHANNEL_ALL

#define SOUND_CHANNEL_ALL   (SOUND_CHANNEL_A | SOUND_CHANNEL_B | SOUND_CHANNEL_C)

The bit-mask to specify all PSG channels.

Definition at line 56 of file sound.h.

SOUND_SPEED_1X

#define SOUND_SPEED_1X   (4)

The value of the playback speed multiplier for 1.0x speed.

See also

sound_set_speed()

Definition at line 62 of file sound.h.

SOUND_SPEED_MIN

#define SOUND_SPEED_MIN   (1)

Minimum value of playback speed multiplier.

Equivalent to SOUND_SPEED_1X / 4 (i.e., 0.25x speed).

See also

sound_set_speed()

Definition at line 69 of file sound.h.

SOUND_SPEED_MAX

#define SOUND_SPEED_MAX   (8)

Maximum value of playback speed multiplier.

Equivalent to SOUND_SPEED_1X * 2 (i.e., 2.0x speed).

See also

sound_set_speed()

Definition at line 76 of file sound.h.

Function Documentation

sound_init()

void sound_init

(

void

)

MSX This function initializes the PSG and the sound driver.

This function must be called at least once. In particular, it must be called before the first call to sound_player().

Note

If sound_player() is called without sound_init() being called, its behavior is undefined and, in the worst case, may cause damage to the (real) MSX machine.

sound_set_speed()

void sound_set_speed

(

uint8_t

multiplier

)

MSX Sets the playback speed multiplier for background music.

This function is used to control the playback speed of background music.

The playback speed multiplier is specified by a value of 4 times. For example, a value of 4 means a playback speed of 1.0x, and a value of 6 means 1.5x.

Note

• The default value of the multiplier is 4 (i.e. 1.0x).
• The minimum value of the multiplier is 1 (i.e. 0.25x).
• The maximum value of the multiplier is 8 (i.e. 2.0x).
• If the specified value is less than 1, it will be modified to 1.
• If the specified value is greater than 8, it will be modified to 8.

Parameters

multiplier

4 times the playback speed multiplier

See also

SOUND_SPEED_1X

SOUND_SPEED_MIN

SOUND_SPEED_MAX

sound_set_volume()

void sound_set_volume

(

uint8_t

volume

)

MSX Set main volume level.

Parameters

volume

main volume level (0..15)

sound_set_repeat()

void sound_set_repeat

(

bool

repeat

)

MSX Turn on/off the auto-repeat of the BGM.

Parameters

repeat

true: turn on, false: turn off

sound_set_mute()

void sound_set_mute

(

uint8_t

mute

)

MSX Mute/unmute for each sound channel.

The parameter mute is a bit-set of the mute switches.

• bit #0 (SOUND_CHANNEL_A) is for PSG channel A
• bit #1 (SOUND_CHANNEL_B) is for PSG channel B
• bit #2 (SOUND_CHANNEL_C) is for PSG channel C

If a bit is 1, the corresponding channel is muted; if a bit is 0, the corresponding channel is unmuted.

Parameters

mute	the bit-set of the mute switches.

sound_effect()

void sound_effect

(

const struct sound_clip *

s

)

MSX Plays the specified music clip as sound effect.

Priority of the sound effect

The priority of the sound effect is specified by s->priority. The larger the value, the higher the priority. This priority determines whether or not the sound driver will play the specified sound clip, as follows

• If no sound effect is playing, the specified sound clip will be played immediately.
• If a sound effect is playing and the priority of the specified sound clip is higher than that, the current sound effect will be stopped and the specified sound clip will be played immediately.
• If a sound effect is playing and the priority of the specified sound clip is lower than or equal to that, the specified sound clip will be ignored and will not be played.

Auto-mute of the background music

While the sound effect is playing, some channels of the background music will be automatically muted (if they conflict with the sound effect) and those channels will be used to play the sound effect.

When the sound effect finishes playing, all channels will be used for the background music again.

Parameters

s	Pointer to the music clip structure to be played as sound effect.

sound_set_bgm()

void sound_set_bgm

(

const struct sound_clip *

s

)

MSX Sets the specified music clip as BGM in the sound driver.

Parameters

s	Pointer to the music clip structure to be played as BGM.

sound_start()

void sound_start

(

void

)

MSX Start the BGM.

sound_stop()

void sound_stop

(

void

)

MSX Stop the BGM.

sound_pause()

void sound_pause

(

void

)

MSX Pause the BGM.

sound_player()

void sound_player

(

void

)

MSX Main routine of the sound driver.

To play the background music and/or sound effects, you need to call this function at every VSYNC timing. The easiest way is to set this function as the VSYNC interrupt handler by calling set_vsync_handler().

// At first, initialize the sound driver.
sound_init();
 
// Then, register the sound driver as the VSYNC interrupt handler.
set_vsync_handler(sound_player);
 
// And then, calls other APIs to start, stop, etc.
sound_set_repeat(true);
sound_set_bgm(&my_bgm);
sound_start();

Note

If sound_player() is called without sound_init() being called, its behavior is undefined and, in the worst case, may cause damage to the (real) MSX machine.