LIB: pm_music

Background Music (BGM) and sound effects (SFX) playback

Note: IRQ_MUSIC must be included in PM_HEADER IRQ flags list for the mixer to work

pmrom_music.s

Type: Source File

Dependency: pm_init.s

Including Rules: Must be after ROM (PM_HEADER) declaration and inside Bank 0

ROM/RAM Usage: 1.2KB of ROM & 67 Bytes of RAM

Functions

Functions	Parameters	Description
Initialize
call pmmusic_init	BA = RAM Pointer HL = Master time No return	Initialize tracker Master time is Tmr 2 Preset with Prescale 6 TicksPerSec = 3906.25 / (Master Time + 1);
Manage master time
call pmmusic_setmastertime	HL = Master time No return	Modify master time (affects both BGM and SFX)
call pmmusic_getmastertime	No parameters Return HL = Master Timer	Get master time
Manage RAM pointer
call pmmusic_setrampointer	HL = RAM pointer No return	Modify RAM pointer (affects both BGM and SFX)
call pmmusic_getrampointer	No parameters Return HL = RAM pointer	Get RAM pointer
Manage master volume
call pmmusic_setvolbgm	A = Volume No return	Set BGM master volume 0 (Silence) to 3 (Max), default is 3 If out of range, the call will be ignored
call pmmusic_getvolbgm	No parameters Return A = Volume	Get BGM master volume
call pmmusic_setvolsfx	A = Volume No return	Set SFX master volume 0 (Silence) to 3 (Max), default is 3 If out of range, the call will be ignored
call pmmusic_getvolsfx	No parameters Return A = Volume	Get SFX master volume
Play music (BGM)
call pmmusic_playbgm	I = BGM Address (Hi) HL = BGM Address (Med & Lo) No return	Play BGM, address must be a list of patterns
call pmmusic_stopbgm	No parameters No return	Stop BGM
call pmmusic_isplayingbgm	No parameters Return Non-Zero if playing Return A != 0 if playing	Is playing BGM?
Play sound effect (SFX)
call pmmusic_playsfx	I = SFX Address (Hi) HL = SFX Address (Med & Lo) No return	Play SFX, address must be a patterns
call pmmusic_stopsfx	No parameters No return	Stop SFX
call pmmusic_isplayingsfx	No parameters Return Non-Zero if playing Return A != 0 if playing	Is playing SFX?

Macros

Note: Macros names are case insensitive

Macro	Description
PMMUSIC_ALIGN	Align data for music data, equivalent to ".align 2" but doesn't override assembler's aligment
PMMUSIC_PATTERN pataddr	Must be inside BGM Define pattern, BGM must have at least 1 pattern pataddr = Label of pattern
PMMUSIC_ROW note_id, pwm_amt, volume, wait_amt	Must be inside SFX or Pattern Define row inside pattern note_id = N_* definition pwm_amt = Pulse-Width, 0 to 255, 128 = 50% (Square) volume = Volume, 0 to 3 wait_amt = Wait ticks, 1 to 255 Set note_id to N____ and pwm_amt to -1 to not update note (saves 4 bytes) Pulse-width changing require note definition!
PMMUSIC_WRITE_RAM address, value	Must be inside SFX or Pattern Write to RAM address = Relative adress pwm_amt = Pulse-Width, 0 to 255, 128 = 50% (Square)
PMMUSIC_MARK loop_id	Must be inside SFX or Pattern Mark position for loop loop_id = Loop identification, 0 to 3
PMMUSIC_LOOP loop_id, loop_num	Must be inside SFX or Pattern Loop back loop_id = Loop identification, 0 to 3 loop_num = Number of loops, 0 to 255
PMMUSIC_NEXT	Must be inside Pattern Go to next pattern
PMMUSIC_GOBACK pattnum	Must be inside Pattern Mark position for loop pattnum = Number of patterns to go back 0 will repeat same pattern over and over 1 will jump to the previous pattern
PMMUSIC_END	Must be inside SFX or Pattern End BGM/SFX playback

