Acorn User 7/AU_CD7.iso/_movies/_armovie/documents/alienfiles

Text File | 1996-11-18 | 15KB | 392 lines

           Alien file format support for Replay
           ====================================

Introduction
------------

Replay's support for alien film formats (e.g. Video for Windows and Quicktime)
is provided by MovieFS (developed by Warm Silence Software Ltd). Replay III is
supplied with a version of MovieFS that handles WAV sound samples and AVI films
in the Indeo format, and the system may be extended by third parties to handle
additional formats. The purpose of this document is twofold:

 * To explain the few changes, in an application's interaction with Replay,
   that are required when MovieFS is involved.

 * To explain the interface by which third parties may extend MovieFS to
   support additional file formats.

Extensions that handle almost all AVI, MOV, FLI, DL, WAV, WVE and VOC files are
already existing, but are not released as part of Replay III.

User Interface
--------------

In some ways it is reasonable to say that MovieFS has no user interface:
MovieFS works by extending the RiscOS operating system with an image filing
system, so as to make files of an alien format look like directories that
contain an ARMovie file (with name "ARMovie"). Users can do anything with the
contained file that they might have done with a normal ARMovie file.

In the Desktop, the illusion is taken further in that drags of, and double
clicks on, alien films are made to seem as though they were applied to the
contained ARMovie. Thus, to the user, alien films behave exactly like ARMovie
files.

For this to work smoothly the alien films should have an appropriate file type
(&FB2 for AVI, and &FB1 for WAV, for example), since the file type is the key
used by RiscOS to decide when to use an image filing system. MovieFS is
sometimes able to set the file type automatically, when invoked by a drag or
double click. An alternative mechanism, using a non-image filing system, comes
into play when the file type cannot be set; this is again transparent to the
user under the Desktop, but carries a few extra complications for application
programmers.

There are occasions when the user may not want to be fooled into viewing alien
films as ARMovie files, and may want to open the images to see the contained
ARMovie. To do this the user presses the shift key while double clicking.
Similarly, pressing shift while dragging cancels MovieFS's interference with
the WIMP, so that the receiver of the drag will be presented with the alien
film file, not the ARMovie file inside it.

On opening the image file, users will see files other than "ARMovie". There is
a text file named "ReadMe", which provide information about the version of
MovieFS in use, and sometimes a second text file named "Error", which reports
any problems that MovieFS had in interpreting the alien film. In fact, the
ARMovie file may sometimes not be present (if MovieFS was not able to make
sufficient sense of the alien film), but at least one of "ARMovie" and "Error"
are always present.

Application programers interface
--------------------------------

The presence of MovieFS makes relatively little difference to application
programmers: if interaction is mainly through clicking and dragging then alien
film files behave like ARMovie files. However, it may be beneficial to perform
some processing of pathnames presented to, and retrieved from the user via
writable icons. As examples:

 * If the user drags an alien film file to your application, and your
   application displays the pathname, then it should cut off the ".ARMovie"
   part, so as not to confuse the user.

 * If the user types, into a writable icon, the pathname of an image file
   that contains an ARMovie file called "ARMovie", then your application
   should add the ".ARMovie" leaf when accessing the film.

In the case that the file type of the alien film is not appropriately set, the
pathname transformation is a little more complicated than simply adding and
removing the ".ARMovie" string. The ARMovie file corresponding to the alien
film

   ADFS::Disc.$.dir.file/avi

is

   MovieFS#ADFS##Disc.$.dir.file/avi:$.ARMovie

That is, all ':'s are replaced by '#'s, "MovieFS#" is stuck on the beginning,
and ":$.ARMovie" is stuck on the end.

System structure
----------------

There are two levels at which film formats vary: they differ in the coding of
audio and video data (the compression formats), and they differ in the overall
ordering and cataloguing, within the file, of the data associated with video
frames and groups of audio samples (the container format).

