                    ARMovie Colour Services
                    =======================

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

To allow for direct upgrade to the source colour model of ARMovie files, there
is an interface between the Player program and the colour mapping programs.
This means that the colour mapping programs can be upgraded in (say) speed or
memory allocation method, or new colour spaces can be added.

A colour service provides mapping resources for various screen modes:

1, 2, 4, 8, 16 and 32 bits per pixel

with the following pixel shapes:

1x1, 2x1 packed, 2x1 unpacked, 2x2

(the output is spread over 1, 2 or 4 pixels which comprise at most 1 word of
table space)

the output screen mode is the current one. A global flag (ARMovie$4Colour)
defines whether 4 bit per pixel screen modes are to be processed in colour - 1
and 2 bit per pixel ones never are.

The interface as seen by the Player program
===========================================

The Player program has read the source ARMovie file and thus is aware of:

- the declared source bits per pixel value (8, 16, 24)

- the declared source colour space (e.g. RGB, YUV or [xxx])
  - if creating your own colour space, please register the name with Acorn
    to prevent clashes...

- a PALETTE entry - currently only specified when the pixel depth is 8

- the destination bits per pixel and pixel shape

It will call a colour service program by using the source colour space and
source bits per pixel value to call a program with destination characteristics
as parameters. The source colour space and bits per pixel value are resolved to
a file within a directory inside the ARMovie resource:

<ARMovie$Dir>.MovingLine.ColourMap.<colour space><source bits per pixel>

For a typical Moving Blocks movie, this would result in:

<ARMovie$Dir>.MovingLine.ColourMap.YUV16

being the called program.

Player passes to this program the values/addresses of interest, either as
parameter strings or as decimal addresses - in the case of the PALETTE type,
Player provides the address of a 256*3 block of RGB byte values.

The parameter string is:

mag value (pixels of output) (1, 2 or 4): m<pix>

number of colours in destination -1: n<bpp>
(values: 1, 3, 15, 63, 255, 65535, -1)

destination palette: d<decimal address>
(only in the return parameter string - Player will never give this)

interpolation: interp
(will only be given with number of colours=65535 or -1)

source palette (only for files with a PALETTE value): s<decimal address>

For example

<ARMovie$Dir>.MovingLine.ColourMap.YUV16 m4 n255 s7654321

The program makes the appropriate colour table and sets a system variable. This
system variable is used to prevent the colour service program being called
again.

ARMovie$ColourMapN <address>,<number>;<size> <parameters> '<colour program>' <usage>

The value N ranges from 0 to 9 and is constrained by the ARMovie$ColourMapMax
value (if this does not exist, then the maximum value is 0, allowing just one
colourmap). The usage is a unary count (e.g. 11) of the number of simulataneous
uses of this colour table - in searching to replace a ColourMapN value, the
colour service program must avoid any with a non-zero usage count (i.e. no
trailing 1 characters) - and is initially null (no trailing 1 characters at
all). Any original parameter strings which resolve to (decimal) addresses are
replaced with new ones which point into values beyond the end of the created
table. If the value of <number> is 'RMA', then the area is on the RMA, else it
is a dynamic area (with that <number>). RMA *must* only be used if a dynamic
area cannot be created. The <size> value is how large the area was; if it was a
dynamic area this is irrelevant. The dynamic area is named 'ARMovie Colour
Map'.

If the address is -1 it signals that no translation of colour is needed.

If the address is -2 it signals that no translation of colour is needed, but
the colour needs to be duplicated across 16 bit words (ORR rd,rs,rs,LSL #16).
(note that tripling or quadrupling the value must be done by using a colour
table).

The address *must* be quad-word aligned. (apart from -1 and -2).

For example, the above call on YUV16 might result in:

ARMovie$ColourMap0 345678900,42;132608 m4 n255 d345809972 s345810740 'YUV16'

Note the relocation of the colour tables (in this case, to immediately after
the main colour map) and the creation of the d value: d returns should only
be made when number of colours is 1, 3, 15 or 255. Player checks all
ARMovie$ColourMapN values, starting at 0 up to the ARMovie$ColourMapMax
value. If it finds one which matches the colour space program it would call,
then it does not call the program, otherwise it does. This check is case
insensitive. (decimal) Address are followed and the contents checked.


Player will signify that it has begun using a ColourMapN by adding a '1' to
it (elongating the string) as playing starts and removing the last character
when it ends.

The system variable
-------------------

Some colour map programs have cached on disc the results of popular palette
sets, in particular the results for the standard 256 colour palette. However,
its not always efficient to access this cached information. A system variable,
ARMovie$FileTime gives the number of seconds to load 128KBytes on the current
system. If this is greater than the algorithmic generation time, then the
cached palette should not be used. A side effect of this is that setting
ARMovie$FileTime to some large number should result in the colour map programs
always generating colour tables algorithmically and never referring to cached
results. If ARMovie$FileTime does not exist, then the file system should be
assumed to be capable of loading 128KByte in 0.1 seconds.

Cleaning up
-----------

The programs <ARMovie$Dir>.MovingLine.ColourMap.Tidy and
<ARMovie$Dir>.MovingLine.ColourMap.Delete will clear the system of cached
colour maps. Tidy removes all unused maps. Delete removes all maps -
dangerous if some program is using them...

Replay API for clients
----------------------

A table may be claimed by using -claimtable in the !ARMovie.Player API -
see the ProgIf document - and release of the table (as well as its correct
use) is then the responsibility of the client program: it will need to
remove the last character from te ARMovie$ColourMapN.

The details of a table entry
----------------------------

    n1, m1:      byte containing 0000000a
    n1, m2:      byte containing 000000ba
    n1, m4:      byte containing 0000dcba

    n3, m1:      byte containing 000000aa
    n3, m2:      byte containing 0000bbaa
    n3, m4:      byte containing ddccbbaa

   n15, m1:      byte containing 0000aaaa
   n15, m2:      byte containing bbbbaaaa
   n15, m4: half word containing ddddcccc bbbbaaaa

  n255, m1:      byte containing aaaaaaaa
  n255, m2: half word containing bbbbbbbb aaaaaaaa
  n255, m4:      word containing dddddddd cccccccc bbbbbbbb aaaaaaaa

n65535, m1: half word containing aaaaaaaa aaaaaaaa
                                 0BBBBBGG GGGRRRRR
                                  4321043 21043210

n65535, m2, 4:   word containing bbbbbbbb bbbbbbbb aaaaaaaa aaaaaaaa
                                 0BBBBBGG GGGRRRRR 0BBBBBGG GGGRRRRR
                                  4321043 21043210  4321043 21043210
n65535, m2,4 in: word containing 000000aaaaaa00000 0aaaaa00 000aaaaa
                                       GG GGG       BBBBB      RRRRR
                                       43 210       43210      43210

n-1, m1, 2, 4:   word containing aaaaaaaa aaaaaaaa aaaaaaaa aaaaaaaa
                                 00000000 BBBBBBBB GGGGGGGG RRRRRRRR
                                          76543210 76543210 76543210
n-1, m2,4 inter: word containing aaaaaaa0 aaaaaaa0 aaaaaaa0 aaaaaaa0
                                 00000000 BBBBBBB  GGGGGGG  RRRRRRR 
                                          7654321  7654321  7654321 

where a, b, c, d are pixels. R, G, B are Red, Green and Blue. 0 is 'must be
zero'. The bits of R, G and B are little endian ordered (i.e. as RISC
OS/VIDC).

If the generation program takes a noticeable time, it should use
Hourglass_Percentage (the hourglass has been turned on by Player) to
reassure the user...
