
      PT3TOOLS 1.1 - 2005/02/25

              -------
              Update:
              -------

1-PT3PLAY.COM has been improved and
  now it's able to display the time-
  length of the module.

2-PT2PLAY has been coded thanks to
  the code of Sergey Bulba. The same
  options that PT3PLAY but no time-
  length is displayed.

3-PT2BASIC.BIN has been coded as
  well. Use CALL PT2LOAD, CALL
  PT2PLAY and CALL PT2STOP.

------------------------------------
1. What is PT3?
------------------------------------

PT3 is the extension of the files
produced by the ZX spectrum tracker
"Pro Tracker 3". This is one of the
most advanced PSG trackers available
on the ZX spectrum.

On the PC there is a tracker
available called "Vortex Tracker II"
(http://bulba.at.kz/vortex_e.htm).
This allows PT3 tunes to be created
in a windows environment, and thus
allows MSX users to make their own
advanced PSG tunes. The tools in
this package allow you to integrate
PT3 music in your own apps on every
MSX with at least 64Kb.

------------------------------------
2. The MSX DOS player
------------------------------------

The MSX DOS player is very basic,
it allows you to play the songs and
adds some basic extra functionality
like muting channels and setting of
the frequency mode.

The usage is:

  PT3PLAY [options] <pt3file>

Where options is empty or one or
more of the following:

  /L - don't loop song
  /P - PAL (50hz)
  /N - NTSC (60hz)
  /1 - switch channel 1 off
  /2 - switch channel 2 off
  /3 - switch channel 3 off
  /? - display a help message

------------------------------------
3. The BASIC driver
------------------------------------

The BASIC driver can be used in 
BASIC applications. It extends the
interpreter with three extra
commands;

  CALL PT3LOAD 
     load the specified filename in
     RAM (without consuming the
     available ram for your BASIC
     program).

  CALL PT3PLAY
     start playing the song that is
     currently loaded in RAM.

  CALL PT3STOP
     stop playing the song that is
     currently being played.

An example:

  10 BLOAD"pt3basic.bin",R
  20 CALL PT3LOAD("song.pt3")
  30 CALL PT3PLAY
  40 A$=INPUT$(1)
  50 CALL PT3STOP
  60 END

------------------------------------
4. The assembly driver
------------------------------------

The assembly driver can be used in
you own assembly applications.

The driver has the following basic
methods available:

  INIT
    This initializes a song
    positioned at [HL].

  PLAY
    This method should be called
    every interrupt and plays a
    single quark of the song.

  MUTE
    This methods mutes all PSG
    registers and should be called
    after the song is finished.

An example of usage of this driver
is:

         ORG $B000
         LD HL,SONG
         CALL INIT  ; initialize
   WAIT: XOR A
         CALL $00D8 ; check space
         OR A       ; if pressed
         RET NZ     ; than exit
         EI
         HALT       ; wait 1 intr.
         CALL PLAY  ; play 1 quark
         JR WAIT
         CALL MUTE  ; silence
         RET
         INCLUDE "pt3.asm"
   SONG: INCBIN "song.pt3"

There are additional features
available, if you need more info
just study the documentation in the
source code.

------------------------------------
5. Credits
------------------------------------
The original PT3 player used in this
package was written by S.V.Bulba
(vorobey@mail.khstu.ru).

This player was ported to MSX by
Alfonso D.C. (dioniso072@yahoo.es)

The tooling was written by Vincent
van Dam (vincentd@erg.verweg.com)
and Alfonso D.C.
