Distribution: COMPANY CONFIDENTIAL
Project: Browser
Issue: 0.01
Author(s): Simon Middleton
Date: 10-05-96
Last Issue: None
0.01 SJM 10-May-96 First created.
ReplaySupport is a module that was originally shipped (in version 0.04) with ARPlayer. It provided four SWIs to allow ARPlayer to do button pressing and time bar updating under callback from Replay and one command which allows ARPlayer to check which version of Replay it is running with. These calls are documented below in the programmer interface.
ReplaySupport was extended as part of the Minnie2 project to provide a number of other facilities for reading information from Replay files. It was intended that all the functionality necessary to interrogate a movie in the way that ARPlayer does will be incorporated into the module. It also provided routines to load Replay sound drivers and attach buffer fill routines to them. A fair amount of application support is still required but the key code for playing sound files under interrupts is be included in the module.
There exists a DefMod definition file for the structures and SWIs. That file should be taken as the definitive documentation for the interface as it is used in the building of the module and ARPlayer.
ReplaySupport has no user interface.
On exit, if V is set then R0 points to a standard error block. If V is clear then R0 will be corrupted.
All registers not specifically mentioned will be preserved.
On entry:
R0 -> sprite area containing buttons
R1 -> array of offsets in bytes from screen base of buttons
R2 -> array of sprite names
R3 = initial button state word
bit 0: 1 = Paused, 0 = Playing
bit 1: 1 = Muted, 0 = Unmuted
On exit:
R0 -> address of update routine
This routine copies the given sprites into the RMA and returns a pointer to a routine to pass to Player via the -mouse parameter. It will then respond to the callbacks from Player to press and unpress the buttons appropriately.
It should be called immediately before calling Player if button control is desired. If any sprites are already registered then they will be freed first.
The sprites must be pre-processed in the following way:
Note that even though 16 bit sprites are not allowed to have lefthand wastage in this case they may have as no OS routines are used to plot the sprites.
The button controls available are
PAUSE, STOP, STEP, MUTE
The sprites can be in any order in the sprite area but their names should be presented in the above order, in the array pointed to by R2. The 4 unpressed varieties should be followed by the 4 pressed versions.
eg for the standard set of buttons in !ARMovie.Sprites :-
static char *sprite_names[] =
{ "pause", "exit", "single", "loud",
"ppause", "pexit", "psingle", "mute"
};
R1 points to an array (in the same order as the sprite names) of the positions of the top left hand corners of the sprites. The values given should be the offset in bytes from the start of the screen. Note that obviously the values for sprites 5-8 will be the same as for 1-4, however an array of 8 values must still be given.
If -1 is given for any sprite then it is assumed to be off screen and button changes relating to it will be ignored.
If there are no errors on exit then R0 contains the address of the routine to pass to Player in the form
"-mouse %d", R0
Note that the address must be passed as a decimal value.
On entry: none
On exit: none
This routine will free up the memory used for the sprites copied in by Replay_RegisterSprites. It should be called after Player returns but it can be called many times without harm.
On entry:
R0 = PixelsPerFrame
R1 = TimebarAddress
R2 = TimebarHeight
R3 = FGColour
R4 = BGColour
R5 = log2bpp for routine wanted
or
R0 = -1
R1 -> Info block
+0: PixelsPerFrame
+4: TimebarAddress
+8: TimebarHeight
+12: FGColour
+16: BGColour
+20: log2bpp for routine wanted
+24: TimebarWidth
On exit:
R0 = 0 or address of time bar paint routine
This SWI configures the time bar paint routine and passes back the address which should be passed to Player as
"-paint %d", R0
Note that R0 may be 0 if no paint routine is available for the current screen mode. Currently all display depths are supported except 1 and 2 bits.
There are two calling methods for this SWI, the original method passed all values in SWI's. A new method was introduced in version 0.17 to allow extra parameters to be passed.
PixelsPerFrame is the number of pixels covered by one frame. It is a 20.12 fixed point value. ie it can be calculated as :-
(TimebarWidthInPixels >> 12) * RateAdjustment / NumFramesInMovie
RateAdjustment is what is passed in the -speed argument to Player.
TimebarAddress is the address of the top left corner of the time bar. The value is the offset in bytes from the screen base address. Note that you should be careful with the positioning of the time bar's left hand side as in 4bpp modes a byte cannot represent any position on screen.
TimebarHeight is the height of the time bar in screen lines.
FGColour is the colour of the time bar. It should be in colour number format as returned by ColourTrans_ReturnColourNumber.
BGColour is the colour of the time bar background. It should be in colour number format as returned by ColourTrans_ReturnColourNumber.
log2bpp is the value for the current screen mode. Currently supported values are 2,3,4 and 5. Other values will mean R0 returns 0.
TimebarWidth is the width in pixels. The calculated values in the update routine are checked against this value so as to avoid painting over any other part of the screen.
On entry:
none
On exit:
R0 = ARMovie version
This SWI gets the value of the ARMovie$Version system variable and decodes it into a decimal number. It returns the version number * 100 thus version 0.34 will be returned as 34.
On entry:
R0 = flags
bits 0-3: open type
0 = R1 points to a file name
1 = R1 points to a file handle
2 = R1 points to a buffer
3-15: reserved
bit 4: 1 = return textual data
bit 5: 1 = return sound track info
bit 6: 1 = return chunk catalogue info
bit 7: 1 = return sprite, 0 return sprite area
bit 8: 1 = read palette in 4 byte format
0 = read palette in 3 byte format
bit 9: 1 = calculate real number of frames
bit 10: 1 = calculate real bit rate of audio
bit 11: 1 = return pointers
0 = return offsets
bits 12-31: reserved
R1 -> file handle, file name, or buffer according to bits 0-3
R2 -> buffer for header info (or 0)
R3 = size of header info buffer
R4 -> helpful sprite buffer (or 0)
R5 = size of helpful sprite buffer
R6 -> palette buffer (or 0)
R7 = size of palette buffer
On exit:
R3 = size needed for header info
R5 = size needed for helpful sprite
R7 = size needed for palette
buffers filled in where non zero buffer ptrs given.
If R0 bit 4 is set then the textual data (the three information lines and the MPEG indirected filename) will be written to the buffer after all other data. If it is clear then the appropriate offset words will be zero. This bit also controls whether any other variable size data (other than the sound tracks and catalogue chunks) is read.
If R0 bit 5 is set then the sound track info will be written out to the header buffer immediately after the main header info.
If R0 bit 6 is set then the chunk catalogue array will be written out to the header info buffer after the sound track info and before the strings.
If R0 bit 7 is clear then the whole sprite file as embedded in the ARMovie file will be read. If this bit is set then the first 12 bytes (the sprite area header) will be skipped and only the individual sprite will be read (from the start of the sprite header).
If the size of the palette buffer is returned as 0 then there is no palette associated with this file. The palette is stored in the file as a packed 3 bytes per entry. If R0 bit 8 is set then this will be expanded on loading into ColourTrans format (ie 1 word per entry 0xBBGGRR00).
If R0 bit 9 is clear then the number of frames in the header is calculated from the number of chunks * frames per chunk. If it is set then the DecompX.Info file is loaded and if the format is uncompressed the real number of frames is calculated.
The number of chunks in the structure is the real number of chunks, not the number - 1 as is actually stored in the file.
If R0 bit 10 is set then the SoundX.Info file is read.
If R0 bit 11 is clear then the 'offset's in this structure are offsets from the start of the structure to the start of the data. If the bit is set then they are real pointers into the buffer.
+0 word fixed header size (before variable length parameters)
+4 word flags
bit 1: offsets have been relocated (ie are real pointers)
bits 1-31: reserved
+8 offset description
+12 offset date and copyright
+16 offset author
+20 word video type
+24 offset indirected filename (for types 12 and 15)
+28 offset colour space
+32 word xsize
+36 word ysize
+40 word bits per pixel
+44 word frames per chunk
+48 word number of chunks
+52 word size of a catalogue chunk
+56 word number of frames
+60 word frames per second (16.16 fixed point)
+64 word start timecode
+68 word base timecode
+72 word catalogue offset
+76 word catalogue size
+80 word sprite offset
+84 word sprite size
+88 word key frame offset
+92 word palette offset
+96 word offset of end of textual header
+100 word max even chunk size
+104 word max odd chunk size
+108 word number of sound tracks
+112 word size of a sound track info block
+116 offset video parameters
+120 offset catalogue chunks
+124 offset sound tracks
+128 offset fetcher name
... any extra parameters
... array sound track info
... array catalogue info
... bytes video parameters
... bytes string data
+0 word flags
bit 0: 1 = Reversed stereo (RL), 0 = LR
bits 1-31: reserved
+4 word sound type
1 = standard audio
2 = indirected audio
other values reserved
+8 word sample rate (22.10 fixed point - ie 1/1024Hz)
+12 byte number of channels
+13 byte bits per sample
+14 byte sample period (if specified that way)
+15 byte bits per sample data decompresses to
+16 word maximum size of sound chunk for this track
+20 string[11] sound file name (nul terminated)
If sound format is 1 then one of
SoundS8
SoundU8
SoundE8
SoundS16
SoundA4
If sound format is 2 then it is the sound name
stored in the header, eg
apdcm
+32
If the sample rate was expressed as a period (ie was less than 256) then this value is stored at +14 in the structure and the actual sample rate calculated from it. If a rate was specified in the first place then the value stored at +14 will be 0.
+0 word file offset of video chunk
+4 word size of video chunk
+8 word size of sound chunk for track 1
+12 word size of sound chunk for track 2
...
All sizes are in bytes.
In the above table an 'offset' type means that data is stored after the end of the structure at 'offset' bytes from the start of the structure unless the relocated bit is set in the flags.
The first word of the structure gives the amount of fixed information returned (which may be greater than the client application knows about).
Read and decode the DecompX.Info file.
On entry:
R0 = flags
bits 0-3: reserved
bit 4: 1 = return textual data
bits 5-7: reserved
bit 8: always set to 1
bits 9-31: reserved
R1 = video type
R2 -> video name
R3 -> buffer for info
R4 = size of info buffer
On exit:
R3 = size needed for info
buffers filled in where non zero buffer ptrs given.
Note an older form of this call had bit 8 clear and didn't pass the video name in R2.
+0 word flags
bit 0: set means codec uses inter-frame compression
+4 word size of info
+12 string offset description
+16 string offset author
+20 word encoded bits per pixel (0 if intra-frame compression used)
+24 word width increment
+28 word minimum width supported
+32 word maximum width supported
+36 word height increment
+40 word minimum height supported
+44 word maximum height supported
+48 word number of colour spaces supported
... string offset array array of colour space offsets
... bytes colour space names
If bit 4 of R0 is set on input then the colour space line of the info file will be read and decoded. Immediately following the fixed data (ie at the offset given by the word at +4) will be an array of string offsets. These offsets will point to the names of the colour spaces supported by this codec. If bit 4 of R0 is clear then the number of colour spaces supported will still be filled in.
Read and decode the <sound>.Info file.
On entry:
R0 = flags
bits 0-31 reserved
R1 = sound type (must be 2 currently)
R2 -> sound file name
R3 -> buffer for info
R4 = size of info buffer
On exit:
R4 = size needed for info
buffers filled in where non zero buffer ptrs given
+0 word flags
bit 0: sound data is seekable
bit 1: set means compression ratio is variable
clear means compression ratio is fixed
+4 word size of info
+12 string offset description
+16 string offset author
+20 word buffer size multiplier (bits)
+24 word max sample size (bits 16.16 precision)
+28 word per channel overhead (bytes)
Read information from the sound codec information file.
Perform various operations on the sound playback code.
On entry:
R0 = flags
bits 0-7: reason code
bits 8-31: reason code dependant
R2-R9 reason code dependant
This call provides the functionality necessary for ARPlayer to play Replay and other sound files back under interrupts, as such is is not as fully specified as it might be for general playback.
Load a sound file ready for use, a call to load must be followed by a call to Unload at some point.
On entry:
R1 = sound type
R2 -> sound name
R3 = number of channels
On exit:
R0 -> sound code info block
Sound type is a replay sound type (ie currently 1 or 2).
Sound name is the name of the sound code file (as given by Replay_ReadFileHeader),ie SoundS8, SoundU8, SoundE8, SoundS16 for a type 1 file or the directory name for a type 2 file.
Mark a playback file as being unwanted. May result in memory being freed
On entry:
R1 -> sound code info block
or
R1 = 0 to discard unused code files
Depending on how many files have been loaded it may or may not be actually be unloaded and the memory freed. Call with R1 = 0 to force the module to discard any files that are not actually in use.
Register playback and decompression buffers with a sound code file.
On entry:
R1 -> sound code info block
R2 -> sound buffer
R3 = file buffer size
R4 = build buffer size
R5 = hardware buffer size
The sound buffer pointed to by R2 must be as big as to 'word-align(R3) + R4 + 2*R5'.
The sound loader code will load data into the file buffer, translate it into the build buffer and register the hardware buffer with the sound driver.
On entry:
R1 -> sound code info block
Start playing a sound file (details as returned by the SoundFile module).
On entry:
R1 -> sound code info block
R2 -> SoundFile format block
R3 = file handle
Start playing a Replay sound file (details as returned by Replay_ReadFileHeader).
On entry:
R1 -> sound code info block
R2 -> Replay_Header
R3 = sound track
R4 = file handle
On entry:
R1 -> sound code info block
On entry:
R1 -> sound code info block
R2 = start sample
R3 = end sample
R4 = n times to play
Call before attaching a loader to set the start time.
On entry:
R1 -> sound code info block
On exit:
R0 = current sample
R1 = n times played
On entry:
R1 -> sound code info block
R2 = action code
0 = Pause at given sample number
other values reserved
R3 = sample number
Look up the given file name in the media access info file.
On entry:
R0 = flags
bits 0-31: reason code dependant
R1 -> file name
R2 -> buffer file access info
R3 = size of buffer
On exit:
R3 = size of buffer needed
+0 word size of info block
+4 word flags
bits 0-31: reserved
+8 word access method
see !ARMovie.Documents.ProgIf#Access for details
+12 word latency (a 16.16 value in seconds)
This SWI is actually compiled out of the current version of the module to save on space as it is not used by ARPlayer.
*ReplayCheckVer >version< >command<
ReplayCheckVer checks the version number of the ARMovie resources against the version given and executes the command if they are out of date.
It is identical in concept to RMEnsure and can be used in the same way.
Acorn Replay file format.
None.
The module build is intergrated into the NC build tree and can be ROMmed.
Support for the rest of the Replay API - a moving target.