oggplay.h File Reference

The liboggplay C API. More...

#include <oggplay/oggplay_enums.h>
#include <oggplay/oggplay_reader.h>
#include <oggplay/oggplay_query.h>
#include <oggplay/oggplay_callback_info.h>
#include <oggplay/oggplay_tools.h>
#include <oggplay/oggplay_seek.h>

Go to the source code of this file.

Typedefs

typedef struct _OggPlay OggPlay
 This is returned by oggplay_open_with_reader() or oggplay_new_with_reader().
typedef struct _OggPlayCallbackInfo OggPlayCallbackInfo
 A structure for storing the decoded frames for the various streams in the Ogg container.
typedef int( OggPlayDataCallback )(OggPlay *player, int num_records, OggPlayCallbackInfo **records, void *user)
 This is the signature of a callback which you must provide for OggPlay to call whenever there's any unpresented decoded frame available.

Functions

OggPlayoggplay_open_with_reader (OggPlayReader *reader)
 Create an OggPlay handle associated with the given reader.
OggPlayoggplay_new_with_reader (OggPlayReader *reader)
 Create a new OggPlay handle associated with the given reader.
OggPlayErrorCode oggplay_initialise (OggPlay *me, int block)
 Initialise the OggPlay handle.
OggPlayErrorCode oggplay_set_data_callback (OggPlay *me, OggPlayDataCallback callback, void *user)
 Sets a user defined OggPlayDataCallback function for the OggPlay handle.
OggPlayErrorCode oggplay_set_callback_num_frames (OggPlay *me, int stream, int frames)
OggPlayErrorCode oggplay_set_callback_period (OggPlay *me, int stream, int milliseconds)
OggPlayErrorCode oggplay_set_offset (OggPlay *me, int track, ogg_int64_t offset)
OggPlayErrorCode oggplay_get_video_y_size (OggPlay *me, int track, int *y_width, int *y_height)
 Get the given video track's Y-plane's width and height.
OggPlayErrorCode oggplay_get_video_uv_size (OggPlay *me, int track, int *uv_width, int *uv_height)
 Get the given video track's UV-plane's width and height.
OggPlayErrorCode oggplay_get_audio_channels (OggPlay *me, int track, int *channels)
 Get the number of channels of the audio track.
OggPlayErrorCode oggplay_get_audio_samplerate (OggPlay *me, int track, int *samplerate)
 Get the sample rate of the of the audio track.
OggPlayErrorCode oggplay_get_video_fps (OggPlay *me, int track, int *fps_denom, int *fps_num)
 Get the frame-per-second value the of a given video track.
OggPlayErrorCode oggplay_get_video_aspect_ratio (OggPlay *me, int track, int *aspect_denom, int *aspect_num)
OggPlayErrorCode oggplay_convert_video_to_rgb (OggPlay *me, int track, int convert, int swap_rgb)
OggPlayErrorCode oggplay_get_kate_category (OggPlay *me, int track, const char **category)
OggPlayErrorCode oggplay_get_kate_language (OggPlay *me, int track, const char **language)
OggPlayErrorCode oggplay_set_kate_tiger_rendering (OggPlay *me, int track, int use_tiger, int swap_rgb, int default_width, int default_height)
OggPlayErrorCode oggplay_overlay_kate_track_on_video (OggPlay *me, int kate_track, int video_track)
OggPlayErrorCode oggplay_start_decoding (OggPlay *me)
OggPlayErrorCode oggplay_step_decoding (OggPlay *me)
 Decode the streams in the Ogg container until we find data that hasn't been presented, yet.
OggPlayErrorCode oggplay_use_buffer (OggPlay *player, int size)
 Use the built-in OggPlayBuffer for buffering the decoded frames.
OggPlayCallbackInfo ** oggplay_buffer_retrieve_next (OggPlay *player)
 Retrive the next element in the buffer.
OggPlayErrorCode oggplay_buffer_release (OggPlay *player, OggPlayCallbackInfo **track_info)
 Release the given buffer item.
void oggplay_prepare_for_close (OggPlay *me)
OggPlayErrorCode oggplay_close (OggPlay *player)
 Destroys the OggPlay handle along with the associated OggPlayReader and clears out the buffer and shuts down the callback function.
int oggplay_get_available (OggPlay *player)
ogg_int64_t oggplay_get_duration (OggPlay *player)
 Get the duration of the Ogg content.
int oggplay_media_finished_retrieving (OggPlay *player)

Detailed Description

The liboggplay C API.

