- 1 Description
- 2 Requirements
- 3 AY Sound System
- 4 Definitions
- 5 Functions
- 6 Set Internal or External AY
- 7 How to use
- 8 Appendices
- 9 References
Library functions for access to internal or external MSX PSG AY-3-8910.
It does not use the BIOS so it can be used to program both ROMs or MSX-DOS executables.
This library is similar to the PSG AY-3-8910 RT, but instead of writing directly to the registers, it does so to a buffer that should be dumped to the AY in each VBLANK frame.
It is designed to work together with the PT3player and/or ayFXplayer libraries, but you can also use it for your own or third-party player.
In this same repository you will find a short version (AY38910BF_S) with the essentials to work with player libraries.
It incorporates the SOUND function with the same behavior as the command included in MSX BASIC, as well as specific functions to modify the different sound parameters of the AY.
Controls the I/O bits of register 7 (Mixer), of the internal AY.
It allows to use the internal PSG of the MSX or an external one (like the one incorporated in the MEGAFLASHROM SCC+ or the Flashjacks).
In the header file there is a definition of SWITCHER type, needed for the functions. This type uses the values "ON" or "OFF", which equals 1 and 0 respectively.
Include definitions to improve the readability of your programs.
Use them for developing MSX applications using Small Device C Compiler (SDCC).
This project is an Open Source library. You can add part or all of this code in your application development or include it in other libraries/engines.
This library is part of the MSX fR3eL Project.
Enjoy it!
The AY38910BF, PT3player and ayFXplayer libraries are designed to work together, so you will have a system to provide music and effects in game development.
Data type definition to be used in switches (same as boolean type).
| Label | Value |
|---|---|
| OFF | 0 |
| ON | 1 |
| Label | Value |
|---|---|
| AY_INTERNAL | 0 |
| AY_EXTERNAL | 1 |
| Label | Value | Description |
|---|---|---|
| AY_ToneA | 0 | Channel A Tone Period (12 bits) |
| AY_ToneB | 2 | Channel B Tone Period (12 bits) |
| AY_ToneC | 4 | Channel C Tone Period (12 bits) |
| AY_Noise | 6 | Noise Period (5 bits) |
| AY_Mixer | 7 | Mixer |
| AY_AmpA | 8 | Channel Volume A (4 bits + B5 active Envelope) |
| AY_AmpB | 9 | Channel Volume B (4 bits + B5 active Envelope) |
| AY_AmpC | 10 | Channel Volume C (4 bits + B5 active Envelope) |
| AY_EnvPeriod | 11 | Envelope Period (16 bits) |
| AY_EnvShape | 13 | Envelope Shape |
The header file defines envelope shapes in case you prefer to use it instead of the numerical form:
| Label | Value |
|---|---|
| AY_ENV_LowerBeat | 1 |
| AY_ENV_Upper | 4 |
| AY_ENV_LeftSaw | 8 |
| AY_ENV_LowerTriangle | 10 |
| AY_ENV_LowerHold | 11 |
| AY_ENV_RightSaw | 12 |
| AY_ENV_UpperHold | 13 |
| AY_ENV_UpperTriangle | 14 |
Attention! The LowerBeat shape may be produced with the values: 0, 1, 2, 3 and 9. The value 1 has been assigned to LowerBeat as 0 can be useful in case you need to control when the envelope is triggered. In this case 0 can act as a "don't write the envelop" event. Remember that, every time the register 13 is written, the sound with the assigned shape is started.
The Upper shape may be produced with the values: 4, 5, 6, 7 and 15.
You can use it in the functions: SetTonePeriod, SetVolume and SetChannel
| Label | Value |
|---|---|
| AY_Channel_A | 0 |
| AY_Channel_B | 1 |
| AY_Channel_C | 2 |
| AY_Init | |
|---|---|
| Initialize the AY buffer. | |
| Function | AY_Init() |
| Input | --- |
| Output | --- |
| Examples: | AY_Init(); |
| SOUND | |
|---|---|
| Write into a register of PSG | |
| Function | SOUND(register, value) |
| register | [char] register number (0 to 13) |
| value | [char] value |
| Output | --- |
| Examples: | Sound(8,16); //channel A envelope on |
| GetSound | |
|---|---|
| Read PSG register value | |
| Function | GetSound(register) |
| register | [char] register number (0 to 13) |
| Output | [char] value |
| Examples: | char value; value = GetSound(7); //read mixer register |
| SetTonePeriod | |
|---|---|
| Set Tone Period for any channel | |
| Function | SetTonePeriod(channel, period) |
| channel | [char] channel (0, 1 or 2) |
| period | [unsigned int] period (0 - 4095) |
| Output | --- |
| Examples: | SetTonePeriod(AY_Channel_B,1100); //set tone period for channel A |
| SetNoisePeriod | |
|---|---|
| Set Noise Period | |
| Function | SetNoisePeriod(period) |
| period | [char] Noise period (0 - 31) |
| Output | --- |
| Examples: | SetNoisePeriod(10); |
| SetEnvelopePeriod | |
|---|---|
| Set Envelope Period | |
| Function | SetEnvelopePeriod(period) |
| period | [unsigned int] Envelope period (0 - 65535) |
| Output | --- |
| Examples: | SetEnvelopePeriod(1000); |
| SetVolume | |
|---|---|
| Set volume channel | |
| Function | SetVolume(channel, volume) |
| channel | [char] channel (0, 1 or 2) |
| volume | [char] volume, 0 to 15 or 16 for activate envelope |
| Output | --- |
| Examples: | SetVolume(0,14); // set 14 volume level for channel A SetVolume(1,16); // activate envelope for channel B |
| SetChannel | |
|---|---|
| Mixer. Enable/disable Tone and Noise channels. | |
| Function | SetChannel(channel, isTone, isNoise) |
| channel | [char] channel (0, 1 or 2) |
| isTone | [SWITCHER] Tone channel state |
| isNoise | [SWITCHER] Noise channel state |
| Output | --- |
| Examples: | SetChannel(0,true,false); SetChannel(1,true,true); SetChannel(2,false,false); |
| PlayEnvelope | |
|---|---|
| Set envelope type. Plays the sound on channels that have a volume of 16. | |
| Function | PlayEnvelope(shape) |
| shape | [char] Envelope shape (0-15) |
| Output | --- |
| Examples: | PlayEnvelope(0); //Play LowerBeat envelope shape PlayEnvelope(ENV_LowerTriangle); //Play LowerTriangle envelope shape |
| PlayAY | |
|---|---|
| Send data from AYREGS buffer to AY registers. (Execute on each interruption of VBLANK). | |
| Function | PlayAY() |
| Input | --- |
| Output | --- |
| Examples: | PlayAY(); |
To indicate in which PSG the sounds are to be played, you have the AY_TYPE variable. To select an external AY (ports 10h to 12h), like the one included in the MegaFlashROM SCC+, Flashjacks or other, you have to set the variable to 1 (or AY_EXTERNAL).
AY_TYPE = AY_EXTERNAL;
Attention! When you execute the AY_Init() function, it will be updated to the default value corresponding to the internal AY.
coming soon...
| Register\bit | B7 | B6 | B5 | B4 | B3 | B2 | B1 | B0 | |
|---|---|---|---|---|---|---|---|---|---|
| R0 | Channel A Tone Period | 8-Bit Fine Tune A | |||||||
| R1 | 4-Bit Coarse Tune A | ||||||||
| R2 | Channel B Tone Period | 8-Bit Fine Tune B | |||||||
| R3 | 4-Bit Coarse Tune B | ||||||||
| R4 | Channel C Tone Period | 8-Bit Fine Tune C | |||||||
| R5 | 4-Bit Coarse Tune C | ||||||||
| R6 | Noise period | 5-Bit Period control | |||||||
| R7 | Enable (bit 0=on, 1=off) | IN/OUT | Noise | Tone | |||||
| IOB | IOA | C | B | A | C | B | A | ||
| R8 | Channel A Amplitude | Env | Amplitude | ||||||
| R9 | Channel B Amplitude | Env | Amplitude | ||||||
| R10 | Channel C Amplitude | Env | Amplitude | ||||||
| R11 | Envelope Period | 8-Bit Fine Tune Envelope | |||||||
| R12 | 8-Bit Coarse Tune Envelope | ||||||||
| R13 | Envelope Shape/Cycle | CONT | ATT | ALT | HOLD | ||||
| R14 | I/O Port A Data Store | 8-Bit Parallel I/O on Port A | |||||||
| R15 | I/O Port B Data Store | 8-Bit Parallel I/O on Port B | |||||||
This document is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.