Commit 6b5aaf5

ISSOtm committed on
Write hUGEDriver docs
commit 6b5aaf585e0ab55856757aeaff3f51c33ebc541d parent 8c04dce
3 changed files +45−3
Modifiedmanual/src/hUGEDriver/integration.md +2−2
@@ -4,7 +4,7 @@ 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 Import `hUGEDriver.asm` and `hUGE.inc` (in the `include` directory) into your project (songs need the latter as well). 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).
8 You will additionally need [`hardware.inc`](https://github.com/gbdev/hardware.inc) 4.2 or later, if you don't already. 8 You will additionally need [`hardware.inc`](https://github.com/gbdev/hardware.inc) 4.2 or later, if you don't already.
9 9
10 Then, simply compile `hUGEDriver.asm` with the rest of your code, and you're done! 10 Then, simply compile `hUGEDriver.asm` with the rest of your code, and you're done!
@@ -18,7 +18,7 @@ Also, if you want to modify the driver yourself for any reason, you will need to
18 18
19 hUGEDriver is written in RGBDS assembly, which is not compatible with SDCC's assembler (SDAS); so a few extra steps are necessary. 19 hUGEDriver is written in RGBDS assembly, which is not compatible with SDCC's assembler (SDAS); so a few extra steps are necessary.
20 20
21 0. You will need [RGBDS](https://rgbds.gbdev.io), and [FreePascal](https://www.freepascal.org). 21 0. You will need [RGBDS](https://rgbds.gbdev.io), and the [FreePascal](https://www.freepascal.org) compiler.
22 1. Assemble hUGEDriver: `rgbasm -o hUGEDriver.obj hUGEDriver.asm` 22 1. Assemble hUGEDriver: `rgbasm -o hUGEDriver.obj hUGEDriver.asm`
23 2. Compile `rgb2sdas`: `make -C tools` 23 2. Compile `rgb2sdas`: `make -C tools`
24 3. Convert the object file: `tools/rgb2sdas hUGEDriver.obj` 24 3. Convert the object file: `tools/rgb2sdas hUGEDriver.obj`
Addedmanual/src/hUGEDriver/sfx.md +42−0
@@ -0,0 +1,42 @@
1 # Sound effects
2
3 hUGEDriver itself does not support sound effects; there exist many solutions for that out there!
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
6 > **Note**: at the moment, there are a few bugs where hUGEDriver will still write to a channel when it's "released".
7 > If you encounter any, please [report them](../contact.md)!
8
9 hUGEDriver cooperates by being able to arbitrarily "release" channels.
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)).
11
12 ## How-to
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
23 A convenience function, `hUGE_mute_channel`, is also provided:
24
25 <details><summary>RGBDS (assembly)</summary>
26
27 Call `hUGE_mute_channel` with `b` containing the channel's ID minus one (so between 0 and 3 inclusive), and `c` being `0` to release the channel, or `1` to unmute it.
28
29 </details>
30
31 <details><summary>GBDK (C)</summary>
32
33 Call `hUGE_mute_channel`; see `hUGEDriver.h` for the corresponding arguments.
34
35 </details>
36
37 ## Notes
38
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`.
40 This will tell hUGEDriver to reload wave RAM when the channel is un-released; otherwise, you may get corrupted notes.
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.
42 Importantly, this means hUGEDriver *will* write to `NR50` (5) and `NR51` (8).
Modifiedmanual/src/hUGETracker/effect-reference.md +1−1
@@ -29,7 +29,7 @@ Effect | Name | Description
29 `7xx` | Note delay | Wait <var>xx</var> ticks before playing the note in this cell. *If `xx` is strictly greater than the tempo, the note will not play at all!* 29 `7xx` | Note delay | Wait <var>xx</var> ticks before playing the note in this cell. *If `xx` is strictly greater than the tempo, the note will not play at all!*
30 `8xx` | Set panning | Set [which channels play on which speakers][NR51]. Consider using the effect editor. Setting a channel to neither left nor right will mute it, but is not recommended[^nr51_mute]. 30 `8xx` | Set panning | Set [which channels play on which speakers][NR51]. Consider using the effect editor. Setting a channel to neither left nor right will mute it, but is not recommended[^nr51_mute].
31 `9xx` | Change timbre | *For pulse channels* (CH1 &amp; 2), this changes the duty cycle[^nrx1]; *for the wave channel* (CH3), this loads wave <var>xx</var>[^wave_retrig]; *for the noise channel* (CH4), this changes [the LFSR's width][NR43] (caution! [^lfsr_lockup]). 31 `9xx` | Change timbre | *For pulse channels* (CH1 &amp; 2), this changes the duty cycle[^nrx1]; *for the wave channel* (CH3), this loads wave <var>xx</var>[^wave_retrig]; *for the noise channel* (CH4), this changes [the LFSR's width][NR43] (caution! [^lfsr_lockup]).
32 `Axy` | Volume slide | Slide the note's volume up by <var>x</var> units, or down by <var>y</var> units (either <var>x</var> or <var>y</var> must be 0). *The active note will be retriggered on each tick*, which may sound bad if envelope and/or length are present. It is recommended to use instead either instrument envelopes, or the `C` effect, if possible. 32 `Axy` | Volume slide | Slide the note's volume up by <var>x</var> units, or down by <var>y</var> units (either <var>x</var> or <var>y</var> must be 0). *The active note will be retriggered on each tick*, which may sound bad if envelope and/or length are present. It is recommended to use instead either instrument envelopes, or the `C` effect, if possible. **This effect is not available on the wave channel (CH3)!**
33 `Bxx` | Position jump | Jump to order <var>xx</var>. 33 `Bxx` | Position jump | Jump to order <var>xx</var>.
34 `Cxy` | Set volume | Set the volume of the channel to <var>y</var>, *and retrigger the active note*. If <var>x</var> is not 0, <var>x</var> will be written to [the envelope bits][NR12]. 34 `Cxy` | Set volume | Set the volume of the channel to <var>y</var>, *and retrigger the active note*. If <var>x</var> is not 0, <var>x</var> will be written to [the envelope bits][NR12].
35 `Dxx` | Pattern break | Jump to the next order, and start on row <var>xx</var>. 35 `Dxx` | Pattern break | Jump to the next order, and start on row <var>xx</var>.