Commit f925915

ISSOtm committed on
Document hUGEDriver usage
commit f9259155146e4f2599456bcf8a1d8a29283731a9 parent 45b7a60
4 changed files +100−6
Modifiedmanual/src/SUMMARY.md +3−1
@@ -1,4 +1,5 @@
1 [Introduction](./introduction.md) 1 [Introduction](./introduction.md)
2 [Contact us](./contact.md)
2 3
3 # hUGETracker 4 # hUGETracker
4 5
@@ -23,5 +24,6 @@
23 24
24 # hUGEDriver 25 # hUGEDriver
25 26
26 - [What is hUGEDriver](hUGEDriver/what-is-hugedriver.md) 27 - [What is hUGEDriver?](hUGEDriver/what-is-hugedriver.md)
27 - [Integration](hUGEDriver/integration.md) 28 - [Integration](hUGEDriver/integration.md)
29 - [Sound effects](hUGEDriver/sfx.md)
Modifiedmanual/src/hUGEDriver/integration.md +75−2
@@ -1,5 +1,78 @@
1 # Integration 1 # Integration
2 2
3 ## SFX 3 Integrating hUGEDriver into your project depends on what you are using.
4 4
5 Note that "global" SFX (5, 8, B, D, and F) still play even if muted 5 <details><summary>RGBDS (assembly)</summary>
6
7 Import `hUGEDriver.asm` and `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.
9
10 Then, simply compile `hUGEDriver.asm` with the rest of your code, and you're done!
11
12 </details>
13
14 <details><summary>GBDK (C)</summary>
15
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.
17 Also, if you want to modify the driver yourself for any reason, you will need to compile it yourself afterwards.
18
19 hUGEDriver is written in RGBDS assembly, which is not compatible with SDCC's assembler (SDAS); so a few extra steps are necessary.
20
21 0. You will need [RGBDS](https://rgbds.gbdev.io), and [FreePascal](https://www.freepascal.org).
22 1. Assemble hUGEDriver: `rgbasm -o hUGEDriver.obj hUGEDriver.asm`
23 2. Compile `rgb2sdas`: `make -C tools`
24 3. Convert the object file: `tools/rgb2sdas hUGEDriver.obj`
25 4. Import `hUGEDriver.h` into your project
26 5. Simply link `hUGEDriver.o` with the rest of your code, and you're done!
27
28 </details>
29
30 ## Usage
31
32 There are two parts to using hUGEDriver: *initializing* a song, and *playing* a song.
33
34 ### Initialization
35
36 You begin playing a song by passing a pointer to it to the `hUGE_init` function.
37 How can you get such a pointer, though?
38 Simple!
39 The "song descriptor" that you choose when exporting your song names a label (assembly) / variable (C) that points to the song!
40 So if your song descriptor was, say, `ryukenden`:
41
42 <table><thead><tr><th>Assembly</th><th>C</th></tr></thead><tbody><tr><td>
43
44 ```avrasm
45 ld de, ryukenden
46 call hUGE_init
47 ```
48
49 </td><td>
50
51 ```c
52 hUGE_init(ryukenden);
53 ```
54
55 </td></tr></tbody></table>
56
57 ### Playing
58
59 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
63 First and foremost, *how often* should that function be called?
64 That actually depends on what the song expects!
65
66 **TODO: screenshot**
67
68 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 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 Using any interrupt handler exposes you to two additional gotchas:
73
74 - `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
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 An alternative (popular, but with several drawbacks) is to disable interrupts (ASM: `di`+`ei`, GBDK: `__critical`) while you call `hUGE_init`.
Modifiedmanual/src/hUGEDriver/what-is-hugedriver.md +22−1
@@ -1 +1,22 @@
1 # What is hUGEDriver 1 # What is hUGEDriver?
2
3 [hUGEDriver](https://github.com/SuperDisk/hUGEDriver) is a *driver* for hUGETracker.
4 What does that mean?
5
6 Well, think like a MP3 file: a program is required to play those back.
7 Similarly, hUGETracker "only" generates music data, and something has to interpret it to actually produce sound.
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.
10 For more information about that, please read the next chapter.
11
12 ## Notes
13
14 **Make sure to always use the same version of hUGETracker and hUGEDriver together!!**
15 For example, you *cannot* use hUGETracker 1.0b10 with hUGEDriver 1.0b9.
16 At best you will get garbled output, at worst your ROM will crash.
17
18 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.
20
21 hUGETracker plays back your songs by actually embarking a copy of hUGEDriver, and emulating a Game Boy running hUGEDriver!
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 +0−2
@@ -25,6 +25,4 @@ I'd like to acknowledge:
25 25
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. 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 27
28 E-mail me at [[email protected]](mailto:[email protected]) or add me on Discord (superdisk#5726) and get in touch!
29
30 —Nick "[SuperDisk](https://nickfa.ro)" Faro 28 —Nick "[SuperDisk](https://nickfa.ro)" Faro