Authors:
Shane Stephens <shane.stephens@annodex.net> Michael Martin Viktor Gal

Typedef Documentation

typedef int( OggPlayDataCallback)(OggPlay *player, int num_records, OggPlayCallbackInfo **records, void *user)

This is the signature of a callback which you must provide for OggPlay to call whenever there's any unpresented decoded frame available.

See also:
oggplay_step_decoding
Parameters:
player The OggPlay handle
num_records size of the OggPlayCallbackInfo array
records array of OggPlayCallbackInfo
user A generic pointer for the data the user provided earlier.
Returns:
0 to continue, non-zero to instruct OggPlay to stop.

Function Documentation

OggPlayErrorCode oggplay_buffer_release ( OggPlay player,
OggPlayCallbackInfo **  track_info 
)

Release the given buffer item.

After retrieving and processing one buffer item, in order to remove the given item from the queue and release the memory allocated by the buffer item one needs to call this function.

Parameters:
player OggPlay handle
track_info OggPlayCallbackInfo array to release.
Return values:
E_OGGPLAY_OK on success.
E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle.
OggPlayCallbackInfo** oggplay_buffer_retrieve_next ( OggPlay player  ) 

Retrive the next element in the buffer.

Parameters:
player OggPlay handle
Returns:
array of OggPlayCallbackInfo - one per track.
Return values:
NULL if there was no available.
OggPlayErrorCode oggplay_close ( OggPlay player  ) 

Destroys the OggPlay handle along with the associated OggPlayReader and clears out the buffer and shuts down the callback function.

Parameters:
player an OggPlay handle
Return values:
E_OGGPLAY_OK on success
OggPlayErrorCode oggplay_get_audio_channels ( OggPlay me,
int  track,
int *  channels 
)

Get the number of channels of the audio track.

Parameters:
me OggPlay handle
track the track number of the audio track
channels the number of channels of the given audio track.
Return values:
E_OGGPLAY_OK on success.
E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle
E_OGGPLAY_BAD_TRACK the given track number does not exists
E_OGGPLAY_WRONG_TRACK_TYPE the given track is not an audio track
E_OGGPLAY_UNINITIALISED the OggPlay handle is uninitalised.
OggPlayErrorCode oggplay_get_audio_samplerate ( OggPlay me,
int  track,
int *  samplerate 
)

Get the sample rate of the of the audio track.

Parameters:
me OggPlay handle
track the track number of the audio track
samplerate the sample rate of the audio track.
Return values:
E_OGGPLAY_OK on success.
E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle
E_OGGPLAY_BAD_TRACK the given track number does not exists
E_OGGPLAY_WRONG_TRACK_TYPE the given track is not an audio track
E_OGGPLAY_UNINITIALISED the OggPlay handle is uninitalised.
ogg_int64_t oggplay_get_duration ( OggPlay player  ) 

Get the duration of the Ogg content.

Parameters:
player OggPlay handle.
Returns:
The duration of the content in milliseconds.
Return values:
E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle
OggPlayErrorCode oggplay_get_video_fps ( OggPlay me,
int  track,
int *  fps_denom,
int *  fps_num 
)

Get the frame-per-second value the of a given video track.

Parameters:
me OggPlay handle
track the track number of the audio track
fps_denom the denumerator of the FPS
fps_num the numerator of the FPS
Return values:
E_OGGPLAY_OK on success.
E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle
E_OGGPLAY_BAD_TRACK the given track number does not exists
E_OGGPLAY_WRONG_TRACK_TYPE the given track is not an audio track
E_OGGPLAY_UNINITIALISED the OggPlay handle is uninitalised.
OggPlayErrorCode oggplay_get_video_uv_size ( OggPlay me,
int  track,
int *  uv_width,
int *  uv_height 
)

Get the given video track's UV-plane's width and height.

Parameters:
me OggPlay handle
track the track number of the video track
uv_width the width of the UV-plane
uv_height the height of the UV-plane
Return values:
E_OGGPLAY_OK on success.
E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle
E_OGGPLAY_BAD_TRACK the given track number does not exists
E_OGGPLAY_WRONG_TRACK_TYPE the given track is not an audio track
E_OGGPLAY_UNINITIALISED the OggPlay handle is uninitalised.
OggPlayErrorCode oggplay_get_video_y_size ( OggPlay me,
int  track,
int *  y_width,
int *  y_height 
)

Get the given video track's Y-plane's width and height.

