QTMPlayer SWIs

This file documents the various SWIs than can be used to control QTMPlayer's layer interface. The SWI chunk for QTMPlay is 0x4cec0, which is an Acorn allocated chunk.
Note that QTMPlayer plays all its songs in dynamic area or on pre-RiscPC machines in a locked Dynamite area, to prevent fragmentation of the RMA.

The re-entrancy of the SWI depends on the re-entrancy of the player module being used at the time of the call. Most player module SWIs (apart from ones associated with loading songs into memory) are re-entrant, but you will have to check the documentation for the player module.

Note that the format of QTMPlayer SWIs has changed considerably since v0.12

The QTMPlayer SWIs are as follows:

QTMPlayer_Recognise
(SWI &4CEC0)

Find out if QTMPlayer can cope with a song
On entry
R0 = pointer to pathname
On exit
R0 = -1 if file not recognised
R0 = layer number (0-x) which deals with this type of file if recognised
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call would be most use in a desktop program, in order to intercept Message_DataOpen and check whether the contents are loadable by QTMPlayer.
Related SWIs
QTMPlayer_Load

QTMPlayer_Load
(SWI &4CEC1)

Loads a file into address space and starts playing it
On entry
R0 = pointer to pathname
R1 = layer to play it with (returned by QTMPlayer_Recognise) or -1 to recognise on-the-fly
On exit
R0, R1 preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call loads a file in and starts it playing. If R1 is -1 on entry, QTMPlayer_Load will recognise the file on the fly, and return an error if it was not recognised. Alternatively, you can do the process in two stages by reading the layer with QTMPlayer_Recognise necessary to play the file, and then using this call to load the file in.
Related SWIs
QTMPlayer_Recognise, QTMPlayer_Unload

QTMPlayer_Unload
(SWI &4CEC2)

Unloads the currently playing song from memory
On entry
No parameters passed in registers
On exit
Registers preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call unloads the current song from memory and finishes use of the associated layer (quitting any play modules, etc.).

QTMPlayer_Pause
(SWI &4CEC3)

Pauses the currently playing song
On entry
No parameters passed in registers
On exit
Registers preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call pauses the song at the current position.
Related SWIs
QTMPlayer_Restart

QTMPlayer_Restart
(SWI &4CEC4)

Restarts a paused or stopped song
On entry
No parameters passed in registers
On exit
Registers preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call restarts a paused song from the position the song was paused at, and starts playing a stopped song from the beginning.
Related SWIs
QTMPlayer_Stop, QTMPlayer_Pause

QTMPlayer_Stop
(SWI &4CEC5)

Stops the currently playing song
On entry
No parameters passed in registers
On exit
Registers preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call stops the currently playing song, but does not unload it.
Related SWIs
QTMPlayer_Restart

QTMPlayer_Position
(SWI &4CEC6)

Sets and returns the current position in the song
On entry
R0 = new position, or -1 to leave position and event unchanged
R1 = new event
On exit
If R0 was -1 on entry:
R0 = current position (ranging from 0 up to R2-1)
R1 = current event
R2 = number of positions in the song
Otherwise, R0-R2 corrupted
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call determines the length and progress through the current song, or sets the position.

QTMPlayer_Sample
(SWI &4CEC7)

Performs miscellaneous sample operations
On entry
R0 = reason code
Other registers depend on reason code
On exit
Registers depend on reason code
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call performs miscellaneous sample operations.

QTMPlayer_Sample 0
(SWI &4CEC7)

Reads information about a sample
On entry
R0 = 0 (reason code)
R1 = sample number
On exit
R0 = pointer to null-terminated sample name
R1 = length of sample in bytes
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call reads information about a sample.

QTMPlayer_Sample 1
(SWI &4CEC7)

Plays a sample
On entry
R0 = 1 (reason code)
R1 = sample number
R2 = pitch (an Amiga note value ranging 1-36)
R3 = volume (linear, 0-64)
On exit
R0-R2 corrupted
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call plays a sample on a layer-defined channel.

QTMPlayer_Volume
(SWI &4CEC8)

Reads and sets the current volume
On entry
R0 = new volume, or -1 to read
On exit
R0 = volume if R0 was -1 on entry
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call reads and sets the current volume. The volume is a value between 0 and 64 (including both 0 and 64), linearly scaled.

QTMPlayer_Quality
(SWI &4CEC9)

Sets the playback quality
On entry
R0 = new sample mixing rate (in microseconds)
On exit
Registers preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call reads and sets the sample mixing rate. Not all layers may support this call.

QTMPlayer_SoundSystem
(SWI &4CECA)

