Documentation to BDOZ Software Development's Ultraplayer II
===========================================================

Release date of version 2.00: 26/01/1992.

Introduction
============

The whole idea of creating a 'player' that is able to recognize as 
many musical formats as possible, was thought of by a guy called 
Arnoud (personally, I believe it was I who came up with the idea, but 
alas ...). He had made one, in GfA (Musica 1.0). It was, to be fair, 
crap. Pure bull.
I had made one too, in assembler, independent from Arnoud, at the 
same time. This was a sad program, like Musica was. Then, one day, 
much later, someone called 'Vincent Partington' shows me a player he 
had designed (he had no knowledge of the fact that I had created one 
too!). It worked as an ACC, played correctly on all resolutions and 
worked, in general, fine (no music recognition though; you had to 
choose what music type was to be played ...). It was called 
GigaMus(ic).
So I started to program one too (yes, I do copy much ;)): the 
Ultraplayer. It had about the same features as GigaMusic, but was 
much easier to use (and was much more unstable, too ...). Despite of 
it's potential, however, I did not continue developing the 
Ultraplayer, hence Vincent did continue the work on GigaMusic. Just 
two weeks ago, I thought: "Well! Let's make a new player!" ... So I 
sat down, took a deep breath, and looked at the source of the 
Ultraplayer ... And what I mess it was! I threw it away, and started 
anew. Now, behold, for your very eyes: "The Brand New, Improved 
Ultraplayer II!"! I think I did quite a good job: programming a 
player from scratch in less then a weeks time, using Assembler, but 
let us not fall into temptation about talking how marvellous we are 
(hehe) ...

Usage
=====

Using the Ultraplayer II should be simple. It is advised that you've 
got a large library of Mad Max/Count Zero/Big Alec musics, for one 
music will annoy you pretty fast ...

Copy ULTRAII.ACC and ULTRAII.RSC onto your bootdrive (usually A: or 
C:), and reboot your computer, or rename ULTRAII.ACC to ULTRAII.PRG 
and run it (the Ultraplayer may be loaded using the Chameleon, but 
this is NOT advised!). After rebooting, you will find the name 
"Ultraplayer II" in your menubar. After clicking on it, you will have 
entered the Ultraplayer II (eerie, no?).

The dialog you are now presented with, offers you the following 
information:

Music On/Off    : Determines whether the music is ON or OFF ...
Fast Forward    : Clicking (and HOLDING!) this button will allow you 
                  to quickly scan through musix.
No Buffer Active: The Ultraplayer II has a built in buffer of 25 Kb. 
                  If, however, a musicfile is larger, the Ultraplayer 
                  will activate a buffer to load the music file into. 
                  The disadvantage is, that buffered musix can't be 
                  played in the background (allocated memory has to 
                  be returned to GEMDOS ...) ...
Mus. Type Loaded: Tells you what music type has been loaded.
File Loaded     : Filename of the loaded file, without extension.
Playing Mus. No.: As music files often contain >1 compositions, you 
                  can use the arrows to advance or decrease the music 
                  number.
Current Status  : Tells you what's happening.
Information     : Gives you some information about the Ultraplayer 
                  II, for you have surely forgot to read the 
                  documents ...
Continue        : Continues, exits.
Load Music      : Let's you load a music file.

Let's play some music. Click on 'Load Music'. In the fileselector 
that now appears, you can select a music file (for example 
'AWESOME.MUS', supplied in the archive). The Ultraplayer II will 
return to the main menu, soothing (?) your ears with some music. To 
see if there's more music in the file, fiddle around with the 'Music 
No.' indicator for a while (but be careful: although the Ultraplayer 
II catches off most errors, it might still bomb out!).

The Ultraplayer II features flying dialogs, too: click & hold a grey 
part in any of the dialogs, and you can place it anywhere you like. 
If there isn't enough memory to buffer the complete screen (32Kb on 
an ST, 150 Kb on a TT ...), flying the dialog will cause it not to be 
removed; click on 'Continue' however, and your screen will be back to 
normal again (sometimes, that is!) The dialog position is remembered.

