]> hackersguide GünterBartsch HeikoSchäfer RichardWareham MiguelFreitas JamesCourtier-Dutton 2001-2002 the xine project team This document should help xine hackers to find their way through xine's architecture and source code. It's a pretty free-form document containing a loose collection of articles describing various aspects of xine's internals. &intro; The source directory in xine-lib contains several modules, this should give you a quick overview on where to find what sources: The heart of xine - it's engine. Contains code to load and handle all the plugins, as well as the generic decoding and synchroniation/output code. Audio output plugins, these provide a thin abstraction layer over different types of audio output architectures/platforms. Basically an audio output plugin provides functions to query/setup the audio hardware and output audio data (e.g. PCM samples). Demuxer plugins that handle various system layer file formats like avi, asf or mpeg. Code specific to the dxr3 / hollywood+ hardware mpeg decoder. Dolby digital audio decoder plugin. Video decoder plugin using libdivx4linux if it is installed. Audio decoder plugin that does nothing but passing through DTS (AC5) data to the audio output plugin. This is only usefull when using an external hardware DTS decoder. Various Audio/Video decoder plugins based on ffmpeg; most importantly this contains a free mpeg-4 video decoder. Audio decoder plugin that "decodes" raw PCM data; most notably endianess-conversions are done here. Mpeg audio decoder plugin (i.e. mp3 decoding). ISO/IEC compliant decoder using fixed point math. Most important mpeg video decoder plugin, provides fast and high-precision mpeg-1/2 video decoding. Various subtitle (spu: subpicture, dvd slang) decoder plugins. Vorbis audio decoder plugin. Video/Audio decoder plugins that exploit some wine code to use win32 (media player) codecs in xine. Works on x86 platforms only. Contains various video output driver plugins. Video output drivers are thin abstraction layers over various video output platforms (e.g. X11, directfb, directX,...). Video output driver plugins provide functions like frame allocation and drawing and handle stuff like hardware acceleration, scaling and colorspace conversion if necessary. They do not handle a/v sync since this is done in the xine-engine already. collection of utility functions and platform abstractions. deprecated. xine architecture Media streams usually consist of audio- and video-packages multiplexed into one bitstream in the so-called system-layer (e.g. AVI, Quicktime or Mpeg). A demuxer plugin is used to parse the system layer and extract audio- and video- packages. The demuxer uses an input-plugin to read the data and stores it in pre-allocated buffers from the global buffer pool. The buffers are then added to the audio- or video- fifo. From the other end of these fifos audio-/video-decoder threads remove the buffers and hand them over to the current audio- or video- decoder plugin for decompression. These plugins then send the decoded data to the audio-/video- output layers. The buffer holding the encoded data is no longer needed and thus released to the global buffer pool. xine uses a lot of design principles normally found in object oriented designs. As xine is written in c, a few basic principles shall be explained here on how xine is object oriented anyway. classes are structs containing (ideally only) function pointers in xine. Example: typedef struct my_stack_s my_class_t; struct my_stack_s { /* method "push" with one parameter and no return value*/ void (*push) (my_stack_t *this, int i); /* method "add" with no parameters and no return value */ void (*add) (my_stack_t *this); /* method "pop" with no parameters (except "this") and a return value */ int (*pop) (my_stack_t *this); } ; /* constructor */ my_class_t *new_my_stack (...); to implement such a "class", frequently "private" member variables can be added: typedef struct { my_stack_t stack; /* public part */ /* private part follows here */ int values[MAX_STACK_SIZE]; int stack_size; } intstack_t; each method is implemented as a static method (static to prevent namespace pollution). The "this" pointer needs to be cast to the private pointer type to gain access to the private member variables. Implementation of the "push" method follows: static void push (my_stack_t *this_gen, int i) { intstack_t *this = (intstack_t *) this_gen; } Finally the contructor mallocs() the data structs (private variant) and fills in function pointers and default values. Usually the constructor is the only public (i.e. non-static) function in the module: my_stack_t *new_my_stack (...) { intstack_t *this; /* alloc memory */ this = malloc (sizeof (intstack_t)); /* fill in methods */ this->push = push; this->add = add; this->pop = pop; /* init data fields */ this->stack_size = 0; /* cast & return */ return (my_stack_t *) this; } Metronom serves two purposes: generate vpts (virtual presentation time stamps) from pts (presentation time stamps) for a/v output and synchronization. provide a master clock (system clock reference, scr), possibly provided by external scr plugins (this can be used if some hardware decoder or network server dictates the time). pts/vpts values are given in 1/90000 sec units. pts values in mpeg streams may wrap (that is, return to zero or any other value without further notice), can be missing on some frames or (for broken streams) may "dance" around the correct values. Metronom therefore has some heuristics built-in to generate clean vpts values which can then be used in the output layers to schedule audio/video output. The heuristics used in metronom have always been a field of research. Current metronom's implementation tries to stick to pts values as reported from demuxers, that is, vpts may be obtained by a simple operation of vpts = pts + vpts_offset, where vpts_offset takes into account any wraps. Whenever pts is zero, metronom will estimate vpts based on previous values. If a difference is found between the estimated and calculated vpts values by above formula, it will be smoothed by using a "drift correction". Every image frame or audio buffer leaving decoder is tagged by metronom with a vpts information. This will tell video_out and audio_out threads when that data should be presented. Usually there isn't a significative delay associated with video driver, so we expect it to get on screen at the time it's delivered for drawing. Unfortunatelly the same isn't true for audio: all sound cards implement some amount of buffering (or fifo), any data being send to it now will only get played some time in future. audio_out thread must take this into account for making perfect A-V sync by asking the sound latency to audio driver. Some audio drivers can't tell the current delay introduced in playback. This is specially true for most sound servers like ESD or aRts and explain why in such cases rarelly the sync is perfect. Another problem xine must handle is the sound card clock drift. vpts are compared to the system clock for presentation but sound card is sampling audio at it's own clocking mechanism, so a small drift may occur. As the playback goes on this error will be integrated possibly resulting audio gaps or frame drops. To avoid that annoying effect the small sound card errors are feedbacked to metronom. The details are given by audio_out.c comments: /* By adding gap errors (difference between reported and expected * sound card clock) into metronom's vpts_offset we can use its * smoothing algorithms to correct sound card clock drifts. * obs: previously this error was added to xine scr. * * audio buf ---> metronom --> audio fifo --> (buf->vpts - hw_vpts) * (vpts_offset + error) gap * <---------- control --------------| * * Unfortunately audio fifo adds a large delay to our closed loop. * * These are designed to avoid updating the metronom too fast. * - it will only be updated 1 time per second (so it has a chance of * distributing the error for several frames). * - it will only be updated 2 times for the whole audio fifo size * length (so the control will wait to see the feedback effect) * - each update will be of gap/SYNC_GAP_RATE. * * Sound card clock correction can only provide smooth playback for * errors < 1% nominal rate. For bigger errors (bad streams) audio * buffers may be dropped or gaps filled with silence. */ The roots of xine overlays capabilities are DVD subpictures and subtitles support (also known as 'spu'). The DVD subtitles are encoded in a RLE (Run Length Encoding - the most simple compressing technique) format, with a palette of colors and transparency levels. You probably thought that subtitles were just simple text saved into DVDs, right? Wrong, they are bitmaps. In order to optimize to the most common case, xine internal format for screen overlays is a similar representation to the 'spu' data. This brings not only performance benefit (since blending functions may skip large image areas due to RLE) but also compatibility: it's possible to reencode any xine overlay to the original spu format for displaying with mpeg hardware decoders like DXR3. Displaying subtitles requires the ability to sync them to the video stream. This is done using the same kind of pts/vpts stuff of a-v sync code. DVD subtitles, for example, may request: show this spu at pts1 and hide it at pts2. This brings the concept of the 'video overlay manager', that is a event-driven module for managing overlay's showing and hiding. The drawback of using internal RLE format is the difficulty in manipulating it as graphic. To overcome that we created the 'OSD renderer', where OSD stands for On Screen Display just like in TV sets. The osd renderer is a module providing simple graphic primitives (lines, rectagles, draw text etc) over a "virtual" bitmap area. Everytime we want to show that bitmap it will be RLE encoded and sent to the overlay manager for displaying. overlays architecture The overlay manager interface is available to any xine plugin. It's a bit unlikely to be used directly, anyway here's a code snipped for enqueueing an overlay for displaying: video_overlay_event_t event; event.object.handle = this->video_overlay->get_handle(this->video_overlay,0); memset( this->event.object.overlay, 0, sizeof(*this->event.object.overlay) ); /* set position and size for this overlay */ event.object.overlay->x = 0; event.object.overlay->y = 0; event.object.overlay->width = 100; event.object.overlay->height = 100; /* clipping region is mostly used by dvd menus for highlighting buttons */ event.object.overlay->clip_top = 0; event.object.overlay->clip_bottom = image_height; event.object.overlay->clip_left = 0; event.object.overlay->clip_right = image_width; /* the hard part: provide a RLE image */ event.object.overlay->rle = something; /* palette must contain YUV values for each color index */ memcpy(event.object.overlay->clip_color, color, sizeof(color)); /* this table contains transparency level for each color index. 0 = completely transparent, 15 - completely opaque */ memcpy(event.object.overlay->clip_trans, trans, sizeof(trans)); /* set the event type and time for displaying */ event.event_type = EVENT_SHOW_SPU; event.vpts = 0; /* zero is a special vpts value, it means 'now' */ video_overlay->add_event(video_overlay,(void *)&event); OSD is a general API for rendereing stuff over playing video. It's available both to xine plugins and to frontends. The first thing you need is to allocate a OSD object for drawing from the renderer. The code below allocates a 300x200 area. This size can't be changed during the lifetime of a OSD object, but it's possible to place it anywhere over the image. osd_object_t osd; osd = this->osd_renderer->new_object (osd_renderer, 300, 200); Now we may want to set font and color for text rendering. Although we will refer to fonts over this document, in fact it can be any kind of bitmap. Font files are searched and loaded during initialization from /usr/[local]/share/xine/fonts/ and ~/.xine/fonts. There's a sample utility to convert truetype fonts at /xine-lib/misc/xine-fontconv.c. Palette may be manipulated directly, however most of the time it's convenient to use pre-defined text palettes. /* set sans serif 24 font */ osd_renderer->set_font (osd, "sans", 24); /* copy pre-defined colors for white, black border, transparent background to starting at the index used by the first text palette */ osd_renderer->set_text_palette (osd, TEXTPALETTE_WHITE_BLACK_TRANSPARENT, OSD_TEXT1 ); /* copy pre-defined colors for white, no border, translucid background to starting at the index used by the second text palette */ osd_renderer->set_text_palette (osd, TEXTPALETTE_WHITE_NONE_TRANSLUCID, OSD_TEXT2 ); Now render the text and show it: osd_renderer->render_text(osd, 0, 0, "white text, black border", OSD_TEXT1 ); osd_renderer->render_text(osd, 0, 30, "white text, no border", OSD_TEXT2 ); osd_renderer->show(osd, 0); /* 0 stands for 'now' */ There's a 1:1 mapping between OSD objects and overlays, therefore the second time you send an OSD object for displaying it will actually substitute the first image. By using set_position() function we can move overlay over the video. for( i=0; i < 100; i+=10 ) { osd_renderer->set_position(osd, i, i ); osd_renderer->show(osd, 0); sleep(1); } osd_renderer->hide(osd, 0); For additional functions please check osd.h. The palette functions demand some additional explanation, skip this if you just want to write text fast without worring with details! :) We have a 256-entry palette, each one defining yuv and transparency levels. Although xine fonts are bitmaps and may use any index they want, we have defined a small convention: /* Palette entries as used by osd fonts: 0: not used by font, always transparent 1: font background, usually transparent, may be used to implement translucid boxes where the font will be printed. 2-5: transition between background and border (usually only alpha value changes). 6: font border. if the font is to be displayed without border this will probably be adjusted to font background or near. 7-9: transition between border and foreground 10: font color (foreground) */ The so called 'transitions' are used to implement font anti-aliasing. That convention requires that any font file must use only the colors from 1 to 10. When we use the set_text_palette() function we are just copying 11 palette entries to the specified base index. That base index is the same we pass to render_text() function to use the text palette. With this scheme is possible to have several diferent text colors at the same time and also draw fonts over custom background. /* obtains size the text will occupy */ renderer->get_text_size (osd, text, &width, &height); /* draws a box using font background color (translucid) */ renderer->filled_rect(osd, x1, y1, x1+width, y1+height, OSD_TEXT2 + 1 ); /* render text */ renderer->render_text(osd, x1, y1, text, OSD_TEXT2 ); xine plugins are built as shared libraries that export at least one public function named init_type_plugin, where type reflects the function of the plugin (video, audio, etc). This function returns a pointer to freshly allocated (typically via malloc()) structure containing mainly function pointers; these are the "methods" of the plugin. If you think this is pretty much an object-oriented aproach, then you're right. All plugins are installed in a special xine plugins directory which can be found using the xine-config --plugindir command. You'll find exact definitions of public functions and plugin structs in the appropriate header files for each plugin type (e.g. demux/demux.h, input/input_plugin.h, xine-engine/video_out.h, etc) within the xine source-code. Many plugins will need some additional "private" data fields. These should be simply added at the end of the plugin structure. For example a demuxer plugin called "foo" with two private fields "xine" and "count" may have a plugin structure declared in the following way: typedef struct { /* public fields "inherited" from demux.h */ demux_plugin_t demux_plugin; xine_t *xine; int count; } demux_foo_t; The plugin would then access public fields via the demux_plugin field and private fields directly. Use an existing demuxer plugin, e.g. demux_mpeg_block as an example. Demuxers need to start/stop their own thread for performance reasons (input plugins may block and if the demuxer runs in a seperate thread other xine modules can work during blocking time). Since xine 0.9.9 some important responsibilities were assigned to demuxers, like providing precise information about pts discontinuities. Besides that it's up to demuxer to tag buffer packets with the specified codec to use and provide control buffers with start and stop information for the rest of the engine. You need to implement all the functions given in demux.h: struct demux_plugin_s { /* * plugin interface version, lower versions _may_ be supported */ int interface_version; /* * ask demuxer to open the given stream (input-plugin) * using the content-detection method specified in "stage" * * return values: * DEMUX_CAN_HANDLE on success * DEMUX_CANNOT_HANDLE on failure */ int (*open) (demux_plugin_t *this, input_plugin_t *ip, int stage); /* * start demux thread * * for seekable streams, a start position can be specified * * start_pos : position in input source * start_time : position measured in seconds from stream start * * if both parameters are !=0 start_pos will be used * for non-seekable streams both values will be ignored */ void (*start) (demux_plugin_t *this, fifo_buffer_t *video_fifo, fifo_buffer_t *audio_fifo, off_t start_pos, int start_time); /* * ask running demux thread to seek * * for seekable streams, a start position can be specified * * start_pos : position in input source * start_time : position measured in seconds from stream start * * if both parameters are !=0 start_pos will be used * for non-seekable streams both values will be ignored */ void (*seek) (demux_plugin_t *this, off_t start_pos, int start_time); /* * stop & kill demux thread, free resources associated with current * input stream */ void (*stop) (demux_plugin_t *this) ; /* * close demuxer, free all resources */ void (*close) (demux_plugin_t *this) ; /* * returns DEMUX_OK or DEMUX_FINISHED */ int (*get_status) (demux_plugin_t *this) ; /* * return human readable identifier for this plugin */ char* (*get_identifier) (void); /* * return MIME types supported for this plugin */ char* (*get_mimetypes) (void); /* * estimate stream length in seconds * may return 0 for non-seekable streams */ int (*get_stream_length) (demux_plugin_t *this); } ; Demuxer plugins export only one function: demux_plugin_t *init_demux_plugin (int iface_version, xine_t *xine); this is called on startup when the demuxer plugin is loaded. The funtion should malloc() a demux_plugin_t* pointer, fill in the function pointers and return the demux_plugin_t * pointer. Demuxer must send data to decoders using two fifo of buffers fifo_video and audio_fifo. Both are passed on demuxer start() method. The following code fragment shows how it's done. buf_element_t *buf; buf = this->video_fifo->buffer_pool_alloc (this->video_fifo); buf->type = BUF_CONTROL_NEWPTS; buf->disc_off = start_pts; this->video_fifo->put (this->video_fifo, buf); Buffers must have set the type field as shown. Several buffer types are defined in buffer.h, and most of them are information needed to select a particular decoder. /* * buffer types * * a buffer type ID describes the contents of a buffer * it consists of three fields: * * buf_type = 0xMMDDCCCC * * MM : major buffer type (CONTROL, VIDEO, AUDIO, SPU) * DD : decoder selection (e.g. MPEG, OPENDIVX ... for VIDEO) * CCCC : channel number or other subtype information for the decoder */ #define BUF_MAJOR_MASK 0xFF000000 #define BUF_DECODER_MASK 0x00FF0000 /* control buffer types */ #define BUF_CONTROL_BASE 0x01000000 #define BUF_CONTROL_START 0x01000000 #define BUF_CONTROL_END 0x01010000 #define BUF_CONTROL_QUIT 0x01020000 #define BUF_CONTROL_DISCONTINUITY 0x01030000 /* former AVSYNC_RESET */ #define BUF_CONTROL_NOP 0x01040000 #define BUF_CONTROL_AUDIO_CHANNEL 0x01050000 #define BUF_CONTROL_SPU_CHANNEL 0x01060000 #define BUF_CONTROL_NEWPTS 0x01070000 #define BUF_CONTROL_RESET_DECODER 0x01080000 /* video buffer types: (please keep in sync with buffer_types.c) */ #define BUF_VIDEO_BASE 0x02000000 #define BUF_VIDEO_MPEG 0x02000000 #define BUF_VIDEO_MPEG4 0x02010000 #define BUF_VIDEO_CINEPAK 0x02020000 #define BUF_VIDEO_SORENSON 0x02030000 #define BUF_VIDEO_MSMPEG4_V12 0x02040000 #define BUF_VIDEO_MSMPEG4_V3 0x02050000 #define BUF_VIDEO_MJPEG 0x02060000 #define BUF_VIDEO_IV50 0x02070000 #define BUF_VIDEO_IV41 0x02080000 #define BUF_VIDEO_IV32 0x02090000 #define BUF_VIDEO_IV31 0x020a0000 #define BUF_VIDEO_ATIVCR1 0x020b0000 #define BUF_VIDEO_ATIVCR2 0x020c0000 #define BUF_VIDEO_I263 0x020d0000 #define BUF_VIDEO_RV10 0x020e0000 #define BUF_VIDEO_RGB 0x02100000 #define BUF_VIDEO_YUY2 0x02110000 #define BUF_VIDEO_JPEG 0x02120000 #define BUF_VIDEO_WMV7 0x02130000 #define BUF_VIDEO_WMV8 0x02140000 #define BUF_VIDEO_MSVC 0x02150000 #define BUF_VIDEO_DV 0x02160000 #define BUF_VIDEO_REAL 0x02170000 #define BUF_VIDEO_VP31 0x02180000 #define BUF_VIDEO_H263 0x02190000 #define BUF_VIDEO_3IVX 0x021A0000 /* audio buffer types: (please keep in sync with buffer_types.c) */ #define BUF_AUDIO_BASE 0x03000000 #define BUF_AUDIO_A52 0x03000000 #define BUF_AUDIO_MPEG 0x03010000 #define BUF_AUDIO_LPCM_BE 0x03020000 #define BUF_AUDIO_LPCM_LE 0x03030000 #define BUF_AUDIO_DIVXA 0x03040000 #define BUF_AUDIO_DTS 0x03050000 #define BUF_AUDIO_MSADPCM 0x03060000 #define BUF_AUDIO_IMAADPCM 0x03070000 #define BUF_AUDIO_MSGSM 0x03080000 #define BUF_AUDIO_VORBIS 0x03090000 #define BUF_AUDIO_IMC 0x030a0000 #define BUF_AUDIO_LH 0x030b0000 #define BUF_AUDIO_VOXWARE 0x030c0000 #define BUF_AUDIO_ACELPNET 0x030d0000 #define BUF_AUDIO_AAC 0x030e0000 #define BUF_AUDIO_REAL 0x030f0000 #define BUF_AUDIO_VIVOG723 0x03100000 /* spu buffer types: */ #define BUF_SPU_BASE 0x04000000 #define BUF_SPU_CLUT 0x04000000 #define BUF_SPU_PACKAGE 0x04010000 #define BUF_SPU_SUBP_CONTROL 0x04020000 #define BUF_SPU_NAV 0x04030000 #define BUF_SPU_TEXT 0x04040000 /* demuxer block types: */ #define BUF_DEMUX_BLOCK 0x05000000 The control buffer types are very important and must be sent by all kind of demuxers. They tell decoders to start/stop their operations and inform metronom about discontinuities, either relative or absolute. There is also a reset buffer type that must be sent when demuxers are seeking as a "warm restart" indication to the decoders. To help finding out buffer types for known codecs, functions from buffer_types.c may be used to convert "FOURCC" codes or audio format tags (as used in AVI files) to the xine type. buf->type = fourcc_to_buf_video((void*)this->avi->bih.biCompression); this->video_fifo->put (this->video_fifo, buf); Many media players expect streams to be stored within files on some local medium. In actual fact, media may be streamed over a network (e.g. via HTTP or RTP), encoded onto a specialist medium (e.g. DVD), etc. To allow you to access this media, xine supports the concept of an "input plugin". The tasks performed by an input plugin are: Validation of Media Resource Locators (MRLs). MRL specific session management (e.g. opening and closing local files). Reading blocks/specific numbers of bytes from the input device. In addition to these tasks, the input plugin may keep track of some input device-specific state information (e.g. a DVD plugin may keep track of navigational state data such as current title/chapter). There are two classes of input device which xine recognises. Byte-oriented devices can, upon request, return an arbitary non-zero number of bytes from a stream. Examples of such devices are files or network streams. Block-oriented devices, however, have a prefered block or "frame"-size. An example of such a device is a DVD where data is stored in logical blocks of 2048 bytes. One may pass the hint to xine that the plugin is block-oriented by setting the INPUT_CAP_BLOCK capability. Note that this is only a hint and xine does not guarantee that all requests to the plugin will be purely block based. The input plugin should export at least the following function: input_plugin_t *init_input_plugin (int iface, xine_t *xine) The iface parameter is the input plugin interface xine is requesting (as of writing this is '5'). The xine parameter is a pointer to the global xine_t for this session. The function should return a pointer to an allocated input_plugin_t (defined in xine/input_plugin.h) which has the following definition: struct input_plugin_s { /* * plugin interface version, lower versions _may_ be supported */ int interface_version; /* * return capabilities of input source */ uint32_t (*get_capabilities) (input_plugin_t *this); /* * open input MRL - return 1 if succ */ int (*open) (input_plugin_t *this, char *mrl); /* * read nlen bytes, return number of bytes read */ off_t (*read) (input_plugin_t *this, char *buf, off_t nlen); /* * read one block, return newly allocated block (or NULL on failure) * for blocked input sources len must be == blocksize * the fifo parameter is only used to get access to the buffer_pool_alloc function */ buf_element_t *(*read_block)(input_plugin_t *this, fifo_buffer_t *fifo, off_t len); /* * seek position, return new position * * if seeking failed, -1 is returned */ off_t (*seek) (input_plugin_t *this, off_t offset, int origin); /* * get current position in stream. * */ off_t (*get_current_pos) (input_plugin_t *this); /* * return length of input (-1 => unlimited, e.g. stream) */ off_t (*get_length) (input_plugin_t *this); /* * return block size of input source (if supported, 0 otherwise) */ uint32_t (*get_blocksize) (input_plugin_t *this); /* * ls function * return value: NULL => filename is a file, **char=> filename is a dir */ mrl_t** (*get_dir) (input_plugin_t *this, char *filename, int *nFiles); /* * eject/load the media (if it's possible) * * returns 0 for temporary failures */ int (*eject_media) (input_plugin_t *this); /* * return current MRL */ char * (*get_mrl) (input_plugin_t *this); /* * stop input source */ void (*stop) (input_plugin_t *this); /* * close input source */ void (*close) (input_plugin_t *this); /* * return human readable (verbose = 1 line) description for this plugin */ char* (*get_description) (input_plugin_t *this); /* * return short, human readable identifier for this plugin * this is used for GUI buttons, The identifier must have max. 4 characters * characters (max. 5 including terminating \0) */ char* (*get_identifier) (input_plugin_t *this); /* * generate autoplay list * return value: list of MRLs */ char** (*get_autoplay_list) (input_plugin_t *this, int *nFiles); /* * request optional data from input plugin. */ int (*get_optional_data) (input_plugin_t *this, void *data, int data_type); /* * check if it is possible/valid to directly branch to this MRL * optional: may be NULL */ int (*is_branch_possible) (input_plugin_t *this, char *next_mrl); }; Typically the init_input_plugin function will initialise all these parameters. The get_capabilities parameter points to a function which returns a bit mask describing the input device's capabilities. You may logically OR the following constants together to get a suitable bit-mask (via the '|' operator). INPUT_CAP_NOCAP -- Input device has no capabilities (alias for '0'). INPUT_CAP_SEEKABLE -- Input device may be 'seeked' (i.e. random access is possible, usually not available on, e.g., network streams). INPUT_CAP_BLOCK -- Input device has a prefered block size (i.e. is block-oriented). INPUT_CAP_AUTOPLAY -- Device can return an 'autoplay' list. INPUT_CAP_GET_DIR -- Device supports the concept of 'directorys' or 'folders' containing other MRLs. INPUT_CAP_BROWSABLE -- Device supports possible MRL enumeration and browsing via the MRL browser. INPUT_CAP_CLUT -- Somewhat of an obsolete kludge. Device supports the querying of sub-picture-unit colour palettes. INPUT_CAP_AUDIOLANG -- Device supports multiple audio streams with different names. INPUT_CAP_SPULANG -- Device supports multiple sub-picture-unit (SPU) streams with different names. INPUT_CAP_VARIABLE_BITRATE -- xine may not experimentally read from the plugin in order to guestimate bit-rate. INPUT_CAP_PREVIEW -- xine may attempt preview mode. Requires INPUT_CAP_SEEKABLE. Most input plugins that are SEEKABLE are also PREVIEWable. xine-dvdnav is an exception to this because it blocks the input during a still video image. E.g DVD Menus. The open parameter points to a function which accepts an MRL and returns a flag indicating whether this plugin accepts the MRL or not. Note that input plugins are not guaranteed to be queried in anay particular order and the first input plugin to claim an MRL gets control so try not to duplicate MRLs already found within xine. You should also do any device-specific initialisation within this function. The close parameter points to a function which cleans up after open. The read reads a specified number of bytes into a buffer and returns the number of bytes actually copied. Should the input plugin set the block-oriented hint and if the demuxer supports it, the function pointed to by read_block will be called to read a block directly into xine's demuxer FIFO buffer. The seek parameter points to a function called by xine when it is required that subsequent reads come from another part of the stream. The get_current_pos parameter points to a function which returns the current position within a finite length stream. Similarly the get_length function returns the length of the stream. The get_blocksize parameter points to a function which returns the device's prefered block-size if applicable. The get_dir parameter point to a function which returns a NULL terminated array of pointers to MRLs which are within the 'directory' passed. The eject_media parameter points to a function called when the user requests that the media be 'ejected' if possible. The get_mrl parameter points to a function which returns the current MRL. The stop parameter points to a function which stops (but does not close) the input device. get_identifier points to a function returning a (short) human-readable description for the plugin (e.g. CDA, NAV, DVD). get_autoplay_list points to a function returning a NULL-temrinated array of MRLs which arise due to the 'autoplay' feature of the plugin. In order to allow for device-dependant acceleration features, xine calls upon the video output plugin for more than just displaying images. The tasks performed by the video plugins are: Allocation of a vo_frame_s structure and its subsequent destruction. Allocation of memory for use by one frame (this is to allow for the ability of some video output plugins to map frames directly into video-card memory hence removing the need for the frame to be copied across the PCI/AGP bus at display time). Most importantly, the ability to render/copy a given frame to the output device. (Optional) The copying of the frame from a file dependant colour-space and depth into the frame structure. This is to allow for on-the fly colour-space conversion and scalaing if required (e.g. the XShm ouput plugin uses this mechanism). Although these extra responsibilities add great complexity to your plugin it should be noted that they allow plugins to take full advantage of any special hardware-acceleration without sacrificing flexibility. All video plugins take the form of a shared library which exports at least the functions init_video_out_plugin() and get_video_out_plugin_info() which returns a pointer to a vo_info_s. This structure has the following declaration: struct vo_info_s { int interface_version; /* plugin interface version */ char *id; /* id of this plugin */ char *description; /* human-readable description of this plugin */ int visual_type; /* visual type supported by this plugin */ int priority; /* priority of this plugin for auto-probing */ }; At the time of writing, the current interface version was `3' but you may wish to look at an existing plugin's source-code to check. The visual_type field is used by the xine UI to determine if it is supported by the UI (e.g. X11 output plugins require the GUI to be running under the X Windowing system) and also to determine the information passed to the init_video_out_plugin() function. The library must also export this function and it has the following declaration: vo_driver_t *init_video_out_plugin (config_values_t *config, void *visual_gen) The arguments to the function are as follows config -- A pointer to an object which allows you to register, change and access configuration information. See elsewhere in this document for more information. visual_gen -- A pointer to a visual-dependant structure/variable. For example, if you had previously claimed your plugin was of the VISUAL_TYPE_X11 type, this would be a pointer to the Display variable associated with the X-server xine is running under. See plugin source-code for other VISUAL_TYPE_... constants and associated structures. Note that this field is provided by the UI and so if you wish to add another visual type you will either need to extend an existing UI or write a new one. The function creates and returns a pointer to a vo_driver_s structure which contains the following function pointers: struct vo_driver_s { uint32_t (*get_capabilities) (vo_driver_t *this); /* for constants see above */ /* * allocate an vo_frame_t struct, * the driver must supply the copy, field and dispose functions */ vo_frame_t* (*alloc_frame) (vo_driver_t *this); /* * check if the given image fullfills the format specified * (re-)allocate memory if necessary */ void (*update_frame_format) (vo_driver_t *this, vo_frame_t *img, uint32_t width, uint32_t height, int ratio_code, int format, int flags); /* display a given frame */ void (*display_frame) (vo_driver_t *this, vo_frame_t *vo_img); /* overlay functions */ void (*overlay_blend) (vo_driver_t *this, vo_frame_t *vo_img, vo_overlay_t *overlay); /* * these can be used by the gui directly: */ int (*get_property) (vo_driver_t *this, int property); int (*set_property) (vo_driver_t *this, int property, int value); void (*get_property_min_max) (vo_driver_t *this, int property, int *min, int *max); /* * general purpose communication channel between gui and driver * * this should be used to propagate events, display data, window sizes * etc. to the driver */ int (*gui_data_exchange) (vo_driver_t *this, int data_type, void *data); void (*exit) (vo_driver_t *this); /* check if a redraw is needed (due to resize) * this is only used for still frames, normal video playback * must call that inside display_frame() function. */ int (*redraw_needed) (vo_driver_t *this); }; The get_info field is simply a pointer to the get_video_out_plugin_info() function described above. The get_capbilities field points to a function which returns a bit-wise ORed combination of the following constants which reflects the video output plugin's capabilities. #define VO_CAP_COPIES_IMAGE 0x00000001 /* driver copies image (i.e. converts it to rgb buffers in the private fields of image buffer) */ #define VO_CAP_YV12 0x00000002 /* driver can handle YUV 4:2:0 pictures */ #define VO_CAP_YUY2 0x00000004 /* driver can handle YUY2 pictures */ #define VO_CAP_HUE 0x00000010 /* driver can set HUE value */ #define VO_CAP_SATURATION 0x00000020 /* driver can set SATURATION value */ #define VO_CAP_BRIGHTNESS 0x00000040 /* driver can set BRIGHTNESS value */ #define VO_CAP_CONTRAST 0x00000080 /* driver can set CONTRAST value */ #define VO_CAP_COLORKEY 0x00000100 /* driver can set COLORKEY value */ #define VO_CAP_AUTOPAINT_COLORKEY 0x00000200 /* driver can set AUTOPAINT_COLORKEY value */ A plugin should use the VO_CAP_COPIES_IMAGE flag if it wishes to provide a copy function to perform on-the-fly colour-space conversion and scaling. The get_property, set_proprty and get_property_min_max fields point to functions which handle the getting, setting of properties and define their bounds. Valid property IDs can be found in the video_out.h header file. The gui_data_exchange field points to a function which can accept various forms of data from the UI (e.g. the mouse has moved or the window has been hidden). Look at existing plugins for examples of data exchanges from various UIs. The alloc_frame field points to a function which returns a pointer to a vo_frame_s structure which is defined as: struct vo_frame_s { struct vo_frame_s *next; int64_t pts; /* presentation time stamp (1/90000 sec) */ int64_t vpts; /* virtual pts, generated by metronom */ int bad_frame; /* e.g. frame skipped or based on skipped frame */ int duration; /* frame length in time, in 1/90000 sec */ /* yv12 (planar) base[0]: y, base[1]: u, base[2]: v */ /* yuy2 (interleaved) base[0]: yuyv..., base[1]: --, base[2]: -- */ uint8_t *base[3]; /* info that can be used for interlaced output (e.g. tv-out) */ int top_field_first; int repeat_first_field; /* pan/scan offset */ int pan_scan_x; int pan_scan_y; /* additional information to be able to duplicate frames: */ int width, height; int ratio; /* aspect ratio, codes see below */ int format; /* IMGFMT_YV12 or IMGFMT_YUY2 */ int drawn; /* used by decoder, frame has already been drawn */ int lock_counter; pthread_mutex_t mutex; /* protect access to lock_count */ /* "backward" references to where this frame originates from */ vo_instance_t *instance; vo_driver_t *driver; int id; /* debugging - track this frame */ /* * member functions */ /* this frame is no longer used by the decoder */ void (*free) (vo_frame_t *vo_img); /* tell video driver to copy/convert a slice of this frame, may be NULL */ void (*copy) (vo_frame_t *vo_img, uint8_t **src); /* tell video driver that the decoder starts a new field */ void (*field) (vo_frame_t *vo_img, int which_field); /* append this frame to the display queue, returns number of frames to skip if decoder is late */ int (*draw) (vo_frame_t *vo_img); /* this frame is no longer used by the video driver */ void (*displayed) (vo_frame_t *vo_img); /* free memory/resources for this frame */ void (*dispose) (vo_frame_t *vo_img); }; Typically the video plugin will add private fields to the end of this structure which are used for internal purposes by the plugin. The function pointers within the frame structure provides a mechanism for the driver to retain full control of how the frames are managed and rendered to. If the VO_CAP_COPIES_IMAGE flag was set in the plugins capabilities then the copy field is required and will be called sequentially for each 16-pixel high strip in the image. The plugin may then decide, based on the frame's format, how this is copied into the frame. Returning to the vo_driver_s structure, the update_frame_format field points to a function which will be called each time the colour-depth/space or size of a frame changes. Typically this function would allocate sufficient memory for the frame, assign the pointers to the individual planes of the frame to the base field of the frame and perform and driver-specific changes. The display_frame field points to a function to render a given frame to the output device. The overlay_blend field points to a function which accepts an association between a frame and overlay which will result in the latter being overlayed on the former. This section contains some guidelines for writing xine-code. These are really just guidelines, no strict rules. Contributions will not be rejected if they do not meet these rules but they will be appreciated if they do. when in doubt, use lower case. BTW: This thing is called xine, never Xine. comment your interfaces in the header files. use expressive variable and function identifiers on all public interfaces. use underscores to seperate words in identifiers, not uppercase letters (my_function_name is ok, myFunctionName is not ok). avoid macros if possible. avoid gotos. use #ifdef LOG printf ("module: ..."[,...]); #endif for debug output. All debug output must be prefixed by the module name which generates the output (see example above). refer to emac's c-mode for all questions of proper indentiation. use c-style comments (/* */), not c++-style (//) Make sure you send your patches in unified diff format to the xine-devel mailing list (you'll have to subscribe first, otherwise you're not allowed to post). Please do not send patches to individual developers unless otherwise instructed because your patch is more likely to get lost in an overfull INBOX in that case. Please be patient, it may take 1-2 weeks before you hear any comments on your work (developers may be working on other parts of the code or are simply busy at the moment).