; note: these routines simply alter the data accessed in interrupt.asm
; this data is defined at the bottom of this source

;****** thxplay.library/thxPlayNote ******************************************
;
;   NAME
;       thxPlayNote -- start playing a user-specified note.
;
;   SYNOPSIS
;       void thxPlayNote(channel, note, instrument)
;                        D0:2     D1    D2
;
;       void thxPlayNote(UBYTE, UBYTE, UBYTE);
;
;       thxPlayNote(channel, note, instrument)
;
;   FUNCTION
;       Plays  one of the instruments in the THX module at a particular note
;       on  a particular channel. It is up to you to ensure that the channel
;       you  play  the  note  on is empty and so will not interfere with the
;       note  being  played.  This function is to allow you to play your own
;       notes  during  THX  play,  for  example  as  part of a game as sound
;       effects.  The  note  played is subject to the same conditions as the
;       song itself, such as the global volume control. In addition, you can
;       apply  'FX'  commands to the note. In effect, what is happening when
;       you  call  thxPlayNote()  is  that  the  'track data' for the chosen
;       channel being played is overwritten (not the module itself, just the
;       sound output). It is overwritten on the first line by your specified
;       instrument  with  note  and  FX,  then  on  consecutive lines by the
;       'blank'  note and instrument. This 'overwriting' stops only when you
;       call thxStopNote(), or stop the module naturaly.
;
;   INPUTS
;       channel    - The channel on which the note is played, from 0 to 3.
;       note       - The halfnote (pitch) at which the instrument is to be
;                    played, from 1 (C-1) to 60 (B-5).
;       instrument - an instrument from the song, from 1-63. You should know
;                    which instrument you want to play!
;
;   EXAMPLE
;       thxPlayNote(2, 8, 12) is equivalent to this in THX Sound System's
;       tracker view:
;
;       ---00000 | ---00000 | G-112000 | ---00000
;       ---00000 | ---00000 | ---00000 | ---00000
;       ---00000 | ---00000 | ---00000 | ---00000
;       [...]
;
;   SEE ALSO
;       thxStopNote(), thxNoteFX()
;
;****************************************************************************
;
;
	cnop	0,4
	xdef	thxPlayNote__iii
thxPlayNote__iii
	ifnd	_LIBRARY_
	move.l	12(sp),d0
	move.l	8(sp),d1
	move.l	4(sp),d2
	endc

	and.w	#%11,d0
	mulu.w	#bn_SIZEOF,d0
	lea	_notes(pc,d0.w),a0	; select notes[channel]

	move.b	d1,bn_note(a0)		; notes[channel].note := note
	move.b	d2,bn_ins(a0)		; notes[channel].ins  := instrument
	st.b	(a0)			; notes[channel].on   := true
	rts




;****** thxplay.library/thxStopNote ******************************************
;
;   NAME
;       thxStopNote -- stop playing user-specified note.
;
;   SYNOPSIS
;       void thxStopNote(channel)
;                        D0:2
;
;       void thxStopNote(UBYTE);
;
;       thxStopNote(channel)
;
;   FUNCTION
;       Stops  anything you started with thxPlayNote(). Please be aware that
;       notes  which  don't  fade  away  on  their own will first need to be
;       silenced with thxNoteFX($C, $00), or such
;
;   SEE ALSO
;       thxPlayNote()
;
;****************************************************************************
;
;
	cnop	0,4
	xdef	thxStopNote__i
thxStopNote__i
	ifnd	_LIBRARY_
	move.l	4(sp),d0
	endc

	and.w	#%11,d0
	mulu.w	#bn_SIZEOF,d0
	lea	_notes(pc,d0.w),a0	; select notes[channel]

	clr.b	(a0)			; notes[channel].on := false
	rts




;****** thxplay.library/thxNoteFX ******************************************
;
;   NAME
;       thxNoteFX -- perform FX command on user-specified channel.
;
;   SYNOPSIS
;       void thxNoteFX(channel, command, parameter)
;                      D0:2     D1:4     D2
;
;       void thxNoteFX(UBYTE, UBYTE, UBYTE);
;
;       thxNoteFX(channel, command, parameter)
;
;   FUNCTION
;       Performs  an  effect command on the particular channel. You can call
;       this  at  any  time,  even before you play the note, if you want the
;       note  to  start  off  with an initial effect. See THX Sound System's
;       documentation for the full list of commands and their parameters.
;
;   INPUTS
;       channel   - The channel affected
;       command   - the effect command, eg $C is the Set Volume command.
;       parameter - the parameter to the command, eg $40 is full volume.
;
;   NOTE
;       No  validation  of  the  command  or  its  parameter is done. Beware
;       feeding wrong or out of range values. Range for command is $0 to $F,
;       parameter is $00 to $FF.
;
;   SEE ALSO
;       thxPlayNote()
;
;****************************************************************************
;
;
	cnop	0,4
	xdef	thxNoteFX__iii
thxNoteFX__iii
	ifnd	_LIBRARY_
	move.l	12(sp),d0
	move.l	8(sp),d1
	move.l	4(sp),d2
	endc

	and.w	#%11,d0
	mulu.w	#bn_SIZEOF,d0
	lea	_notes(pc,d0.w),a0	; select notes[channel]

	and.b	#$F,d1
	move.b	d1,bn_fx(a0)		; notes[channel].fx    := command
	move.b	d2,bn_fxval(a0)		; notes[channel].fxval := parameter
	rts




	STRUCTURE bangnote,0
	UBYTE	bn_on		; BOOL bang in effect
	UBYTE	bn_note		; UBYTE (1-63) instrument to bang
	UBYTE	bn_ins		; UBYTE (0-60) halftone to bang at
	UBYTE	bn_fx		; UBYTE ($0-$F) fx command for bang
	UBYTE	bn_fxval	; UBYTE ($00-$FF) fx parameter
	LABEL	bn_SIZEOF
; this structure order is depended on in _playnote of interrupt.asm

; VARIABLES
_notes
chan0	dcb.b	bn_SIZEOF,0
chan1	dcb.b	bn_SIZEOF,0
chan2	dcb.b	bn_SIZEOF,0
chan3	dcb.b	bn_SIZEOF,0