OggSquish API Specification

This document is all you need to start programming with libogg!

The error lists in this document are not yet complete; they will be updated to match libogg releases as they occur

This document is a reference specification of the library API provided by libogg series 0.98. This specification [likely with minor modification] will become the full OggSquish 1.0 compression engine specification.

This specification does not discuss OggScript programming; that is left to its own document.

Last updated: June 3 1996
Recent changes:

• added endianness defines to i/o buffer calls
• added description of recovering input data with 'ogg_output_xxx' functions
• clarified distinctions in machine readiness state
• clarified usage of odd bit sizes
• Extended ogg_input_dsp and ogg_output_dsp to handle arbitrary bitwidths from 2 bits to 32 bits
• More typos corrected
• Added multiscripting to the specification; this was slated for after 1.0, but it became clear it would be useful to have sooner
• The ogg_bitstream_xxxxx variables are now set by ogg_script_loadheader and ogg_script_makeheader

Table of contents

1. Overview
   1. Function Quick Reference
   2. Global Variable Quick Reference
   3. Error List Quick Reference
   4. Memory Management
   5. Error Handling
   6. Multiscripting
   7. Archive and Stream Formats
2. Engine Setup
   1. Global Variables
   2. Functions
3. I/O Buffers
   1. Named Buffers
   2. Buffer Query Functions
   3. Buffer Data Submission Functions
   4. Buffer Data Reading Functions
4. Engine Use
   1. Global Variables
   2. Runtime Functions

Overview

Libogg works by operating on single frames of data at a time. The data frames are provided by the application as pointers to data buffers. It is worth noting that the engine need not be used for compression/decompression; the buffer and scripting setup is quite flexible and can be used for various DSP functions.

Function List

Setup Functions

void ogg_settings_get(struct ogg_settings *s)
void ogg_settings_submit(struct ogg_settings *s)

void ogg_script_reset(void)
void ogg_script_parse(char *script)
void ogg_script_use(int scriptnum)
void ogg_script_makeheader(char **header,long *bytes)
long ogg_script_loadheader(char *header,long bytes)

Buffer Query Functions

int ogg_buffer_used(int group,int name)
void ogg_buffer_dsp(int group,int name,struct ogg_dspinfo *s)
void ogg_buffer_bit(int group,int name,struct ogg_bitinfo *s)
void ogg_buffer_vid(int group,int name,struct ogg_vidinfo *s)
void ogg_buffer_txt(int group,int namer,struct ogg_txtinfo *s)

Buffer I/O Functions

long ogg_input_query(int group,int number)
void ogg_input_reset(int group,int number)
void ogg_input_dsp(int group,int number,
                        void *data,long elements,int bitwidth,
                        int endianness, int signedness, int scale)
void ogg_input_bit(int group,int number,
                   char *data,long elements)
[void ogg_input_vid(...)]
[void ogg_input_txt(...)]
void ogg_output_dsp(int group,int number,
                    void **data,long *elements,int bitwidth,
		    int endianness,int signedness,int scale)
void ogg_output_bit(int group,int number,
                    char **data,long *elements)
[void ogg_output_vid(...)]
[void ogg_output_txt(...)]

Runtime Functions

void ogg_run_set(int scriptnum)
void ogg_run(void)
void ogg_run_reset(void)
void ogg_run_clear(void)

Global Variable List

int   ogg_errno
char *ogg_strerr

int   ogg_bitstream_major
int   ogg_bitstream_minor
int   ogg_bitstream_revision
char *ogg_bitstream_vendor

int   ogg_script_ready

int   ogg_script_err_line
int   ogg_script_err_statement
int   ogg_script_err_argument
int   ogg_script_err_number
char *ogg_script_err_string

int   ogg_run_ready
int   ogg_run_scriptnum

Error List

0 - No error

No error occurred

1 - Out of memory

Libogg was unable to allocate more memory.

2 - Out of data

Libogg read past the end of a provided buffer. Additional data provided by the ogg_buffer_errgroup and ogg_buffer_errbuffer variables.

3 - Virtual memory error

Libogg captured a SIGSEGV caused either by lack of working memory or an internal error.

4 - Interrupt