Replay provides interfaces (see documents CodecIf and ToUseSound) to cope with
variation in compression formats, and the fetcher interface (see document
Fetchers) to cope with variation in container format. Associated with MovieFS
are a number of video decompressers, audio decompressers, and fetchers, of
which the Indeo video decompresser, various WAV audio decompressers, and a
fetcher for WAV and AVI(Indeo only) are supplied with Replay III. All the
details necessary for third parties to add new decompressers and fetchers are
given in the documents just mentioned.

The decompressers and fetchers are not sufficient on their own to allow Replay
to play alien films, since Replay requires knowledge of many parameters (not
least, it needs to know which decompressers and fetchers to actually use). All
the necessary parameters are contained within the ARMovie header, which must be
present in any film that is to be played. Of course alien films don't have
ARMovie headers, but the image filing system provided by MovieFS makes them
look as though they do.

That is the purpose of MovieFS: to recognise alien films, derive from them the
parameters required by Replay, and fake enough of an ARMovie file to convince
Replay to play it.

The functionality is split amongst several modules, which communicate with each
other via a protocol designed specifically for the purpose. In this protocol,
some modules play the part of providers and others that of clients.

Providers take on the role of recognising files: on the request of a client,
they analyse a file to see if it is one that they support; and if so they
provide a set of entry points through which an ARMovie-type view of the file
can be accessed. As supplied with Replay III, MovieFS has one provider (or
recogniser), which is the module named MFSUniv, but it is intended that third
parties should produce additional recognisers for new film formats.

On the other side of the protocol, there are two clients:

 * The module named MovieFS provides the file system and image file system,
   giving embodiment within RiscOS of the ARMovies faked by the recognisers.

 * The module named Kickstart provides the WIMP filter that redirects double
   clicks and drags.

Clients expect there to be multiple recognisers, which they poll in sequence
when they have a new film file that they wish to have interpreted.

Module initialisation
---------------------

When the various modules start up, the clients have to get to know about the
recognisers. That is achieved through the use of Service calls. These Service
calls and the entry points provided by recognisers are described next.

Service_RecogAnnounce (Service call &XXXXXXXX)

   Register or deregister as a recognition module.

On entry

   R1 = &XXXXXXXX (reason code)
   R0 = 1 for register
        2 for deregister
   R2 = address of recognition information block
   R3 = 0 (for future expansion)

On exit

   All registers preserved

Use

   This service call is used by recognisers, usually during initialisation, to
announce their presence to all clients that are loaded at that time, and
usually at finalisation to inform clients that they will no longer provide a
recognition service. Clients should ignore calls that have a value other than 0
for R3.

Service_RecogEnumerate (Service call &XXXXXXXX)

   Request registration from recogniser modules

On entry

   R1 = &XXXXXXXX (reason code)
   R2 = Address to call for registration
   R3 = 0 (for future expansion)

On exit

   All registers preserved

Use

   When a client module is loaded, there may be recognition modules already
present. This service call is used by clients to request that such recognisers
announce their presence. The recognisers should set up registers R0-R3 as
though they were going to issue Service_RecogAnnounce, but should instead call
the address contained in R2. The APCS is assumed, so the address can be called
from C, if necessary. Recognisers should ignore calls to Service_RecogEnumerate
that have a value other than 0 for R3.

The recognition information block contains the following.

  &00         File type recognised by this module
  &04         Address of descriptive string (null terminated)
  &08         Address of RecEntry_Recognise
  &0C         Address of RecEntry_Open
  &10         Address of RecEntry_Close
  &14         Address of RecEntry_FileHandle
  &18         Address of RecEntry_Read
  &1C         Address of RecEntry_size
  &20         Address of RecEntry_Error

Clients should not assume that block itself has life beyond the registering
service call, but a recogniser is obliged to maintain the string and entry
points until it deregisters. Several recognisers are permitted to register with
a common file type, and a single recogniser is permitted to register a set of
entry points multiply, with different file types. Clients must cope with this,
and should avoid calling the same RecEntry_Recognise entry point twice when
polling, just because they have been informed of it twice. However, to test
whether a set of entry points has been seen before, it sufficient for the
client to check the address of RecEntry_Recognise.

The descriptive string is for presentation to the user. It may be used by
clients to display a list of recognisers. The entry points shall obey the APCS,
and can be called from C.

