trying to add zsound pcm player example as well

compiler/res/prog8lib/cx16/syslib.p8

@@ -411,28 +411,28 @@ asmsub mouse_pos() -> ubyte @A {
 inline asmsub rombank(ubyte bank @A) {
     ; -- set the rom banks
     %asm {{
-        sta  $01            ; rom bank register (v39+, used to be cx16.d1prb $9f60 in v38)
+        sta  $01
     }}
 }
 
 inline asmsub rambank(ubyte bank @A) {
     ; -- set the ram bank
     %asm {{
-        sta  $00            ; ram bank register (v39+, used to be cx16.d1pra $9f61 in v38)
+        sta  $00
     }}
 }
 
 inline asmsub getrombank() -> ubyte @A {
     ; -- get the current rom bank
     %asm {{
-        lda  $01            ; rom bank register (v39+, used to be cx16.d1prb $9f60 in v38)
+        lda  $01
     }}
 }
 
 inline asmsub getrambank() -> ubyte @A {
     ; -- get the current ram bank
     %asm {{
-        lda  $00            ; ram bank register (v39+, used to be cx16.d1pra $9f61 in v38)
+        lda  $00
     }}
 }
 

docs/source/todo.rst

@@ -3,7 +3,6 @@ TODO
 
 For next release
 ^^^^^^^^^^^^^^^^
-- don't put main and main.start() at the top, allow other modules to sit in front (zsound)
 - pipe operator: (targets other than 'Virtual'): allow non-unary function calls in the pipe that specify the other argument(s) in the calls.  Already working for VM target.
 - add McCarthy evaluation to shortcircuit and/or expressions. First do ifs by splitting them up? Then do expressions that compute a value?
 ...

examples/cx16/zsound/pcmplayer.txt

@@ -0,0 +1,80 @@
+;...........
+; init_pcm :
+; ===========================================================================
+; Arguments: (none)
+; Returns: (none)
+; Affects: A
+; ---------------------------------------------------------------------------
+; Call this before using any of the other routines.
+;
+; Initializes the memory locations used by PCMM player to a stopped playback
+; state, sets VERA playback rate to 0 (disabled) and clears the PCM FIFO
+; also sets the volume to 15 (F).
+
+
+;...........
+; play_pcm :
+; ===========================================================================
+; Arguments: (none)
+; Returns: (none)
+; Affects: A,X,Y
+; ---------------------------------------------------------------------------
+; Call this once per frame to ensure that the PCM samples are being fed
+; into VERA's PCM FIFO. While this routine is technically IRQ-safe, it is
+; recommended that it not be executed during the VSYNC IRQ, as higher
+; quality sample streams can consume up to ~30k CPU cycles to process.
+;
+; Consistent, jitter-free low-latency playback can be assured using a line IRQ
+;
+; If using ZSM player module, it is recommended that this call happen after
+; the ZSM player's update function (playmusic) so that any PCM events will
+; be processed on the same frame.
+
+;...........
+; stop_pcm :
+; ===========================================================================
+; Arguments: (none)
+; Returns: (none)
+; Affects: A
+; ---------------------------------------------------------------------------
+; Disables PCM playback in VERA_audio_rate register, clears the FIFO, and
+; sets the PCM player module's status to clear.
+
+;.............
+; start_digi :
+; ===========================================================================
+; Arguments: Pointer to digi parameter table in memory.
+;	.A  = RAM bank
+; 	.XY = Memory address
+; Returns: none
+; Affects: none
+; ---------------------------------------------------------------------------
+; Documentation and terminology in Zsound uses the term "digi" to refer to
+; a digital audio clip, as the term "sample" also refers to an individual
+; PCM sample. Thus "digi" disambiguates between the two.
+;
+; start_digi expects a pointer to a digi parameter table in memory (low or
+; high memory are both acceptable locations. If in Hi memory, the table
+; must exist entirely within the same bank.
+;
+; The table's contents are the same as the DIGITAB struct at the
+; beginning of this inc file.
+;
+; note that start_digi is a one-shot call to trigger a digi. There is
+; currently no infrastructure to make callbacks at the end of a digi's
+; playback, or any granular controls to modify a playback in progress
+; such as volume changes, etc.
+;
+; In the future, more granular controls are planned, but the exact
+; nature and functionality are as yet to be determined.
+
+;.................
+; set_pcm_volume :
+; ===========================================================================
+; Arguments: Pointer to digi parameter table in memory.
+;	.A  = new volume level (only the 4 LSB are used)
+;
+; Returns: none
+; Affects: none
+; ---------------------------------------------------------------------------
+; Sets the PCM volume level 0..F

examples/cx16/zsound/play-pcm.p8

@@ -0,0 +1,45 @@
+%import textio
+%import cx16diskio
+%zeropage basicsafe
+%zpreserved $22,$26     ; zsound lib uses this region
+
+
+;; Proof Of Concept ZCM player using a binary blob version of zsound library by ZeroByte relocated to something usable here.
+
+; "issues": see play-zsm.p8
+
+
+main $0830 {
+
+zsound_lib:
+    ; this has to be the first statement to make sure it loads at the specified module address $0830
+    %asmbinary "pcmplayer-0830.bin"
+
+    ; note: jump table is offset by 2 from the load address (because of prg header)
+    romsub $0832 = pcm_init() clobbers(A)
+    romsub $0835 = pcm_trigger_digi(ubyte bank @A, uword song_address @XY)
+    romsub $0838 = pcm_play() clobbers(A, X, Y)
+    romsub $083b = pcm_stop() clobbers(A)
+    romsub $083e = pcm_set_volume(ubyte volume @A)
+
+    const ubyte digi_bank = 1
+    const uword digi_address = $a000
+
+    sub start() {
+        txt.print("zsound pcm digi demo program!\n")
+
+        if not cx16diskio.load_raw(8, "shoryuken.zcm", digi_bank, digi_address) {
+            txt.print("?can't load digi\n")
+            return
+        }
+
+        pcm_init()
+        txt.print("playing digi! hit enter to stop.\n")
+        pcm_trigger_digi(digi_bank, digi_address)
+        while cx16.joystick_get2(0)==$ffff {
+            sys.waitvsync()
+            pcm_play()
+        }
+        pcm_stop()
+    }
+}