Parameters:
me OggPlay handle
track the track number of the video track
y_width the width of the Y-plane
y_height the height of the Y-plane
Return values:
E_OGGPLAY_OK on success.
E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle
E_OGGPLAY_BAD_TRACK the given track number does not exists
E_OGGPLAY_WRONG_TRACK_TYPE the given track is not an audio track
E_OGGPLAY_UNINITIALISED the OggPlay handle is uninitalised.
OggPlayErrorCode oggplay_initialise ( OggPlay me,
int  block 
)

Initialise the OggPlay handle.

This function creates an Oggz handle and sets it's OggzIO* functions to the OggPlayReader's io_* functions. Moreover it reads the Ogg container's content until it hasn't got all the streams' headers.

Parameters:
me OggPlay handle
block passed as the second argument to the OggPlayReader's initialise function. E.g. in case of OggPlayTCPReader block == 0 sets the socket to non-blocking mode.
Return values:
E_OGGPLAY_OK on success
E_OGGPLAY_OGGZ_UNHAPPY something went wrong while calling oggz_io_set_* functions.
E_OGGPLAY_BAD_INPUT got EOF or OGGZ_ERR_HOLE_IN_DATA occured.
E_OGGPLAY_OUT_OF_MEMORY ran out of memory
E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle.
OggPlay* oggplay_new_with_reader ( OggPlayReader reader  ) 

Create a new OggPlay handle associated with the given reader.

Parameters:
reader OggPlayReader handle associated with the Ogg content
Returns:
A new OggPlay handle
Return values:
NULL in case of error.
OggPlay* oggplay_open_with_reader ( OggPlayReader reader  ) 

Create an OggPlay handle associated with the given reader.

This functions creates a new OggPlay handle associated with the OggPlayReader and it calls oggplay_initialise to read the header packets of the Ogg container.

Parameters:
reader an OggPlayReader handle associated with the Ogg content
Returns:
A new OggPlay handle
Return values:
NULL in case of error.
OggPlayErrorCode oggplay_set_data_callback ( OggPlay me,
OggPlayDataCallback  callback,
void *  user 
)

Sets a user defined OggPlayDataCallback function for the OggPlay handle.

Parameters:
me OggPlay handle.
callback A custom callback function.
user Arbitrary data one wishes to pass to the callback function.
Return values:
E_OGGPLAY_OK on success
E_OGGPLAY_BUFFER_MODE We are running in buffer mode, i.e. oggplay_use_buffer has been called earlier.
E_OGGPLAY_BAD_OGGPLAY Invalid OggPlay handle.
OggPlayErrorCode oggplay_step_decoding ( OggPlay me  ) 

Decode the streams in the Ogg container until we find data that hasn't been presented, yet.

Whenever there is data that hasn't been presented the OggPlayDataCallback function will be called.

Parameters:
me OggPlay handle
Return values:
E_OGGPLAY_OK reached the end of the stream or shutdown detected
E_OGGPLAY_CONTINUE successfully decoded the frames.
E_OGGPLAY_BAD_INPUT OGGZ_ERR_HOLE_IN_DATA occured while decoding
E_OGGPLAY_UNINITIALISED the OggPlayDataCallback of the OggPlay handle is not set.
E_OGGPLAY_USER_INTERRUPT user interrupted the decoding
E_OGGPLAY_OUT_OF_MEMORY ran out of memory while decoding
OggPlayErrorCode oggplay_use_buffer ( OggPlay player,
int  size 
)

Use the built-in OggPlayBuffer for buffering the decoded frames.

The built-in OggPlayBuffer implements a simple lock-free FIFO for storing the decoded frames.

It tries to set the OggPlay handle's OggPlayDataCallback function to it's own implementation (oggplay_buffer_callback). Thus it will fail if a user already set OggPlayDataCallback of the OggPlay handle with oggplay_set_data_callback.

One can retrive the next record in the queue by calling oggplay_buffer_retrieve_next.

Parameters:
player the OggPlay handle
size The size of the buffer, i.e. the number of records it can store
Return values:
E_OGGPLAY_OK on succsess
E_OGGPLAY_BAD_OGGPLAY The supplied OggPlay handle is not valid
E_OGGPLAY_CALLBACK_MODE The given OggPlay handle's OggPlayDataCallback function is already set, i.e. running in callback-mode.
E_OGGPLAY_OUT_OF_MEMORY Ran out of memory while trying to allocate memory for the buffer.

Generated on Sat Dec 26 23:56:53 2009 for liboggplay by  doxygen 1.6.1