Kinds of Reggae classes

Grzegorz Kraszewski

Multimedia.class

This is the master class of Reggae. It estabilishes basic methods and attributes. It also performs Reggae initialization when opened the first time after boot. All other classes are subclasses of multimedia.class. This class is also responsible for data formats detection and automatic building of decoding tree. It also provides secondary functionality like event logging, metadata support, AltiVec friendly memory allocations and more. Because of all these features multimedia.class is the one and only Reggae class having shared library API except of BOOPSI (object) one.

Streams

Streams form input data abstraction layer of Reggae. A stream is always the first object in any Reggae processing structure. It has one output port. All streams have common set of attributes and methods for data fetching and control. Currently available streams are:

• memory.stream for accessing data in memory: buffered, generated or embedded in application code.
• file.stream for reading files via dos.library.
• http.stream is easy to use yet powerful implementation of HTTP/1.1 protocol client. It can fetch any network resource available via HTTP GET request.

While memory.stream and file.stream are relatively simple wrappers, http.stream is a component useful stadalone as well as a Reggae data source. Any application can just use it for easy data downloading via HTTP, without even touching sockets API and dealing with HTTP internals.

Demuxers

Every media format recognized by Reggae has its own demuxer. Demuxer class is responsible for format recognition, header decoding, metadata extraction and demultiplexing (hence the name) media streams to separate output ports. While there is no real demultiplexing in simple audio or image formats, splitting functionality between demuxer and decoder allows for code reusing, as multiple demuxers may use the same decoder class (for example all demuxers for audio formats using uncompressed PCM, use audiopcm.decoder).

There are also a few "general" demuxers not associated with particular data format. They either handle some common metadata (like id3tag.demuxer), or common compression schemes at datastream level (xpk.demuxer). Such demuxers are usually the first stage of demuxer cascade.

Decoders

A decoder takes a single, demuxed media stream and converts it to one of Reggae common formats. This conversion usually means decompression and decoding of stream. Some decoders are dedicated to one particular media format, some are more general and used with many demuxers.

Filters

A Reggae filter accepts data in one of Reggae common formats, performs some transformation on data and deliver them in the same or other Reggae common format. Most filters have the same format on inputs and outputs, but it is not the rule of thumb. Imagine a filter generating visualisations for audio player, it will accept audio and generate video.

Outputs

Outputs form output abstraction layer of Reggae. They are not symmetrical to streams however. Outputs can be divided into two groups:

• user presentation outputs, which direct data stream to some output device of a computer (audio.output, picture.output),
• storage outputs, which store data stream somewhere (file.output).

Constructing a chain of connected Reggae objects does not start data processing automatically. Reggae is a pull-driven system, so something must pull data at the end of chain. It may be the application, who actively call MMM_Pull() method on output port(s) at the end of chain. Then it just gets data in some memory buffer and can do whatever it wants with them. Alternatively the last chain object may be an instance of some Reggae output class. Then the whole processing is done by Reggae.

Every Reggae output object creates a subprocess which pulls data from the chain of objects and either stores them or presents to the user. It means that all Reggae data processing is automatically offloaded from application to the subprocess. Main application process is free to handle GUI, display processing progress and control the processing by performing methods on the output object. Subprocessing Reggae chain makes creating GUI-based applications easier, and allows for example background processing, just by setting subprocess priority below 0. It may be useful for storage outputs. User presentation outputs have to work in real time, so their default priorities are above 0.

Internal classes

There are some helper classes, which are used by Reggae internally, but may be interesting for advanced Reggae programmers. Here is a brief description of them:

• processblock.class is used for grouping sets of connected objects into groups seen as a single object from outside. For example MediaNewObject() call returns a "single" object, which is in fact a complete tree consisting of at least four objects (a stream, a multiread buffer, a demuxer and a decoder).
• multiread.buffer implements a FIFO buffer with data peeking feature. It is used in format recognition process to present the same stream header to multiple recognition routines, even if the source stream is not seekable.

See autodocs of these classes for more details.