Defines

Definition	Description
IRQ_MUSIC	Interrupt for handling the music, must be defined in PM_HEADER IRQ flags list for the mixer to work. This definition is equivalent to IRQ_TMR2_HI

Notes for PMMUSIC_ROW

Definition	Description
N____	Don't change note
N_C_n	Play C, n is octave number between 1 and 7
N_CSn	Play C#, n is octave number between 1 and 7
N_D_n	Play D, n is octave number between 1 and 7
N_DSn	Play D#, n is octave number between 1 and 7
N_E_n	Play E, n is octave number between 1 and 7
N_F_n	Play F, n is octave number between 1 and 7
N_FSn	Play F#, n is octave number between 1 and 7
N_G_n	Play G, n is octave number between 1 and 7
N_GSn	Play G#, n is octave number between 1 and 7
N_A_n	Play A, n is octave number between 1 and 7
N_ASn	Play A#, n is octave number between 1 and 7
N_B_n	Play B, n is octave number between 1 and 7

Example

  .include "pm_libs/pm_init.s"

  ; 1st: Game Title string, must be 12 characters
  ; 2nd: Interrupts to map, OR flags for multiple interrupts
  ; 3rd: Extra flags
  pm_header "PMMusic TsT ", IRQ_KEY_POWER | IRQ_MUSIC, 0

  ; Note! For pm_music to work you MUST define IRQ_MUSIC (or IRQ_TMR2_HI)
  ; in PM_HEADER IRQs flag list!
  .include "pm_libs/pmrom_music.s"

  ; Power button, shutdown PM
irq_key_power:	; Interrupt function (same name as definition but in lowercase)
  cint CINT_SHUTDOWN	; Call shutdown in BIOS

  ; Code starts here
main:
  ; Enable power key interrupt
  enable_irqs IRQ_KEY_POWER

  ; Initialize PM Music
  mov ba, 0	; RAM pointer isn't needed
  mov hl, $00FF	; Master time of 255 (approx. 61 Hz)
  call pmmusic_init

  ; Enable interrupts
  mov f, ENABLE_IRQ

  ; Play PM Intro sound
  mov hl, pm_intro
  call pmmusic_playbgm

: halt
  jmp :b

  ; 2 bytes alignment is recommended before any pmmusic data
  ; data can be located anywhere in 2MB range and support bank crossing
  pmmusic_align

  ; PM Intro list of patterns
pm_intro:
  pmmusic_pattern pm_intro_pat

  ; PM Intro pattern
pm_intro_pat:
  ;           Note    Pw  V  Wait
  pmmusic_row N_E_5, $80, 3, 4
  pmmusic_row N____,  -1, 2, 4
  pmmusic_row N_A_5, $80, 3, 4
  pmmusic_row N____,  -1, 2, 4
  pmmusic_row N____,  -1, 0, 9
  pmmusic_row N_D_6, $80, 3, 4
  pmmusic_row N____,  -1, 2, 4
  pmmusic_row N_CS6, $80, 3, 4
  pmmusic_row N____,  -1, 2, 4
  pmmusic_row N_A_5, $80, 3, 4
  pmmusic_row N____,  -1, 2, 4
  pmmusic_row N_E_6, $80, 3, 4
  pmmusic_row N____,  -1, 2, 4
  pmmusic_row N____,  -1, 0, 24
  pmmusic_row N_D_6, $80, 3, 3
  pmmusic_row N_A_6, $80, 3, 3
  pmmusic_row N_E_7, $80, 3, 3
  pmmusic_row N_B_7, $80, 3, 3
  pmmusic_row N_E_7, $80, 3, 3
  pmmusic_row N_B_7, $80, 3, 3
  pmmusic_row N____,  -1, 0, 6
  pmmusic_end

  pm_rominfo	; Optional, report ROM and RAM size

PokeMini

Libraries