dos33fsprogs/pt3_player
2019-12-28 23:51:12 -05:00
..
docs
music pt3_lib: fix issue where vibrato was broken 2019-08-31 01:34:01 -04:00
table_gen pt3: update z80 checker 2019-10-16 22:07:01 -04:00
visual
dump.bas
empty.dsk ootw: ending: update Makefile to know about music file 2019-08-21 15:04:07 -04:00
FAQ.pt3_player pt3: update FAQ 2019-05-18 11:12:16 -04:00
fire.s optimize fire some more 2019-06-01 01:49:30 -04:00
gr_fast_clear.s pt3_player: optimize clear_screens 2019-06-07 21:31:33 -04:00
gr_offsets.s pt3: some work on visualization 2019-05-16 11:38:57 -04:00
gr_putsprite.s pt3_player: fix the putsprite code 2019-06-07 21:35:50 -04:00
gr_setpage.s pt3: some work on visualization 2019-05-16 11:38:57 -04:00
hardware.inc pt3: split hardware.inc off from zp.inc 2019-06-09 01:01:28 -04:00
HELLO
hello_debug.bas
hello.bas pt3_player: update to auto-detect mockingboard slot 2019-12-28 23:20:17 -05:00
interrupt_handler.s pt3: create combined version for pt3_lib and pt3_player 2019-09-11 16:08:36 -04:00
keypress_minimal.s slightly faster key handling 2019-06-03 11:58:29 -07:00
Makefile pt3_player: update to auto-detect mockingboard slot 2019-12-28 23:20:17 -05:00
OPTIMIZATION.txt pt3_player: update with optimized/fixed code 2019-09-11 00:32:59 -04:00
pageflip.s pt3: visualize: we have fire 2019-05-16 13:03:33 -04:00
pt3_dumper.s pt3: doing some testing, still looking for bugs 2019-11-20 15:18:24 -05:00
pt3_lib_core.s pt3_player: update to auto-detect mockingboard slot 2019-12-28 23:20:17 -05:00
pt3_lib_init.s pt3_lib: fix minor typo 2019-12-28 23:29:16 -05:00
pt3_lib_irq_handler.s pt3_player: update to auto-detect mockingboard slot 2019-12-28 23:20:17 -05:00
pt3_lib_mockingboard_detect.s pt3_player: update to auto-detect mockingboard slot 2019-12-28 23:20:17 -05:00
pt3_lib_mockingboard_setup.s pt3_lib: make more similar to the cycle-counting version 2019-12-28 23:51:12 -05:00
pt3_player.dsk pt3_lib: make more similar to the cycle-counting version 2019-12-28 23:51:12 -05:00
pt3_player.s pt3_player: update to auto-detect mockingboard slot 2019-12-28 23:20:17 -05:00
pt3_table_test.s pt3: create combined version for pt3_lib and pt3_player 2019-09-11 16:08:36 -04:00
pt3_timer.s pt3_player: update to auto-detect mockingboard slot 2019-12-28 23:20:17 -05:00
put_letters.s pt3_player: optimize letter drawing code 2019-06-07 21:39:56 -04:00
qkumba_rts.s pt3_player: add iic support 2019-06-07 16:52:31 -04:00
random16.s pt3: visualize: we have fire 2019-05-16 13:03:33 -04:00
README.pt3_player pt3: add looping support 2019-05-17 13:19:04 -04:00
song_list.inc pt3: doing some testing, still looking for bugs 2019-11-20 15:18:24 -05:00
text_print.s pt3: save an instruction in text print 2019-06-18 13:43:13 -04:00
TODO pt3: work on tone table 2019-05-23 00:28:55 -04:00
zp.inc pt3_player: update to auto-detect mockingboard slot 2019-12-28 23:20:17 -05:00

The PT3_player
~~~~~~~~~~~~~~

	by Vince "Deater" Weaver
	17 May 2019
	http://www.deater.net/weave/vmwprod/pt3_player/

	Plays Vortex Tracker II .pt3 files on the Apple II