The interface provides access to a film, as though it had been converted to an
ARMovie file. In fact, a recogniser must achieve this by performing the
conversion on demand, but for simplicity the entry points are described below
as though a one-pass conversion were permissible.

RecEntry_Recognise

   Recognise a file

On entry

   R0 = 0
   R1 = file handle

On exit

   R0 = correct file type         if recognised
        -1                        otherwise

Use

   This entry point is used by a client to identify the correct recogniser for
a particular file. The client will call this entry point for each recogniser it
is aware of, until one returns a value other than -1. The client will, from
then on, use the entry points from the successful recogniser. A single
recogniser may handle files of several types, but returns the correct type for
the file in question when RecEntry_Recognise is called. A recogniser should
perform this task as quickly as possible, as it may be part of a long chain of
calls.

Note: if R0 is not 0 on entry then it should be -1 on exit.

RecEntry_Open

   Convert a file, in preparation for reads

On entry

   R0 = file handle

On exit

   R0 = recogniser handle

Use

   This is called by a client in preparation for calls to RecEntryRead, so that
the recogniser can analyse the file and build any data structures it may need.

RecEntry_Close

   Close the converted file

On entry

   R0 = recogniser handle

On exit

   ---

Use

   This entry point is called by a client after all reads have been completed,
so that the recogniser can release all resources that it claimed when opening
the file.

RecEntry_FileHandle

   Inform of new file handle

On entry

   R0 = recogniser handle
   R1 = new file handle

On exit

   ---

Use

   A recogniser typically needs to read the alien film file during calls to
RecEntry_Read, and therefore must record the file handle. However, it is
sometimes necessary for a client to close and reopen the alien film file,
between calls to RecEntry_Open and RecEntry_Close, causing the file handle to
change. This entry point allows a client to inform a recogniser of the change.

RecEntry_Read

   Read from converted file

On entry

   R0 = Address of buffer to receive data
   R1 = Position within file of first byte of data
   R2 = Number of bytes to read
   R3 = recogniser handle

On exit

   ---

Use

   This entry point is used by a client to indirectly read the file; the data
returned must be as though the alien film file had been converted to an
equivalent ARMovie file, and as though it were the converted file that is being
read.

RecEntry_size

   Return the size of the converted file

On entry

   R0 = recogniser handle

On exit

   R0 = size

RecEntry_Error

   Return a string describing the problems that were encountered in converting
the file.

On entry

   R0 = recogniser handle

On exit

   R0 = Address of string (null terminated)     if errors occurred
      = 0                                       otherwise

Extending MovieFS
-----------------

As already explained, dealing with new film formats usually involves coding new
video and audio decompressers, which is independent of the MovieFS part of the
system. It is when supporting a new container format that it is necessary to
extend MovieFS with a new recogniser module.

When coding a recogniser, a developer has several choices in what sort of
ARMovie to fake. It is possible, although quite difficult, to fake a Replay II
file. Previous versions of MovieFS worked that way: during a call to
RecEntry_Read, pieces of data had to be picked up from various places within
the alien film, and packed together to form legitimate ARMovie chunks; careful
buffering was needed for this not to cause excessive seeking from disc (and
hence lumpy play back).

Under Replay III, the job of the recogniser can be far simpler. The faked file
can consist of just an ARMovie header and an unaltered copy of the original
file, offset by enough bytes to allow for the header. When using this method, a
suitable fetcher must also be written and referred to from the header (see
document Fetchers). That method may be appropriate in many circumstances, but
places the onus for doing most of the hard work on the fetcher.

There is also a middle road, where again the recogniser must fake an ARMovie
header, and a shifted, but otherwise unaltered, copy of the original file. This
time, however, the recogniser also fakes a catalogue. The recogniser can
perform detailed analysis of the film file, and pass information to the fetcher
via the catalogue. That way the fetcher's work is simplified. The format of the
catalogue is at the discretion of the developer; Replay III will not pay heed
to it, except to pass its offset (which should be present in the header) to the
fetcher.

(c) Copyright Warm Silence Software Ltd, 1996