romdev-mcp 0.1.1

package/src/platforms/gb/lib/c/hUGEDriver.upstream.asm

@@ -0,0 +1,1908 @@
+include "include/hardware.inc"
+include "include/hUGE.inc"
+
+MACRO add_a_to_r16
+    add LOW(\1)
+    ld LOW(\1), a
+    adc HIGH(\1)
+    sub LOW(\1)
+    ld HIGH(\1), a
+ENDM
+
+;; Thanks PinoBatch!
+MACRO sub_from_r16 ;; (high, low, value)
+    ld a, \2
+    sub \3
+    ld \2, a
+    sbc a  ; A = -1 if borrow or 0 if not
+    add \1
+    ld \1, a
+ENDM
+
+MACRO retMute
+    bit \1, a
+    ret nz
+ENDM
+
+MACRO checkMute
+    ld a, [mute_channels]
+    bit \1, a
+    jr nz, \2
+ENDM
+
+;; Maximum pattern length
+DEF PATTERN_LENGTH EQU 64
+
+SECTION "Playback variables", WRAM0
+;; Active song descriptor
+order_cnt: db
+_start_song_descriptor_pointers:
+;; Pointers to the song's current four orders (one per channel)
+order1: dw
+order2: dw
+order3: dw
+order4: dw
+
+;; Pointers to the instrument tables
+duty_instruments: dw
+wave_instruments: dw
+noise_instruments: dw
+
+;; Misc. pointers
+routines: dw
+waves: dw
+_end_song_descriptor_pointers:
+
+;; Pointers to the current patterns (sort of a cache)
+pattern1: dw
+pattern2: dw
+pattern3: dw
+pattern4: dw
+
+;; How long a row lasts in ticks (1 = one row per call to `hUGE_dosound`, etc. 0 translates to 256)
+ticks_per_row: ds 4
+
+_hUGE_current_wave::
+hUGE_current_wave::
+;; ID of the wave currently loaded into wave RAM
+current_wave: db
+def hUGE_NO_WAVE equ 100
+    EXPORT hUGE_NO_WAVE
+
+;; Everything between this and `end_zero` is zero-initialized by `hUGE_init`
+start_zero:
+
+_hUGE_mute_mask::
+mute_channels: db
+
+counter: db
+tick: db
+row_break: db
+next_order: db
+row: db
+current_order: db
+
+IF DEF(PREVIEW_MODE)
+loop_order: db
+single_stepping: db
+single_step_stopped: db
+ENDC
+
+channels:
+;;;;;;;;;;;
+;;Channel 1
+;;;;;;;;;;;
+channel1:
+channel_period1: dw
+toneporta_target1: dw
+channel_note1: db
+highmask1: db
+vibrato_tremolo_phase1: db
+envelope1: db
+table1: dw
+table_row1: db
+ds 5
+
+;;;;;;;;;;;
+;;Channel 2
+;;;;;;;;;;;
+channel2:
+channel_period2: dw
+toneporta_target2: dw
+channel_note2: db
+highmask2: db
+vibrato_tremolo_phase2: db
+envelope2: db
+table2: dw
+table_row2: db
+ds 5
+
+;;;;;;;;;;;
+;;Channel 3
+;;;;;;;;;;;
+channel3:
+channel_period3: dw
+toneporta_target3: dw
+channel_note3: db
+highmask3: db
+vibrato_tremolo_phase3: db
+envelope3: db
+table3: dw
+table_row3: db
+ds 5
+
+;;;;;;;;;;;
+;;Channel 4
+;;;;;;;;;;;
+channel4:
+channel_period4: dw
+toneporta_target4: dw
+channel_note4: db
+highmask4: db
+step_width4: db
+vibrato_tremolo_phase4: db
+envelope4: db
+table4: dw
+table_row4: db
+ds 4
+
+end_zero:
+
+SECTION "Sound Driver", ROM0
+
+IF DEF(GBDK)
+_hUGE_init::
+    ld h, d
+    ld l, e
+ENDC
+
+;;; Sets up hUGEDriver to play a song.
+;;; !!! BE SURE THAT `hUGE_dosound` WILL NOT BE CALLED WHILE THIS RUNS !!!
+;;; Param: HL = Pointer to the "song descriptor" you wish to load (typically exported by hUGETracker).
+;;; Destroys: AF C DE HL
+hUGE_init::
+    ld de, ticks_per_row
+
+REPT 4
+    ld a, [hl+] ; tempo
+    ld [de], a
+    inc de
+ENDR
+
+    ld a, [hl+]
+    ld [order_cnt], a
+
+    ld c, _end_song_descriptor_pointers - (_start_song_descriptor_pointers)
+    ld de, order1
+
+.copy_song_descriptor_loop:
+    ld a, [hl+]
+    ld [de], a
+    inc de
+    dec c
+    jr nz, .copy_song_descriptor_loop
+
+IF !DEF(PREVIEW_MODE)
+    ;; Zero some ram
+    ld c, end_zero - start_zero
+    ld hl, start_zero
+    xor a
+.fill_loop:
+    ld [hl+], a
+    dec c
+    jr nz, .fill_loop
+ENDC
+
+    ;; These two are zero-initialized by the loop above, so these two writes must come after
+    ld a, %11110000
+    ld [envelope1], a
+    ld [envelope2], a
+
+    ;; Force loading the next wave
+    ld a, hUGE_NO_WAVE
+    ld [current_wave], a
+
+;; Preview mode needs to load the order ID from memory
+IF !DEF(PREVIEW_MODE)
+    ld c, 0
+ELSE
+    ld a, [current_order]
+    ld c, a
+ENDC
+    ;; fallthrough (load the pattern pointers)
+
+;;; Sets all 4 pattern pointers from a certain index in the respective 4 orders.
+;;; Param: C = The index (in increments of 2)
+;;; Destroy: AF DE HL
+load_patterns:
+IF DEF(PREVIEW_MODE)
+    db $fc ; signal order update to tracker
+ENDC
+
+    ld hl, order1
+    ld de, pattern1
+    call .load_pattern
+
+    ld hl, order2
+    call .load_pattern
+
+    ld hl, order3
+    call .load_pattern
+
+    ld hl, order4
+    ;; fallthrough
+
+.load_pattern:
+    ld a, [hl+]
+    add c
+    ld h, [hl]
+    ld l, a
+    adc h
+    sub l
+    ld h, a
+
+    ld a, [hl+]
+    ld [de], a
+    inc de
+    ld a, [hl]
+    ld [de], a
+    inc de
+    ret
+
+IF DEF(GBDK)
+_hUGE_mute_channel::
+    ld b, a
+    ld c, e
+ENDC
+
+;;; Sets a channel's muting status.
+;;; Muted channels are left entirely alone by the driver, so that you can repurpose them,
+;;; for example for sound effects, CH3 sample playback, etc.
+;;; If muting the channel, the note being played will be cut.
+;;; Param: B = Which channel to enable; 0 for CH1, 1 for CH2, etc.
+;;; Param: C = 0 to unmute the channel, 1 to mute it
+;;; Destroy: A C E HL
+hUGE_mute_channel::
+    ld e, $fe
+    ld a, b
+    or a
+    jr z, .enable_cut
+.enable_loop:
+    sla c
+    rlc e
+    dec a
+    jr nz, .enable_loop
+.enable_cut:
+    ld a, [mute_channels]
+    and e
+    or  c
+    ld [mute_channels], a
+    and c
+    jp nz, note_cut
+    ret
+
+
+;;; Reads a pattern's current row.
+;;; Param: BC = Pointer to the pattern
+;;; Param: [row] = Index of the current row
+;;; Return: A = Note ID
+;;; Return: B = Instrument (upper nibble) & effect code (lower nibble)
+;;; Return: C = Effect parameter
+;;; Destroy: HL
+get_current_row:
+    ld a, [row]
+.row_in_a:
+    ld h, a
+    ;; Multiply by 3 for the note value
+    add h
+    add h
+
+    ld h, 0
+    ld l, a
+    add hl, bc ; HL now points at the 3rd byte of the note
+    ld a, [hl+]
+    ld b, [hl]
+    inc hl
+    ld c, [hl]
+    ret
+
+;;; Gets the "period" of a pattern's current note.
+;;; Param: HL = Pointer to the pattern pointer
+;;; Param: [row] = Index of the current row
+;;; Param: DE = Location to write the note's index to, if applicable
+;;; Return: HL = Note's period
+;;; Return: CF = Set if and only if a "valid" note (i.e. not a "rest")
+;;; Return: [DE] = Note's ID, not updated if a "rest"
+;;; Return: B = Instrument (upper nibble) & effect code (lower nibble)
+;;; Return: C = Effect parameter
+;;; Destroy: AF
+get_current_note:
+    ld a, [hl+]
+    ld c, a
+    ld b, [hl]
+
+    call get_current_row
+    ld hl, 0
+
+    ;; If the note we found is greater than LAST_NOTE, then it's not a valid note
+    ;; and nothing needs to be updated.
+    cp LAST_NOTE
+    ret nc
+
+    ;; Store the loaded note value in channel_noteX
+    ld [de], a
+
+;;; Gets a note's "period", i.e. what should be written to NRx3 and NRx4.
+;;; Param: A = Note ID
+;;; Return: HL = Note's period
+;;; Return: CF = 1
+;;; Destroy: AF
+get_note_period:
+    add a ; double it to get index into hi/lo table
+    add LOW(note_table)
+    ld l, a
+    adc HIGH(note_table)
+    sub l
+    ld h, a
+    ld a, [hl+]
+    ld h, [hl]
+    ld l, a
+
+    scf
+    ret
+
+;;; Gets a note's "polynomial counter", i.e. what should be written to NR44.
+;;; Param: A = Note ID
+;;; Return: A = Note's poly
+;;; Destroy: F HL
+get_note_poly:
+    ;; Invert the order of the numbers
+    add 192 ; (255 - 63)
+    cpl
+
+    ;; Thanks to RichardULZ for this formula
+    ;; https://docs.google.com/spreadsheets/d/1O9OTAHgLk1SUt972w88uVHp44w7HKEbS/edit#gid=75028951
+    ; if A > 7 then begin
+    ;   B := (A-4) div 4;
+    ;   C := (A mod 4)+4;
+    ;   A := (C or (B shl 4))
+    ; end;
+
+    ; if A < 7 then return
+    cp 7
+    ret c
+
+    ld h, a
+
+    ; B := (A-4) div 4;
+    srl a
+    srl a
+    dec a
+    ld l, a
+
+    ; C := (A mod 4)+4;
+    ld a, h
+    and 3 ; mod 4
+    add 4
+
+    ; A := (C or (B shl 4))
+    swap l
+    or l
+    ret
+
+
+;;; Computes the pointer to a member of a channel.
+;;; Param: B = Which channel (0 = CH1, 1 = CH2, etc.)
+;;; Param: D = Offset within the channel struct
+;;; Return: HL = Pointer to the channel's member
+;;; Destroy: AF
+ptr_to_channel_member:
+    ld a, b
+    swap a
+    add d
+    add LOW(channels)
+    ld l, a
+    adc HIGH(channels)
+    sub l
+    ld h, a
+    ret
+
+
+;; TODO: Make this take HL instead of DE
+
+;;; Updates a channel's frequency, and possibly restarts it.
+;;; Note that CH4 is *never* restarted by this!
+;;; Param: B = Which channel to update (0 = CH1, 1 = CH2, etc.)
+;;; Param: (for CH4) E = Note ID
+;;; Param: (otherwise) DE = Note period
+;;; Destroy: AF C
+;;; Destroy: (for CH4) HL
+update_channel_freq:
+    ld h, 0
+.nonzero_highmask:
+    ld c, b
+    ld a, [mute_channels]
+    dec c
+    jr z, .update_channel2
+    dec c
+    jr z, .update_channel3
+    dec c
+    jr z, .update_channel4
+
+.update_channel1:
+    retMute 0
+
+    ld a, e
+    ld [channel_period1], a
+    ldh [rAUD1LOW], a
+    ld a, d
+    ld [channel_period1+1], a
+    or h
+    ldh [rAUD1HIGH], a
+    ret
+
+.update_channel2:
+    retMute 1
+
+    ld a, e
+    ld [channel_period2], a
+    ldh [rAUD2LOW], a
+    ld a, d
+    ld [channel_period2+1], a
+    or h
+    ldh [rAUD2HIGH], a
+    ret
+
+.update_channel3:
+    retMute 2
+
+    ld a, e
+    ld [channel_period3], a
+    ldh [rAUD3LOW], a
+    ld a, d
+    ld [channel_period3+1], a
+    or h
+    ldh [rAUD3HIGH], a
+    ret
+
+.update_channel4:
+    retMute 3
+
+    ld d, h
+    ld a, e
+    call get_note_poly
+    ld hl, step_width4
+    or [hl]
+    ldh [rAUD4POLY], a
+
+    ld a, d
+    ldh [rAUD4GO], a
+    ret
+
+
+play_note_routines:
+    jr play_ch1_note
+    jr play_ch2_note
+    jr play_ch3_note
+    jr play_ch4_note
+
+play_ch1_note:
+    ld a, [mute_channels]
+    retMute 0
+
+    ;; Play a note on channel 1 (square wave)
+    ld hl, channel_period1
+    ld a, [hl+]
+    ldh [rAUD1LOW], a
+
+    ;; Get the highmask and apply it.
+    ld a, [highmask1]
+    or [hl]
+    ldh [rAUD1HIGH], a
+    ret
+
+play_ch2_note:
+    ld a, [mute_channels]
+    retMute 1
+
+    ;; Play a note on channel 2 (square wave)
+    ld hl, channel_period2
+    ld a, [hl+]
+    ldh [rAUD2LOW], a
+
+    ;; Get the highmask and apply it.
+    ld a, [highmask2]
+    or [hl]
+    ldh [rAUD2HIGH], a
+    ret
+
+play_ch3_note:
+    ld a, [mute_channels]
+    retMute 2
+
+    ;; Triggering CH3 while it's reading a byte corrupts wave RAM.
+    ;; To avoid this, we kill the wave channel (0 → NR30), then re-enable it.
+    ;; This way, CH3 will be paused when we trigger it by writing to NR34.
+    ;; TODO: what if `highmask3` bit 7 is not set, though?
+
+    ldh a, [rAUDTERM]
+    push af
+    and %10111011
+    ldh [rAUDTERM], a
+
+    xor a
+    ldh [rAUD3ENA], a
+    cpl
+    ldh [rAUD3ENA], a
+
+    ;; Play a note on channel 3 (waveform)
+    ld hl, channel_period3
+    ld a, [hl+]
+    ldh [rAUD3LOW], a
+
+    ;; Get the highmask and apply it.
+    ld a, [highmask3]
+    or [hl]
+    ldh [rAUD3HIGH], a
+
+    pop af
+    ldh [rAUDTERM], a
+
+    ret
+
+play_ch4_note:
+    ld a, [mute_channels]
+    retMute 3
+
+    ;; Play a "note" on channel 4 (noise)
+    ld a, [channel_period4]
+    ldh [rAUD4POLY], a
+
+    ;; Get the highmask and apply it.
+    ld a, [highmask4]
+    ldh [rAUD4GO], a
+
+    ret
+
+;;; Executes a row of a table.
+;;; Param: BC = Pointer to which table to run
+;;; Param: [HL] = Which row the table is on
+;;; Param: E = Which channel to run the table on
+do_table:
+    ;; Increment the current row
+    ld a, [hl]
+    inc [hl]
+    push hl
+
+    ;; Grab the cell values, return if no note.
+    ;; Save BC for doing effects.
+    call get_current_row.row_in_a
+    pop hl ; TODO: don't trash HL in the first place
+    push bc
+
+    ld d, a
+
+    ;; If there's a jump, change the current row
+    ld a, b
+    and $F0
+    bit 7, d
+    jr z, .no_steal
+    res 7, d
+    set 0, a
+.no_steal:
+    swap a
+    jr z, .no_jump
+    dec a
+    ld [hl], a
+
+.no_jump:
+    ld a, d
+    ;; If there's no note, don't update channel frequencies
+    cp NO_NOTE
+    jr z, .no_note2
+
+    sub 36 ; bring the number back in the range of -36, +35
+
+    ld b, e
+    ld e, a
+    ld d, 4
+    call ptr_to_channel_member
+    ld a, e
+    add [hl]
+    inc hl
+    ld d, [hl]
+
+    ;; A = note index
+    ;; B = channel
+    ;; D = highmask
+    ;; pushed = instrument/effect
+
+    ;; If ch4, don't get note period (update_channel_freq gets the poly for us)
+    ld e, a
+    inc b
+    bit 2, b
+    ld c, d
+    jr nz, .is_ch4
+
+    call get_note_period
+    ld d, h
+    ld e, l
+.is_ch4:
+    ld h, c
+    res 7, h
+    dec b
+    call update_channel_freq.nonzero_highmask
+
+.no_note:
+    ld e, b
+.no_note2:
+    pop bc
+
+    ld d, 1
+    jr do_effect.no_set_offset
+
+;;; Performs an effect on a given channel.
+;;; Param: E = Channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Param: B = Effect type (upper 4 bits ignored)
+;;; Param: C = Effect parameters (depend on FX type)
+;;; Destroy: AF BC DE HL
+do_effect:
+    ;; Return immediately if effect is 000
+    ld d, 0
+.no_set_offset:
+    ld a, b
+    and $0F
+    or c
+    ret z
+
+    ;; Strip the instrument bits off leaving only effect code
+    ld a, b
+    and $0F
+    ;; Multiply by 2 to get offset into table
+    add a
+
+    add LOW(.jump)
+    ld l, a
+    adc HIGH(.jump)
+    sub l
+    ld h, a
+
+    ld a, [hl+]
+    ld h, [hl]
+    ld l, a
+    bit 0, d
+    jr z, .no_offset
+    inc hl
+.no_offset:
+    ld b, e
+    ld a, [tick]
+    or a ; We can return right off the bat if it's tick zero
+    jp hl
+
+.jump:
+    ;; Jump table for effect
+    dw fx_arpeggio                     ;0xy
+    dw fx_porta_up                     ;1xy
+    dw fx_porta_down                   ;2xy
+    dw fx_toneporta                    ;3xy
+    dw fx_vibrato                      ;4xy
+    dw fx_set_master_volume            ;5xy ; global
+    dw fx_call_routine                 ;6xy
+    dw fx_note_delay                   ;7xy
+    dw fx_set_pan                      ;8xy ; global
+    dw fx_set_duty                     ;9xy
+    dw fx_vol_slide                    ;Axy
+    dw fx_pos_jump                     ;Bxy ; global
+    dw fx_set_volume                   ;Cxy
+    dw fx_pattern_break                ;Dxy ; global
+    dw fx_note_cut                     ;Exy
+    dw fx_set_speed                    ;Fxy ; global
+
+
+;;; Processes (global) effect 5, "set master volume".
+;;; Param: C = Value to write to NR50
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: A
+fx_set_master_volume:
+    ret nz
+
+    ld a, c
+    ldh [rAUDVOL], a
+    ret
+
+
+;;; Processes effect 6, "call routine".
+;;; Param: B = Current channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Param: C = Routine ID
+;;; Param: A = Current tick
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: Anything the routine does
+fx_call_routine:
+    nop ; In place of `ret cc`. Allows to be used in subpatterns
+
+    ld hl, routines
+    ld a, $0f
+    and c
+    add a
+    add [hl]
+    ld e, a
+    inc hl
+    ld a, $0
+    adc [hl]
+    ld h, a
+    ld l, e
+
+    ld a, [hl+]
+    ld h, [hl]
+    ld l, a
+
+    ld d, b
+    ld e, c ; SDCC compatibility
+
+    ld a, [tick]
+    or a ; set zero flag if tick 0 for compatibility
+    jp hl
+
+
+;;; Processes (global) effect 8, "set pan".
+;;; Param: B = Current channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Param: C = Value to write to NR51
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: A
+fx_set_pan:
+    ret nz
+
+    ;; Pretty simple. The editor can create the correct value here without a bunch
+    ;; of bit shifting manually.
+    ld a, c
+    ldh [rAUDTERM], a
+    ret
+
+
+;;; Processes effect 9, "set duty cycle".
+;;; Param: B = Current channel ID (0 = CH1, anything else = CH2)
+;;; Param: C = Value to write to NRx1
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: AF
+fx_set_duty:
+    ret nz
+
+    ;; $900 = 12.5%
+    ;; $940 = 25%
+    ;; $980 = 50%
+    ;; $9C0 = 75%
+
+    ld a, [mute_channels]
+    dec b
+    jr z, .chan2
+    dec b
+    jr z, .chan3
+    dec b
+    jr z, .chan4
+.chan1:
+    retMute 0
+    ld a, c
+    ldh [rAUD1LEN], a
+    ret
+.chan2:
+    retMute 1
+    ld a, c
+    ldh [rAUD2LEN], a
+    ret
+.chan4:
+    retMute 3
+    ldh a, [rAUD4POLY]
+    res 3, a
+    or c
+    ldh [rAUD4POLY], a
+    ret
+.chan3:
+    retMute 2
+
+    ld a, c
+    ld hl, current_wave
+    call update_ch3_waveform
+
+    ld b, 2
+    jp play_note
+
+update_ch3_waveform:
+    ld [hl], a
+    ;; Get pointer to new wave
+    swap a
+    ld hl, waves
+    add [hl]
+    inc hl
+    ld h, [hl]
+    ld l, a
+    adc h
+    sub l
+    ld h, a
+
+    ldh a, [rAUDTERM]
+    push af
+    and %10111011
+    ldh [rAUDTERM], a
+
+    xor a
+    ldh [rAUD3ENA], a
+
+FOR OFS, 16
+    ld a, [hl+]
+    ldh [_AUD3WAVERAM + OFS], a
+ENDR
+
+    ld a, %10000000
+    ldh [rAUD3ENA], a
+
+    pop af
+    ldh [rAUDTERM], a
+
+    ret
+
+;;; Processes (global) effect F, "set speed".
+;;; Param: C = New amount of ticks per row
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: A
+fx_set_speed:
+    ret nz
+
+    ld a, c
+    ld hl, ticks_per_row
+    ld [hl+], a
+    ld [hl+], a
+    ld [hl+], a
+    ld [hl], c
+    ret
+
+
+IF DEF(GBDK)
+_hUGE_set_position::
+    ld c, a
+    xor a
+ENDC
+
+hUGE_set_position::
+;;; Processes (global) effect B, "position jump".
+;;; Param: C = ID of the order to jump to
+;;; Destroy: A
+fx_pos_jump:
+    ret nz
+
+    ld hl, row_break
+
+    or [hl] ; a = 0 since we know we're on tick 0
+    jr nz, .already_broken
+    ld [hl], 1
+.already_broken:
+    inc hl
+    ld [hl], c
+    ret
+
+
+;;; Processes (global) effect D, "pattern break".
+;;; Param: C = ID of the next order's row to start on
+;;; Destroy: A
+fx_pattern_break:
+    ret nz
+
+    ld a, c
+    ld [row_break], a
+    ret
+
+
+;;; Processes effect E, "note cut".
+;;; Param: B = Current channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Param: C = Tick to cut the note on
+;;; Param: A = Current tick
+;;; Destroy: A
+fx_note_cut:
+    cp c
+    ret nz
+
+    ;; check channel mute
+
+    ld a, b
+    ;; 0 → $01, 1 → $02, 2 → $04, 3 → $05
+    ;; Overall, these two instructions add 1 to the number.
+    ;; However, the first instruction will generate a carry for inputs of $02 and $03;
+    ;; the `adc` will pick the carry up, and "separate" 0 / 1 from 2 / 3 by an extra 1.
+    ;; Luckily, this yields correct results for 0 ($01), 1 ($02), and 2 ($03 + 1 = $04).
+    ;; We'll see about fixing 3 afterwards.
+    add -2
+    adc 3
+    ;; After being shifted left, the inputs are $02, $04, $08 and $0A; all are valid BCD,
+    ;; except for $0A. Since we just performed `add a`, DAA will correct the latter to $10.
+    ;; (This should be correctly emulated everywhere, since the inputs are identical to
+    ;; "regular" BCD.)
+    ;; When shifting the results back, we'll thus get $01, $02, $04 and $08!
+    add a
+    daa
+    rra
+    ld d, a
+    ld a, [mute_channels]
+    cpl
+    and d
+    ret z
+
+    ;; fallthrough
+
+
+;;; Cuts note on a channel.
+;;; Param: B = Current channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Destroy: AF HL
+note_cut:
+    ld a, b
+    add a
+    add a
+    add b ; multiply by 5
+    add LOW(rAUD1ENV)
+    ld l, a
+    ld h, HIGH(rAUD1ENV)
+    xor a
+    ld [hl+], a
+    ld a, b
+    cp 2
+    ret z ; return early if CH3-- no need to retrigger note
+
+    ;; Retrigger note
+    inc l ; Not `inc hl` because H stays constant (= $FF)
+    ld [hl], $FF
+    ret
+
+
+;;; Processes effect C, "set volume".
+;;; Param: B = Current channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Param: C = Volume to set the channel to
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: AF BC
+fx_set_volume:
+    ret nz ; Return if we're not on tick zero.
+
+    swap c
+    ld a, [mute_channels]
+    dec b
+    jr z, .set_chn_2_vol
+    dec b
+    jr z, .set_chn_3_vol
+    dec b
+    jr z, .set_chn_4_vol
+
+.set_chn_1_vol:
+    retMute 0
+
+    ldh a, [rAUD1ENV]
+    and %00001111
+    or c
+    ldh [rAUD1ENV], a
+    jp play_ch1_note
+
+.set_chn_2_vol:
+    retMute 1
+
+    ldh a, [rAUD2ENV]
+    and %00001111
+    or c
+    ldh [rAUD2ENV], a
+    jp play_ch2_note
+
+.set_chn_3_vol:
+    retMute 2
+
+    ;; "Quantize" the more finely grained volume control down to one of 4 values.
+    ld a, c
+    cp 10 << 4
+    jr nc, .one
+    cp 5 << 4
+    jr nc, .two
+    or a
+    jr z, .done ; Zero maps to zero
+.three:
+    ld a, %01100000
+    jr .done
+.two:
+    ld a, %01000000
+    jr .done
+.one:
+    ld a, %00100000
+.done:
+    ldh [rAUD3LEVEL], a
+    ret
+
+.set_chn_4_vol:
+    retMute 3
+
+    ld a, c
+    ldh [rAUD4ENV], a
+    jp play_ch4_note
+
+
+;;; Processes effect 4, "vibrato".
+;;; Param: B = Current channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Param: C = FX param
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: AF B DE HL
+fx_vibrato:
+    ret z
+
+    ;; Extremely poor man's vibrato.
+    ;; Speed values:
+    ;; (0x0  = 1.0)
+    ;; (0x1  = 0.5)
+    ;; (0x3  = 0.25)
+    ;; (0x7  = 0.125)
+    ;; (0xf  = 0.0625)
+    ld d, 4
+    call ptr_to_channel_member
+
+    ld a, c
+    and %11110000
+    swap a
+    ld e, a
+
+    ld a, [counter]
+    and e
+    ld a, [hl]
+    jr z, .go_up
+.restore:
+    call get_note_period
+    ld d, h
+    ld e, l
+    jr .finish_vibrato
+.go_up:
+    call get_note_period
+    ld a, c
+    and %00001111
+    add l
+    ld e, a
+    adc h
+    sub e
+    ld d, a
+.finish_vibrato:
+    jp update_channel_freq
+
+
+;;; Processes effect 0, "arpeggio".
+;;; Param: B = Current channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Param: C = Offsets in semitones (each nibble)
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: AF B DE HL
+fx_arpeggio:
+    nop ; In place of `ret cc`. Allows to be used in subpatterns
+
+    ld d, 4
+    call ptr_to_channel_member
+    ld d, [hl]
+
+    ld a, [counter]
+    dec a
+
+    ;; TODO: A crappy modulo, because it's not a multiple of four :(
+
+    jr .test_greater_than_two
+.greater_than_two:
+    sub 3
+.test_greater_than_two:
+    cp 3
+    jr nc, .greater_than_two
+
+    ;; Multiply by 2 to get offset into table
+    add a
+
+    add LOW(.arp_options)
+    ld l, a
+    adc HIGH(.arp_options)
+    sub l
+    ld h, a
+    jp hl
+
+.arp_options:
+    jr .set_arp1
+    jr .set_arp2
+    ;; No `jr .reset_arp`
+
+.reset_arp:
+    ld a, d
+    jr .finish_skip_add
+
+.set_arp2:
+    ld a, c
+    swap a
+    db $FE ; cp <imm8> gobbles next byte
+
+.set_arp1:
+    ld a, c
+.finish_arp:
+    and %00001111
+    add d
+.finish_skip_add:
+    call get_note_period
+    ld d, h
+    ld e, l
+    jp update_channel_freq
+
+
+;;; Processes effect 1, "portamento up".
+;;; Param: B = Current channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Param: C = How many units to slide the pitch by per tick
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: A B DE HL
+fx_porta_up:
+    ret z
+
+    ld d, 0
+    call ptr_to_channel_member
+
+    ;; Add C to 16-bit value at HL
+    ld a, [hl+]
+    add c
+    ld e, a
+    adc [hl]
+    sub e
+    ld d, a
+
+    jp update_channel_freq
+
+
+;;; Processes (global) effect 2, "portamento down".
+;;; Param: B = Current channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Param: C = How many units to slide the pitch down by per tick
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: A B DE HL
+fx_porta_down:
+    ret z
+
+    ld d, 0
+    call ptr_to_channel_member
+
+    ;; Subtract C from 16-bit value at [HL]
+    ld a, [hl+]
+    sub c
+    ld e, a
+    sbc a
+    add [hl]
+    ld d, a
+
+    jp update_channel_freq
+
+
+;;; Processes effect 2, "tone portamento".
+;;; Param: B = Current channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Param: C = Target note
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: A B DE HL
+fx_toneporta:
+    jr z, .setup
+
+    ld d, 0
+    call ptr_to_channel_member
+    push hl
+
+    ld a, [hl+]
+    ld e, a
+    ld a, [hl+]
+    ld d, a
+
+    ld a, [hl+]
+    ld h, [hl]
+    ld l, a
+
+    ;; Comparing which direction to move the current value
+    ;; TODO: Optimize this!!!!
+
+    ;; Compare high byte
+    ld a, h
+
+    cp d
+    jr c, .subtract ; target is less than the current period
+    jr nz, .add
+.high_byte_same:
+    ld a, l
+    cp e
+    jr c, .subtract ; the target is less than the current period
+    jr z, .done ; both nibbles are the same so no portamento
+.add:
+    ld a, c
+    add_a_to_r16 de
+
+    ld a, h
+    cp d
+    jr c, .set_exact
+    jr nz, .done
+    ld a, l
+    cp e
+    jr c, .set_exact
+
+    jr .done
+
+.subtract:
+    sub_from_r16 d, e, c
+
+    bit 7, d ; check for overflow
+    jr nz, .set_exact
+
+    ld a, d
+    cp h
+    jr c, .set_exact
+    jr nz, .done
+    ld a, e
+    cp l
+    jr c, .set_exact
+
+    jr .done
+.set_exact:
+    ld d, h
+    ld e, l
+.done:
+
+    pop hl
+    ld a, e
+    ld [hl+], a
+    ld [hl], d
+
+
+    ld a, 4
+    add_a_to_r16 hl
+
+    ld a, [hl]
+    res 7, [hl]
+    ld h, a
+    ;; B must be preserved for this
+    jp update_channel_freq.nonzero_highmask
+
+.setup:
+    ;; We're on tick zero, so load the note period into the toneporta target.
+    ld d, 4
+    call ptr_to_channel_member
+
+    ld a, [hl-]
+    ld d, h
+    ld e, l
+    call get_note_period
+    ld a, h
+    ld [de], a
+    dec de
+    ld a, l
+    ld [de], a
+
+ret_dont_play_note:
+    ;; Don't call play_chX_note. This is done by popping the saved AF register and clearing
+    ;; the C flag, which relies on the way the caller is implemented!!
+    pop hl
+    pop af
+    and a ; Clear carry to avoid calling `play_chX_note`
+    push af
+    jp hl
+
+
+;;; Processes effect A, "volume slide".
+;;; Param: B = Current channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Param: C = FX param; either nibble should be 0, otherwise weird (unspecified) behavior may arise
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: AF C DE HL
+fx_vol_slide:
+    ret nz
+
+    ;; This is really more of a "retrigger note with lower volume" effect and thus
+    ;; isn't really that useful. Instrument envelopes should be used instead.
+    ;; Might replace this effect with something different if a new effect is
+    ;; ever needed.
+
+    ;; check channel mute
+
+    ld a, b
+    ;; 0 → $01, 1 → $02, 2 → $04, 3 → $05
+    ;; Overall, these two instructions add 1 to the number.
+    ;; However, the first instruction will generate a carry for inputs of $02 and $03;
+    ;; the `adc` will pick the carry up, and "separate" 0 / 1 from 2 / 3 by an extra 1.
+    ;; Luckily, this yields correct results for 0 ($01), 1 ($02), and 2 ($03 + 1 = $04).
+    ;; We'll see about fixing 3 afterwards.
+    add -2
+    adc 3
+    ;; After being shifted left, the inputs are $02, $04, $08 and $0A; all are valid BCD,
+    ;; except for $0A. Since we just performed `add a`, DAA will correct the latter to $10.
+    ;; (This should be correctly emulated everywhere, since the inputs are identical to
+    ;; "regular" BCD.)
+    ;; When shifting the results back, we'll thus get $01, $02, $04 and $08!
+    add a
+    daa
+    rra
+    ld d, a
+    ld a, [mute_channels]
+    cpl
+    and d
+    ret z
+
+    ;; setup the up and down params
+    ld a, c
+    and %00001111
+    ld d, a
+
+    ld a, c
+    and %11110000
+    ld e, a
+    swap e
+
+    ; There are 5 bytes between each envelope register
+    ld a, b
+    add a
+    add a
+    add b
+    add LOW(rAUD1ENV)
+    ld c, a
+
+    ldh a, [c]
+    and %11110000
+    swap a
+    sub d
+    jr nc, .cont1
+    xor a
+.cont1:
+    add e
+    cp $10
+    jr c, .cont2
+    ld a, $F
+.cont2:
+    swap a
+    ldh [c], a
+
+    ; Go to rAUDxGO, which is 2 bytes after
+    inc c
+    inc c
+    ldh a, [c]
+    or %10000000
+    ldh [c], a
+
+    jr play_note
+
+
+;;; Processes effect 7, "note delay".
+;;; Param: B = Current channel ID (0 = CH1, 1 = CH2, etc.)
+;;; Param: C = Amount of ticks by which to delay the note
+;;;            Caveats: 0 never plays the note, and a delay longer than a row's duration skips the note entirely
+;;; Param: ZF = Set if and only if on tick 0
+;;; Destroy: AF D HL
+fx_note_delay:
+    jr z, ret_dont_play_note
+
+    cp c
+    ret nz ; wait until the correct tick to play the note
+
+    ;; fallthrough
+
+
+;;; Plays a channel's current note.
+;;; Param: B = Which channel (0 = CH1, 1 = CH2, etc.)
+;;; Destroy: AF D HL
+play_note:
+    ld a, b
+    add a
+    add LOW(play_note_routines)
+    ld l, a
+    adc HIGH(play_note_routines)
+    sub l
+    ld h, a
+    jp hl
+
+
+;;; Computes the pointer to an instrument.
+;;; Param: B = The instrument's ID
+;;; Param: HL = Instrument pointer table
+;;; Return: HL = Pointer to the instrument
+;;; Return: ZF = Set if and only if there was no instrument (ID == 0)
+;;; Destroy: AF
+setup_instrument_pointer:
+    ld a, b
+    and %11110000
+    swap a
+    ret z ; If there's no instrument, then return early.
+
+    dec a ; Instrument 0 is "no instrument"
+.finish:
+    ;; Multiply by 6
+    add a
+    ld e, a
+    add a
+    add e
+
+    add_a_to_r16 hl
+
+    rla ; reset the Z flag
+    ret
+
+_hUGE_dosound::
+;;; Ticks the sound engine once.
+;;; Destroy: AF BC DE HL
+hUGE_dosound::
+IF DEF(PREVIEW_MODE)
+   ld a, [single_stepping]
+   ld hl, single_step_stopped
+   and [hl]
+   ret nz
+ENDC
+
+    ld a, [tick]
+    or a
+    jp nz, process_effects
+
+    ;; Note playback
+    ld hl, pattern1
+    ld de, channel_note1
+    call get_current_note
+
+    push af ; Save carry for conditonally calling note
+    jr nc, .do_setvol1
+
+    ld a, b
+    and $0F
+    cp 3 ; If toneporta, don't load the channel period
+    jr z, .toneporta
+    ld a, l
+    ld [channel_period1], a
+    ld a, h
+    ld [channel_period1+1], a
+.toneporta:
+
+    ld hl, duty_instruments
+    ld a, [hl+]
+    ld h, [hl]
+    ld l, a
+    call setup_instrument_pointer
+    ld a, [highmask1]
+    res 7, a ; Turn off the "initial" flag
+    jr z, .write_mask1
+
+    checkMute 0, .do_setvol1
+
+    ld a, [hl+]
+    ldh [rAUD1SWEEP], a
+    ld a, [hl+]
+    ldh [rAUD1LEN], a
+    ld a, [hl+]
+    ldh [rAUD1ENV], a
+    ld a, [hl+]
+    ld [table1], a
+    ld a, [hl+]
+    ld [table1+1], a
+    xor a
+    ld [table_row1], a
+
+    ld a, [hl]
+
+.write_mask1:
+    ld [highmask1], a
+
+.do_setvol1:
+    ld e, 0
+    call do_effect
+
+    pop af
+    call c, play_ch1_note
+
+    ld a, [table1]
+    ld c, a
+    ld a, [table1+1]
+    ld b, a
+    or c
+    ld hl, table_row1
+    ld e, 0
+    call nz, do_table
+
+process_ch2:
+    ;; Note playback
+    ld hl, pattern2
+    ld de, channel_note2
+    call get_current_note
+
+    push af ; Save carry for conditonally calling note
+    jr nc, .do_setvol2
+
+    ld a, b
+    and $0F
+    cp 3 ; If toneporta, don't load the channel period
+    jr z, .toneporta
+    ld a, l
+    ld [channel_period2], a
+    ld a, h
+    ld [channel_period2+1], a
+.toneporta:
+
+    ld hl, duty_instruments
+    ld a, [hl+]
+    ld h, [hl]
+    ld l, a
+    call setup_instrument_pointer
+    ld a, [highmask2]
+    res 7, a ; Turn off the "initial" flag
+    jr z, .write_mask2
+
+    checkMute 1, .do_setvol2
+
+    inc hl
+
+    ld a, [hl+]
+    ldh [rAUD2LEN], a
+    ld a, [hl+]
+    ldh [rAUD2ENV], a
+    ld a, [hl+]
+    ld [table2], a
+    ld a, [hl+]
+    ld [table2+1], a
+    xor a
+    ld [table_row2], a
+
+    ld a, [hl]
+
+.write_mask2:
+    ld [highmask2], a
+
+.do_setvol2:
+    ld e, 1
+    call do_effect
+
+    pop af
+    call c, play_ch2_note
+
+    ld a, [table2]
+    ld c, a
+    ld a, [table2+1]
+    ld b, a
+    or c
+    ld hl, table_row2
+    ld e, 1
+    call nz, do_table
+
+process_ch3:
+    ld hl, pattern3
+    ld de, channel_note3
+    call get_current_note
+
+    push af ; Save carry for conditonally calling note
+    jp nc, .do_setvol3
+
+    ld a, b
+    and $0F
+    cp 3 ; If toneporta, don't load the channel period
+    jr z, .toneporta
+    ld a, l
+    ld [channel_period3], a
+    ld a, h
+    ld [channel_period3+1], a
+.toneporta:
+
+    ld hl, wave_instruments
+    ld a, [hl+]
+    ld h, [hl]
+    ld l, a
+    call setup_instrument_pointer
+    ld a, [highmask3]
+    res 7, a ; Turn off the "initial" flag
+    jr z, .write_mask3
+
+    checkMute 2, .do_setvol3
+
+    ld a, [hl+]
+    ldh [rAUD3LEN], a
+    ld a, [hl+]
+    ldh [rAUD3LEVEL], a
+    ld a, [hl+]
+    push hl
+
+    ;; Check to see if we need to copy the wave
+    ld hl, current_wave
+    cp [hl]
+    jr z, .no_wave_copy
+    call update_ch3_waveform
+
+.no_wave_copy:
+    pop hl
+    ld a, [hl+]
+    ld [table3], a
+    ld a, [hl+]
+    ld [table3+1], a
+    xor a
+    ld [table_row3], a
+
+    ld a, [hl]
+
+.write_mask3:
+    ld [highmask3], a
+
+.do_setvol3:
+    ld e, 2
+    call do_effect
+
+    pop af
+    call c, play_ch3_note
+
+    ld a, [table3]
+    ld c, a
+    ld a, [table3+1]
+    ld b, a
+    or c
+    ld hl, table_row3
+    ld e, 2
+    call nz, do_table
+
+process_ch4:
+    ld hl, pattern4
+    ld a, [hl+]
+    ld c, a
+    ld b, [hl]
+    call get_current_row
+    cp LAST_NOTE
+
+    push af ; Save carry for conditonally calling note
+    jr nc, .do_setvol4
+
+    ld [channel_note4], a
+
+    ;; No toneporta check because it's not supported for CH4 anyway
+
+    call get_note_poly
+    ld [channel_period4], a
+
+    ld hl, noise_instruments
+    ld a, [hl+]
+    ld h, [hl]
+    ld l, a
+    call setup_instrument_pointer
+
+    ld a, [highmask4]
+    res 7, a ; Turn off the "initial" flag
+    jr z, .write_mask4
+
+    checkMute 3, .do_setvol4
+
+    ld a, [hl+]
+    ldh [rAUD4ENV], a
+
+    ld a, [hl+]
+    ld [table4], a
+    ld a, [hl+]
+    ld [table4+1], a
+    xor a
+    ld [table_row4], a
+
+    ld a, [hl]
+    and %00111111
+    ldh [rAUD4LEN], a
+
+    ld a, [channel_period4]
+    ld d, a
+    ld a, [hl]
+    and %10000000
+    swap a
+    ld [step_width4], a
+    or d
+    ld [channel_period4], a
+
+    ld a, [hl]
+    and %01000000
+    or  %10000000
+.write_mask4:
+    ld [highmask4], a
+
+.do_setvol4:
+    ld e, 3
+    call do_effect
+
+    pop af
+    call c, play_ch4_note
+
+    ld a, [table4]
+    ld c, a
+    ld a, [table4+1]
+    ld b, a
+    or c
+    ld hl, table_row4
+    ld e, 3
+    call nz, do_table
+
+    ;; finally just update the tick/order/row values
+    jp tick_time
+
+process_effects:
+    ;; Only do effects if not on tick zero
+    checkMute 0, .after_effect1
+
+    ld hl, pattern1
+    ld a, [hl+]
+    ld c, a
+    ld b, [hl]
+    call get_current_row
+
+    ld a, c
+    or a
+    jr z, .after_effect1
+
+    ld e, 0
+    call do_effect      ; make sure we never return with ret_dont_play_note!!
+
+;; TODO: Deduplicate this code by moving it into do_table?
+.after_effect1:
+    ld a, [table1]
+    ld c, a
+    ld a, [table1+1]
+    ld b, a
+    or c
+    ld hl, table_row1
+    ld e, 0
+    call nz, do_table
+
+.process_ch2:
+    checkMute 1, .after_effect2
+
+    ld hl, pattern2
+    ld a, [hl+]
+    ld c, a
+    ld b, [hl]
+    call get_current_row
+
+    ld a, c
+    or a
+    jr z, .after_effect2
+
+    ld e, 1
+    call do_effect      ; make sure we never return with ret_dont_play_note!!
+
+.after_effect2:
+    ld a, [table2]
+    ld c, a
+    ld a, [table2+1]
+    ld b, a
+    or c
+    ld hl, table_row2
+    ld e, 1
+    call nz, do_table
+
+.process_ch3:
+    checkMute 2, .after_effect3
+
+    ld hl, pattern3
+    ld a, [hl+]
+    ld c, a
+    ld b, [hl]
+    call get_current_row
+
+    ld a, c
+    or a
+    jr z, .after_effect3
+
+    ld e, 2
+    call do_effect      ; make sure we never return with ret_dont_play_note!!
+
+.after_effect3:
+    ld a, [table3]
+    ld c, a
+    ld a, [table3+1]
+    ld b, a
+    or c
+    ld hl, table_row3
+    ld e, 2
+    call nz, do_table
+
+.process_ch4:
+    checkMute 3, .after_effect4
+
+    ld hl, pattern4
+    ld a, [hl+]
+    ld c, a
+    ld b, [hl]
+    call get_current_row
+
+    ld a, c
+    or a
+    jr z, .after_effect4
+
+    ld e, 3
+    call do_effect      ; make sure we never return with ret_dont_play_note!!
+
+.after_effect4:
+    ld a, [table4]
+    ld c, a
+    ld a, [table4+1]
+    ld b, a
+    or c
+    ld hl, table_row4
+    ld e, 3
+    call nz, do_table
+
+tick_time:
+IF DEF(PREVIEW_MODE)
+    db $f4 ; signal tick to tracker
+ENDC
+
+    ld a, [row]
+    and 3
+    ld hl, ticks_per_row
+    add_a_to_r16 hl
+    ld b, [hl]
+
+    ld hl, counter
+    inc [hl]
+
+    assert counter + 1 == tick
+    inc hl ; ld hl, tick
+    inc [hl] ; Increment tick counter
+
+    ;; Should we switch to the next row?
+    ld a, b
+    sub [hl]
+    ret nz ; Nope.
+    ld [hl+], a ; Reset tick to 0
+    ;; Below code relies on a == 0
+
+    assert tick + 1 == row_break
+    ;; Check if we need to perform a row break or pattern break
+    or [hl] ; a == 0, so this is `ld a, [hl]` that also alters flags
+    jr z, .no_break
+
+    ;; These are offset by one so we can check to see if they've
+    ;; been modified
+    dec a
+    ld b, a
+
+    xor a
+    ld [hl+], a
+    assert row_break + 1 == next_order
+    or [hl]     ; a = [next_order], zf = ([next_order] == 0)
+    jr z, .neworder
+    ld [hl], 0
+
+    dec a
+    add a ; multiply order by 2 (they are words)
+
+    jr .update_current_order
+
+.no_break:
+    ;; Increment row.
+    ld a, [row]
+    inc a
+    cp PATTERN_LENGTH
+    jr nz, .noreset
+
+    ld b, 0
+.neworder:
+IF DEF(PREVIEW_MODE)
+    ld a, [loop_order]
+    and a
+    jr z, .no_loop_order
+    xor a
+    jr .noreset
+.no_loop_order:
+ENDC
+    ;; Increment order and change loaded patterns
+    ld a, [order_cnt]
+    ld c, a
+    ld a, [current_order]
+    add 2
+    cp c
+    jr nz, .update_current_order
+    xor a
+.update_current_order:
+    ;; Call with:
+    ;; A: The order to load
+    ;; B: The row for the order to start on
+    ld [current_order], a
+    ld c, a
+    call load_patterns
+
+    ld a, b
+.noreset:
+    ld [row], a
+
+IF DEF(PREVIEW_MODE)
+    db $fd ; signal row update to tracker
+
+    ld a, [single_stepping]
+    or a
+    ret z
+
+    ; a is nonzero
+    ld [single_step_stopped], a
+ENDC
+    ret
+
+note_table:
+include "include/hUGE_note_table.inc"