
ARLib Overview

This library is primarily intended for the playback of Acorn Replay soundtracks, although 
the components can be used in other ways.

Source code is provided as an aid to understanding and for tracing any problems that may 
occur, only the object code provided in the library should be included in any product as only 
that can be supported. Any bugs or problems with the library should be reported to 
Uniqueway. All software is S.J.Middleton and Uniqueway Ltd. 1993, 1994.

Functionality

The library can be used at its simplest with just 2 functions. armovie_init() sets things 
up and then armovie_playsound() will initiate multi-tasking audio playback of any 
Replay file. Assuming the host application makes use of the standard Risc_OSLib event 
handling routines then the file will be played with no further work needed by the front end.

Facilities are :-
	- play a selected region of a file.
	- loop all or part of a file seamlessly, a number of times or indefinitely.
	- stop the sound prematurely.
	- queue up another file to be played when the current finishes.
	- interrogate the library to find out what is currently playing.
	- play any one of the soundtracks in the file.
	- handles any of the Replay standard audio types (4 bit ADPCM, 8 bit linear signed, 
unsigned and VIDC format, 16 bit linear).
	- handles any new type 2 audio format that may appear.
	- play through external hardware with appropriate sound code.

The support routines in the library may also be used to manipulate Replay files generally, eg
	- decode Replay header (get descriptive text, frame rate, length ...)
	- extract the default sprite

Overheads

The library will add about 15K to the unsqueezed size of the host application.

It uses the alarm module of Risc_OSLib to handle its processing whilst playing thus should 
place a very small overhead on the running of the application.

Requirements

As detailed below under Sound Code, ARlib requires an ARMovie resource containing the 
sound code files. It also requires Floating Point support, so if creating a RISC OS 2 
application with it, remember to RMEnsure FPEmulator in your !Run file.


Files

The files included in the library are:-

o.arhdr:	Decodes an Acorn Replay file's header.

o.arhdr1:	Extract the chunk catalogue.

o.arspr:		Extract the default sprite.

o.armovie:	Manages the alarm task to load chunks and provides the high level 
interface to all the other routines.

o.arsndcode:	Manages the playback code and buffers in the RMA. Provides interfaces 
into the playback code.

o.arsnd:	A few small general Replay related routines.

o.arlibmain:	Provides simple top-level initialisation.

o.device:	Provides simple interface to the device claim message protocol (used by 
armovie_playsound())

o.utils, o.utilasm:	Provide a few general non-Replay specific routines.

o.c_alloc	Swappable memory management routines
o.f_alloc
o.m_alloc
o.d_alloc

The headers provided are:-

h.armovie:	Has all the important function prototypes for the outside world.

h.arspr:	Has function prototypes for extracting default sprite.

h.arsound:	Internal definitions of the sound playback and buffer structure.

h.utils:	Prototypes for the generic routines.

h.device:	Device claim prototypes and device numbers.

h.memalloc:	Prototypes for the memory allocation routines.

h.arutils:	Prototypes for a few simple armovie utilitity functions.

h.replaytype:	Some basic defines for Replay.

Also included:-

c.main:	Shows a very simple application using the library.

Initialisation

First Risc_OSLib should be initialised ie

	res_init();
	msgs_init();
	wimpt_init();
	alarm_init();

The set of Risc_OSLib modules actually used is alarm, event, msgs, os, sprite, werr, wimp, 
wimpt, win.

And if you use the flex module then

	flex_init();

Then you may either call armovie_init() which sets up a mode change handler and various 
other handlers or call its separate actions yourself, ie

	armovie_setreleasefn(armovie_abort);
	atexit(armovie_cleanup);

The first sets the library to stop playback and release the sound system if anyone else tries to 
claim it (this can be left out if this is not the desired action), the second ensures that 
everything should deallocated and cleared up properly when the application exits.

You should also ensure that

	armovie_modechange();

is called whenever a mode change occurs. This marks the current VIDC timing as out of date 
and next time a file is played VIDC will be retimed. This ensures that movies are always 
played at the correct pitch no matter what VIDC enhancer or other software is around. If 
external hardware or VIDC20 is being used then the timing will not be necessary. To 
insulate your code from knowing this just ensure this functon is called.

If you do use the flex module then call

	armovie_registermemfns(f_alloc, f_free);
	armovie_registercataloguememfns(f_alloc, f_free);

this will cut down the demands on the malloc heap as a buffer is needed the size of a chunk 
of audio within your application somewhere and space is needed for the chunk catalogues 
(normally only a few K but can get large with very long movies).