From version 2.10 and onwards, it is possible to let the Ultraplayer 
II 'autoload' a music file; it will be played whenever you run the 
Ultraplayer! Setting up an auto-file can be done in two ways: either 
you fetch a diskmonitor, and search around the Ultraplayer for the 
bytes '&^&' and '^&^' (they lie somewhere at the end of the program). 
These two signs respectively mark the start of the filename to load & 
the start of the pathname (pathname+filename, I mean ...). Just type 
the file over there, and be sure to terminate the two strings using a 
NULL byte.
Or you can use the program that's included in the LZH, which is much 
easier, infact :) ... You'll have to specify the filename of the 
Ultraplayer II, and after having scanned the file for the two marks 
(see above), you can select a file, clear the autofile, or quit the 
program.
NOTE: You cannot set musix larger then 25 K, or musix that cannot be 
played in the background to autoload.

Program specifications & queer things for version 2.10
======================================================

- Recognizes & plays the following music types (types with an 
  asterisk in front can't be played in the background):

  "Mad Max" PC Relativ (his newer ones, NOT Thrust or Warhawk or 
  (Arjen!)) ....
  "Big Alec" without digidrums.
  "Count Zero" with header.
  "Count Zero" without header (TriSound MODules (converted with the 
  program "TRIMOD" are recognized and played as Count Zero without 
  header! And it works! I'll get myself a copy of this TRIMOD as soon 
  as possible!)).
  *"Mad Max Digidrum" only the types that are ripped correctly (ONE 
  file!)
  *"Synth Dream" digidrum, only the 10Khz ones (samples+song in one 
  file).

- Keyclick remains on (if it WAS on!), while playing. This is crazy, 
  but I fancied it to be the best solution after all.
- Should work on all ST-compatible models (ST/Mega ST/STE/Mega 
  STE/Stacy/TT/ST-Book/Falcon), but I ain't sure (I've only got an 
  ST!).
- As the Mad Max format is VERY 'global' (ie. Synth Dream music looks 
  a LOT like it!), it might be that the player mistakes something for 
  a Mad Max thingie. LOAD A NEW FILE as soon as possible (if 
  possible, that is!!!) when this happens!!! It might crash your ST!
- During file transfers, it might be that the Ultraplayer shuts 
  down for a while (leaving you with an annoying 'BEEEEEEP!'). This 
  is normal, and is caused by the OS, which temporarily shuts Timer C 
  down when doing certain (?) things with the RS232 (Modem).
- A feature called 'autoloading' has been added in version 2.10. It 
  will cause the Ultraplayer II to load a music file when it is 
  started. See 'Usage'.

Known bugs
==========

- 'Drag' your mousepointer over the 'music on/off' button; and the 
  music will do exactly the opposite of what the box says it does! 
  Doubleclicking also does the job.

Technical Titbits
=================

