                      The programmer's view of Acorn Replay
                      =====================================

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

The software for replaying movies resides in the directory !ARMovie (think
of it like a rather large system directory - currently about 1MByte). The
!Boot file for !ARMovie sets up the computer to play movies:

- loads the iconsprites for the AE7 filetype
- sets File$Type for AE7
- sets the RunType alias for AE7 to point to the Player program

- sets ARMovie$Dir so that the Player program knows where it is
  (there are dither tables and video codecs in the directory)

- sets ARMovie$SoundDir so that the sound code can be found by Player and
  other programs.

- ensures the computer has ColourTrans and Floating point emulators loaded
  (in the RISC OS ROM or from the system directory - any version will do)

After this, double clicking on an Acorn Replay Movie will play the movie on
the desktop. Just running the program at the cli will play it. A program can
do:

SYS"Wimp_StartTask","/"+"movie file name"

to play the movie.

The program !ARPlayer is a desktop viewer for replay files - it can display
the helpful sprite and allows desktop control of a few of the capabilities
of the Acorn Replay Player program. See the section on ARMovie$Dir below for
information on how to treat !ARMovie.

Note that the !ARMovie.Player program by default takes over the entire machine
in order to get its work done (but see -multi below). It consists of
independent interrupt run processes:

- file chunk loader
- master time 'conductor'
- video decompressor
- video frame refresh and dither
- sound player
- mouse event handler

The video sections of this code are custom assembled to suit the particular
screen mode etc.

The interrupt run processes are communicating using shared memory in the
ordinary virtual address space - a wimp task swap would be fatal... A large
amount is memory is required:

- double buffer for the file I/O (odd and even chunk size given in the
  AE7 file header)
- double buffered queue of decompressed frames
- queue of sound chunks

The amount of memory required is at least:

  "odd" chunk size + "even" chunk size + 320K 
  + 48K (or more) if sound is to be played
  + 128K for dithering tables
  (the video compressor program gives an accurate value)

The Player program can use more memory if it is available! It will (by
default) return with a textual error if there isn't enough memory.

A major limitation of the video frame refresh and dither section of the
program is that it uses word addressing in order to paint on the screen:
this results in the displayed section being somewhat to the left or right of
the desired position. With 32bpp it is accurate, but with 16bpp it can be 2
pixels out, 8 bpp 4 pixels, 4bpp 8 pixels, 2bpp 16 pixels, 1bpp 8 pixels.
The program rounds the pixel address to the word address to minimise the
total effect, thus making it 16bpp +/- 1 pixel etc.

ADPCM sound is Copyright 1992 by Stichting Mathematisch Centrum, Amsterdam,
The Netherlands. See notice at the end.

Simple Control
--------------

The Player program has some default controls in it:

Esc
   
   The Esc key terminates a display sequence.

Menu (Mouse middle button)

   The Menu button (also) terminates a display sequence.

Adjust (Mouse right button)

   The Adjust button attaches sound to a multitasking movie. See also
   ARMovie$ManySounds.

Other capabilities may be provided as icons by the calling program.

Parameters
----------

The Player program also accepts a list of parameters on the command line
after the Acorn Replay movie file. These are

-At <Number>,<Number>

   Specifies the position of the bottom left corner of the replayed movie in
   OS units x,y. Player will move the output display such that it is
   entirely on screen, and may clip the bottom of the movie if it is still
   too large. Note the comments above about precision of positioning the
   output.

-Big

   The Player program will try to make the movie as large as possible. It uses
   the value in ARMovie$PrefBigMode to find an appropriate mode for playing
   the movie. If ARMovie$PrefBigMode is not set, then it assumes "13;49;28".

   Appropriate modes have eigx=eigy, 8 or more bpp OR eigx=2, eigy=1, 8 or more
   bpp OR eigx=1, eigy=0, 8 or more bpp. An appropriate mode must exist in
   ARMovie$PrefBigMode.

   eigx=eigy=1 or 2: magnification 2
   eigx=eigy=0:      magnification 1
   eigx=2, eigy=1:   magnification 2x, 4y
   eigx=1, eigy=0:   magnification 1x, 2y

   Larger magnification factors are more expensive in CPU terms, but may give
   a better picture (for example, in combination with interpolation).

   The -nomenu flag is overridden when -big is asserted.

-ClaimTable

   Causes Player to ensure that an appropriate colour table for this movie,
   magnification factor and screen mode/colours is loaded and claimed. The
   variable ARMovie$Return will be set to the decimal number of the colour
   table index, if one is required. After the table is claimed, Player will
   stop immediately. The base address of the colour table can be found from the
   ARMovie$ColourMap<index> variable. Release the table by reducing the length
   of ARMovie$ColourMap<index> by 1 - see the ColourIf document.
   See -Decomp, -Display, -Interpolate.

-Decomp

   Causes the decompression size to be forced, rather than chosen
   automatically. Value 1 causes the B decompressor to be used, 2 the H, 4 the
   W (default). Most profitably used with -ClaimTable or when testing the
   paint routines. See docuements on ColourIf, PaintRouts. See also -ClaimTable
   and -Display and -Interpolate.

-Display

   Build painting code. How can this work?

