include/oggplay/oggplay.h

   1 /*
   2    Copyright (C) 2003 Commonwealth Scientific and Industrial Research
   3    Organisation (CSIRO) Australia
   4
   5    Redistribution and use in source and binary forms, with or without
   6    modification, are permitted provided that the following conditions
   7    are met:
   8
   9    - Redistributions of source code must retain the above copyright
  10    notice, this list of conditions and the following disclaimer.
  11
  12    - Redistributions in binary form must reproduce the above copyright
  13    notice, this list of conditions and the following disclaimer in the
  14    documentation and/or other materials provided with the distribution.
  15
  16    - Neither the name of CSIRO Australia nor the names of its
  17    contributors may be used to endorse or promote products derived from
  18    this software without specific prior written permission.
  19
  20    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  23    PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE ORGANISATION OR
  24    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  27    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  28    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  29    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  30    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 */
  32
  33 /** @file
  34  *
  35  * The liboggplay C API.
  36  *
  37  * @authors
  38  * Shane Stephens <shane.stephens@annodex.net>
  39  * Michael Martin
  40  * Viktor Gal
  41  */
  42
  43 #ifndef __OGGPLAY_H__
  44 #define __OGGPLAY_H__
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 #include <oggplay/oggplay_enums.h>
  51 #include <oggplay/oggplay_reader.h>
  52
  53 /**
  54  * This is returned by oggplay_open_with_reader() or oggplay_new_with_reader().
  55  */
  56 typedef struct _OggPlay OggPlay;
  57
  58 /**
  59  * A structure for storing the decoded frames for the various streams in the
  60  * Ogg container.
  61  */
  62 typedef struct _OggPlayCallbackInfo OggPlayCallbackInfo;
  63
  64 /**
  65  * This is the signature of a callback which you must provide for OggPlay
  66  * to call whenever there's any unpresented decoded frame available.
  67  *
  68  * @see oggplay_step_decoding
  69  * @param player The OggPlay handle
  70  * @param num_records size of the OggPlayCallbackInfo array
  71  * @param records array of OggPlayCallbackInfo
  72  * @param user A generic pointer for the data the user provided earlier.
  73  * @returns 0 to continue, non-zero to instruct OggPlay to stop.
  74  *
  75  */
  76 typedef int (OggPlayDataCallback) (OggPlay *player, int num_records,
  77                                    OggPlayCallbackInfo **records, void *user);
  78
  79 #include <oggplay/oggplay_query.h>
  80 #include <oggplay/oggplay_callback_info.h>
  81 #include <oggplay/oggplay_tools.h>
  82 #include <oggplay/oggplay_seek.h>
  83
  84 /**
  85  * Create an OggPlay handle associated with the given reader.
  86  *
  87  * This functions creates a new OggPlay handle associated with
  88  * the OggPlayReader and it calls oggplay_initialise to
  89  * read the header packets of the Ogg container.
  90  *
  91  * @param reader an OggPlayReader handle associated with the Ogg content
  92  * @return A new OggPlay handle
  93  * @retval NULL in case of error.
  94  */
  95 OggPlay *
  96 oggplay_open_with_reader(OggPlayReader *reader);
  97
  98 /**
  99  * Create a new OggPlay handle associated with the given reader.
 100  *
 101  * @param reader OggPlayReader handle associated with the Ogg content
 102  * @return A new OggPlay handle
 103  * @retval NULL in case of error.
 104  */
 105 OggPlay *
 106 oggplay_new_with_reader(OggPlayReader *reader);
 107
 108
 109 /**
 110  * Initialise the OggPlay handle.
 111  *
 112  * This function creates an Oggz handle and sets it's OggzIO*
 113  * functions to the OggPlayReader's io_* functions. Moreover
 114  * it reads the Ogg container's content until it hasn't got
 115  * all the streams' headers.
 116  *
 117  * @param me OggPlay handle
 118  * @param block passed as the second argument to the OggPlayReader's initialise
 119  * function. E.g. in case of OggPlayTCPReader block == 0 sets the socket to non-blocking
 120  * mode.
 121  * @retval E_OGGPLAY_OK on success
 122  * @retval E_OGGPLAY_OGGZ_UNHAPPY something went wrong while calling oggz_io_set_* functions.
 123  * @retval E_OGGPLAY_BAD_INPUT got EOF or OGGZ_ERR_HOLE_IN_DATA occured.
 124  * @retval E_OGGPLAY_OUT_OF_MEMORY ran out of memory
 125  * @retval E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle.
 126  */
 127 OggPlayErrorCode
 128 oggplay_initialise(OggPlay *me, int block);
 129
 130 /**
 131  * Sets a user defined OggPlayDataCallback function for the OggPlay handle.
 132  *
 133  * @param me OggPlay handle.
 134  * @param callback A custom callback function.
 135  * @param user Arbitrary data one wishes to pass to the callback function.
 136  * @retval E_OGGPLAY_OK on success
 137  * @retval E_OGGPLAY_BUFFER_MODE We are running in buffer mode, i.e. oggplay_use_buffer
 138  * has been called earlier.
 139  * @retval E_OGGPLAY_BAD_OGGPLAY Invalid OggPlay handle.
 140  */
 141 OggPlayErrorCode
 142 oggplay_set_data_callback(OggPlay *me, OggPlayDataCallback callback,
 143                           void *user);
 144
 145
 146 OggPlayErrorCode
 147 oggplay_set_callback_num_frames(OggPlay *me, int stream, int frames);
 148
 149 OggPlayErrorCode
 150 oggplay_set_callback_period(OggPlay *me, int stream, int milliseconds);
 151
 152 OggPlayErrorCode
 153 oggplay_set_offset(OggPlay *me, int track, ogg_int64_t offset);
 154
 155 /**
 156  * Get the given video track's Y-plane's width and height.
 157  *
 158  * @param me OggPlay handle
 159  * @param track the track number of the video track
 160  * @param y_width the width of the Y-plane
 161  * @param y_height the height of the Y-plane
 162  * @retval E_OGGPLAY_OK on success.
 163  * @retval E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle
 164  * @retval E_OGGPLAY_BAD_TRACK the given track number does not exists
 165  * @retval E_OGGPLAY_WRONG_TRACK_TYPE the given track is not an audio track
 166  * @retval E_OGGPLAY_UNINITIALISED the OggPlay handle is uninitalised.
 167  */
 168 OggPlayErrorCode
 169 oggplay_get_video_y_size(OggPlay *me, int track, int *y_width, int *y_height);
 170
 171 /**
 172  * Get the given video track's UV-plane's width and height.
 173  *
 174  * @param me OggPlay handle
 175  * @param track the track number of the video track
 176  * @param uv_width the width of the UV-plane
 177  * @param uv_height the height of the UV-plane
 178  * @retval E_OGGPLAY_OK on success.
 179  * @retval E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle
 180  * @retval E_OGGPLAY_BAD_TRACK the given track number does not exists
 181  * @retval E_OGGPLAY_WRONG_TRACK_TYPE the given track is not an audio track
 182  * @retval E_OGGPLAY_UNINITIALISED the OggPlay handle is uninitalised.
 183  */
 184 OggPlayErrorCode
 185 oggplay_get_video_uv_size(OggPlay *me, int track, int *uv_width, int *uv_height);
 186
 187 /**
 188  * Get the number of channels of the audio track.
 189  *
 190  * @param me OggPlay handle
 191  * @param track the track number of the audio track
 192  * @param channels the number of channels of the given audio track.
 193  * @retval E_OGGPLAY_OK on success.
 194  * @retval E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle
 195  * @retval E_OGGPLAY_BAD_TRACK the given track number does not exists
 196  * @retval E_OGGPLAY_WRONG_TRACK_TYPE the given track is not an audio track
 197  * @retval E_OGGPLAY_UNINITIALISED the OggPlay handle is uninitalised.
 198  */
 199 OggPlayErrorCode
 200 oggplay_get_audio_channels(OggPlay *me, int track, int *channels);
 201
 202 /**
 203  * Get the sample rate of the of the audio track
 204  *
 205  * @param me OggPlay handle
 206  * @param track the track number of the audio track
 207  * @param samplerate the sample rate of the audio track.
 208  * @retval E_OGGPLAY_OK on success.
 209  * @retval E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle
 210  * @retval E_OGGPLAY_BAD_TRACK the given track number does not exists
 211  * @retval E_OGGPLAY_WRONG_TRACK_TYPE the given track is not an audio track
 212  * @retval E_OGGPLAY_UNINITIALISED the OggPlay handle is uninitalised.
 213  */
 214 OggPlayErrorCode
 215 oggplay_get_audio_samplerate(OggPlay *me, int track, int *samplerate);
 216
 217 /**
 218  * Get the frame-per-second value the of a given video track.
 219  *
 220  * @param me OggPlay handle
 221  * @param track the track number of the audio track
 222  * @param fps_denom the denumerator of the FPS
 223  * @param fps_num the numerator of the FPS
 224  * @retval E_OGGPLAY_OK on success.
 225  * @retval E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle
 226  * @retval E_OGGPLAY_BAD_TRACK the given track number does not exists
 227  * @retval E_OGGPLAY_WRONG_TRACK_TYPE the given track is not an audio track
 228  * @retval E_OGGPLAY_UNINITIALISED the OggPlay handle is uninitalised.
 229  */
 230 OggPlayErrorCode
 231 oggplay_get_video_fps(OggPlay *me, int track, int* fps_denom, int* fps_num);
 232
 233 OggPlayErrorCode
 234 oggplay_get_video_aspect_ratio(OggPlay *me, int track, int* aspect_denom, int* aspect_num);
 235
 236 OggPlayErrorCode
 237 oggplay_convert_video_to_rgb(OggPlay *me, int track, int convert, int swap_rgb);
 238
 239 OggPlayErrorCode
 240 oggplay_get_kate_category(OggPlay *me, int track, const char** category);
 241
 242 OggPlayErrorCode
 243 oggplay_get_kate_language(OggPlay *me, int track, const char** language);
 244
 245 OggPlayErrorCode
 246 oggplay_set_kate_tiger_rendering(OggPlay *me, int track, int use_tiger, int swap_rgb, int default_width, int default_height);
 247
 248 OggPlayErrorCode
 249 oggplay_overlay_kate_track_on_video(OggPlay *me, int kate_track, int video_track);
 250
 251 OggPlayErrorCode
 252 oggplay_start_decoding(OggPlay *me);
 253
 254 /**
 255  * Decode the streams in the Ogg container until we find data that hasn't
 256  * been presented, yet.
 257  *
 258  * Whenever there is data that hasn't been presented the OggPlayDataCallback
 259  * function will be called.
 260  *
 261  * @param me OggPlay handle
 262  * @retval E_OGGPLAY_OK reached the end of the stream or shutdown detected
 263  * @retval E_OGGPLAY_CONTINUE successfully decoded the frames.
 264  * @retval E_OGGPLAY_BAD_INPUT OGGZ_ERR_HOLE_IN_DATA occured while decoding
 265  * @retval E_OGGPLAY_UNINITIALISED the OggPlayDataCallback of the OggPlay handle is not set.
 266  * @retval E_OGGPLAY_USER_INTERRUPT user interrupted the decoding
 267  * @retval E_OGGPLAY_OUT_OF_MEMORY ran out of memory while decoding
 268  */
 269 OggPlayErrorCode
 270 oggplay_step_decoding(OggPlay *me);
 271
 272 /**
 273  * Use the built-in OggPlayBuffer for buffering the decoded frames
 274  *
 275  * The built-in OggPlayBuffer implements a simple lock-free FIFO for
 276  * storing the decoded frames.
 277  *
 278  * It tries to set the OggPlay handle's OggPlayDataCallback function to it's
 279  * own implementation (oggplay_buffer_callback). Thus it will fail if
 280  * a user already set OggPlayDataCallback of the OggPlay handle
 281  * with oggplay_set_data_callback.
 282  *
 283  * One can retrive the next record in the queue by
 284  * calling oggplay_buffer_retrieve_next.
 285  *
 286  * @param player the OggPlay handle
 287  * @param size The size of the buffer, i.e. the number of records it can store
 288  * @retval E_OGGPLAY_OK on succsess
 289  * @retval E_OGGPLAY_BAD_OGGPLAY The supplied OggPlay handle is not valid
 290  * @retval E_OGGPLAY_CALLBACK_MODE The given OggPlay handle's OggPlayDataCallback
 291  * function is already set, i.e. running in callback-mode.
 292  * @retval E_OGGPLAY_OUT_OF_MEMORY Ran out of memory while trying to allocate memory for the buffer.
 293  */
 294 OggPlayErrorCode
 295 oggplay_use_buffer(OggPlay *player, int size);
 296
 297 /**
 298  * Retrive the next element in the buffer.
 299  *
 300  * @param player OggPlay handle
 301  * @return array of OggPlayCallbackInfo - one per track.
 302  * @retval NULL if there was no available.
 303  */
 304 OggPlayCallbackInfo **
 305 oggplay_buffer_retrieve_next(OggPlay *player);
 306
 307 /**
 308  * Release the given buffer item.
 309  *
 310  * After retrieving and processing one buffer item, in order
 311  * to remove the given item from the queue and release the
 312  * memory allocated by the buffer item one needs to call this
 313  * function.
 314  *
 315  * @param player OggPlay handle
 316  * @param track_info OggPlayCallbackInfo array to release.
 317  * @retval E_OGGPLAY_OK on success.
 318  * @retval E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle.
 319  */
 320 OggPlayErrorCode
 321 oggplay_buffer_release(OggPlay *player, OggPlayCallbackInfo **track_info);
 322
 323 void
 324 oggplay_prepare_for_close(OggPlay *me);
 325
 326 /**
 327  * Destroys the OggPlay handle along with the associated OggPlayReader
 328  * and clears out the buffer and shuts down the callback function.
 329  *
 330  * @param player an OggPlay handle
 331  * @retval E_OGGPLAY_OK on success
 332  */
 333 OggPlayErrorCode
 334 oggplay_close(OggPlay *player);
 335
 336 int
 337 oggplay_get_available(OggPlay *player);
 338
 339 /**
 340  * Get the duration of the Ogg content.
 341  *
 342  * @param player OggPlay handle.
 343  * @return The duration of the content in milliseconds.
 344  * @retval E_OGGPLAY_BAD_OGGPLAY invalid OggPlay handle
 345  */
 346 ogg_int64_t
 347 oggplay_get_duration(OggPlay * player);
 348
 349 int
 350 oggplay_media_finished_retrieving(OggPlay * player);
 351
 352 #ifdef __cplusplus
 353 }
 354 #endif
 355
 356 #endif /* __OGGPLAY_H__ */