From 0fe675bc96253471116e936ae9b9c18644d747ff Mon Sep 17 00:00:00 2001 From: Vince Weaver Date: Wed, 15 May 2019 12:21:39 -0400 Subject: [PATCH] pt3: update documentation --- pt3_player/README.pt3_player | 87 +++++++++++++++++++++++++++++++++--- pt3_player/docs/doc.tex | 14 ++++-- 2 files changed, 92 insertions(+), 9 deletions(-) diff --git a/pt3_player/README.pt3_player b/pt3_player/README.pt3_player index f7bf843b..6a4766b7 100644 --- a/pt3_player/README.pt3_player +++ b/pt3_player/README.pt3_player @@ -1,13 +1,90 @@ -PT3_player +The PT3_player +~~~~~~~~~~~~~~ + + by Vince "Deater" Weaver + 15 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 +~~~~~~~~~~~~~~~~~~~~ + + TODO: keyboard/other info + +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 get the player to play them, just rename them to fit the naming + scheme (I think it will just be 00.PT3, 01.PT3, 02.PT3) and replace + the existing files on the disk image with your favorite Apple II + disk tool. + + +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 - - -Notes: - signed 8-bit comparison see http://6502.org/tutorials/compare_beyond.html#2.2 diff --git a/pt3_player/docs/doc.tex b/pt3_player/docs/doc.tex index 47266f57..b3852bbc 100644 --- a/pt3_player/docs/doc.tex +++ b/pt3_player/docs/doc.tex @@ -63,15 +63,21 @@ Related Work/Earlier French-touch + guy playing on Apple II with z80 + YM5 files, limitation Vortex Tracker format By a Russian, russian docs, Delphi/Pascal. + +Research + First to C on Raspberry Pi + Validation against AY_emul + Then to 6502 assembly + Decode to screen using COUT, re-direct to "printer" on emulator, + take text output and diff against proper output with Linux tool. + Final Output - - - -