Performs miscellaneous sound system operations
On entry
R0 = reason code
Other registers depend on reason code
On exit
Registers depend on reason code
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call is a multi-purpose sound system call. The currently supported reason codes are:
reason code 0 -- R1 = new transparent sound system state
This sets the state of the transparent sound system. If the transparent sound system is turned on, then system beeps can be heard whilst a song is playing. The only layer known to support this call currently is QTMTracker.

QTMPlayer_SongInfo
(SWI &4CECB)

Reads information about the currently loaded song
On entry
No parameters passed in registers
On exit
R0 = pointer to null-terminated song name string
R1 = pointer to null-terminated song author string
R2 = pointer to null-terminated extended song information string
R3 = duration of song in seconds
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call returns miscellaneous information about the currently loaded song.

QTMPlayer_Info
(SWI &4CECC)

Returns miscellaneous information
On entry
R0 = reason code
Other registers depend on reason code
On exit
R0 preserved
Other registers depend on reason code
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call returns miscellaneous information about the state of the QTMPlayer module.

QTMPlayer_Info 0
(SWI &4CECC)

Returns version of QTMPlayer module
On entry
R0 = 0 (reason code)
On exit
R0 preserved
R1 = current QTMPlayer module version, multiplied by 100
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call returns the current version of the QTMPlayer module.

QTMPlayer_Info 1
(SWI &4CECC)

Returns number of layers loaded into QTMPlayer
On entry
R0 = 1 (reason code)
On exit
R0 preserved
R1 = number of layers loaded into QTMPlayer
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
The call returns the number of layers that have been loaded in the QTMPlayer module using QTMPlayer_Layer.

QTMPlayer_Info 2
(SWI &4CECC)

Returns information about a specific layer
On entry
R0 = 2 (reason code)
R1 = layer number (0 <= layer number < number of layers returned by QTMPlayer_Info 1)
On exit
R0, R1 preserved
R2 = pointer to null-terminated layer name string
R3 = pointer to null-terminated author string
R3 = version number of layer, multiplied by 100
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call returns information about a specific layer.

QTMPlayer_Info 3
(SWI &4CECC)

Returns internal information about a layer
On entry
R0 = 3 (reason code)
R1 = layer number (0 <= layer number < number of layers)
On exit
R0, R1 preserved
R2 = pointer to layer's code area
R3 = pointer to layer's workspace area
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call returns internal information about a layer. The pathname with which the layer was loaded is stored at (R3 + 256).

QTMPlayer_Layer
(SWI &4CECD)

Loads in layers and performs other miscellaneous functions
On entry
R0 = reason code
Other registers depend on R0
On exit
Registers depend on entry value of R0
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
The main function of this call is to load layers in.

QTMPlayer_Layer 0
(SWI &4CECD)

Loads in a layer directory
On entry
R0 = 0 (reason code)
R1 = pointer to null-terminated string (path of directory)
On exit
Registers preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call will load the layer's sprites in to the WIMP sprite pool, load the layer code into workspace, and register the layer internally.

QTMPlayer_Layer 1
(SWI &4CECD)

Calls an internal layer function
On entry
R0 = 1 (reason code)
R1-R4 = R0-R3 on entry to layer stub
R5 = layer to branch into (or -1 for current layer)
R6 = jump table point
Other registers depend on R0
On exit
R0-R4 = returned registers from sub
Registers depend on entry value of R0
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call is provided so that an exterior module can branch into one of the jump table words in a layer. It could be used to branch to extension jump table words that perform extra functions (eg. the forthcoming CD layer uses it for communication).

QTMPlayer_Layer 2
(SWI &4CECD)

Returns supported functions
On entry
R0 = 2 (reason code)
R1 = layer number
On exit
R0 = bitmask
R1 preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call is provided so that desktop player programs can find out if a layer supports a certain call. Each bit in the returned bitmask is set if the layer supports a function. The bits are as follows: 
      0 supports play sample                8 supports read song name
      1 supports set sample rate            9 supports read song duration
      2 supports transparent sound system  10 supports pause song
      3 supports read sample length        11 supports restart song
      4 supports read song position        12 supports stop song
      5 supports read song length          13 supports set volume
      6 supports set song position         14 supports read volume
      7 supports read song author          15 supports read sample name

QTMPlayer_Clear
(SWI &4CECE)

Returns the QTMPlayer module to its initial state
On entry
No parameters passed in registers
On exit
Registers preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call unloads any playing songs and removes all layers from workspace. It is the eqivalent of reloading QTMPlayer.

QTMPlayer_CarouselInfo
(SWI &4CECF)

Reads information about the carousel state
On entry
No parameters passed in registers
On exit
R0 = wrap state (0 = no wrap, 1 = wrap mode)
R1 = currently playing item number (or -1 if not playing a carousel item)
R2 = number of items in the carousel
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call returns various information on the state of the carousel. If wrap mode is engaged (check the return value of R0 to find out) then the carousel is advancing on to the next carousel item at the end of the currently playing one.

