Commit c422a2f

Nick Faro committed on
Manual tweaks
commit c422a2f29f8254ee6594325ed0fa8217a4140839 parent f7470e1
4 changed files +50−51
Modifiedmanual/src/hUGEDriver/integration.md +16−16
@@ -4,6 +4,8 @@ Integrating hUGEDriver into your project depends on what you are using.
4 4
5 <details><summary>RGBDS (assembly)</summary> 5 <details><summary>RGBDS (assembly)</summary>
6 6
7 Get the [release of hUGEDriver](https://github.com/SuperDisk/hUGEDriver/releases) that matches your version of hUGETracker.
8
7 Import [`hUGEDriver.asm`](https://github.com/SuperDisk/hUGEDriver/blob/master/hUGEDriver.asm) and [`hUGE.inc`](https://github.com/SuperDisk/hUGEDriver/blob/master/include/hUGE.inc) (in the `include` directory) into your project (songs need the latter as well). 9 Import [`hUGEDriver.asm`](https://github.com/SuperDisk/hUGEDriver/blob/master/hUGEDriver.asm) and [`hUGE.inc`](https://github.com/SuperDisk/hUGEDriver/blob/master/include/hUGE.inc) (in the `include` directory) into your project (songs need the latter as well).
8 You will additionally need [`hardware.inc`](https://github.com/gbdev/hardware.inc) 4.2 or later, if you don't already. 10 You will additionally need [`hardware.inc`](https://github.com/gbdev/hardware.inc) 4.2 or later, if you don't already.
9 11
@@ -13,15 +15,17 @@ Then, simply compile `hUGEDriver.asm` with the rest of your code, and you're don
13 15
14 <details><summary>GBDK (C)</summary> 16 <details><summary>GBDK (C)</summary>
15 17
16 > **Note**: some people circulate pre-compiled versions of `hUGEDriver.o` / `hUGEDriver.lib`; this is fine, but you must be sure to use the right version. 18 hUGEDriver releases contain a pre-compiled `.lib` for use with GBDK-2020. Link it while compiling, include `hUGEDriver.h`, and you're done:
17 Also, if you want to modify the driver yourself for any reason, you will need to compile it yourself afterwards. 19
20 ```sh
21 lcc ... -Wl-lhUGEDriver.lib
22 ```
18 23
19 hUGEDriver is written in RGBDS assembly, which is not compatible with SDCC's assembler (SDAS); so a few extra steps are necessary. 24 If you want to compile the driver yourself, a few extra steps are necessary.
20 25
21 0. You will need [RGBDS](https://rgbds.gbdev.io), and the [FreePascal](https://www.freepascal.org) compiler. 26 0. You will need [RGBDS](https://rgbds.gbdev.io), and [Python](https://www.python.org/)
22 1. Assemble hUGEDriver: `rgbasm -o hUGEDriver.obj hUGEDriver.asm` 27 1. Assemble hUGEDriver: `rgbasm -o hUGEDriver.obj hUGEDriver.asm`
23 2. Compile `rgb2sdas`: `make -C tools` 28 3. Convert the object file: `python tools\rgb2sdas.py -o hUGEDriver.o hUGEDriver.obj`
24 3. Convert the object file: `tools/rgb2sdas hUGEDriver.obj`
25 4. Import `hUGEDriver.h` into your project 29 4. Import `hUGEDriver.h` into your project
26 5. Simply link `hUGEDriver.o` with the rest of your code, and you're done! 30 5. Simply link `hUGEDriver.o` with the rest of your code, and you're done!
27 31
@@ -42,7 +46,7 @@ So if your song descriptor was, say, `ryukenden`:
42 <table><thead><tr><th>Assembly</th><th>C</th></tr></thead><tbody><tr><td> 46 <table><thead><tr><th>Assembly</th><th>C</th></tr></thead><tbody><tr><td>
43 47
44 ```avrasm 48 ```avrasm
45 ld de, ryukenden 49 ld hl, ryukenden
46 call hUGE_init 50 call hUGE_init
47 ``` 51 ```
48 52
@@ -57,22 +61,18 @@ hUGE_init(ryukenden);
57 ### Playing 61 ### Playing
58 62
59 The function `hUGE_dosound` plays a single tick of the current song when called. 63 The function `hUGE_dosound` plays a single tick of the current song when called.
60 Sounds simple?
61 Well, unfortunately, there are a few of gotchas.
62 64
63 First and foremost, *how often* should that function be called? 65 First and foremost, *how often* should that function be called? That actually depends on what the song expects!
64 That actually depends on what the song expects!
65 66
66 **TODO: screenshot** 67 **TODO: screenshot**
67 68
68 If the song does not use "timer playback", then `hUGE_dosound` must be called once per frame. 69 If the song does not use "timer playback", then `hUGE_dosound` must be called once per frame.
69 This is usually done either by calling it from your game's main loop (or whatever), or by calling it from your VBlank interrupt handler. 70 This is usually done either by calling it from your game's main loop, or by calling it from your VBlank interrupt handler.
70 However, if the song *does* use timer playback, then you must set the timer registers appropriately (TODO), and call `hUGE_dosound` from the timer interrupt handler. 71 However, if the song *does* use timer playback, then you must set the timer registers appropriately (TODO), and call `hUGE_dosound` from the timer interrupt handler.
71 72
72 Using any interrupt handler exposes you to two additional gotchas: 73 Using an interrupt handler exposes you to two additional constraints:
73 74
74 - `hUGE_dosound` must not run in the middle of `hUGE_init`. 75 - `hUGE_dosound` must not run in the middle of `hUGE_init`.
75 - `hUGE_dosound` must not be called before the first call ever to `hUGE_init` complete. 76 - `hUGE_dosound` must not be called before the first call ever to `hUGE_init`.
76 77
77 Preferably, create a variable that you set to 0 on boot &amp; before calling `hUGE_init`, and to 1 after `hUGE_init` returns; in the interrupt handler, skip calling `hUGE_dosound` if the variable isn't 0. 78 Preferably, create a variable that you set to 0 on boot before calling `hUGE_init`, and to 1 after `hUGE_init` returns; in the interrupt handler, skip calling `hUGE_dosound` if the variable isn't 0. An alternative is to disable interrupts (ASM: `di`+`ei`, GBDK: `__critical`) while you call `hUGE_init`.
78 An alternative (popular, but with several drawbacks) is to disable interrupts (ASM: `di`+`ei`, GBDK: `__critical`) while you call `hUGE_init`.
Modifiedmanual/src/hUGEDriver/sfx.md +17−19
@@ -1,26 +1,16 @@
1 # Sound effects 1 # Sound effects
2 2
3 hUGEDriver itself does not support sound effects; there exist many solutions for that out there! 3 hUGEDriver itself does not provide sound effects, but is compatible with existing sound effect solutions. Both music and sound effects need to contend for the Game Boy's four sound channels, so a little cooperation is required.
4 But, both music and sound effects need to contend for the Game Boy's four sound channels, so a little cooperation is required.
5 4
6 > **Note**: at the moment, there are a few bugs where hUGEDriver will still write to a channel when it's "released". 5 The general outline of how to play sound effects and music is as follows:
7 > If you encounter any, please [report them](../contact.md)!
8 6
9 hUGEDriver cooperates by being able to arbitrarily "release" channels. 7 1. Tell hUGEDriver to "release" a channel; that is, hUGEDriver refrains from touching it at all, which leaves it free for other code to use (say, an SFX engine, or [a sample player](https://github.com/DevEd2/SamplePlayer)).
10 While a channel is "released", hUGEDriver refrains from touching it at all—which leaves it free for other code to use (say, a SFX engine, or [a sample player](https://github.com/DevEd2/SamplePlayer)). 8 2. Use your SFX engine to play a sound effect on that channel
9 3. After the sound effect is complete, tell hUGEDriver to use the channel again, so music will resume playing on that channel
11 10
12 ## How-to 11 "Releasing" a channel is also known as "muting."
13
14 A channel can be released by modifying a variable:
15
16 RGBDS (assembly) | GBDK (C)
17 ------------------|----------
18 `_hUGE_mute_mask` | `hUGE_mute_mask`
19
20 Bit 0 of the mask represents CH1, bit 1 represents CH2, bit 2 represents CH3, and bit 3 represents CH4.
21 For as long as a channel's bit is 0, that channel is released.
22 12
23 A convenience function, `hUGE_mute_channel`, is also provided: 13 ## How-to
24 14
25 <details><summary>RGBDS (assembly)</summary> 15 <details><summary>RGBDS (assembly)</summary>
26 16
@@ -37,6 +27,14 @@ Call `hUGE_mute_channel`; see `hUGEDriver.h` for the corresponding arguments.
37 ## Notes 27 ## Notes
38 28
39 - **IMPORTANT** precaution for CH3: if you release this channel and modify wave RAM, you **must** inform hUGEDriver, by writing `hUGE_NO_WAVE` to `hUGE_current_wave`. 29 - **IMPORTANT** precaution for CH3: if you release this channel and modify wave RAM, you **must** inform hUGEDriver, by writing `hUGE_NO_WAVE` to `hUGE_current_wave`.
40 This will tell hUGEDriver to reload wave RAM when the channel is un-released; otherwise, you may get corrupted notes. 30 This will tell hUGEDriver to reload wave RAM when the channel is un-released; otherwise, you may get the wrong waveform when the music resumes.
41 - "Global" [effects](../hUGETracker/effect-reference.md) (5, 8, B, D, and F) still play, even if the channel they are attached to is released. 31 - "Global" [effects](../hUGETracker/effect-reference.md) (5, 8, B, D, and F) are still processed, even if the channel they are attached to is released.
42 Importantly, this means hUGEDriver *will* write to `NR50` (5) and `NR51` (8). 32 Importantly, this means hUGEDriver *will* write to `NR50` (5) and `NR51` (8).
33
34 ## SFX Engines
35
36 These projects aren't part of hUGETracker, but they're known solutions that work well with it:
37
38 1. [VGM2GBSFX](https://github.com/untoxa/VGM2GBSFX) - Can use VGM files as sound effects. Since hUGETracker can export to `.vgm`, you can make your sound effects in hUGETracker!
39 2. [CBT-FX](https://github.com/datguywitha3ds/CBT-FX) - Sound effect engine compatible with FX Hammer
40 3. [Libbet's SFX Engine](https://github.com/pinobatch/libbet/blob/master/src/audio.z80) - Simple engine for assembly projects
Modifiedmanual/src/hUGEDriver/what-is-hugedriver.md +6−8
@@ -3,20 +3,18 @@
3 [hUGEDriver](https://github.com/SuperDisk/hUGEDriver) is a *driver* for hUGETracker. 3 [hUGEDriver](https://github.com/SuperDisk/hUGEDriver) is a *driver* for hUGETracker.
4 What does that mean? 4 What does that mean?
5 5
6 Well, think like a MP3 file: a program is required to play those back. 6 Well, think about an MP3 file: a program like VLC is required to play those back.
7 Similarly, hUGETracker "only" generates music data, and something has to interpret it to actually produce sound. 7 Similarly, hUGETracker "only" generates music data, and something has to interpret it to actually produce sound.
8 8
9 This is also why some call hUGEDriver a "player" for hUGETracker, though this is slightly inexact, because hUGEDriver is not a complete playback solution: it's meant to integrate with *your* code, that will decide what music must be played, when, and how. 9 This is also why hUGEDriver is also called a "player" for hUGETracker, though this is slightly inexact, because hUGEDriver is not a complete playback solution: it's meant to integrate with *your* code, that will decide what music must be played, when, and how.
10 For more information about that, please read the next chapter. 10 For more information about that, please read the next chapter.
11 11
12 ## Notes 12 ## Notes
13 13
14 **Make sure to always use the same version of hUGETracker and hUGEDriver together!!** 14 **Make sure to always use compatible versions of hUGETracker and hUGEDriver together!!**
15 For example, you *cannot* use hUGETracker 1.0b10 with hUGEDriver 1.0b9. 15 For example, you *cannot* use hUGETracker 1.0b10 with hUGEDriver 1.0b9, as the data format is different between those two versions.
16 At best you will get garbled output, at worst your ROM will crash.
17 16
18 hUGEDriver is the reference driver, meaning that it will always be kept up to date. 17 hUGEDriver is the reference driver, meaning that it will always be kept up to date.
19 Other implementations are available, but they are not officially supported. 18 Other implementations (such as [fortISSimO](https://github.com/ISSOtm/fortISSimO)) are available, but they are not officially supported.
20 19
21 hUGETracker plays back your songs by actually embarking a copy of hUGEDriver, and emulating a Game Boy running hUGEDriver! 20 Under the hood, hUGETracker plays your songs by emulating a Game Boy running hUGEDriver. Doing it this way instead of interpreting the music data directly helps avoiding any discrepancies between playback in the tracker and on the console. If you find any, it's probably a bug, [please tell us!](https://github.com/SuperDisk/hUGETracker/issues)
22 Doing it this way instead of interpreting the music data directly helps avoiding any discrepancies between playback in the tracker and on the console—if you find any, it's probably a bug, [please tell us](../contact.md)!
Modifiedmanual/src/introduction.md +11−8
@@ -1,6 +1,5 @@
1 ![hUGETracker logo](https://camo.githubusercontent.com/47f1b09f240985f1e93c3188ebb73f503a050430a67f18a12411838cc41270b5/68747470733a2f2f6e69636b66612e726f2f696d616765732f485547454c6f676f2e676966) 1 ![hUGETracker logo](https://camo.githubusercontent.com/47f1b09f240985f1e93c3188ebb73f503a050430a67f18a12411838cc41270b5/68747470733a2f2f6e69636b66612e726f2f696d616765732f485547454c6f676f2e676966)
2 2
3 Hi!
4 This is the manual to [hUGETracker](https://github.com/SuperDisk/hUGETracker). 3 This is the manual to [hUGETracker](https://github.com/SuperDisk/hUGETracker).
5 I wrote this program because there wasn't a music editing tool for the Game Boy which fulfilled the following requirements: 4 I wrote this program because there wasn't a music editing tool for the Game Boy which fulfilled the following requirements:
6 5
@@ -13,16 +12,20 @@ But now there is!
13 12
14 I'd like to acknowledge: 13 I'd like to acknowledge:
15 14
15 1. [Eldred "ISSOtm" Habert](https://eldred.fr), who helped me navigate the Game Boy's peculiarities, and for writing [an alternative sound driver](https://github.com/ISSOtm/fortISSimO) for the tracker;
16 1. [Tony "Toxa" Pavlov](https://github.com/untoxa), who helped work on the sound driver and did super valuable work on integration with GBDK-2020;
17 1. [Coffee "Valen" Bat](https://coffeebat.neocities.org/), for a crazy amount of testing, documentation, code, and support for new users;
18 1. [Michael "Calindro" Stegmaier](https://emulicious.net) for Emulicious, a super-accurate emulator that is invaluable for debugging
19 1. [Evelyn "Eevee" Woods](https://eev.ee), whose article on the Game Boy sound system was valuable in writing the music driver;
20 1. [B00daW](https://battleofthebits.org/barracks/Profile/b00daw), for testing and debugging support on Linux;
21 1. [Lior "LIJI32" Halphon](https://github.com/LIJI32) for SameBoy, a super-accurate emulator which I used for debugging, and copied the LFSR code from;
16 1. [Christian Hackbart](https://github.com/TetrisSQC) for creating UGE, which serves as hUGETracker's emulation core; 22 1. [Christian Hackbart](https://github.com/TetrisSQC) for creating UGE, which serves as hUGETracker's emulation core;
17 1. [Rusty Wagner](https://github.com/D0ntPanic) for writing the sound code which was adapted for UGE; 23 1. [Rusty Wagner](https://github.com/D0ntPanic) for writing the sound code which was adapted for UGE;
18 1. [Lior "LIJI32" Halphon](https://github.com/LIJI32) for SameBoy, a super-accurate emulator which I used for debugging, and copied the LFSR code from; 24 1. [The team who created RGBDS](https://github.com/gbdev/rgbds/contributors), the assembler used for building ROMs from songs;
19 1. [Tony "Toxa" Pavlov](https://github.com/untoxa), who helped work on the sound driver and did super valuable work on integration with GBDK 25 1. [The GBDev community](https://gbdev.io/), [the GBDK-2020 community](https://gbdk-2020.github.io/gbdk-2020/), and [the GBStudio community](https://www.gbstudio.dev/).
20 1. [Eldred "ISSOtm" Habert](https://github.com/ISSOtm), who helped me navigate the Game Boy's peculiarities, and for writing [an alternative sound driver](https://github.com/ISSOtm/fortISSimO) for the tracker;
21 1. [Michael "Calindro" Stegmaier](https://github.com/Calindro) for Emulicious, a super-accurate emulator that is invaluable for debugging
22 1. [Evelyn "Eevee" Woods](https://github.com/eevee), whose article on the Game Boy sound system was valuable in writing the music driver;
23 1. [B00daW](https://battleofthebits.org/barracks/Profile/b00daw), for testing and debugging support on Linux;
24 1. [The folks who created RGBDS](https://github.com/gbdev/rgbds/contributors), the assembler used for building ROMs from songs.
25 26
26 I hope you enjoy composing in hUGETracker, and if you make any cool songs, I'd love to hear from you and potentially include them as demo tunes that come with the tracker. 27 I hope you enjoy composing in hUGETracker, and if you make any cool songs, I'd love to hear from you and potentially include them as demo tunes that come with the tracker.
27 28
29 [Join the hUGETracker discord](https://discord.gg/9DVqN9Jgcv) and get in touch!
30
28 —Nick "[SuperDisk](https://nickfa.ro)" Faro 31 —Nick "[SuperDisk](https://nickfa.ro)" Faro