Background
~~~~~~~~~~
	Vortex Tracker is commonly used to create AY-3-8910 music for the
	ZX Spectrum and Atari ST systems.  A large number of great pt3 files
	can be found on the internet.

	There are many benefits to using .pt3 format, but until now there
	was no player available for Apple II/6502.  (Though some people
	had been playing the files using a z80-card in their system).
	Part of the challenge was the documentation for the format was
	in Russian, and the only source-code available for .pt3
	players were in uncommented z80 assembly or else Russian-commented
	Pascal.

	Why .pt3?  Why not play YM5 files?
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	There are already many projects (including one of my own) for
	playing the .YM file format, which is much simpler.  It is just a
	series of AY-3-8910 raw-register dumps which can quickly be sent
	to the Mockingboard.

	The issue is uncompressed YM5 files are really huge.  So you have to
	do some sort of decompression on the fly, and even then you are looking
	at 32k+ or more of RAM.  This might be fine on an Apple IIe with
	128k of RAM, but I am targetting a II+ where I don't have that much
	available.

	A PT3 file is a tracker format, meaning a list of notes, patterns, and
	ornaments and can be played in place.  Once you load the music file and
	the player, no additional RAM is needed at all.  It does take more CPU
	than playing a YM5 file.


Using the PT3_PLAYER
~~~~~~~~~~~~~~~~~~~~

	The pt3_player.dsk should boot automatically.

	Controls:
		Right/Left arrow	Switch songs
		Spacebar		Pause playback.
		M			Switch from 1MHz to 1.77MHz mode
		L			Enables looping in the song

	FUTURE FEATURES:
		Key to disable visualization
		Key to skip ahead/back in pattern list


ZX Compatability:
~~~~~~~~~~~~~~~~~

	ZX Spectrum songs expect a 1.77MHz AY-3-8910, but the Apple II
		is 1MHz so by default songs would sound lower
		pitched.  By default now we multiply by 9/16 to scale
		things properly, but that does eat up extra CPU cycles.
		You can toggle this on/off by pressing "M" when playing.

	In theory we can create songs that expect 1MHz, but the pt3 format
		has no way of indicating this.

Adding other files
~~~~~~~~~~~~~~~~~~

	Unlike YM5 players which require complicated preparation of files
	(with often complex, or hard-to find tools) the PT3_PLAYER can in
	theory play plain .pt3 files.

	To play your own files, just copy the file you want over an
	existing file (using the same filename).

	TODO: It would be great if the player was smart enough to catalog
	the disk and just play all the files it finds, but that's a level
	of disk manipulation I don't have time to mess with right now.


Other Future Plans
~~~~~~~~~~~~~~~~~~

	The PT3 format can handle 6-channel songs (which a Mockingboard
	can play).  I'd like to add support for this, but it will
	need some low-level changes to the code.

Code Optimization
~~~~~~~~~~~~~~~~~

	The original working code is about 4k (not counting the pt3 file)
	and has an overhead of roughly 20% when playing a song interrupt-driven
	at 50Hz.

	I'm keeping some stats here as I try to optimize the size and speed.

	Song: "Summer of Rain"
	~~~~~~~~~~~~~~~~~~~~~~
					lz4 compressed
	pt3 size:	raw size:	ym5 size:	pt3.lz4:
	3871		137015		7637		1793

	Decoder Type	size	ZP use	decode	total	CPU overhead
	-------------------------------------------------------------
	Original	4k(?)	22B	28.16s	171s	16%


Random Programming Reminders
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

ASR = CMP #$80 / ROR

signed 8-bit comparison
see http://6502.org/tutorials/compare_beyond.html#2.2

          SEC       ; prepare carry for SBC
          SBC NUM   ; A-NUM
          BVC LABEL ; if V is 0, N eor V = N, otherwise N eor V = N eor 1
          EOR #$80  ; A = A eor $80, and N = N eor 1
    LABEL

If the N flag is 1, then A (signed) < NUM (signed) and BMI will branch
If the N flag is 0, then A (signed) >= NUM (signed) and BPL will branch