QTMPlayer_CarouselPlay
(SWI &4CED0)

Starts playing the carousel
On entry
R0 = carousel item to play
On exit
R0 corrupted
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call allows a carousel song to be loaded and played. The carousel will automatically play each song the number of times specified for that item, and fade out according to the flags. If errors occur under callback routines while trying to play songs in the carousel, QTMPlayer_Poll will be setup to return a pointer to the error block in R1 when it is next called, and the song that caused the error will be marked as 'failed'. The carousel will then skip past the failed song and go onto the next song. If that fails, it goes on, and so on, until all the carousel songs are marked as 'failed' at which point the carousel stops playing altogether.
Related SWIs
QTMPlayer_CarouselStop

QTMPlayer_CarouselStop
(SWI &4CED1)

Stops the carousel playing
On entry
No parameters passed in registers
On exit
Registers preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call turns off carousel wrap mode and stops the currently playing song (but does not unload it).
Related SWIs
QTMPlayer_CarouselPlay

QTMPlayer_Poll
(SWI &4CED2)

Returns information to indicate changed status
On entry
No parameters passed in registers
On exit
R0 = poll state word
R1 = error indicator
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
Once QTMPlayer has started playing the carousel, use this call to find out whether it has changed song. If QTMPlayer has not changed song since the last time someone called QTMPlayer_Poll, the poll state word will be zero, otherwise it will be set to a value of 1. The error indicator is a pointer to an error block setup whenever errors occur inside callback routines. If it is zero, no error has occured since the last poll. Also, whenever QTMPlayer_Poll is called, the 'failed' flags are cleared for all carousel items

QTMPlayer_Choices
(SWI &4CED3)

Sets up various aspects of the carousel
On entry
R0 = reason code of aspect to alter
R1 = value
On exit
R0,R1 preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call sets up various aspects of the carousel.

QTMPlayer_Choices 0
(SWI &4CED3)

Sets the carousel fadeout speed
On entry
R0 = 0 (reason code)
R1 = carousel fadeout speed
On exit
R0,R1 preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call alters the delay in 1/50s of a second between successive alterations of the volume (it goes down by 1 volume unit every alteration).

QTMPlayer_Choices 2
(SWI &4CED3)

Sets up various aspects of the carousel
On entry
R0 = 2 (reason code)
R1 = whether to mask out system flags
On exit
R0,R1 preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
QTMPlayer uses a whole word to store whether a song should fade out at the end, and obviously this is 32x more than necessary. Therefore, it uses some of the higher bits in the word to store system information (eg. the 'failed' flag). Normally, when you call QTMPlayer_ReadItem these system bits are masked out, but should you want to read them, set R1 to zero and call this SWI. The system bits are currently bit 8 (bit 8 set means the item has failed since the last QTMPlayer_Poll).

QTMPlayer_AddItem
(SWI &4CED4)

Adds an item to the carousel
On entry
No parameters passed in registers
On exit
R0 = item number of new item
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call adds a blank item to the carousel, returning an error if there is not enough memory. All entries are nullified, apart from the repeats counter which is set to 1 (zero would make the song wrap continuously).
Related SWIs
QTMPlayer_DeleteItem

QTMPlayer_DeleteItem
(SWI &4CED5)

Deletes an item from the carousel
On entry
R0 = item number
On exit
R0 corrupted
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call deletes an item, returning an error if the item was out of range.
Related SWIs
QTMPlayer_AddItem

QTMPlayer_ReadItem
(SWI &4CED6)

Reads information about a carousel item
On entry
R0 = carousel item number
On exit
R0 preserved
R1 = pointer to null-terminated string (pathname)
R2 = pointer to null-terminated string (display name, typically leafname)
R3 = number of times this carousel item repeats
R4 = song fade out state (0 = do not fade out, 1 = fade out)
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call returns various information about a carousel item. The display name is a separate area that can be used at the user's discretion. Various things it could be filled with are: the name of the song, the leafname of the song.
Related SWIs
QTMPlayer_SetItem

QTMPlayer_SetItem
(SWI &4CED7)

Sets information about a carousel item
On entry
R0 = carousel item
R1 = reason code of value to set
R2 depends on reason code
On exit
R0 corrupted
R1,R2 preserved
Interrupts
Interrupts status not defined
Fast interrupt status not defined
Processor Mode
Processor is in SVC mode
Re-entrancy
Not defined
Use
This call sets various bits of information about a carousel item. The reason codes are:
0 -- R2 = pointer to null-terminated path name
1 -- R2 = pointer to null-terminated display name
2 -- R2 = number of times this item repeats
3 -- R2 = item fade out statue (0 = do not fade out, 1 = fade out)
Related SWIs
QTMPlayer_ReadItem



[ QTMPlay | Overview | QTMPlayer | Downloads | Links ]