On the new architecture you can cut down on the RMA usage by using Dynamic Areas. 
Allocator functions are provided in d_alloc.c and can be used like any of the others. The 
function dynamicarea_init() can be used to see if dynamic areas are available. So you could 
do :-

	if (dynamicarea_init())
		armovie_registersoundmemfns(d_alloc, d_free);

in your initialisation somewhere. If  dynamic areas are not available then the function will 
return FALSE without giving an error, so this procedure is safe to use on any machine.

Configuration

There are two system variables looked at by the library code. 

ARPlayer$NoShrinkRMA - If this is not set then when playback has ceased try and 
shrink the RMA back down as far as possible.

ARPlayer$Quality - This can be set to a value from 1 to 4 and will force the quality 
setting to this value. If this variable is unset then the library will use quality 4 (the best).

These are provided for experimentation. You shouldn't set either of these variables up in any 
production code.

To Play a Sound

To play the first soundtrack of a movie then simply call

	armovie_playsound(movie_name, 0, 0, 0, 0, 1, 0);

When it is finished then memory will be deallocated.

To interrupt it with a new movie then just call the function again or

	armovie_playsound(movie_name,0,0,0,arplay_QueueSound,1,0);

to queue up the new movie.

These function will return NULL if playback could not commence for some reason and give 
an error with werr().

If queueing movies then it is advisable to give a different value for the last parameter, the 
reference, so that you can tell which movie is playing when you call,

	armovie_getpos(&time_now, &num_loops);

which returns the reference code of the movie playing or -1 if none.

You can also set up an event handler. Your event handler will be called whenever playback 
stops for any reason and also at various other pertinent times. You will often not need to 
bother with the event handler. Reason codes are defined in armovie.h.

Note that the first time any sound is played in a given screen mode there will be 
approximately one second delay while the sound system is retimed.

The Sound Code

The sound code to play the movies is loaded from the !ARMovie resource. So in your !Run 
file you should check for its presence and complain if it is not found. eg.

If "<ARMovie$Dir>" = "" Then Error ARMovie resources not 
found. Please open a directory display containing the !ARMovie 
application and run App again.

The sound code is found by looking in the directory given by the system variable 
ARMovie$SoundDir. If this variable is not set then <ARMovie$Dir>.MovingLine is used 
instead. This means that new sound drivers for external hardware can be supplied as an 
application directory that just sets ARMovie$SoundDir. This is all handled by the ARLib 
automatically.

The sound code remains in memory (in the RMA) after the sound is stopped so that when the 
next sound is played the initial overheads are avoided. Note that only one code file can be 
held at once so playing different format files or files with different numbers of channels will 
result in the sound code being repeatedly reloaded and reinitialised.

Media

You should ensure that the storage media from which you are playing is fast enough to make 
the sound data available in time. The library checks how long it takes to load the first chunk 
of the movie and if it is slow it immediately loads the second chunk (rather than starting to 
play the first chunk whilst the second is loaded). This ensures that one and two chunk 
movies are always played smoothly, however if the media cannot keep up then pauses in the 
sound will develop between future chunks.

When running off floppy you should probably stick to mono 8 bit 12kHz samples. If stereo 
is important then try using ADPCM - stereo ADPCM will take the same space as mono 8 bit 
uncompressed.

To load a default sprite

A helpful sprite is included in every Replay file. It will usually be an 8 bit sprite of the same 
logical size as the movie, either in MODE 13, 15 or 21. Functions are provided to load the 
sprite into its own sprite area and to register the memory allocations functions to be used for 
this area.

You should include the header file and if you are using flex, register the flex memory 
functions , ie:-

#include "arspr.h"
arspr_registermemfns(f_alloc, f_free);
Then to load a sprite do:-

static	sprite_area *defsprite = NULL;

void fn(sprite_area **defsprite_addr)
{
	if (armovie_defaultsprite(filename, defsprite_addr))
	{
		/* sprite is loaded into a flex allocated sprite area
		   free afterwards using f_free((mem_ptr)&defsprite); 
		*/
	}
	else
	{
		/* not replay file or out of memory
		   error already given using werr() or wimpt_complain() 
*/
	}

	...
}

Note that the memory allocation routines assume that the pointer they are getting the address 
of is A valid pointer or NULL so you must initialise the sprite_area pointer to NULL before 
using it.

By default arspr uses c_alloc() and c_free() (which just call realloc() and free()).

More Information

More information on each of the functions is given in their header files. Also the file main.c 
when linked with the library gives a very basic playback application and gives examples of 
some of the library features.

If there are any further problems or queries, please contact me either by email or phone,

email:	arlib@uniqway.demon.co.uk
phone:	Cambridge (0223) 560747

Simon Middleton.
Uniqueway Ltd.

Last Modified: 22/03/94

eof Overview
