SNMacro+GG - a SN76489 meta-engine with macro and Game Gear stereo
by Shiru 09'2021


A more advanced SN76489 PSG engine. It improves over the previous
SNBasic engine by adding macro (software envelopes) support and
Game Gear stereo support.

It is not a real engine as in coded in Z80 assembly or such. Instead,
it is an 1tracker script that produces a stream of SN76489 register
writes inside a VGM file container. 

The engine provides volume, arpeggio, and pitch envelopes, plus a
volume column and a detune column. The capabilities are all tied up
to the actual chip limitations. All noise modes supported. The clock
frequency is set to the Master System/Game Gear one, so tone channels
can't get below A-2.



Pattern format

Sp T1 dVoInS T2 dVoInS T3 dVoInS NseRVoInS
.. ......... ......... ......... .........
   |       | |       | |       | |      |
   +---ch1-+ +---ch2-+ +---ch3-+ +--ch4-+
   
Sp : Speed, 1..99

T1,T2,T3 : Tone channels
   Tn : Note, A-2..B-8
    d : Detune, 1..9
   Vo : Volume, 1..16 (lowest to loudest)
   In : Instrument number, 1..99
    S : Stereo, 1 left, 2 middle (default), 3 right

T4 : Noise channel
  Nse : Noise note, see below
    R : Noise reset, see below
   Vo : Volume, 1..16 (lowest to loudest)
   In : Instrument number, 1..99
    S : Stereo, 1 left, 2 middle (default), 3 right



Noise channel

The noise channel has eight modes, some of which are hijacking the
third tone channel. The modes are selected with a note in the Nse field.
The note effect number repeats in groups of 8.

The pitch in the variable pitch modes is controlled with notes in the
T3 channel. Volume of the both channels make an effect on the sound,
so the tone component can also be heard. To avoid this and keep the noise
sound only, set T3 volume to 1.

The periodic noise is a metallic sounding note that play more like a
distorted square than an actual noise. It is the only way to go below A-2
on the SN76489.

When the noise reset is set to 1, it re-writes the last value to the chip
every frame, causing restarting the pseudo noise frequency. It makes the
sound even more metallic and distorted, so it is useful as an effect.

C-6 : Fixed high pitch periodic noise
C#6 : Fixed mid pitch periodic noise
D-6 : Fixed low pitch periodic noise
D#6 : Variable pitch periodic noise
E-6 : Fixed high pitch white noise
F-6 : Fixed mid pitch white noise
F#6 : Fixed low pitch white noise
G-6 : Variable pitch white noise



Instruments and envelopes

One instrument consist of three similar software driven envelopes:

- Volume, allows to make smooth decays
- Arpeggio, adds an offset in semitones, good for drums, too
- Pitch, measured in the internal SN76489 periods, good for vibrato

The envelope contains a series of numeric values that is used per
each frame.

The values can be -120..120, even though normal volume
range is 0..15.

A value can be negative, or specified in the hex format using
# prefix.

A value can be repeated a few times by adding a *N postfix
(N is number of repeats).

Loop starting point can be set with | symbol.