-Follow <file name> or "<file name>",<Number>

   Specifies a "trajectory" file and optional trajectory step rate (which
   overrides the rate specified in the file). The file contains a list of
   origin positions which move the -at position in real time while the movie is
   being played. The format of the file is:

   ARMovie Trajectory 1
   Comment line describing the trajectory
   10 steps per second
   M shapes
   <shape description file names>
   N instances
   <instances>

   M represents the number of shapes referred to in the trajectory. If is
   non zero, then the following lines contain shape file names. Shapes are
   referenced by integer numbers in the order they are referred to in the
   trajectory file. Shape 0 is the default rectangle and does not need to be
   defined.

   N provides instances of the selected frame shape at a particular position,
   for a given number of frame times. It is followed by N lines containing
   this information:

   <x>,<y>:<frame shape>;<repeat count>

   as textual decimal numbers. <x> and <y> are in RISC OS graphics
   coordinates and represent offsets from the -at position. <repeat count>
   may be omitted in which case the line is used once only. <frame shape>
   may be omitted if there is no list of shapes. The movie is played in each
   shape at each position (positions changing at the step rate) until the
   end of the list is reached when it restarts at the start of the list.

   If the "file name" (of the trajectory file or of the shape) is not found,
   then it will be looked for in the ARMovie directory.

   Example: :6.armovie.fred -at "circle",50

-Forcespace <colourspace>

   Override the colour space specified for this movie in the header with the
   one on the command line. Note that the system will go wrong if the
   decompressed number of bits per pixel and their format are not the same -
   you can substitute YUV for CYUV and vice versa, but can't use 6Y5UV for
   YUV. Supplied colour spaces are RGB, YUV, 6Y5UV, 6Y6UV (all full scale
   range of components) and CYUV, C6Y5UV and C6Y6UV (CCIR601/656 ranges).

-Full

   Sets the movies scale factors to make it fill the entire screen. No mode
   change is required but a 16 or 32 bit per pixel screen mode is required.
   If the current screenmode is 8 bit per pixel or less this parameter is
   ignored.

-Furniture <optional value>

   By default, when running with -multi, the window has no window furniture.
   -Furniture by itself specifies a default set of furniture (back icon,
   close icon, title bar) and the optional parameter can specify a new
   flag combination for the window manager (bits 24-30 of the window flags).

-Height <number>

   Sets the number of pixel rows to be painted (replacing the definition in
   the source ARMovie file). Note this is the pre-magnification number.

-Interpolate <number>

   Override the interpolation value found from using ARMovie$Interpolate,
   ARMovie$MachinePixels and ARMovie$PlayPixels. Value 0 sets no interpolation
   (and uses half word decompressors in 8 and 16 bit modes unless overridden by
   -decomp 4), value 1 sets horizontal only interpolation, value 2 sets
   bilinear interpolation. Not recommended for general use other than setting
   0.

-Leave

   By default, Player removes the output from the display. If -Leave is
   specified it will leave the output on the display when the program is
   left (either by getting to the end or Escape/Menu). Leave state is forced
   if the user exits by clicking on the CAPTURE/EXIT button.

-Loop

   Player will loop back to the start of the movie when it gets to the end,
   thus playing for ever. This overrides -playfor. This effect can also be
   attained by specifying "forever" in the number of chunks field of the
   header of the ARMovie file see AE7Doc.

-Loop <number>

   Player will loop back to the start of the movie when it gets to the end,
   for the specified number of times.

   Note that both forms of loop may have problems on a CD-ROM where access
   time to move the head from finish to start might cause a break in the
   sequence.

-Magx <number>[:][<number>]

   Sets the magnification in the x direction, overriding the value computed
   from the RISC OS screen mode definition, -small and -big. <number> only
   gives an integer magnification, <number>: gives a requested size (i.e.
   the x size of the movie is implied) and <number>:<number> gives an
   arbitrary rational ratio. Possible values are 7:8, 1 (or 1:1), 9:8, 5:4,
   11:8, 3:2, 13:8, 7:4, 15:8 or 2 (or 2:1). Some magnifications are not
   possible in some screen modes - use -snap if required.
   In 16 and 32 bit modes any scale factor can be used.

-Magy <number>[:][<number>]

   Sets the magnification/minification in the y direction, overriding the
   value computed from the RISC OS screen mode definition, -small and -big.
   <number> only gives an integer magnification, <number>: gives a requested
   size (i.e. the y size of the movie is implied) and <number>:<number>
   gives an arbitrary rational ratio. Interpolative scaling is available for
   5:4, 3:2, 2 (or 2:1) and 4 (or 4:1), though some of these magnifications
   are not possible in some screen modes. Non interpolative vertical scaling
   of any ratio is always available.

-Mode <number>|<string>

   Player will change to this screen mode before playing (see also -Big,
   ARMovie$PrefBigMode and ARMovie$PrefMode). On RISC OS 3.50, the mode may
   be defined as a string of the following form:

   -mode X320,Y256,C256,F60,EX2,EY2

   X plus resolution, Y plus resolution are always required.

   C plus number of colours (C2, C4, C16, C256, C32T, C16M) is optional and
   defaults to C32T (16bpp) if not specified.

   F plus frame rate: fastest available rate if not specified.

   EX plus External to Internal Graphics X value (eigx),
   EY plus External to Internal Graphics Y value (eigy), default to RISC OS
   supplied values for the mode if not specified.

   The , delimiter above can be any character other than <space> (even
   <space> may be used when defining ARMovie$PrefMode or ARMovie$PrefBigMode).
   No delimiter at all is also allowable. Parameters can be given in any order.

