Capabilities of Director Player for RISC OS.
============================================


This note briefly describes the capabilities, features and omissions
of Director Player for RISC OS.  This addresses the version for
Set-top boxes; the differences inherent in the Desktop player will be
added and an appendix to this document when its design is finalised.

The reader is assumed to be familiar with Macromedia Director for
Windows, as this document summarises the differences between that
product and the RISC OS Player.

The Beta release of the Player has certain known problems and
limitations which can be found by searching this text for the word
"beta".

1) Installation

Copy !MMPlayer to !Boot.Resources.

2) General

Director Player for RISC OS is a playback engine for applications
authored using the Mac or Windows versions of Macromedia Director.  It
will play back almost all Director 4 movies provided a few simple
guidelines and restrictions are adhered to.  As time goes on, many of
these restrictions will be lifted in future versions of the Player.

Full Lingo scripting is supported, as are script libraries.

Director Projectors are supported.  These are single files containing
all the resources for a collections of movies.  Projector files should
be given the file type AE3 ("Director").  To run them, ensure that the
Filer has seen the !MMPlayer application and double-click on the file.


3) Screen

The Player runs under the Wimp in any 8 bpp or 16bpp screen mode.  It
can be instructed (via the Initial file) to change mode at startup,
using the mode number or mode strings (except Grey).  The screen mode
may be any size provided it is big enough for the stage size defined 
by the application.

Palette programming is supported in 8bpp screen modes.  This means
that the Player is a poor citizen of the RISC OS desktop; rather than
mapping to the default palette for the mode, it reprograms it to suit
the colour tables in the Director title.  Normally the Director stage
window should be set up to cover the whole screen, so this should not
be a problem.  If you do not want palette programming, you should
ensure you run in a 16bpp mode.  This reprogramming is necessary for
fade transitions to work.  Fade transitions are not implemented in
16bpp.  (A later release may support a subset of the fade transitions
in 16bpp, probably only fade to/from black.)


3.1) Transitions

Transitions are supported.  Any which involve pushing the existing
stage off the display are implemented in a non-optimal fashion 
currently (this can be improved if required).

Pattern dissolve transitions are not supported (again this can be added
if required).


4) Graphics

All bitmaps stored inside the Director movies (BITD format) can be
read and displayed.  Linked castmember bitmaps must be in PICT or DIB
form.  Only the first object in a PICT file is loaded, and it must be
a bitmap.

Linked castmembers should be placed inside the application directory.
It is necessary to ensure that the original directory hierarchy is
retained, and that file extensions are mapped to a slash character.


4.1) Text 

The Beta release has support for text in all of Director's ink modes, though
the behaviour of some inks with a non-white text background colour differs
from both the Windows and Mac behaviours.  Full anti-aliasing is supported
in some inks, including blending with the background data, however some
slight fringing effects can be noticed in 8 bit modes.

Bold and Italic fonts are supported.  Italic fonts are synthesized via
a sheer where a true italic font is not available, however bold is
not synthesized.

Strikeout and underlined text is not supported in the Beta, it is
planned however for a future release.

'Outline' and 'shadow' fonts are not provided as these are specific to
the Macintosh and have no mapping on our system.

Scroll bars are not supported in the Beta, however they are planned for a
future release.

Font mapping has been improved in the beta version to allow additional
cross-platform mapping files named "FontMap" to be included in the !MMPlayer
application and in the movie application directory.  These files are in the
same format as the font mapping chunk compiled into a movie by Director; the
search order for any font conversion attempt is to look up the font mapping
chunk, then the movie's FontMap file, then the !MMPlayer's FontMap file. 
Note that for arcane reasons, the FontMap file should have its lines
terminated by a <CR> (character 13) like LINGO.INI.

The default FontMap provided with !MMPlayer contains some suggested mappings
for the standard Mac and Windows fonts to standard RISC OS fonts, and
mappings for the "top-bit-set" characters.


4.2) Shapes

Shape rendering is supported (both filled / outline).


5) Input

The remote control device can simulate keypresses, there is a default
mapping between buttons on the controller and the keystrokes
simulated.  An application that must be driven purely by the remote
control needs to provide a user interface that can be driven entirely
mouselessly, e.g. by tabbing a selection around using the arrow keys.
This type of user interface can be programmed easily in Lingo.

Due to the limitations of the remote control protocol, reliable
detection of a key being held down is not possible.

If the STB has a mouse and keyboard connected, these can be used in
the normal way.

The Beta player always returns a KeyUp event immediately after the
corresponding KeyDown event (possibly before the key is really
released).


6) Sound

Up to two channels of stereo sampled sound can be played back
simultaneously.  All sound format may be played, both embeded and 
linked castmembers.


7) Video

There is partial implementation of MPEG playback in the Beta player.
Please contact Online Media for guidance in incorporating MPEG
playback into your applications.

Limited playback of MPEG video is supported.  Currently a single
digital video channel, consisting of full-screen MPEG, may be played
from a CD-ROM.  The application may nominate a colour number or RGB
value to be the "transparent" colour, and the palette is programmed to
ensure that the output of the MPEG decoder is seen wherever that
colour appears.  Thus it is important to design sprites so that that
colour is avoided other than using it to define the video "window".

See subsequent section for how to set the "transparent" colour.

The MPEG file must be "wrapped up" as a flattened QuickTime object
because Director does not allow plain MPEG files to be imported.  If
you want to jump around inside the video clip, the seeking performance
will be greatly improved if during your QuickTime mastering you can
arrange for index atoms that match your proposed cue points to be
present in the QuickTime header.

