diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/xine.h.in | 417 |
1 files changed, 202 insertions, 215 deletions
diff --git a/include/xine.h.in b/include/xine.h.in index 49ba0785b..815087716 100644 --- a/include/xine.h.in +++ b/include/xine.h.in @@ -17,7 +17,7 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA * - * $Id: xine.h.in,v 1.19 2002/09/22 14:29:40 mroi Exp $ + * $Id: xine.h.in,v 1.20 2002/10/14 15:46:48 guenter Exp $ * * public xine-lib (libxine) interface and documentation * @@ -25,7 +25,7 @@ * some programming guidelines about this api: * ------------------------------------------- * - * (1) libxine has (per instance) a fairly static memory + * (1) libxine has (per stream instance) a fairly static memory * model * (2) as a rule of thumb, never free() or realloc() any pointers * returned by the xine engine (unless stated otherwise) @@ -54,6 +54,7 @@ extern "C" { */ typedef struct xine_s xine_t; +typedef struct xine_stream_s xine_stream_t; typedef struct xine_ao_driver_s xine_ao_driver_t; typedef struct xine_vo_driver_s xine_vo_driver_t; @@ -67,9 +68,7 @@ typedef struct xine_vo_driver_s xine_vo_driver_t; * to fully init the xine engine, you have to load config values * (either using your own storage method and calling * xine_config_register_entry, or by using the xine_load_config - * utility function - see below) and then call xine_open_audio - * and xine_open_video to obtain audio/video pointers which - * you then pass to the xine_init function. + * utility function - see below) and then call xine_init * * the only proper way to shut down the xine engine is to * call xine_exit() - do not try to free() the xine pointer @@ -79,6 +78,12 @@ typedef struct xine_vo_driver_s xine_vo_driver_t; xine_t *xine_new (void); /* + * post_init the xine engine + */ + +void xine_init (xine_t *self); + +/* * helper functions to find and init audio/video drivers * from xine's plugin collection * @@ -88,7 +93,10 @@ xine_t *xine_new (void); * visual: video driver flavor selector, constants see below * * both functions may return NULL if driver failed to load, was not - * found ... + * found ... + * + * use xine_close_audio/video_driver() to close loaded drivers + * and free resources allocated by them */ xine_ao_driver_t *xine_open_audio_driver (xine_t *self, const char *id, @@ -97,21 +105,35 @@ xine_ao_driver_t *xine_open_audio_driver (xine_t *self, const char *id, xine_vo_driver_t *xine_open_video_driver (xine_t *self, const char *id, int visual, void *data); +void xine_close_audio_driver (xine_t *self, xine_ao_driver_t *driver); + +void xine_close_video_driver (xine_t *self, xine_vo_driver_t *driver); + /* - * post_init the xine engine, specify audio and video drivers to use + * create a new stream for media playback/access + * + * returns xine_stream_t* if OK, + * NULL on error (use xine_get_error for details) + * + * the only proper way to free the stream pointer returned by this + * function is to call xine_close() on it. do not try to access any + * fields in xine_stream_t, they're all private and subject to change + * without further notice. */ -void xine_init (xine_t *self, xine_ao_driver_t *ao, xine_vo_driver_t *vo); +xine_stream_t *xine_stream_new (xine_t *self, + xine_ao_driver_t *ao, xine_vo_driver_t *vo); /* * open a stream * - * look for input / demuxer plugins, find out about the format - * see if it is supported + * look for input / demux / decoder plugins, find out about the format + * see if it is supported, set up internal buffers and threads * * returns 1 if OK, 0 on error (use xine_get_error for details) */ -int xine_open (xine_t *self, const char *mrl); + +int xine_open (xine_stream_t *stream, const char *mrl); /* * play a stream from a given position @@ -120,7 +142,7 @@ int xine_open (xine_t *self, const char *mrl); * * returns 1 if OK, 0 on error (use xine_get_error for details) */ -int xine_play (xine_t *self, int start_pos, int start_time); +int xine_play (xine_stream_t *stream, int start_pos, int start_time); /* * set xine to a trick mode for fast forward, backwards playback, @@ -129,7 +151,7 @@ int xine_play (xine_t *self, int start_pos, int start_time); * * returns 1 if OK, 0 on error (use xine_get_error for details) */ -int xine_trick_mode (xine_t *self, int mode, int value); +int xine_trick_mode (xine_stream_t *stream, int mode, int value); /* * get information about the stream such as @@ -138,19 +160,27 @@ int xine_trick_mode (xine_t *self, int mode, int value); * constants see below */ -uint32_t xine_get_stream_info (xine_t *self, int info); -const char *xine_get_meta_info (xine_t *self, int info); +uint32_t xine_get_stream_info (xine_stream_t *stream, int info); +const char *xine_get_meta_info (xine_stream_t *stream, int info); /* - * stop playback + * stop stream playback, free all stream-related resources + * xine_stream_t stays valid for new xine_open */ -void xine_stop (xine_t *self); +void xine_stop (xine_stream_t *stream); /* * ask current/recent input plugin to eject media - may or may not work, * depending on input plugin capabilities */ -int xine_eject(xine_t *self); +int xine_eject (xine_stream_t *stream); + +/* + * stop playback, dispose all stream-related resources + * xine_stream_t no longer valid when after this + */ + +void xine_dispose (xine_stream_t *stream); /* * free all resources, close all plugins, close engine. @@ -163,32 +193,29 @@ void xine_exit (xine_t *self); */ /* return last error */ -int xine_get_error (xine_t *self); +int xine_get_error (xine_stream_t *stream); /* get current xine engine status (constants see below) */ -int xine_get_status (xine_t *self); +int xine_get_status (xine_stream_t *stream); /* * set/get xine engine parameters * e.g. playback speed, constants see below */ -void xine_set_param (xine_t *self, int param, int value); -int xine_get_param (xine_t *self, int param); +void xine_set_param (xine_stream_t *stream, int param, int value); +int xine_get_param (xine_stream_t *stream, int param); /* * try to find out audio/spu language of given channel * (use -1 for current channel) * - * returns 0-terminated string on success, NULL otherwise - * - * the pointer returned by xine_get_audio_lang stays valid until - * xine_get_audio_lang is called again. - * the pointer returned by xine_get_spu_lang stays valid until - * xine_get_spu_lang is called again. + * returns 1 on success, 0 on failure */ -const char *xine_get_audio_lang (xine_t *self, int channel); -const char *xine_get_spu_lang (xine_t *self, int channel); +int xine_get_audio_lang (xine_stream_t *stream, int channel, + char *lang); +int xine_get_spu_lang (xine_stream_t *stream, int channel, + char *lang); /* * get position / length information @@ -198,7 +225,7 @@ const char *xine_get_spu_lang (xine_t *self, int channel); * (e.g. live network streams may not have a valid length) */ -int xine_get_pos_length (xine_t *self, +int xine_get_pos_length (xine_stream_t *stream, int *pos_stream, /* 0..65535 */ int *pos_time, /* milliseconds */ int *length_time);/* milliseconds */ @@ -213,7 +240,8 @@ int xine_get_pos_length (xine_t *self, * * returns 1 on success, 0 failure. */ -int xine_get_current_frame (xine_t *self, int *width, int *height, +int xine_get_current_frame (xine_stream_t *stream, + int *width, int *height, int *ratio_code, int *format, uint8_t *img); @@ -247,46 +275,13 @@ void xine_register_log_cb (xine_t *self, xine_log_cb_t cb, void *user_data); /* - * codec reporting callback. - * - * codec_type : type of codec being reported - * (XINE_CODEC_AUDIO/XINE_CODEC_VIDEO) - * fourcc : codec identifier (fourcc) in machine endianness - * (only valid if description is empty FIXME: why?) - * description : description or human readable codec name ("" if unkown) - * handled : if true, the plugin exist and will be used - * otherwise it's an error condition - * (plugin not found or codec unknown) - */ - -#define XINE_CODEC_AUDIO 0 -#define XINE_CODEC_VIDEO 1 - -typedef void (*xine_report_codec_cb_t) (void *user_data, int codec_type, - uint32_t fourcc, - const char *description, - int handled); -/* - * register an codec reporting callback - * - * report_codec : callback function (see above) - * user_data : will be used as first parameter to callback - * - * returns 1 if the callback was registerd, 0 if it could not. - */ -int xine_register_report_codec_cb(xine_t *self, - xine_report_codec_cb_t report_codec, - void *user_data); - - -/* * xine error codes */ #define XINE_ERROR_NONE 0 #define XINE_ERROR_NO_INPUT_PLUGIN 1 -#define XINE_ERROR_NO_DEMUXER_PLUGIN 2 -#define XINE_ERROR_DEMUXER_FAILED 3 +#define XINE_ERROR_NO_DEMUX_PLUGIN 2 +#define XINE_ERROR_DEMUX_FAILED 3 /* * xine engine parameters @@ -318,10 +313,10 @@ int xine_register_report_codec_cb(xine_t *self, * engine status codes */ -#define XINE_STATUS_STOP 0 -#define XINE_STATUS_PLAY 1 -#define XINE_STATUS_QUIT 2 -#define XINE_STATUS_LOGO 3 +#define XINE_STATUS_IDLE 0 /* no mrl assigned */ +#define XINE_STATUS_STOP 1 +#define XINE_STATUS_PLAY 2 +#define XINE_STATUS_QUIT 3 /* speed values */ @@ -350,12 +345,18 @@ int xine_register_report_codec_cb(xine_t *self, #define XINE_STREAM_INFO_VIDEO_CHANNELS 5 #define XINE_STREAM_INFO_VIDEO_STREAMS 6 #define XINE_STREAM_INFO_VIDEO_BITRATE 7 -#define XINE_STREAM_INFO_FRAME_DURATION 8 /* 1/90000 sec */ -#define XINE_STREAM_INFO_AUDIO_CHANNELS 9 -#define XINE_STREAM_INFO_AUDIO_BITS 10 -#define XINE_STREAM_INFO_AUDIO_SAMPLERATE 11 -#define XINE_STREAM_INFO_AUDIO_BITRATE 12 -#define XINE_STREAM_INFO_HAS_CHAPTERS 13 +#define XINE_STREAM_INFO_VIDEO_FOURCC 8 +#define XINE_STREAM_INFO_VIDEO_HANDLED 9 /* codec available? */ +#define XINE_STREAM_INFO_FRAME_DURATION 10 /* 1/90000 sec */ +#define XINE_STREAM_INFO_AUDIO_CHANNELS 11 +#define XINE_STREAM_INFO_AUDIO_BITS 12 +#define XINE_STREAM_INFO_AUDIO_SAMPLERATE 13 +#define XINE_STREAM_INFO_AUDIO_BITRATE 14 +#define XINE_STREAM_INFO_AUDIO_FOURCC 15 +#define XINE_STREAM_INFO_AUDIO_HANDLED 16 /* codec available? */ +#define XINE_STREAM_INFO_HAS_CHAPTERS 17 +#define XINE_STREAM_INFO_HAS_VIDEO 18 +#define XINE_STREAM_INFO_HAS_AUDIO 19 /* xine_get_meta_info */ @@ -495,7 +496,7 @@ const char *const *xine_list_video_output_plugins (xine_t *self) ; */ /* talk to video output driver */ -int xine_gui_send_vo_data (xine_t *self, +int xine_gui_send_vo_data (xine_stream_t *self, int type, void *data); typedef struct { @@ -748,182 +749,168 @@ void xine_config_save (xine_t *self, const char *cfg_filename); void xine_config_reset (xine_t *self); /* - * xine event mechanism + * async xine event mechanism + * + * to receive events you have to register an event queue with + * the xine engine (xine_event_new_queue, see below). + * + * then you can either + * 1) check for incoming events regularly (xine_event_get/wait), + * process them and free them using xine_event_free + * 2) use xine_event_create_listener_thread and specify a callback + * which will then be called for each event * - * WARNING: events can be used to break all abstraction - * layers in xine. they also are likely to cause - * deadlocks - so handle with care. + * to send events to every module listening you don't need + * to register an event queue but simply call xine_event_send. */ /* event types */ -#define XINE_EVENT_MOUSE_BUTTON 1 -#define XINE_EVENT_MOUSE_MOVE 2 -#define XINE_EVENT_SPU_BUTTON 3 -#define XINE_EVENT_SPU_CLUT 4 -#define XINE_EVENT_UI_CHANNELS_CHANGED 5 /* inform ui that new channel info is available */ -#define XINE_EVENT_UI_SET_TITLE 6 /* request title display change in ui */ -#define XINE_EVENT_INPUT_MENU1 7 -#define XINE_EVENT_INPUT_MENU2 8 -#define XINE_EVENT_INPUT_MENU3 9 -#define XINE_EVENT_INPUT_UP 10 -#define XINE_EVENT_INPUT_DOWN 11 -#define XINE_EVENT_INPUT_LEFT 12 -#define XINE_EVENT_INPUT_RIGHT 13 -#define XINE_EVENT_INPUT_SELECT 14 -#define XINE_EVENT_PLAYBACK_FINISHED 15 -#define XINE_EVENT_BRANCHED 16 -#define XINE_EVENT_NEED_NEXT_MRL 17 -#define XINE_EVENT_INPUT_NEXT 18 -#define XINE_EVENT_INPUT_PREVIOUS 19 -#define XINE_EVENT_INPUT_ANGLE_NEXT 20 -#define XINE_EVENT_INPUT_ANGLE_PREVIOUS 21 -#define XINE_EVENT_SPU_FORCEDISPLAY 22 -#define XINE_EVENT_FRAME_CHANGE 23 -#define XINE_EVENT_CLOSED_CAPTION 24 -#define XINE_EVENT_INPUT_BUTTON_FORCE 25 -#define XINE_EVENT_INPUT_MENU4 26 -#define XINE_EVENT_INPUT_MENU5 27 -#define XINE_EVENT_INPUT_MENU6 28 -#define XINE_EVENT_INPUT_MENU7 29 - -#define XINE_EVENT_INPUT_NUMBER_0 30 -#define XINE_EVENT_INPUT_NUMBER_1 31 -#define XINE_EVENT_INPUT_NUMBER_2 32 -#define XINE_EVENT_INPUT_NUMBER_3 33 -#define XINE_EVENT_INPUT_NUMBER_4 34 -#define XINE_EVENT_INPUT_NUMBER_5 35 -#define XINE_EVENT_INPUT_NUMBER_6 36 -#define XINE_EVENT_INPUT_NUMBER_7 37 -#define XINE_EVENT_INPUT_NUMBER_8 38 -#define XINE_EVENT_INPUT_NUMBER_9 39 -#define XINE_EVENT_INPUT_NUMBER_10_ADD 40 - -#define XINE_EVENT_ASPECT_CHANGE 41 /* Generally should be viewed as a hint to the GUI */ -#define XINE_EVENT_OUTPUT_VIDEO 42 -#define XINE_EVENT_OUTPUT_NO_VIDEO 43 - -#define XINE_EVENT_UI_MESSAGE 44 /* message (dialog) for the ui to display */ -#define XINE_EVENT_AUDIO_LEVEL 45 /* report current audio level (l/r) */ - -/* - * generic event type. +#define XINE_EVENT_UI_PLAYBACK_FINISHED 1 /* frontend can e.g. move on to next playlist entry */ +#define XINE_EVENT_UI_CHANNELS_CHANGED 2 /* inform ui that new channel info is available */ +#define XINE_EVENT_UI_SET_TITLE 3 /* request title display change in ui */ +#define XINE_EVENT_UI_MESSAGE 4 /* message (dialog) for the ui to display */ +#define XINE_EVENT_FRAME_FORMAT_CHANGE 5 /* e.g. aspect ratio change during dvd playback */ +#define XINE_EVENT_AUDIO_LEVEL 6 /* report current audio level (l/r) */ +#define XINE_EVENT_QUIT 7 /* last event sent when stream is disposed */ +#define XINE_EVENT_BUILDING_INDEX 8 /* event sent through index generation */ + +/* input events coming from frontend */ + +#define XINE_EVENT_INPUT_MOUSE_BUTTON 101 +#define XINE_EVENT_INPUT_MOUSE_MOVE 102 +#define XINE_EVENT_INPUT_MENU1 103 +#define XINE_EVENT_INPUT_MENU2 104 +#define XINE_EVENT_INPUT_MENU3 105 +#define XINE_EVENT_INPUT_MENU4 106 +#define XINE_EVENT_INPUT_MENU5 106 +#define XINE_EVENT_INPUT_MENU6 108 +#define XINE_EVENT_INPUT_MENU7 109 +#define XINE_EVENT_INPUT_UP 110 +#define XINE_EVENT_INPUT_DOWN 111 +#define XINE_EVENT_INPUT_LEFT 112 +#define XINE_EVENT_INPUT_RIGHT 113 +#define XINE_EVENT_INPUT_SELECT 114 +#define XINE_EVENT_INPUT_NEXT 115 +#define XINE_EVENT_INPUT_PREVIOUS 116 +#define XINE_EVENT_INPUT_ANGLE_NEXT 117 +#define XINE_EVENT_INPUT_ANGLE_PREVIOUS 118 +#define XINE_EVENT_INPUT_BUTTON_FORCE 119 +#define XINE_EVENT_INPUT_NUMBER_0 120 +#define XINE_EVENT_INPUT_NUMBER_1 121 +#define XINE_EVENT_INPUT_NUMBER_2 122 +#define XINE_EVENT_INPUT_NUMBER_3 123 +#define XINE_EVENT_INPUT_NUMBER_4 124 +#define XINE_EVENT_INPUT_NUMBER_5 125 +#define XINE_EVENT_INPUT_NUMBER_6 126 +#define XINE_EVENT_INPUT_NUMBER_7 127 +#define XINE_EVENT_INPUT_NUMBER_8 128 +#define XINE_EVENT_INPUT_NUMBER_9 129 +#define XINE_EVENT_INPUT_NUMBER_10_ADD 130 + +/* + * xine event struct */ typedef struct { - uint32_t type; /* The event type (determines remainder of struct) */ + int type; /* event type (constants see above) */ + xine_stream_t *stream; /* stream this event belongs to */ - /* Event dependent data goes after this. */ + void *data; /* contents depending on type */ + int data_length; } xine_event_t; /* - * input events + * input event dynamic data */ typedef struct { - xine_event_t event; - uint8_t button; /* Generally 1 = left, 2 = mid, 3 = right */ - uint16_t x,y; /* In Image space */ -} xine_input_event_t; + xine_event_t event; + uint8_t button; /* Generally 1 = left, 2 = mid, 3 = right */ + uint16_t x,y; /* In Image space */ +} xine_input_data_t; /* - * Menu events + * UI event dynamic data - send information to/from UI. */ -typedef struct { - xine_event_t event; - uint8_t button; - uint16_t status; /* 0:no status, 1:selected, 2:actioned */ - uint8_t command[8]; /* DVD virtual machine command. */ -} xine_menu_event_t; -/* - * SPU event - send control events to the spu decoder - */ typedef struct { - xine_event_t event; - void *data; -} xine_spu_event_t; + int num_buttons; + int str_len; + char str[256]; /* might be longer */ +} xine_ui_data_t; /* - * UI event - send information to/from UI. + * notify frame format change */ - typedef struct { - xine_event_t event; - void *data; - uint32_t data_len; - int handled; -} xine_ui_event_t; + int width; + int height; + int aspect; +} xine_format_change_data_t; /* - * ui message - ask ui to display a message dialog - * dialog can have up to three buttons, labels for - * the buttons are provided. - * the response (which button was pressed) should be - * returned in "response" with 0=>button0, 1=>button1, - * 2=>button3, -1 => window closed / error / dialog could - * not be displayed. + * audio level for left/right channel */ - typedef struct { - xine_event_t event; - char *message; - char *button0, *button1, *button2; - int num_buttons; - int response; -} xine_ui_message_event_t; + int left; + int right; /* 0..255 */ +} xine_audio_level_data_t; /* - * next_mrl + * index generation / buffering */ typedef struct { - xine_event_t event; - const char *mrl; - int handled; -} xine_next_mrl_event_t; + int percent; +} xine_idx_progress_data_t; + + +/* opaque xine_event_queue_t */ +typedef struct xine_event_queue_s xine_event_queue_t; /* - * notify frame change + * register a new event queue + * + * you have to receive messages from this queue regularly + * + * use xine_event_dispose_queue to unregister and free the queue */ -typedef struct { - xine_event_t event; - int width; - int height; - int aspect; -} xine_frame_change_event_t; + +xine_event_queue_t *xine_event_new_queue (xine_stream_t *stream); +void xine_event_dispose_queue (xine_event_queue_t *queue); /* - * closed caption + * receive events (poll) + * + * use xine_event_free on the events received from these calls + * when they're no longer needed */ -typedef struct { - xine_event_t event; - uint8_t *buffer; - uint32_t buf_len; - int64_t pts; - uint32_t scr; -} xine_closed_caption_event_t; -/* - * audio level for left/right channel +xine_event_t *xine_event_get (xine_event_queue_t *queue); +xine_event_t *xine_event_wait (xine_event_queue_t *queue); +void xine_event_free (xine_event_t *event); + +/* + * receive events (callback) + * + * a thread is created which will receive all events from + * the specified queue, call your callback on each of them + * and will then free the event when your callback returns + * */ -typedef struct { - xine_event_t event; - int left, right; /* 0..255 */ -} xine_audio_level_event_t; -/* event listener callback */ typedef void (*xine_event_listener_cb_t) (void *user_data, - xine_event_t *event); + const xine_event_t *event); +void xine_event_create_listener_thread (xine_event_queue_t *queue, + xine_event_listener_cb_t callback, + void *user_data); -/* register an event listener callback */ -int xine_register_event_listener (xine_t *self, - xine_event_listener_cb_t listener, - void *user_data); - -int xine_remove_event_listener (xine_t *self, - xine_event_listener_cb_t listener); - -/* send an event to all event listeners */ -void xine_send_event (xine_t *self, xine_event_t *event); +/* + * send an event to all queues + * + * the event will be copied so you can free or reuse + * *event as soon as xine_event_send returns. + */ +void xine_event_send (xine_stream_t *stream, const xine_event_t *event); /* @@ -954,7 +941,7 @@ void xine_send_event (xine_t *self, xine_event_t *event); typedef struct xine_osd_s xine_osd_t; -xine_osd_t *xine_osd_new (xine_t *self, int x, int y, +xine_osd_t *xine_osd_new (xine_stream_t *self, int x, int y, int width, int height); void xine_osd_draw_point (xine_osd_t *self, int x, int y, int color); @@ -1007,12 +994,12 @@ void xine_osd_get_palette (xine_osd_t *self, const uint32_t *color, */ /* dynamic info from actually linked libxine */ -const char *xine_get_version_string(void); +const char *xine_get_version_string (void); void xine_get_version (int *major, int *minor, int *sub); /* compare given version to libxine version, return 1 if compatible, 0 otherwise */ -int xine_check_version(int major, int minor, int sub) ; +int xine_check_version (int major, int minor, int sub) ; /* static info - which libxine release this header came from */ |