Vortex Tracker II v1.0 PT3 player for ZX Spectrum Release 6
(c)2004 S.V.Bulba <vorobey@mail.khstu.ru> http://bulba.at.kz
Release date: 19 of December 2004

Common remarks
--------------

This PT3-player subject is a playing PT3-modules of all ZX Spectrum Pro Tracker
version 3 by one player only. You no need now to play PT3.3 modules in one
player, PT3.6 modules in another one and so on. Any module of any known version
will be played correctly in this new universal PT3-player.

Before this release project was compiled in assembler for Win32:

ZXASM, Z80 cross-platform assembler version 1.4.2
(C) Copyright 1997-2002 by Ilya G. Aniskovets

But current release cannot be compiled in it due its bug and limitations. So,
use corrected sources for ZX Spectrum assemblers (Alasm and ZX Turbo Assembler
3.10).

Files
-----

VTII10bA.asm - source Z80 assembler code.
VTII10bA.h - same text is prepared for Alasm.
VTII10bA.txt - same text is prepared for ZX Asm 3.10.
VTII10bA - assembled binary code block to load at #C000 address.

Entry points
------------

Before playing call START (loading) address. Player are not realocable, so you
need to assemble with other ORG value, if you want to load code at other than
#C000 address, also you can place VARS area to any other address too. After
calling START AY is stop any sounding. At START+10 is located SETUP byte, where
bit 0 is used to control looping of melody. At any time you can set bit 0 to
disable loop. Bit 7 can be checked at any moment, it is set after reaching end
of module (finishing playing of last position).

In current compilation module must be loaded after variables (by default). Of
course, you can change it in source or in assembled code. Also you can specify
module address in HL as follows:

	LD HL,PT3ModuleAddress
	CALL START+3

The easiest way to compile player with module is using built-in Vortex Tracker
II exporter to ZX Spectrum, where you can specifiy both START address and setup
byte.

By calling START you are proceeding INIT procedure, which analizes PT3 module
header and prepares corresponding note and volume tables (it is need for correct
playing of modules of different PT3 subversions). Also you can call START after
stopping playing to mute AY sound. In last case you can call START+8 to simple
mute AY sound, to continue playing simply continue calling START+5 as usually.

To play, call START+5 address each 1/50 of second (interrupt). Playing selects
right portamento algorithm for old (v3.5-) and new (v3.6+ or VT II) modules.
During running PLAY subprogram no any interrupts are expected, it is your task
to right call PLAY. For example, next example is totaly right:

	CALL #C000 ;calling init
	EI ;enable interrupts
_LP	HALT ;wait for next interrupt
	CALL #C005 ;call play, player uses 9500 tacts max,
;so no interrupt can be before next HALT
	XOR A ;test keyboard
	IN A,(#FE)
	CPL
	AND 15
	JR Z,_LP
;1 first way to mute sound (you can resume playing from current place):
	CALL #C008 ;mute AY sound

;2 second way to mute sound (resuming playing is able only from begin):
;2	CALL #C000 ;reset AY to stop sound

	RET

At START+11 address word pointer is placed. This is pointer to module to current
position. To calculate position number use code like this:

	LD HL,(START+11)
	LD DE,-PT3ModuleAddress-201
	ADD HL,DE

In HL register will be position number (H will be 0 if module is not modified).

Example of playing without loop:

	LD A,1
	LD (START+10),A
	CALL START
	EI
LOOP	HALT
	CALL START+5
	LD A,(START+10)
	RLA
	JR NC,LOOP
	RET

Loop three times:

	CALL START
	LD A,3
	EI
LOOP	PUSH AF
	HALT
	CALL START+5
	POP AF
	LD HL,START+10
	SLA (HL)
	JR NC,LOOP
	DEC A
	JR NZ,LOOP
	CALL START+8
	RET

Read also all comments in source file.

Sergey Bulba

19 of September - 19 of December 2004
