mirror of
https://github.com/irmen/prog8.git
synced 2024-07-05 22:29:04 +00:00
196 lines
7.5 KiB
Plaintext
196 lines
7.5 KiB
Plaintext
;..............
|
|
; init_player :
|
|
; ===========================================================================
|
|
; Arguments: (none)
|
|
; Returns: (none)
|
|
; Affects: A
|
|
; ---------------------------------------------------------------------------
|
|
; Call this before using any of the other routines.
|
|
;
|
|
; Initializes the memory locations used by ZSM player to a stopped playback
|
|
; state, with the data pointer pointing at a dummy "end-of-data" command frame.
|
|
|
|
|
|
;............
|
|
; playmusic :
|
|
; ===========================================================================
|
|
; Arguments: none
|
|
; Returns: none
|
|
; Affects: See stepmusic
|
|
; ---------------------------------------------------------------------------
|
|
; 60hz frontend for stepmusic.
|
|
; Call it once per frame to play ZSM music.
|
|
;
|
|
; Playmusic calls stepmusic however many times is determined from the ZSM tick
|
|
; rate header information. This function does not "smooth" time - i.e. it
|
|
; just calls stepmusic N times in a row. For more accurate timing
|
|
; you should generate your own timing source and call stepmusic directly.
|
|
;
|
|
; NOTE: playmusic calls stepmusic, WHICH IS NOT IRQ SAFE! Use playmusic_IRQ instead
|
|
; if you wish to run the music update during the IRQ handler, or else your
|
|
; handler should save and restore the VERA ctrl register and the address
|
|
; registers for the data0 data port.
|
|
|
|
|
|
;................
|
|
; playmusic_IRQ :
|
|
; ===========================================================================
|
|
; IRQ-safe version of playmusic, which restores VERA registers and the active
|
|
; HiRAM bank.
|
|
;
|
|
; It does NOT save or restore the CPU registers. Your IRQ handler should
|
|
; pull those from the stack prior to RTI as usual if not jumping into the
|
|
; Kernal's once per frame routine.
|
|
;
|
|
; Alternatively, you can use this interface as a VERA-safe call from outside
|
|
; of IRQ handlers. A,X,and Y are still clobbered by stepmusic.
|
|
|
|
|
|
;............
|
|
; stepmusic :
|
|
; ===========================================================================
|
|
; Arguments: (none)
|
|
; Returns: Carry flag: (currently broken) 0=playing, 1=stopped or looped
|
|
; Affects: A,X,Y, VERA CTRL and data port 0 address registers
|
|
; ---------------------------------------------------------------------------
|
|
; Advances the music by one tick.
|
|
; Music must be initialized by startmusic before this will have any effect.
|
|
;
|
|
; This routine may be removed from the API in future revisions!
|
|
;
|
|
; Call as many times per frame as required by the ZSM's playback rate.
|
|
; (usually 60Hz - once per frame)
|
|
; THIS ROUTINE IS NOT SAFE to call directly during IRQ, as it clobbers VERA
|
|
; registers w/o fixing them (for speed reasons). If your program
|
|
; is designed to run the music player during an IRQ, use one of the IRQ-safe
|
|
; wrapper functions that save and restore VERA before calling this
|
|
; core routine, or else be sure to save the states of the affected VERA registers
|
|
|
|
|
|
;-----------------------------------------------------[Music Control]--------
|
|
|
|
|
|
;.............
|
|
; startmusic :
|
|
; ===========================================================================
|
|
; Arguments:
|
|
; A : HIRAM bank of tune
|
|
; XY : Memory address of beginning of ZSM header
|
|
; Returns: Carry flag: 0=success, 1=fail
|
|
; Affects: A,X,Y
|
|
; ---------------------------------------------------------------------------
|
|
; Uses the ZSM header to determine the default playback parameters.
|
|
; Copies them into the active data structures, and adjusts header pointers
|
|
; such as loop and PCM (future) sample bank offsets relative to where the
|
|
; ZSM was actually loaded into memory.
|
|
;
|
|
; Calls setmusicspeed with the song's default play speed from header.
|
|
; Defaults the looping behavior based on the ZSM being played. If the tune
|
|
; contains a loop, the playback is set for infinite loop mode. If it does
|
|
; not, the loop pointer is set to the beginning of the tune, but looping
|
|
; remains disabled.
|
|
; You may call set_loop, force_loop, or disable_loop to modify these defaults
|
|
; afterwards.
|
|
|
|
|
|
;............
|
|
; stopmusic :
|
|
; ===========================================================================
|
|
; Arguments: (none)
|
|
; Returns: (none)
|
|
; Affects: (none)
|
|
; ---------------------------------------------------------------------------
|
|
; Halts music playback, silences all voices used by the current tune,
|
|
; and clears music channel mask
|
|
|
|
|
|
; ------------------------------------------------[On-The-Fly Controls]------
|
|
|
|
|
|
;................
|
|
; setmusicspeed :
|
|
; ===========================================================================
|
|
; Arguments:
|
|
; X/Y : Playback speed in Hz. (x=lo, y=hi)
|
|
; Returns: (none)
|
|
; Affects: A,X,Y
|
|
; ---------------------------------------------------------------------------
|
|
; Converts Hz into ticks/frame, and adjusts playback speed to the new rate.
|
|
; Setting a 60hz song to play back at 120hz will play at double speed and
|
|
; setting it to 30hz will play at 1/2 speed.
|
|
; (I suppose I should make an accessor function to return the native speed
|
|
; of a ZSM so that you don't have to guess in order to make calculated speed
|
|
; changes)
|
|
|
|
|
|
;.............
|
|
; force_loop :
|
|
; ===========================================================================
|
|
; Arguments: .A = number of times to loop the music. 0 = infinite
|
|
; Returns: none
|
|
; Affects: none
|
|
; ---------------------------------------------------------------------------
|
|
; Note that if the music was intended to be a one-shot playback (i.e. contains
|
|
; no loop), this will force looping play of the entire song. Use set_loop
|
|
; to modify the looper's behavior without forcing looping play of non-looped
|
|
; songs.
|
|
|
|
|
|
;...........
|
|
; set_loop :
|
|
; ===========================================================================
|
|
; Arguments: .A = number of times to loop the music. 0 = infinite
|
|
; Returns: none
|
|
; Affects: none
|
|
; ---------------------------------------------------------------------------
|
|
; Sets the number of repeats that loopback mode will perform after the current
|
|
; pass through the song is finished. If the playback mode is one-shot (no looping)
|
|
; then this will have no effect.
|
|
|
|
|
|
;...............
|
|
; disable_loop :
|
|
; ===========================================================================
|
|
; Arguments: none
|
|
; Returns: none
|
|
; Affects: none
|
|
; ---------------------------------------------------------------------------
|
|
; When music reaches EOF, playback will stop, regardless of loops in the tune.
|
|
; Has no effect if looping was not already enabled.
|
|
|
|
|
|
;-----------------------------------------------------[Information]----------
|
|
|
|
|
|
;...............
|
|
; set_callback :
|
|
; ===========================================================================
|
|
; Arguments:
|
|
; .XY = address of callback function
|
|
; Returns: none
|
|
; Affects: none
|
|
; ---------------------------------------------------------------------------
|
|
; Sets a notification callback whenever a tune finishes or loops.
|
|
; The callback passes the following parameters:
|
|
; Z=0 if music is stopped, Z=1 if music is playing
|
|
; .A = number of remaining loops
|
|
|
|
;.................
|
|
; clear_callback :
|
|
; ===========================================================================
|
|
; Arguments: none
|
|
; Returns: none
|
|
; Affects: A
|
|
; ---------------------------------------------------------------------------
|
|
; Disables the EOF notification callback
|
|
|
|
;..................
|
|
; get_music_speed :
|
|
; ===========================================================================
|
|
; Arguments: none
|
|
; Returns: .XY = song's play rate in Hz
|
|
; Affects: none
|
|
; ---------------------------------------------------------------------------
|
|
; This function returns the default playback rate in Hz of the active song.
|
|
; This is NOT the current playback speed, but the speed in the song's header.
|