The Ultraplayer II is a rather low-level program, despite of it's 
nice and harmless look. I do not know how well (if ...) it will work 
on TT's and Mega STE's, but it should work fine.
The Ultraplayer II installs a cookie of 'XMuz', with a pointer to 
it's cookieblock, offering you some useable information (see below). 
It also installs an XBRA ID of 'XMuz'.
To achieve 50hz playing on all syncmodes, the Ultraplayer II uses 
Timer C for replaying the music (200hz/4=50hz ...). The routine was 
written as fast as I possibly could, and uses about 1 to 2 percents 
of the CPU time, including the music replay routine (NOTE: some music 
programmers use very slow replay routines, sometimes needing upto 7 
percent of time!). To get a clear look at the time usage, try Quick 
Index (run before and after!).
The phase where most musix bomb, is the initialising phase; so the 
Ultraplayer II installs it's own bomb routines for the time the music 
is inited. Afterwards, the old bomb routines are given back 
(ofcourse).
The screen buffering is resolution independent, although I do not use 
any VDI copy functions (buffering the whole screen is much easier, 
and as the Ultraplayer II was written in ASM, it might be faster too 
:) ...).

   The Cookieblock:

   Name:       Size:    Description:
   Ultra_Id    LONG     Pointer to the Application ID returned by 
                        AES. Can be used to call upon the Ultraplayer 
                        II by using APPL_WRITE.
   Ultra_Vers  LONG     Pointer to the string which tells you the 
                        version number.
   Ultra_Num   WORD     How many music types can be played and 
                        recognized (rather: the space there is for 
                        music init routines etc.).
   Ultra_Desc  LONG     Pointer to the music descriptor strings. Each 
                        of the strings is 21 bytes in size, 
                        terminated by a NULL byte.
   Ultra_Init  LONG     Pointer to the Initialization table of the 
                        Ultraplayer II. This is built up of several 
                        pairs of LONGs, in which the first LONG 
                        points to the routine to jump to, and the 
                        second is the offset to jump with. If the 
                        first LONG (routine) is 0, the Ultraplayer II 
                        jumps to the buffer (taking the offset into 
                        account, ofcourse). An example:

                        init_routs: DC.L rts,0 ; Jumps to routine 
                                                 RTS, with an offset 
                                                 of 0 bytes.
                                    DC.L 0,8   ; Jumps to the buffer, 
                                                 with an offset of 8 
                                                 bytes.

   Ultra_Play  LONG     See above, but for the play routines.

   Ultra_Type  LONG     Pointer to the WORD that specifies which 
                        music type we loaded (this is used to jump to 
                        the correct Init & Play routines, and also 
                        for the descriptions; eg. Ultra_Type is 4, 
                        then the 4th 'line' in Ultra_Init and 
                        Ultra_Play are used (Ultra_Type * 8 bytes is 
                        added to Ultra_Init and Ultra_Play)).
   Ultra_Mtype LONG     Pointer to the routine that checks the music 
                        types.

   Ultra_Buf   LONG     Pointer to the pointer (...) of the buffer 
                        (as the Ultraplayer II will Malloc() buffers 
                        too, when the internal 25 K buffer is too 
                        small).

   If you want to write your own play routines etc., you must proceed 
   as follows:

   1) Replace the Ultra_Mtype routine with one of yourself (Move.L 
   #newtype,Ultra_Mtype).
   2) Fill in the Ultra_Type flag.
   3) Check how many music types can be recognized (= how large is 
   space for the initrouts etc ...), and fill in the Ultra_Play and 
   Ultra_Init tables (MAY NOT CONTAIN MORE MUSIX THEN SPECIFIED IN 
   ULTRA_NUM, OR YOU'LL OVERWRITE VARIOUS OTHER FLAGS (among which 
   the cookieblock)!)
   4) Change the Ultra_Desc descriptor strings.
   5) Pray.

   I haven't tested this myself, so I don't know how this 'll work! 
   But, all of the code is there, so ...

Disclaimer
==========

********************************************************************
********************************************************************
***  TAKE GREAT CARE IN USING THE ULTRAPLAYER II! WHEN IN DOUBT  ***
***  OVER A MUSIC FILE, SAVE!!! NEVER TRY A NEW MUSIC FILE YOU   ***
***  JUST GOT WITHOUT SAVING! ALTHOUGH I DID THE BEST I COULD    *** 
***  TO CATCH ERRORS AND REMOVE BUGS, IT IS IMPOSSIBLE TO SAY    ***  
***  WHETHER A MUSIC FILE IS ERRORFREE AND CLEAN!                ***
***  I CANNOT BE HELD RESPONSIBLE FOR ANY DAMAGE DONE BY THE     ***
***  ULTRAPLAYER II TO EITHER YOUR HARD- OR SOFTWARE!!!          ***
********************************************************************
********************************************************************

Things yet to do
================

- Buffer size determinable by the user.
- Sort of 'modular' concept.

But, nobody uses this program anyway, except me, so ... <schnuff> ...

Update history
==============

Ultraplayer II/2.10: Removed a little (stupid) bug, and added the 
nice 'autoload' feature. Also made a program which enables you to 
edit the autoload swiftly.

Ultraplayer II/2.00: The first version ever, hope you like it (well, 
what should I say!!!)!!!