The size and position of the digital video sprite is ignored.

Later releases of the Player will feature the ability to play MPEG
from other sources such as video servers, and may also support
a range of popular software CODECs.


8) XObjects

XObjects may be loaded at run-time to extend the capabilites of the
Player.  An XObject is a specially formatted C object that is
"carried" by a RISC OS relocatable module.  Please see the document
"XObject Developer's Kit" (xobjdev.docs.xobjdev) for details of how to
turn your code into such a module.

The only XObject supplied with the Player is FileIO.  This currently
does not implement a filepicker, so the "?read", "?write" and
"?append" access modes cannot be used.

Please note that XObject names MUST have a leading capital letter as 
their first character, the rest should be lower case. (e.g Name)

XObjects are sought by name in the following locations:
  current directory
  <Player$MovieDir>
  <Player$Dir>


9) Structure of an application

A standard !MMPlayer is shipped with all media, this contains the portable
player and its resources - there is no reason for this to be changed by the
application author.

Each Director application is stored in a seperate directory
e.g. !Mech, within which there is a !Run file and a Initial file,
an example of this is given, therefore allowing each of these
objects to be double-clickable.

At present it is only possible to run one Player at a time,
but this restriction will be lifted in future releases.


9.1) Initial file

Here are some of the standard Initial (.INI) file entries understood
by Director Player on all platforms.  The values shown in the
Settings section below are the default ones.

[Settings]
MessageWindow=1        [currently unimplemented]
EscapeOk=1
LoopPlayList=0
FullScreen=0           [currently unimplemented, use a suitable size mode instead]
UseTitleBar=1
BackgroundAnimation=0  [currently unimplemented, always animates]
SwitchColorDepth=0     [currently unimplemented]
CenterStage=0          [currently unimplemented]
ResizeStage=0          [currently unimplemented]

[Movies]
Movie01=Foo.DIR
Movie02=Bar.DIR
(etc)


9.2) Initial file extensions

A new section has been defined in the initial file, this is
OnlineMedia and it contains settings specific to the OnlineMedia
player, within these the most important are:

    ModeString=abc
    NTSCModeString=abc
    PALModeString=abc
    
    ModeNumber=x
    NTSCModeNumber=x
    PALModeNumber=x

These define the screen mode which the Player should start up in,
when starting the Player determines which display type is being used,
once this is known it attempts to read either the PAL or NTSC mode
number from the file, if that fails (because they are not specified)
it then attempts to read ModeNumber.

[Note: the Beta release does not correctly detect what type of display
is being used.  Use the ModeNumber variable rather than NTSCModeNumber
or PALModeNumber]

If none of the above settings are present in the OnlineMedia
section then the Player will use the current mode, adjusting it
to support full palette programming if it is 8 bit.

When the Player exits it restores the screen mode to its
previous setting.

To support video overlay it is important to define which key colours
are going to be used.  In 8 bit modes you must define which index
this is going to be, eg. 234, this ensures that the Player remaps
all colour index's into a suitable form that the 'transparent' colour
is logical colour 1 (this is required due to limitations in the current
video hardware).

The colour index is defined using the following line in the
Player's initial file:

    KeyColourIndex=x

When the Player re-programmes the palette it ensures that it keeps
the 'ext'palette flags preserved, therefore it is possible to 
program the transparent colour to be transparent befor the Player is
started.  

When programming the transparent colour you must modify palette
entry 1, setting or clearing bit 7 of the entry to enable/disable
transparency.

In 16 bit or above modes this becomes more complicated, this will
be resolved in later releases.


9.3) Filename syntax

For portability reasons, the Player stores filenames internally in a
DOS-like way, using the separator '\' between pathname components, and
'.' for an extension character.  These characters are converted to the
correct RISC OS characters ('.' and '/') only when they are passed to
the filesystem.  At present, any externally visible filenames have to
be expressed in this way, particularly ones constructed in a Lingo
script (e.g. by concatenation with the path of the application).

If your application tests the machineType to determine which path
separators to use, it should use backslash ('\') for the Online Media
STB.  The machineType codes are 1024 (for RISC PC and STB1) and 1025
(for STB2).

9.4) File Count

Only a maximum of 77 files are allowed in any one directory under RISC OS.

9.5) Filename mapping

When externally linked resource files are used, problems can arise
mapping their filenames onto RISC OS filenames.  To help with this is
is possible to specify explicit mappings between the filenames in the
movie and the real RISC OS filenames under which you have stored the
files.  These mappings should be placed in the Initial file under a
section called [FileMappings].  The format each line is <old
name>=<new name>.  First the whole filename is looked up, and if
no translation is found then just the leafname is looked up.

For example:-

[FileMappings]
A60001--.MPG=CDFS::FOO\$\MEDIA\A60001__.MPG
FOO.BMP=Bitmaps\Foo



10) Known problems

Scrollbars are currently unimplemented. 

Text underline/strikeout is unimplememted.

Menu font styles are unimplemented.

You must always store XObject instances in global variables.

The file Lingo/ini and FontMap have to be separated by CR characters, not LF. 
When editing the file with !Edit, use the Edit => CR/LF menu option.

Currently the Message Window is unimplemented.  Comments on what form
of message window is most useful are invited.  We are considering using
a serial terminal as a message "window".