Libogg caught a SIGINT or SIGTERM while working.

5 - Internal Error

Internal libogg error; this indicates a serious corruption of the Ogg engine. On Macs and machines running Windows, this could simply be caused by low memory.

6 - Incompatible OggSQUISH version

The submitted header is from a bitstream produced by an OggSQUISH version before 0.98; 0.97 and before are not forward compatible.

7 - Not an OggSQUISH bitstream

The submitted header does not begin with an OggSQUISH bitstream marker.

8 - Bitstream Corruption

Header/bitstream processing failed in such a way that could only be explained by a bitstream corruption.

9 - Script/Header not parsed

The application attempted to use an OggSQUISH script/header when none has been loaded.

10 - Script/Header not complete

The application attempted to use an OggSQUISH script/header which has been loaded only partially.

11 - Script/Header already parsed

The application attempted to load a new script/header while the parser is already storing a complete script.

12 - Script/Header already in use

The application attempted to use a script (ogg_script_use) when the engine already is using a burned in script.

13 - Invalid setting value

One of the submitted settings (ogg_settings_submit is out of range.

14 - Stream not loss tolerant

ogg_run_clear was called when the loaded script is not loss/seek tolerant.

15 - I/O buffer not in use

An I/O buffer function was called on a buffer that the current bitstream does not use.

16 - Wrong type of I/O buffer

A buffer I/O function was called on a nonsensical buffer, eg, calling ogg_dsp_in on the buffer ogg_bit_out.

17 - Alignment error

Misaligned data was given to libogg, causing a SIGBUS during processing

18 - Illegal datum width

DSP data was submitted or requested with an invalid bitwidth argument

19 - Machine not loaded

An interpreter or data request was made on an interpreter bank that has not loaded any script.

20 - Machine not ready

An interpreter or data request requiring the ogg_run_ready flag to be set was made on an interpreter bank that was not ready.

100 - Error while parsing

Parsing/linking/burning broke down on some script/header defect. The global variables ogg_script_err_number, ogg_script_err_line, ogg_script_err_statement, ogg_script_err_argument and ogg_script_err_string contain more specific error information.

101 - Error while creating Ogg machine

Ogg script 'burn in' failed on some script/header defect. The global variables ogg_script_err_number, ogg_script_err_line, ogg_script_err_statement, ogg_script_err_argument and ogg_script_err_string contain more specific error information.

102 - Runtime Error

A buggy script caused an error during ogg_run. This should never happen.

Memory Management

Buffers submitted to libogg

Buffers read from libogg

Reading from the same buffer more than once per frame will return different allocated pointers.

Buffers pointed to by globals

Error Handling

Exceptions that occur during runtime (a call to ogg_run) leave the engine in an undefined state (however, ogg_run_ready remains set; some scripts would be able to simply continue); most scripts would require the engine to be reset (via ogg_run_reset or ogg_run_clear.

Libogg returns all errors as nonzero entries in the ogg_errno global variable; this variable should be checked for nonzero status after every function call without exception. The variable value should not be modified; it will be reset to zero at the beginning of the next libogg request.

In addition to ogg_errno, the ogg_strerr variable will be set to point to a text description of any error; int he case of no error, the variable will be NULL. The string pointed to by ogg_strerr is managed internally by libogg; the application should make no attempt to modify or free it.

Some errors (such as error 100 - Parse error) will set additional global variables to provide more information about the error encountered. These variables are described elsewhere.

Multiscripting

Scripts are numbered when sent to the engine by calling ogg_script_use. The ogg_run_set function is used as a 'bank switching' mechanism to specify which script is to be active for subsequent engine calls. Thus, the application can load a decompression script as script '0', a frequency equalization script as script '1' and a script to add echos as number '2'. The application calls ogg_run_set(0) to perform the engine calls for decompression, then calls ogg_run_set(1) to process the data read from the decompression buffer, then calls ogg_run_set(2) and submit the output from the second script to the third. The three scripts function independently within libogg.

Archive and Stream Formats

When an application is using 'live' streams (that is, when it is generating and transmitting packetized streams realtime), although the header itself is formalized, exaclty how the decoding is to receive the header is left to the application. In the case of the [upcoming] OggStream server, a connection that wishes to listen to a multicast bitstream fetches the bitstream header independantly from a known port on the OggStream server. The header and the bitstream are available seperately; once the header is decoded, the listening application can jump into the bitstream at the next packet. Similarly, exact usage on non-primary named buffers is left to the application to arrange and standardize.

In the case of OggSquish archives (bitstreams frozen in 'files'), the header is to be placed at the beginning of an archived bitstream. The last byte of a header must be followed by the first byte of a bitstream. An archive may also contain more than a single bitstream; when a bitstream terminates, the last byte of the bitstream may be immediately followed by the first byte of another header, and so on.

At the moment, no "Table of Contents" structures are defined for OggSquish archives, but these are intended in the near future to allow instant seeking through large archives or bitstreams to a desired point. The TOC structure does, however, break the single pass bitstream model that Ogg uses; that is, the table of contents can only be constructed as the bitstream is written, and must be written last (most Ogg archive formats will use variable size output frames) despite the fact that the TOC should be positioned in the header. Thus, an 'in bitstream' TOC Ogg archive would be a two-pass operation that could not be constructed as a stream. Xiphophorus OggSquish conversion applications will generally provide the TOC feature as a postprocessing option for non-stream uses.

Table of contents structure specifications will appear soon.

Engine Setup

Global Variables

ogg_script_ready

is set to a nonzero value when a script or header is fully successfuly loaded without error.ogg_script_use and ogg_script_makeheader may be called only when ogg_script_ready is set.

ogg_bitstream_major, ogg_bitstream_minor and ogg_bitstream_vendor

are set after calling ogg_script_makeheader or ogg_script_loadheader. In the case of scripts packed using ogg_script_makeheader, ogg_bitstream_major is the major release version, ogg_bitstream_minor is the minor release version and ogg_bitstream_revision is the revision number of the libogg in use (eg, 0.98pl0 would set the variables to 0, 98 and 0 respectively). ogg_bitstream_vendor would point to the string "OggSquish" as this script is being run by a genuine OggSquish library. In the case of a loaded header, ogg_bitstream_major, ogg_bitstream_minor, ogg_bitstream_revision and are set to whatever libogg release number with which the producing application was compatible. ogg_bitstream_vendor would be set to the name of the application that produced the header/bitstream. The values of the above variables are not to be manipulated by the application.

Important: Unlike other parser global variables, ogg_bitstream_major, ogg_bitstream_minor and ogg_bitstream_revision are *not* cleared on error or when the parser is reset. These variables hold their values between calls to ogg_script_makeheader and ogg_script_loadheader. They will be set on any call to the header functions in which the input is an ogg header, even if the functions return on error.

ogg_script_err_number

reports a specific kind of parse, link or machine creation error. It should be checked only when ogg_errno is set to '100' (Error while parsing) or '101' (Error while creating machine).

The following errors can occur during parsing:

1 - Missing argument

An expected argument was missing.

2 - Duplicate define

Two define statements specify expanding from the same symbol.

3 - Extra symbols after '%'

The parser found code after the terminating '%' .

4 - Syntax Error

5 - Type mismatch

The parser found that an argument to a statement differed from the requested type.

6 - Mismatched parentheses

An arithmetic expression contained mismatched parentheses.

7 - Blank statement

No symbols appeared between two semicolons, or the last semicolon and the terminating percent sign.

8 - Duplicate label

More than one label was given the same name.

9 - Unknown module type

The script/header requested a module type that this parser does not understand. This is possible if a header is corrupt (resulting in a garbage label) or if an older version of libogg is trying to use a bitstream generated by a newer version that uses module type the older version does not have.

10 - Unknown label

A label was used without being defined.

11 - Wrong number of arguments

The statement contained the wrong number of arguments; this could mean that there were the wrong number of fixed arguments, the wrong number of variable length list arguments, or the wrong number of variable length lists.

12 - Illegal symol name

OggScript symbols may be composed only of alphanumeric characters and underscores.

13 - Unknown module

A module was referenced with no corresponding label definition.

The next list of errors can occur during a call to ogg_script_use (after which ogg_errno is set to 101):

100 - Illegal I/O buffer group/name specified

An I/O buffer must match the funtion of the module using it.

101 - I/O buffer already in use

An I/O buffer cannot be shared by more than one A module.

ogg_script_err_string

is set to a string version of ogg_script_err_number.

ogg_script_err_line

will be set to the line number the error occurred on or..

ogg_script_err_statement

will be set to the statement number of the error. Only one will be set at a time; the other will be set to -1 (lines containing defines are not considered to be 'statements'; after they are stripped off during parsing, libogg reports parsing errors in terms of statement number).

ogg_script_err_argument

will be set to the argument number on which the error occurred; argument 0 is the module name (or indirection declaration) itself.

Functions

ogg_settings_get

void ogg_settings_get(struct ogg_settings *s)

ogg_settings_get places the currently defined machine settings in the ogg_settings structure. This structure is currently defined in libogg.h to be:

 
struct ogg_settings{
  int ogg_memory;
  int ogg_precision;
};

ogg_memory specifies how far libogg should restrict memory usage at the expense of speed. The valid range is -5 to 0 where -5 instructs libogg to use as little memory as possible and 0 allows libogg to make use of as much memory as it sees fit.

ogg_precision instructs libogg as to how precise to be during waveform reconstruction; the valid range is from -5 (fastest) to 0 (full precision). Note: This flag is not yet used by the 0.98 libogg series.

ogg_settings_submit

void ogg_settings_submit(struct ogg_settings *s)

ogg_settings_submit sends a new set of settings to libogg. See the above entry for a description of the ogg_settings structure. It is not necessary to submit new settings to the libogg engine before use; libogg is initialized with a valid defailt set.

ogg_script_reset

void ogg_script_reset(void)

ogg_script_reset clears any pending (assembled, but not burned in) or partially assembled scripts from the parser, resets ogg_errno, ogg_strerr, ogg_script_ready, and the ogg_script_err_xxxxxx globals. Calling ogg_script_reset does not affect a burned in script (scripts that have been loaded into the engine using ogg_script_use) or the engine interpreter state.

It is conceivable that ogg_script_reset could return an error; this would indicate a serious internal engine corruption. Such a state is possible under Windows or the Macintosh where libogg is not protected from other applications or system errors clobbering libogg's internal code or state.

ogg_script_parse

void ogg_script_parse(char *script)

OggScripts can be passed to libogg in string form with ogg_script_parse. Entire scripts need not be submitted in one call; the script may be broken at any point. Libogg will break down the script as complete lines are received, then assemble the script after the terminal '%' is found. After an entire script is successfully parsed and assembled, the ogg_script_ready flag will be set.

If only a partial script is submitted, libogg will parse up to the last complete line, then wait for another submission. A successful partial submission will simply be marked by the function call returning without error.

An error during parsing or linking will abort the linking process, reset the parser and set the appropriate error flags. Most parsing errors will be errors in the submitted script; in this case, ogg_errno would be set to 100, and the ogg_script_err_xxxxx variables would be set appropriately. After a script loading error, a subsequent script submission must start from the beginning of the script.

After loading a complete script, the parser must be cleared by ogg_script_use, ogg_script_makeheader or ogg_script_reset before another script or header can be submitted.

ogg_script_use

void ogg_script_use(int scriptnum)

The parser and interpretation engine in libogg function mostly seperately; after a script has been parsed by the libogg parser, it then must be sent to the libogg engine to run.

After a complete script has been loaded either by ogg_script_parse or ogg_script_loadheader and the ogg_script_ready flag has been set, ogg_script_use submits [burns in] the successfully parsed/linked script to the libogg engine for actual interpretation.

The interpreter is capable of using more than one script at the same time. Scripts are numbered upon submission using the 'scriptnum' argument; each script will function as if it were contained in an entirely seperate copy of libogg. The first action performed by ogg_script_use will be to set the active script number as if ogg_run_set had been called (ogg_run_set is used to simulate multiple seperate copies of the libogg interpreter).

The libogg interpreter also initiates its state and creates an internal 'register machine' to run the requested script at this time; it is possible for ogg_script_use to abort on creation errors if a script was syntactically correct, but contained an impossible module request that the context-free parser could not see. In this case, ogg_errno will be set to 101, and the ogg_script_err_xxxxx globals will be set appropriately.

A creation error (101) during a call to ogg_script_use will implicitly reset the interpreter engine. All other errors will leave parser and interpreter state unchanged.

A successful call to ogg_script_use will internally mark that interpreter bank in use and set the ogg_run_ready flag to signify that the selected interpreter engine is ready for use, as well as implicitly reset the parser. ogg_script_use can only be called on an interpreter bank that is not in use; ogg_run_loaded must not be set.

ogg_script_makeheader

void ogg_script_makeheader(char **header,long *bytes)

In order to convert a script to header form (eg, to convert a decompression script into header form for a bitstream), the application submits the complete script using ogg_script_parse, then using ogg_script_makeheader to return the parsed header in header-packed form. The returned buffer is a complete OggSquish bitstream header.

The header is returned in an allocated buffer pointed to by *header. *bytes specifies how many bytes the header consists of. The header will not be a string; it is normal for the header to contain the '\0' character. The application is responsible for later freeing the returned buffer.

A successful call will implicitly reset and clear the parser.

ogg_script_loadheader

long ogg_script_loadheader(char *header,long bytes)

A bitstream header (which is essentially a packed decompression script) may be loaded using ogg_script_loadheader, just as ogg_script_parse is used to load a script in string form. Because headers can normally contain the '\0' character, an additional 'bytes' argument specifies how much data the application is submitting. The function call returns the number of bytes of the input buffer were read during the loading call.

Headers need not be loaded all at once; when reading the beginning of a bitstream we will generally not be able to tell how long the header is, only where it begins. For this reason, the application may simply submit some amount of data, then check the ogg_script_ready flag after the call returns. If the call did not result in an error and the ogg_script_ready flag is not set, more data must be submitted. Do not resubmit any data in this case; simply submit more data beginning with the first unread byte of the bitstream. Note that even in the case when ogg_script_ready is not set, ogg_script_loadheader might not have read all of the submitted bytes. Be certain in this case that the next submission block begins with the first unread byte, not the first unsubmitted byte.

A successfully, fully loaded script will set the ogg_script_ready flag.

I/O Buffers

Each libogg interpreter (see ogg_run_set) possesses an independent full set of named buffers; the buffers being accessed therefore depend on which interpreter bank is active.

Named Buffers

Xiphophorus retains the right to reserve and designate new groups in future versions of OggSquish.

The currently defined groups are:

ogg_dsp_in

used for submitting raw, 2 1/2 dimensional data to the engine (the data consists of one or more interleaved value-by-time vectors. That is, if we have a stereo audio input signal, channels A and B are arranged A,B,A,B,A,B at sample periods 0,0,1,1,2,2, etc).

ogg_dsp_out

for outputting raw audio data as above.

ogg_vid_in

for inputting raw, 3 [1/2] dimensional data (such as video frames) to the engine in [rgb]-by-x-by-y-by-time form. Although reserved, this group will not be implemented in libogg 1.0.

ogg_vid_out

for ouputting video data as above. Although reserved, this group will be implemented after libogg 1.0.

ogg_txt_in

allows storage/compression of text frames along with audio and video data. Although reserved, this group will be implemented after OggSquish 1.0.

ogg_txt_out

for outputting text as above. Although reserved, this group will be implemented after OggSquish 1.0.

ogg_bit_in

for submitting a raw bitstream (such as compressed data) to the engine.

ogg_bit_in

for outputting a raw bitstream (such as compressed data) from the engine.

Each group/primary pair has a specific function. If an application queries a primary buffer and finds it to be in use, the application may assume that the buffer is performing its designated function.

ogg_dsp_in / ogg_primary

Primary audio submission buffer.

ogg_dsp_out / ogg_primary

Primary audio output buffer.

ogg_bit_in / ogg_primary

Primary compressed data submission buffer.

ogg_bit_out / ogg_primary

Primary compressed data output buffer.

Specific information about the data available at each buffer (for example, suggested sample speed in the case of an audio output buffer) may be obtained using the buffer query functions.

Buffer Query Functions

ogg_buffer_used

int ogg_buffer_used(int group,int name)

ogg_buffer_used returns nonzero if the loaded OggScript makes use of the named buffer, or 0 if no 'A' module references it. This function can be called only when ogg_run_loaded is set (after a call to ogg_script_use).

ogg_buffer_dsp

void ogg_buffer_dsp(int group,int number,struct ogg_dspinfo *s)

ogg_buffer_dsp is used to fetch information specific to the audio buffer named by group/name. The 's' argument must point to an allocated structure. ogg_buffer_dsp may be called only when ogg_run_loaded is set.

The returned information (which is described by the OggScript program in use) is:

struct ogg_dspinfo{
  long  rate;      /* The sampling rate of the audio data */
  long  channels;  /* The number of interleaved channels in the audio data */
  long  dynrange;  /* The dynamic range (in bits) of the data */
};

These specifics are inherent to the audio stream; other issues such as endianness are set by the ogg_input_dsp or ogg_output_dsp function calls.

ogg_buffer_dsp may be called on both input and output buffers.

ogg_buffer_bit

void ogg_buffer_bit(int group,int number,struct ogg_bitinfo *s)

ogg_buffer_bit is used to fetch information specific to the bitstream I/O buffer named by group/name. The 's' argument must point to an allocated structure. ogg_buffer_bit may be called only when ogg_run_loaded is set.

the ogg_bitinfo structure is defined in libogg.h as follows:

struct ogg_bitinfo{
  long seekable;
};

The field 'seekable' is nonzero if the stream will tolerate seeking to arbitrary positions and packet loss (essentially the same concept). ogg_buffer_bit may be called on both input and output buffers.

ogg_buffer_vid

void ogg_buffer_vid(int group,int number,struct ogg_vidinfo *s)

To be specified in the future; currently reserved.

ogg_buffer_txt

void ogg_buffer_txt(int group,int number,struct ogg_txtinfo *s)

To be specified in the future; currently reserved.

Buffer Data Submission Functions

ogg_input_query

long ogg_input_query(int group,int number)

ogg_input query is used to judge the minimum safe amount of data to submit to an input buffer before calling ogg_run. The returned value will be the number of elements (of the appropriate data type) requested by libogg. For example, if libogg requests '16' elements of data be submitted to ogg_dsp_in/ogg_primary, and the submission array is sizeof(short)=2 bytes, then we should submit 16 short integers for a total of 32 bytes. The number of channels would be irrelevant; the request is in terms of vector elements. In this example, if the input data contained 2 channels of interleaved short integers, we would still input 32 bytes containing 8 stereo sampling frames.

It is safe to submit a small excess amount of data; the excess will be buffered until the next frame. It is also possible for ogg_input_query to return 0; in this case no data should be submitted. Notes: The only time that less than the requested number of elements should ever be submitted to an audio input buffer is when there are no more elements available in the audio stream, and the last, short submission is intended to terminate the stream. Most OggScripts are designed to terminate the bitstream if they read past the end of the available amount of audio data.

When using a packetized input compressed bitstream, it is possible to know in advance how much data to submit; in this case, the exactly correct number of bytes may be submitted for decompression.

ogg_input_reset

void ogg_input_reset(int group,int number)

Libogg input buffers can be cleared of all internally buffered data using ogg_input_reset. This action is implicit when resetting and clearing the engine.

Resetting input buffers that are using exact packet sizes from frame to frame is recommended to guard against the possibility of an error in packet size in one frame propogating garbage data to the next.

ogg_input_dsp

void ogg_input_dsp(int group,int name,
                   void *data,long elements,int bitwidth,
                   int endianness, int signedness, int scale)

ogg_input_dsp is used to submit a raw audio buffer of arbitrary bitwidth, and endianness to an audio input buffer.

Group and name name the destination input buffer. Data is the vector to be submitted (cast to void *); elements is the length of the vector in terms of the bitwidth. The bitwidth can be any value from 6 to 32 bits inclusive, but the input values must be padded to an integer number of bytes (eg, if submitting 20 bit data, the input array values must be three bytes wide even if only 20 of the 24 bits is used, the submitted data must be left bit justified, ie submitted in AIFC style with the unused least significant pits padded to zero. See the AIFF-C specification draft for a precise decscription). Mind alignment issues in submitted data; 2 and 4 byte wide submissions must be aligned appropriately, however 3 byte data is broken down as if from a character array and need not be specially aligned.

Endianness specifies if the input data is littleendian (OGG_LITTLEENDIAN), bigendian (OGG_BIGENDIAN), the same endianness as the current platform (OGG_SAMEENDIAN) or to force swapping of bytes (OGG_SWAPENDIAN). Signedness specifies signed data (nonzero) or unsigned data (zero).

The scale argument specifies libogg behavior when the specified input bitwidth does not match the OggScript's declared dynamic range for that buffer; a nonzero scale argument directs libogg to scale the input data from the specified input range into the declared dynamic range by increasing or decreasing the input signal's amplitude. A zero scale argument will cause the data to simply be truncated or padded to the OggScript's dynamic range.

Care should be taken to submit at least the amount of data requested by the libogg engine (determined by calling ogg_input_query). The only time that less than the minimum request should be submitted is when there is no more data to submit; in this case, the bitstream will terminate after all the data has been processed.

ogg_input_bit

void ogg_input_bit(int group,int name,
                   char *data,long elements)

Bitstream data (such as the compressed bitstream) is submitted to a buffer using ogg_input_bit. The group and name arguments name the intended destination buffer, data is the bitstream data to be submitted and elements specifies how many bytes of data are in the bitstream vector.

In some cases (such as dealing with paketized data), it is possible to know the exact size of the bitstream frame to submit. When dealing with non or only partially packetized streams, however, ogg_input_query can be used to determine the minimum safe amount of data to submit to the bitstream input buffer.

If too little data is submitted and the engine reads past the end of the submitted data, ogg_run will halt with an error and leave the engine in an undefined state. If the bitstream being decoded is not loss/seek tolerant, the out of data error is fatal to decoding. Running out of data under normal circumstances is an application error that can be entirely avoided. In the case of a corrupt bitstream, the error could be unavoidable; a loss tolerant bitstream may simply clear the engine and contine at the next packet; a non-loss tolerant bitream would break down at this point in any case.

Buffer Data Reading Functions

The output functions can also be used to recover excess data submission from an input buffer. Normally this would not be necessary; buffered data would simply be used in the next frame. However, when manipulating input that is comprised of more than one header/bitstream combination, the machine state must be reset to initialize the interpreter with a new input header before which any excess input data must be recovered. The example OggSquish application distributed with libogg contains examples of both data recovery and handling multi-header bitstreams.

ogg_output_dsp

void ogg_output_dsp(int group,int name,
                    void **data,long *elements,
                    int bitwidth,int endianness,int signedness,
		    int scale)

Audio output generated by libogg is read from the appropriate output buffer using ogg_output_dsp. The group and name arguments specify the output buffer. The output audio data is returned (in the same form as it would be submitted) in an allocated buffer pointed to by *data; *elements is the size of the output array. Bitwidth, endianness, signedness and scale request that the output data have the requested bitwidth, endianness and signedness properties (as discussed in ogg_input_dsp). Scale specifies whether the output is scaled or truncated/padded to fit the output bitwidth in the case of a mismatch with the dynamic range declared by the OggScript decompression code.

Output buffers are cleared upon the next call to ogg_run; unread buffers will not accumulate. The allocated buffer returned by a call to ogg_output_dsp is not retained by libogg; the application is responsible for managing and eventually freeing that memory. Reading the same buffer repeatedly via more than one call to ogg_output_dsp will return seperate allocated memory blocks; each must be managed.

Reading a buffer that is not in use or empty will set *data to NULL.

ogg_output_bit

void ogg_output_bit(int group,int name,
                    char **data,long *elements)

Bitstream data generated by libogg is read from a bitstream output buffer using ogg_output_bit. The group and name arguments specify the output buffer. Bitstream data is returned in an allocated buffer pointed to by *data; *elements is the size of the output bitstream in bytes.

Output buffers are cleared upon the next call to ogg_run; unread buffers will not accumulate. The allocated buffer returned by a call to ogg_output_dsp is not retained by libogg; the application is responsible for managing and eventually freeing that memory. Reading the same buffer repeatedly via more than one call to ogg_output_dsp will return seperate allocated memory blocks; each must be managed.

Reading a buffer that is not in use or empty will set *data to NULL.

Engine Use

The libogg interpreter can, however, function as if multiple independent copies of the interpreter are available; which interpreter is active for a function call is specified by ogg_run_set. Each bank has its own global variables (specifically, ogg_run_ready) and its own independent I/O buffers. Thus, the values available in the interpreter global variables and the data available from I/O buffer function calls depend on the currently active interpreter bank (readable from ogg_run_scriptnum). Reset calls also affect only the active bank.

If only one script is in use, then ogg_run_set need never be called.

Global Variables

ogg_run_loaded

is set when a program is loaded into the interpreter. It will only be cleared when the engine is explicitly reset using ogg_run_reset. ogg_run_loaded does not reflect whether or not the engine is in a ready to run state; for that information, check ogg_run_ready.

ogg_run_ready

is set when the interpreter has a program to run and is ready for a call to ogg_run. ogg_run_ready does not reflect whether or not data has been submitted to input buffers or if output buffers have been read.

ogg_run_ready is set when a program is successfully burned in using ogg_script_use. It is cleared after a call to ogg_run_reset or after normal bitstream termination. Calls to ogg_run_clear do not affect the status of ogg_run_ready. ogg_run_ready is valid only for the active interpreter bank set by ogg_run_set or ogg_script_use.

ogg_run_scriptnum

is always set to the number of the currently active interpreter bank. The bank number is set by any call to ogg_script_use or ogg_run_set.

Runtime Functions

ogg_run_set

void ogg_run_set(int scriptnum)

The libogg interpreter can function as if multiple independent copies [banks] of the interpreter are available; which interpreter bank is active for a function call is specified by ogg_run_set. Each bank has its own global variables (specifically, ogg_run_loaded and ogg_run_ready) and its own independent I/O buffers. Thus, the values available in the interpreter global variables and the data available from I/O buffer function calls depend on the currently active interpreter bank (readable from ogg_run_scriptnum). Reset calls also affect only the active bank.

Normally when using more than one script, an engine transaction requires several function calls; the bank switching mechanism provides a convenient means to perform a block of calls to the same interpreter bank with a single bank specification.

If only one script is in use, then ogg_run_set need never be called.

Note: The libogg parser functions seperately from the interpreter; the parser's global variables and internal state (described in the Engine Setup section) are not related to the interpreter banks.

ogg_run

void ogg_run(void)

ogg_run is used to process a single frame of data submitted using one of the ogg_input_xxxx functions; it will produce a single frame of output data which may be read using the ogg_output_xxxxx functions. ogg_run is intended to be called in a loop to compress a continuous stream.

If the bitstream processing terminates normally during a call to ogg_run, ogg_run_ready is cleared and the machine implicitly reset. An error during processing does not reset the engine or clear ogg_run_ready; the engine is left in an undefined state. The application then has a choice of calling ogg_run_reset for a full engine reset, ogg_run_clear to restore the engine to it's initial state [the state it began in after ogg_script_use], or simply attempting to continue from the error.

ogg_run_reset

void ogg_run_reset(void)

ogg_run_reset performs a full libogg interpreter reset that clears and deallocates the current interpreter state as well as the program the interpreter is currently running. ogg_run_reset also clears ogg_run_loaded and ogg_run_ready.

A new OggScript must be loaded [burned] into the interpreter using ogg_script_use before ogg_run can be called again.

ogg_run_clear

void ogg_run_clear(void)

ogg_run_clear performs a 'soft reset' of the interpreter; it restores the engine to a clean state, as it was immediately after the previous call to ogg_script_use. It does not clear ogg_run_loaded or ogg_run_ready or clear the OggScript program currently used by the interpreter.

ogg_run_clear is the generally recommended method of continuing processing of a loss tolerant bitstream after an error, or (if needed) after seeking to a new position in a stream.