QTM user load information                         Steve Harrison, 1993-2013
----------------------------------------------------------------------------

As of QTM v1.27, full support for user-memory operation of the QTM player
became possible. This means it is possible to load the module to anywhere you
like in memory, and use it from there, without interfering with other
versions of QTM which could be loaded in the RMA or user-loaded by other
programs - an obvious advantage for games and demos etc. which are expected
to return to an unaltered desktop.

To use QTM in it's user-memory system, you must be using the uncompressed
module (as supplied in QTM v1.42) version of QTM (eg. not "!Crunch"ed). The
module can be loaded into an application's memory, or combined into the
application itself at the time of compiling, and used from there as described
below.

From here on, the address at which the QTM module is loaded shall be called
QTMaddr.

QTM in this form cannot be controlled via SWIs or *Commands as these relate
to the module version of QTM, which could be loaded separately in the RMA.
Instead of this, the program must communicate with QTM by using the 4 user
entry points available. These entry points are:

  QTMaddr+52  Initialisation routine
  QTMaddr+56  SWI calling routine
  QTMaddr+60  Service call entry point
  QTMaddr+64  Finalisation routine

The entry points are described below, followed by some notes on using
user-loaded QTM in different situations.

Note that in versions before v1.41 the entry points started at QTMaddr+40. The
location of the entry points had to be changed to make room for the module
flags word. 


Initialisation routine                             QTMaddr+52  (QTMaddr+&34)
----------------------------------------------------------------------------

On entry: -
On exit : -

V flag set if error occurred and QTM could not initialise.

You should call this address only once, during the programs own
initialisation routines. It sets up all QTMs internal registers and
workspace, ready for operation through the SWI entry point.


SWI calling routine                                QTMaddr+56  (QTMaddr+&38)
----------------------------------------------------------------------------

On entry: R0-R9 dependant on R11
          R11 = QTM SWI offset to call (= QTM SWI number-&47E40)

On exit : R0-R9 dependant on SWI called
          R11 preserved

V set if error occurred.

This is the main communication route to the user-loaded QTM module.

To execute a QTM SWI (see the SWI help file) put the QTM SWI number minus
&47E40 in R11 (which gives a range of &00-&1F, at the moment). The other
registers, R0-R9, should be set as required by the SWI. Then simply jump to
this entry point... couldn't be simpler!

Note: As some QTM SWIs assume SVC or an IRQ mode, if you call this entry
point from User mode, QTM will issue SWI OS_EnterOS to allow the code to
operate correctly, and then return to user mode after the operation.


Service call entry point                           QTMaddr+60  (QTMaddr+&3C)
----------------------------------------------------------------------------

On entry: R1 = service call number
          Other registers dependant on call

On exit : R1 preserved
          Other registers dependant on call

V set if error occurred.

This entry point has currently only one use, as QTM v1.27 only responds to
one useful service call. That is to inform QTM of a screen mode change.

The service number is &46 (R1=&46, other registers not required) - by calling
QTM with this number when the screen mode changes, QTM's auto pitch
correction is able to operate. You MUST call this entry point, with R1=&46,
after EVERY mode change your program issues (and every time you receive the
Wimp message Message_ModeChange, if you are using QTM in a desktop task),
otherwise the music pitch may be incorrect on pre-RiscPC computers.


Finalisation routine                               QTMaddr+64  (QTMaddr+&40)
----------------------------------------------------------------------------

On entry: -
On exit : -

No errors are returned by this call.

This address should be called after you have finished using QTM, and your
program is about to end. The routine clears up any left-over interrupts from
QTM (cancels any music playing, turns off VU bar interrupts, etc.) and
releases all claimed memory, leaving the memory taken up by the QTM module
free.

After calling this entry point, you should not make any more calls to QTM,
unless it is to the initialisation entry point, to re-initialise the module -
although you should not ever have to do this as you should only finalise when
your program is about to end.


Notes on using user-loaded QTM
------------------------------

1) Memory handling. All RMA handling by QTM is exactly the same in the
user-loaded form as in the module form, for example, songs can still be
loaded to the RMA by calling the SWI entry point for QTM_Load (R11=0) with
R1=0, the memory used for the song will still be released when the song is
cleared.

2) Using user-loaded QTM on the desktop. If you intend to use the user-loaded
version of QTM in a desktop task, as opposed to a single tasking game etc.
with a desktop front end, you must user-load the module to an RMA claimed
memory block, so that interrupts can still access QTM whatever task may be
paged in.

3) Using QTM in a game etc. with a desktop front end. You can use QTM from
your own application memory, as long as you do not access QTM from the
desktop front to your program. Also, you must return QTM to a dormant state
before going to back to the desktop, by calling QTM_Stop or QTM_Pause, and
QTM_VUBarControl, if necessary - otherwise the computer will cause an error
when an interrupt occurs and QTM is paged out of memory.

4) Oh, and remember: Don't use *Commands, or call SWIs by SWI 'QTM_....' - it
won't work!