-Mouse <file>|<decimal address>

   Player will call a supplied routine after a mouse initiated change. The
   value supplied is checked to see if it is a valid decimal number (VALx$>0)
   or it is treated as a position independent file which is loaded into memory
   by Player at some quad word aligned address (determined at run time). The
   routine is called immediately after a frame has been painted; the CPU is
   in interrupt mode and the routine is entered with a BL. The registers
   contain:

     r0: address of state bits word:
         bit 0: true if paused
         bit 1: true if sound muted
         bit 2: true if exiting
         bit 3: true if single frame advance (which doesn't last long!)
         bit 4: true if capture class exit (bit 2 true too)
         bit 5: true if playing invisible frames (i.e. don't change screen)
         bit 6: true if end of loop
         bit 7: true if painting suppressed
         bit 8: true if painting while paused requested
         bit 9: true if at the end of the play
     r1: mouse x
     r2: mouse y
     r3: mouse buttons
     r4: mouse button which changed (bit set for each button which changed)
     r5: points to: nx
                    ny
                    number of colours
                    screen base address
                    rowbytes
                    number of rows
                    vertical expansion ratio
                    movie x
                    movie y
                    frames per second*100
     r6: points to button data structure:
         4 words per button being: left x, bottom y, right x, top y
         buttons ordered: pause, exit, capture, single frame advance,
                          ffwd, half speed, quiet, loud, mute
     r7..r12: nothing
    r13: RISC OS Irq stack
    r14: return address

   If interrupts are to be reenabled, the routine *must* worry about being
   called recursively. Returning as soon as possible is advised - playing
   a movie can be quite short of processor time...

-Multi <address>

   Play the movie using multitasking. All memory is allocated in interrupt
   shareable space (module area or Sprite Area on pre-RiscPC machines, dynamic
   areas on the RiscPC), the playing code is put onto the module area. The
   movie is played with a Wimp polling scheme, so it cannot withstand long
   delays within the window managed system. The initial caller is not returned
   to until the movie has stopped, but may get called on other threads by the
   window manager. When the movie stops, ARMovie$Return is valid.
      The calling program must ensure that the screen mode is not changed
   while the movie is being played. The tolerance of source device latency
   is reduced to the value defined in the Access file, or to a default of
   0.28 seconds.

   The (decimal) address is filled in with the address of a word which
   contains the following alterable status bits:

   bit 0: pause
   bit 1: mute the sound
   bit 2: exit
   bit 3: single frame advance
   bit 4: exit/capture
   bit 7: don't display the video
   bit 8: request paint even if paused

   The other bits in the word must not be altered. The calling program must
   ensure that the screen mode is not changed while the movie is being played.
   Bit 2 becoming set in the status word signals that the movie has finished
   or the user has initiated an exit somehow. Setting bit 8 will cause a paint
   at the next VSync if the movie is paused; bit 8 will be cleared after the
   next paint even if the movie is not paused; bit 8 should not be set inside
   an interrupt routine. See -mouse for the readable status in the word. If an
   address of 0 is given, then no update happens. While the Player starts, the
   address given will be 0, while it runs there will be a value, then after it
   stops, the address will be changed back to 0 (because the memory is returned
   to RISC OS).

   Offset  4: movie bottom X
   Offset  8: movie bottom Y
   Offset 12: movie top X
   Offset 16: movie top Y
   Offset 20: movie played fps (after -speed is taken into account) * 100

   See also -furniture, which gives control over the window.

   To attach sound to a movie which hasn't got it, click the right button.
   To make movies generate sounds simultaneously, see ARMovie$ManySounds.

   If the movie to be played has no video in it, then a white window of the
   size declared in the movie header will be produced.

>>> yet to be done - for non-wimp multi tasking
   Play the movie using multitasking. All memory is allocated in interrupt
   shareable space (module area or Sprite Area on pre-RiscPC machines, dynamic
   areas on the RiscPC), the playing code is put onto the module area. The
   movie is played with an interrupt/callback based file IO system, so that it
   withstands arbitary delays within the window managed system (but it cannot
   tolerate long SWI service times, so it may still be possible to break the
   playing of the movie). The initial caller is returned to as soon as the
   movie has started playing: ARMovie$Return is valid and its values should be
   copied. ARMovie$ReturnCode gives the address of the control word.

-Mute

   Player starts up with sound initially turned off. See -quiet.

-MyWindow <address>

   Instead of creating a window for -multi, -mywindow causes the movie to be
   painted into a window owned by another task. The address is of a control
   block

   Offset  0: task handle of calling task
   Offset  4: window handle to display in

   Once the movie has started, +8 is filled in with the address of a routine
   to call whenever an Open_Window_Request message is received.

   Whenever an Open_Window_Request for the window is seen, the program owning
   the window calls this routine with r0=0 and r1 pointing to the Wimp_Poll
   block. ARMovie will re-open the window as required and returns with all
   registers preserved; errors are returned in the normal manner (V set, R0
   points to an error block).

   When the movie exits, the code can no longer be called. In order to ensure
   that there are no problems, the window owning task must always check to see
   if the movie has exited before calling the handler routine.

-NoAdjust

   Suppresses the use of Adjust for pause.

-NoError

   Suppresses all possible textual errors from the Player program. The
   variable ARMovie$ReturnCode will contain the error.

-NoMenu

   Suppresses the use of Menu for exit.

-NoPaint

   Player starts up with video painting intially turned off. See -Novideo.

-NoVideo

   Disables the decompression and painting of the video. It cannot be
   reenable during the running of the movie.

-Paint <file>|<decimal address>

   Player will call a supplied routine after painting each frame. The value
   supplied is checked to see if it is a valid decimal number (VALx$>0) or
   it is treated as a position independent file which is loaded into memory
   by Player at some quad word aligned address (determined at run time). The
   routine is called immediately after a frame has been painted; the CPU is
   in interrupt mode and the routine is entered with a BL. The registers
   contain:

     r0: points to: nx
                    ny
                    number of colours
                    screen base address
                    rowbytes
                    number of rows
                    vertical expansion ratio
                    movie x
                    movie y
                    frames per second*100
     r1: movie base address on screen
     r2: frame number of just painted frame
     r3..r12: nothing
    r13: RISC OS Irq stack
    r14: return address

   If interrupts are to be reenabled, the routine need not worry about being
   called recursively - Player is in a semaphored area which will not be
   reentered until this thread terminates. Returning as soon as possible is
   advised - playing a movie can be quite short of processor time... Note that
   the routine is only called when a frame is actually painted and this does
   not happen if processor time is running short.

-PauseAtEnd

   Instead of stopping at the end of the movie, Player enters pause mode with
   the last frame still displayed. The status word will say paused and at the
   end of the play.

-Paused

   Player starts up in paused state. It paints the first available frame in
   order to show what's going on, but this isn't the frame indicated by
   -startat (its actually the first frame of the same video chunk). If
   -startat has been used there may be a short pause between the first
   press of the pause button (or left mouse button) and anything actually
   happening.

-PlayFor <Number>

   <Number> represents a time in centiseconds: this amount of the movie is
   played and the program exits. Note that Pause, fast forward, half speed
   etc. do not affect this time limit - it represents a duration in frames
   (or feet of the original film) rather than a time in the future.

   If the number is zero, then just the initial frame is displayed, no sound
   is played and double buffer reads are disabled.

-Quiet

   Disables the sound permanently. (Unlike -Mute it cannot be turned back on
   with the controls if they are provided)

-Relative

   Changes button definitions such that the origin is relative to the -at
   value rather than absolute.

-ReleaseTable

   Releases the colour table for this movie. See -ClaimTable.

-Shape <filename>

   Describes a shape other than a rectangle for the output to appear in. The
   format of the file is:

      ARMovie Shape 1
      A comment line to describe the shape
      800 640 OS unit size of the shape (0,0,x,y)

   Followed immediately by the entries, each of the form:

   entry header:
      byte 0: low 8 bits of dest X OS coord
      byte 1: bottom 4 bits: high 4 bits of dest X OS coord
              top 4 bits: low 4 bits of dest Y OS coord
      byte 2: high 8 bits of dest Y OS coord
          *Must* resolve to a mode 13 pixel (i.e. multiples of 4)
          bottom left of dest = 0
      byte 3: N: number of replay pixels to copy 0-255

      followed by N entries of the form:

      byte 0: low byte source X replay pixel
      byte 1: high byte source X replay pixel
      byte 2: low byte source Y replay pixel
      byte 3: high byte source Y replay pixel
              top left of source image = 0

   There should be no surplus junk at the end of the file...

   Replay source pixel (X,Y)s are black if the pixel doesn't exist in the
   movie (e.g. because the movie is smaller than the shape). If Y=-1, then
   X=-1 will be black and X=-2 will be white.

   Replay always paints a mode 13 size pixel, so the destination OS coordinates
   should be multiples of 4. The image position will be controlled by -at, so,
   if you want a circle in the centre of the screen, the shape file should have
   a circle whose minimum x and y is 0 and maximum the diameter.

-Small

   -small plays the movie without the normal 2:1 scale up. The colour rendition
   will be noticeably worse (unless you are in a millions of colours screen
   mode) (and if used in, say, mode 15 positional information will be worse)

-Snap

   Snaps the x magnification factor to those implemented for the current screen
   mode with optimal code.

-Speed <Number>

   <Number> represents a speed up ratio: the movie is played faster or
   slower than normal. For example -speed 2 or -speed 0.5 for twice speed
   or half speed play. It is recommended that -mute is used at the same time
   as -speed... No attempt is made to enforce speed ratios that the computer
   can actually decompress, so use with care!

-Startat <Number>

   <Number> represents a time in centiseconds: the movie is played from this
   point. It can be very time consuming to reach a random point in a none
   key frame movie, but Player can do it if necessary. Key frame movies
   should only take a few seconds to start playing at any point.

-Tools <Number>

   This gives tools to a multitasking movie, so can provide a desktop
   player for replay. You can attach sound to a movie which hasn't got it
   by clicking the right button, but use of select and menu to pause/end
   the movie is disabled. Click Menu to bring up a menu containing:

    Info: Information on the current version of the frontend.
    ARMovie: Information on the current version of ARMovie.
    File: Information on the movie playing in the window.
    Stop: Ends the movie.

   The window title is set to the movie title, or if it does not have one
   the filename of the movie.

   <Number> selects which tools you want with a multitasking movie.
   Possible values are:
    1: giving control icons
    2: giving time information
    3: giving both

-Track <Number>

   <Number> selects which of the multiple sound tracks in the ARMovie file is
   played. The track must exist.

-Width <number>

   Sets the number of pixel columns to be painted (replacing the definition in
   the source ARMovie file). Note this is the pre-magnification number.

In addition to those parameters, the calling program can specify the positions
of control buttons on screen. The Player program caters for buttons with the
following functions:

   attach sound (when playing multitasking)
   exit
   capture exit (exactly like exit, but leaves pixel map on screen)
   pause
   single frame advance when in pause mode
   fast forward
   half speed
   quiet (no sound)
   loud (sound back on)
   mute (toggle sound)
   display (toggle video)

By default no button definitions exist except for pause, defined as the
whole screen: so by default a left click will pause the movie and another
will restart it. Buttons are defined with the initial character followed by
the bottom left corner i.e. E10,40 - this gives a default sized button of 32
OS units. E10,40,50 gives a square button of 50 OS units. E10,40,50,25 gives
a rectangular button 50 OS units wide, 25 tall. (-relative makes button
definitions relative to the -at position). Defining any button position will
remove the effect of the default pause button; use -NoMenu and -NoAdjust if
you need to prevent the other mouse buttons.

A typical command line might be:

<movie name> -loop -leave -startat 2000 -playfor 2000 -quiet E640,512 P0,0

case is irrelevant.

System Variables
----------------

There are several system variables which affect the Acorn Replay player
program:

ARMovie$CBAIState

   Set by Player to 0 (for no CBAI) or 1 (for CBAI) if it didn't previously
   exist when Player runs. Can be changed from 1 to 0 if required - changing
   from 0 to 1 requires CBAI to be there! [See Call Back After Interrupt
   documentation from Acorn for details of what this does]

ARMovie$ColourMapMax

   This gives the maximum number of simultaneously present colour maps. If
   it is not set, one map is assumed. See the document 'ColourIf'.

ARMovie$ColourMethod

   Normally the Player program finds the number of colours by reading the OS
   Mode Variable 3 (NColour): values acceptable are 1, 3, 15, 63, 255,
   65535, -1 signifying 1, 2, 4, 8 (fixed palette), 8 (variable palette), 16
   and 32 bit per pixel modes. All is well for modes up to 8 bits per pixel,
   however a RISC OS 3.1x (or earlier) with an externally upgraded graphics
   system (such as the Computer Concepts ColourCard or State Machine G8) is
   incapable of returning 65535 from this call: the programmers of the 16
   bit screen modes of these cards have adopted a variety of approaches to
   the problem(!). If NColour is less than 256, then Player checks Mode
   Variable 9 (Log2BPP) and if this is greater than 3, uses it to compute
   the 'correct' value of NColour. This method doesn't work for the Computer
   Concepts ColourCard (it returns 3, i.e. 8 bit), so the !Boot file of
   !ARMovie alters the check to Mode Variable 10 (Log2BPC). This area is
   extremely nasty, but other checks may be possible by arrangement with
   Acorn.

ARMovie$Default

   This variable allows the default characteristics of the Player to be set.
   It is only used if the movie is played with no parameters (both the rest
   of the CLI and the variable ARMovie$ExtraArgs are empty) so can be set to
   affect the desktop double click (or CLI run) action without affecting
   other programs which use Replay.

ARMovie$Dir

   This is set by the !ARMovie application so that Player can get at its
   resources - Player won't work without this variable! Applications should
   only set this variable if it is not already set: for example, suppose you
   wish to play a movie on filer_boot of your application and therefore need
   to have Player work and have therefore included a copy of !ARMovie on your
   disc. You should do:

   IF "<ARMovie$Dir>"="" THEN Run <My$Dir>.!ARMovie.!Boot

   This allows for new versions of the !ARMovie application to replace the one
   on your disc by being seen first. IT WILL BE NECESSARY FOR THIS TO HAPPEN:
   FOR EXAMPLE, NEW VIDEO HARDWARE WILL NEED NEW VERSIONS OF !ARMovie AND
   Player.

ARMovie$ExtraArgs

   Command strings to the Player program can exceed the 256 character limit,
   so an additional set of arguments of up to 256 characters can be placed
   in this system variable. After the Player program has read the value and
   used it, it sets it to a null string.

ARMovie$Fetcher

   Sets a default named fetcher for movies with no fetcher reference in their
   header. See Fetcher documentation.

ARMovie$FileTime

   Gives the number of seconds the system takes to load a 128KByte file into
   memory. If unset, 0.1 seconds is assume. Used to control the colour map
   programs - see ColourIf documentation.

ARMovie$Frames

   A variable which is set by the Player program at the end of the movie.
   It contains the number of frames not displayed (either due to the machine
   being rather slow, or to ARMovie$MachinePixels taking effect) out of the
   total number of frames. It also displays if the machine is 'slow' - if it
   is then a minimum of every other frame will have been missed.

   Its possible to use ARMovie$Frames to help set a value for
   ARMovie$MachinePixels. First set a very high value for
   ARMovie$MachinePixels, then play increasingly difficult movies until
   frames are missed. Then set ARMovie$MachinePixels to that value.

ARMovie$Interpolate

   This variable controls the Player interpolating missing pixels in 16 and
   32 bit per pixel screen modes. There are three possible forms for setting
   the variable:

   (a) set to a string containing limit numbers: a,b. The number a is the
       maximum number of pixels per second which can be bilinearly interpolated
       on the machine; the number b is the maximum number of pixels per
       second which can be horizontally only linear interpolated on the
       machine. For example 'Set ARMovie$Interpolate 256000,512000'
       This allows the interpolation setting to depend on the movie being
       played. All interpolation can be turned off by setting 0,0.

   (b) set to a single character. This is equivalent to setting the
       value to '1024000,2048000'. In 16 or 32 bpp, for most movies bilinear
       interpolation will be used (up to 320x256x12.5fps) and then horizontal
       only will be used (up to 320x256x25fps).
       For example 'Set ARMovie$Interpolate .'

   (c) unset (i.e. the default for the machine) or set to no characters. 
       This is equivalent to setting the value to '128000,512000'. For
       very small or slow movies bilinear interpolation will be used, but
       for most movies (up to 160x128x25fps) horizontal only will be used.

   The following interpolation routines are available:

   In 16 bit modes, if xeig=yeig=1 *or* xeig=yeig=2 with -big *or*
   xeig=2,yeig=1 with -big *or* xeig=1 and yeig=2, horizontal only
   interpolation can be done (and is on by default) (it costs a small
   amount [5 F cycles per interpolated pixel] to do it at 16bpp). Bilinear
   interpolation can be done, but costs somewhat more.

   In 24/32 bit modes, if xeig=yeig=1 *or* xeig=yeig=2 with -big *or*
   xeig=2,yeig=1 with -big *or* xeig=1 and yeig=2, horizontal only
   interpolation can be done (and is on by default) (it costs very little
   [1 F cycle per interpolated pixel] to do it at 24bpp). Bilinear
   interpolation can be done, but costs somewhat more.

   Interpolation works whatever colour space and compression method the movie
   had. Interpolation is not available for -shape definitions (and thus for
   some -follow trajectories). [note interpolation at 8 bits per pixel was
   withdrawn]

ARMovie$Keyboard

   Contains a textual string describing which keys do what. Note that this
   variable is intended for system wide use - use in a particular way by one
   program should take care to restore the previous state. The string contains
   sets of three characters, the first one defining which key, the second how
   it acts and the third on which function of the player.

   The first character can be either a character or | followed by a decimal
   code of the character.

   The second character can be: s - set the state of
                                c - clear the state of
                                t - toggle the state of

   The third character can be: e: exit
                               c: capture exit
                               a: attach sound
                               p: pause
                               s: single frame advance
                               m: mute
                               d: disable video
                               f: fast forward
                               h: half speed

   After a group of characters, a ',' must appear. Space is not allowed after
   the ,.

   For example:

   *set ARMovie$Keyboard |13cp,|32tp,mtm,qsm,lcm,sss,ese

   sets RETURN to clear pause (i.e. play), SPACE to toggle pause (pause/play),
   'm' to toggle mute (sound on/off), 'q' to set mute (sound off), 'l' to clear
   mute (sound on), 's' to single frame advance, 'e' to exit.

ARMovie$MachinePixels

   This variable sets the number of pixels per second which the machine is
   capable of decompressing and displaying. If movies exceed this total, then
   the Player program will take some actions:

   - change the number of frames decompressed per interrupt
   - halve the paint rate (i.e. display every other frame)
   - in 16 bit per pixel modes, defeat horizontal dithering
   - in 8 bit per pixel modes, defeat vertical dithering in 2x2 paint

   The default value is 1024000. For 16 bit modes there are a total of 6
   possible states for the painting routine:

   routine:                        pixel rate below:
    bidirectional interpolation     ARMovie$Interpolate first value
    horizontal interpolation        ARMovie$Interpolate secondvalue
    horizontal dithered             midway between horiz interp and slow
    horizontal undithered           ARMovie$MachinePixels
    slow horizontal dithered        ARMovie$MachinePixel plus horiz interp
    slow horizontal undithered      infinity

   For 8 bit 2x2 painting there are a total of 4 routines:

   routine:                        pixel rate below:
    2x2 dithering                   midway between horiz interp and slow
    vertically undithered           ARMovie$MachinePixels
    slow 2x2 dithering              ARMovie$MachinePixel plus horiz interp
    slow vertically undithered      infinity

   (note that a similar algorithm was tried for 8bpp 2x4 paint, but the
   4x vertical replication of the dither pattern didn't look very good...)

ARMovie$Mags, ARMovie$MagsBig

   These variable provides a generic way to set the default magnification
   (it can be overridden with -magx, -magy and -small, though) for files based
   on their sizes. ARMovie$Mags is checked for all "normal" playing, while
   ARMovie$MagsBig is checked if -big is specified. The variable contains a ;
   seperated list containing the following elements:

    x-range<,>y-range<,>magx<,>magy<;>

   A range is <integer>-<integer> or <integer>.
   A mag is <integer>:<integer>.

   The list is processed left to right until both the x-range and y-range
   include the movie's declared size - the specified pair of magnifications is
   then used instead of the mode derived values intended to ensure a nominally
   sized magnification of 2. For example, the setting of ARMovie$Mags to:

   240-256,288,3:2,1:1;0-40000,0-30000,1:1,1:1

   would make files with sizes in the range 240x288 to 256x288 be subject to
   magnification of -magx 3:2 -magy 1:1 while all other files are subject to
   a magnification of 1:1. The setting of ARMovie$MagsBig to

   0-480,0-352,480:,352:;0-640,0-480,640:,480:

   would play movies on big screen modes as large as the mode (or thereabouts
   - see -snap). Magnification setting by ARMovie$Mags is subject to -snap
   automatically.

ARMovie$ManySounds

   (Applies to 16 bit sound systems)
   When playing a movie -multi, Player does not assume it is the sole owner
   of the sound system (since if it does, other things will grind to a halt
   with a lack of sound interrupts). There are two possible behaviours - to
   allow only one of the things generating sounds to be heard (this is the
   default) or to allow all of the things generating sounds to be heard.
   If ARMovie$ManySounds exists, then all -multi movies will generate sound.
   If it doesn't, only one will (the most recently started, or the one which
   has been made active).

ARMovie$PlayingSound

   8 bit sound machines cannot do the mixing which player does. Therefore
   this variable is set if a movie is playing sound (even if -muted), and
   if another movie is started and finds this variable set, it will not
   play any sound.
   To stop a movie playing sound add the -quiet arguement.
   (See above for 16 bit sound)

ARMovie$PrefMode

   Used by the machine's owner to get the movie to display in a different
   mode to the current one. For example, a user may like working in a very
   high resolution mode with a low number of colours. Player can display
   movies in such modes but they don't look good, so the user can set
   ARMovie$PrefMode to an alternative mode. Note that the user won't be able
   to see the buttons.

   See -mode for a description of the after RISC OS 3.50 syntax.

ARMovie$PrefBigMode

   Used by the machine's owner to set a list of modes to use the -big
   display. The modes must be in order of ascending magnified size in
   the X direction - the first mode whose magnified number of X pixels is >=
   to the number required by the movie will be used, or the last mode of
   all. Each mode has to have square pixels: eigx=eigy; or have eigx=2,
   eigy=1, or eigx=1, eigy=0 (see -big for list of magnification factors for
   particular eig values). It can be 8, 16 or 32 bpp and can be any size.
   The list is separated by ';' characters.

   The best setting for ARMovie$PrefBigMode depends on your machine. See
   'PrefBig' for a more detailed (but by no means exhaustive) list. The
   default setting is "13;49;28".

   See -mode for a description of the after RISC OS 3.50 syntax.

   Before RISC OS 3.50 example setting:

   *set ARMovie$PrefBigMode 49;28

   After RISC OS 3.50 example settings:

   (TV standard monitor)

   *set ARMovie$PrefBigMode x320,y256,c32t,ex2,ey2;x384,y288,c32t

   (VGA monitor)

   *set ARMovie$PrefBigMode x320,y480,c16m,ex2,ey1;x480,y352,c16m;x640,y480,c32k

ARMovie$Suffix

   Used by the machine's owner to preselect different versions of the
   movie if they are available. For example, if one knows that one's machine
   can only manage 12.5fps movies, *set ARMovie$Suffix to 2 and Player will
   preferentially play the 12.5fps movies. See the file on AE7 file naming
   conventions.

ARMovie$TimeSource

   Used by the machine's owner to preselect different sources of real time. It
   contains values for single tasking and for multi-tasking as <single>,<multi>.
   Currently defined values are:

   0: Timer0 (i.e. RISC OS 100Hz) - this is the least accurate of the
      systems (though removing the RTCAdjust module can help)
   1: Timer1 (often used by other tasks)
   2: TimeCode system.

   If ARMovie$TimeSource does not exist, the default is 1,0. Other suitable
   values are 0,0 and 2,2.

ARMovie$4Colour

   If this variable is defined, then square pixel hi-resolution (e.g. mode 27)
   displays will be done in colour, with an automatically computed lookup table
   - this may take some time, but since the table is then cached, it will be
   as quick as anything else.

Some system variables are used by Player to return information to the calling
programs:

ARMovie$Buffs

   Player sets this to a complicated value, giving the state of the buffer
   system and painting methods. For example:

     ARMovie$Buffs : 100(160),100(128) 2:1 4:1 S3H Decomp19.Dec16 1232983 access=64 H

   means 100x100 painted from a 160x128 movie, 2:1 x and 4:1 y, from a
   single buffered filesystem, 3 decompressed buffer frames held as half words
   using Decomp19's Dec16, total buffer memory 1232983 bytes, access=64,
   horizontal interpolation only used (values ., H or B).

ARMovie$Pause

   Player sets this to 0 if the movie was playing when it exited, 1 if it is
   paused on exit. This, plus the use of -paused, allows pause state to be
   preserved between the applications and the Player program.

ARMovie$Return

   Player sets this to the actual position on screen of the video information.
   If -leave has been set or use user has exitted Player using the CAPTURE/EXIT
   button, this is the section that has been 'dirtied' and should be repainted
   by the window manager. It is set to

   <leftx> <bottomy> <rightx> <topy> <C>

   where the <C> is present only if the user has pressed CAPTURE/EXIT.

ARMovie$ReturnCode

   If -NoError has been set, this will contain the textual error message.
   It will not exist if there was no error.

ARMovie$Sound

   Player sets this to 0 if the sound has been disabled by clicking on
   one of the icons, 1 if it is enabled. This, plus the use of -mute,
   allows sound on/off state to be preserved between the applications and
   the Player program.

ARMovie$Time

   Player sets this to the number of centiseconds of movie which have been
   played. Note that (like -playfor) this refers strictly to the amount of
   the movie, not the total elapsed time: playing a movie and playing the
   movie pausing every frame for an hour will end up with the same value
   for ARMovie$Time.

ARMovie$Version

   Player sets this to its version number and date string.

The Player programme uses some system variables to prevent it having to reread
files. The system variables ARMovie$ColourMap used by the colour interface are
detailed in the ColourIf document. The format of variables which cache the
<ARMovie$Dir>.Decomp<n>.Info file) may change, but at present is:

ARMovie$Decomp<n>Info contains, in order:

0/1: has a !RunImage file
0/1: source is not temporally compressed
0/1: C call sequence to be used
<nn>,: exact number of bits per pixel is
<nn>,: x multiple
<nn>,: Y multiple
<nn>,: size of Decompress file
<nn>,: size of DecompresB file
<nn>,: size of DecompresH file
<nn>,: size of Dec16 file
<nn>,: size of Dec8 file

Acorn Replay Icons
------------------

The !ARMovie application has already *iconsprite'd the icons for the AE7
filetype into the window manager's icon pool - you should not include them
(or any other system icons...) in your application's own !Sprite files.

A standard set of icons is made available for the buttons used to control
the player. They are in <ARMovie$Dir>.Sprites (plus Sprites22 and Sprites23
using the RISC OS 3.00 discipline for alternative resolutions). This gives
all eight buttons with names 'exit' 'pause' 'single' 'fast' 'half' 'quiet'
'loud' and 'mute'. In addition, there are 'play', 'pplay' (pushed play) and
'playbig' buttons to complete a control panel.

Applications wishing to use the button set should load (check for failure)
the sprite file into their own sprite area (rather than *iconsprite'ing
it - the definitions use up quite a bit of memory).

If you wish to use your own icons for control buttons (for example, you
want the buttons to be a different size) then please ensure that the
buttons appearance (especially the shape of the glyph design) is close to
the standard ones.

The sprite file <ARMovie$Dir>.Default contains the default sprite used by
the !ARMovie program to indicate that an ARMovie file can be dragged there.

Not done yet
------------

The player does not, in fact, respond to double speed and half speed play
buttons (h and f).

File IO Access Resource file
----------------------------

The method by which the Player program accesses the ARMovie file can be
altered. The file "<ARMovie$Dir>.MovingLine.Access" contains a list of the file
root pathnames and an associated access method and latency times. For example:

ADFS  32,0.1  ::HardDisc4 64,0.2
CDFS  2,0.4
SCSI  1,0.1   ::Fred 128,0.2     ::Jim 0,0.4  ::Jim.$.Slow 0,0.8

The text, plus a ":", is matched against the left of the filename - if it is
identical (excluding case) then the access method specified is used. Different
access methods for different discs on the same filing system and for different
sections of the same disc can be provided by splitting the rest of the defining
substring across the line (i.e. SCSI::Fred will matched against the left of the
file, then SCSI::Jim, then SCSI::Jim.$.Slow). 2 is used for the default access
method and 0.28 is used for the default latency time. There can be any number
of spaces between the string and the access method.

The access methods defined so far are:

0: no chunk buffers at all (file is in RAM somewhere)
1: single chunk buffers
2: double chunk buffers if possible, single chunks if not enough RAM
3-256: n K sub blocks of single chunks
257-512: ditto, but rounded up to 2K values
513-1024: ditto, but rounded up to 4K values
1025: next different method

The access latency mainly affects -multi, where the amount of frames buffered
is reduced to the minimum possible.

Note that access methods 0,1,3-1024 produce faster start up times (since only a
single chunk is read) and use less memory (note that 3-1024 use the same amount
of memory as 1 since the whole chunk must still be read). But they do require
much faster access times - access=3 especially - compared with 2. The supplied
default file is:

SCSI  1,0.1
ADFS  128,0.1
Nexus 16,.4
CDNet  8,.4

In order to use access=0, Player needs to be able to read the base address in
memory of the file and it needs to be held in contiguous memory with the start
address word aligned (so that chunk start addresses will also be word aligned).
Player finds the base address by using OS_FSControl 21 on the file to read the
internal filing system file handle and then it assumes this points to a block
of information of which the first word is the base address of the file (this is
what CacheFS does, for example). Other RAM based filing systems will need to
support this method or come to an arrangement with Acorn on an alternative
inside Player.

ADPCM sound copyright notice
----------------------------

ADPCM sound code was implemented by Mark Taunton of Acorn Computers using
original code supplied with the following notice:

Copyright 1992 by Stichting Mathematisch Centrum, Amsterdam, The
Netherlands.

                        All Rights Reserved

Permission to use, copy, modify, and distribute this software and its 
documentation for any purpose and without fee is hereby granted, 
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in 
supporting documentation, and that the names of Stichting Mathematisch
Centrum or CWI not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
