readme.md
1PSGlib library from [devkitSMS](https://github.com/sverx/devkitSMS)
2synchronized March 29, 2017
3
4PSGlib
5======
6
7these are the currently defined functions/macros:
8
9```
10void PSGPlay (unsigned char *song); /* this will make your PSG tune start */
11void PSGCancelLoop (void); /* tell the library to stop the tune at next loop */
12void PSGPlayNoRepeat (unsigned char *song); /* this will make your PSG tune start and stop at loop */
13void PSGStop (void); /* this will make your PSG tune stop */
14unsigned char PSGGetStatus (void); /* get the current status of the tune */
15
16void PSGSetMusicVolumeAttenuation (unsigned char attenuation); /* this will set the tune attenuation (0-15) */
17
18void PSGSFXPlay (unsigned char *sfx, unsigned char channels); /* this will make your SFX start */
19void PSGSFXPlayLoop (unsigned char *sfx, unsigned char channels); /* this will make your looping SFX start */
20void PSGSFXCancelLoop (void); /* tell the library to stop the SFX at next loop */
21void PSGSFXStop (void); /* this will make your SFX stop */
22unsigned char PSGSFXGetStatus (void); /* get the current status of the SFX */
23
24void PSGSilenceChannels (void);
25 /* this will silence all PSG channels */
26void PSGRestoreVolumes (void);
27 /* this will restore PSG channels volume */
28
29void PSGFrame (void); /* you should call this at a constant pace */
30void PSGSFXFrame (void); /* you should call this too at a constant pace, if you use SFXs */
31```
32
33Information
34===========
35
36Z80 ASM library (and C conversion/compression tools) to allow replay of VGMs as background music/SFX in SEGA 8 bit homebrew programs
37
38Typical workflow:
39
401) You (or a friend of yours) track one or more module(s) and SFX(s) using either Mod2PSG2 or DefleMask or VGM Music Maker (or whatever tool you prefer as long as it supports exporting in VGM format).
41
422) Optional, but warmly suggested: optimize your VGM(s) using Maxim's VGMTool
43
443) Convert the VGM to PSG file(s) using the vgm2psg tool.
45
464) Optional, suggested: compress the PSG file(s) using the psgcomp tool. The psgdecomp tool can be used to verify that the compression was right.
47
485) include the library and 'incbin' the PSG file(s) to your Z80 ASM source.
49
506) call PSGInit once somewhere near the beginning of your code.
51
527) Set up a steady interrupt (vertical blanking for instance) so to call PSGFrame and PSGSFXFrame at a constant pace (very important!). The two calls are separated so you can eventually switch banks when done processing background music and need to process SFX.
53
548) Start/stop tunes when needed using PSGPlay and PSGStop calls, start/stop SFXs when needed using PSGSFXPlay and PSGSFXStop calls.
55
56 * Looping SFXs are supported too: fire them using a PSGSFXPlayLoop call, cancel their loop using a PSGSFXCancelLoop call.
57
58 * Tunes can be set to run just once instead of endlessly using PSGPlayNoRepeat call, or set a playing tune to have no more loops using PSGCancelLoop call at any time.
59
60 * To check if a tune is still playing use PSGGetStatus call, to check if a SFX is still playing use PSGSFXGetStatus call.
61
62+) You can set the music 'master' volume using PSGSetMusicVolumeAttenuation, even when a tune it's playing (and this won't affect SFX volumes).
63
64+) If you need to temporary suspend audio, use PSGSilenceChannels and stop calling PSGFrame and PSGSFXFrame. When ready to resume, use PSGRestoreVolumes.
65