OggPlay:              opaque internal data pointer
OggPlayReader:        reader object for retrieving data
OggPlayErrorCode:     enumeration of error codes (shared between main library
                      and the readers)
OggPlayDataCallback:  callback to indicate decoded synchronised data is 
                      available (return value can be used to pause decoding)
OggPlayVideo:         struct containing video data including picture size and 
                      number of pictures available
OggPlayAudio:         struct containing audio data, audio information, and
                      number of samples available
OggPlayCMML:          struct containing cmml data
OggPlayInfoType:      enumeration of information sources (http headers, comment
                                          packets, track headers, etc.)
OggPlayFormat:        enumeration of formats that tracks can be returned in
                      (e.g. pcm data in shorts or floats)

/* initialisation and teardown */
OggPlay * or NULL <- oggplay_open_with_reader(OggPlayReader *, char *)
OggPlay * or NULL <- oggplay_open(char *)
OggPlayErrorCode  <- oggplay_close(OggPlay *)

After initialisation and setting of reader / source, the library will read
enough data to determine what logical bitstreams (tracks) are present.
        
/* stream querying */
int               <- oggplay_get_num_tracks(OggPlay *)
OggzStreamContent <- oggplay_get_track_type(OggPlay *, int)
const char *      <- oggplay_get_track_typename(OggPlay *, int)
OggPlayErrorCode  <- oggplay_set_track_active(OggPlay *, int)
char *            <- oggplay_get_track_info(OggPlay *, int, OggPlayInfoType,
                                              char *)
OggPlayErrorCode  <- oggplay_set_track_format(OggPlay *, int, OggPlayFormat)

/* playback control */
OggPlayErrorCode  <- oggplay_set_data_callback(OggPlay *, OggPlayDataCallback)
OggPlayErrorCode  <- oggplay_set_callback_rate(OggPlay *, ogg_int64_t)
OggPlayErrorCode  <- oggplay_set_callback_num_frames(OggPlay *, int, int)
OggPlayErrorCode  <- oggplay_start_decoding(OggPlay *)
OggPlayErrorCode  <- oggplay_seek(OggPlay *, ogg_int64_t)
OggPlayErrorCode  <- oggplay_seek_frame(OggPlay *, int, ogg_int64_t)
OggPlayErrorCode  <- oggplay_caching_hint(OggPlay *, ogg_int64_t)
OggPlayErrorCode  <- oggplay_caching_hint_frame(OggPlay *, int, ogg_int64_t)

/* call from within OggPlayDataCallback */
OggPlayErrorCode  <- oggplay_caching_hint_now(OggPlay *)
OggPlayFrames *   <- oggplay_get_video_data(OggPlay *, int)
OggPlayAudio *    <- oggplay_get_audio_data(OggPlay *, int)
OggPlayCMML *     <- oggplay_get_cmml_data(OggPlay *, int)
OggPlayErrorCode  <- oggplay_lock_data(OggPlay *, 
        
/* calls that break Reader abstraction */
OggPlayCMML **    <- oggplay_extract_all_cmml(OggPlay *)

------------------------------------------------------------------------

/* OggPlayReader API (INTERNAL ONLY!) */

OggPlayErrorCode   <- initialise(OggPlayReader *, char *)
OggPlayErrorCode   <- destroy(OggPlayReader *)
                
/* return size, location of data, absolute pos in pointers. */
OggPlayErrorCode   <- get_next_chunk(OggPlayReader *, char * const *, 
                                                              int *, int *)
OggPlayErrorCode   <- seek_to_chunk(OggPlayReader *, int)

/* mark a chunk as not required again in the immediate future */
OggPlayErrorCode   <- mark_chunk_consumed(OggPlayReader *, char *)

/* mark an absolute pos / size region as good for caching */
OggPlayErrorCode   <- set_caching_hint(OggPlayReader *, int, int)

-----------------------------------------------------------------------