mirror of
https://github.com/deater/dos33fsprogs.git
synced 2024-09-10 23:54:33 +00:00
.. | ||
empty.dsk | ||
hardware.inc | ||
hello.bas | ||
interrupt_handler.s | ||
LICENSE | ||
Makefile | ||
pt3_lib_core.s | ||
pt3_lib_init.s | ||
pt3_lib_irq_handler.s | ||
pt3_lib_mockingboard_detect.s | ||
pt3_lib_mockingboard_setup.s | ||
pt3_lib.dsk | ||
pt3_test.s | ||
README.pt3_lib | ||
zp.inc |
The PT3_player Library version 0.2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ by Vince "Deater" Weaver <vince@deater.net> http://www.deater.net/weave/vmwprod/pt3_lib/ Last Update: 28 December 2019 Plays Vortex Tracker II .pt3 files on the Apple II Background: ~~~~~~~~~~~ This code is meant as a relatively simple, reasonably optimized version of the PT3 Vortex-Tracker player for use in other programs. For some more background on this you can watch the talk I gave at Demosplash 2019 on this topic. What is a PT3 file? ~~~~~~~~~~~~~~~~~~~ A PT3 file is a tracker format with a compact file size used on systems with AY-3-8910 based audio. This is most commonly the ZX-spectrum and Atari ST machines. Originally most PT3 players were in z80 assembly language for use on Z80 based machines. I have written code that will play the files on modern systems (using C) and also the included code designed for the 6502-based Apple II machines with Mockingboard sound cards installed. You can find many pt3 files on the internet, or you can use the VortexTracker tracker to write your own. Using the Code (irq driven): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See the "pt3_test.s" example. The code is in cc65 6502 assembly language but should be relatively easy to port to other assemblers. To get a pt3 file playing: + Optionally include "pt3_lib_mockingboard_detect.s" and call "mockingboard_detect" and "mockingboard_patch" if you want to auto-detect which slot the mockingboard is in. Otherwise it will default to Slot#4 The patch code does a vaguely unsafe find/replace of $C4 live patch of the slot values, if you want a safer (but much larger) version you can go into the file and ifdef out the right code. + Be sure to either include the pt3 file as a binary, or load it from disk to a buffer pointed to by PT3_LOC. Not the beginning of the song needs to be aligned on a page boundary (this makes the decode code a bit more simple) + If you want to make the code more compact but use a lot of the zero page, you can set PT3_USE_ZERO_PAGE in "pt3_lib_core.s" This will use zp $80-$FF but make the pt3 code a bit faster/smaller + You can set the interrupt speed in pt3_lib_mockingboard_setup.s Generally files you find online are 50Hz. For less overhead you can set something like 25Hz but in that case you'll want to adjust the speed in the tracker otherwise the songs will play at the wrong speed. + Vortex tracker by default assumes a system with a 1.77MHz clock and sets frequencies accordingly. The Mockingboard runs at 1MHz, so the pt3_lib converts on the fly. For less overhead you can have the tracker generate 1MHz music and strip out the 1.77MHz conversion code. + If you want the music to Loop then set the LOOP value to 1. Using the Code (cycle-counted): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ I started work on a cycle-counted (deterministic cycle count) pt3 decoder, but it turned out to be large and complex enough to not be worth the trouble. You can still use pt3 files in cycle-counted demos. See the ../demosplash2019/ directory for an example. What this code does is decode the pt3 files to memory during non-cycle-counted times, and then use a deterministic playback function to play back this music. Each frame of music decodes to 11bytes of register info, which means at 60Hz you can get roughly 4s of music per 3kB of RAM. Overhead: ~~~~~~~~~ It depends exactly on what features you use, but in general it will use around 3KB of RAM plus the size of the PT3 file (which is often a few K). Playback overhead depends on the complexity of the sound file but is typically in the 10% to 15% range when playing back at 50Hz. The player also uses 26 zero-page locations. More compact/faster code can be generated if you're willing to sacrifice 128+ zero page locations.