]> hackersguide GünterBartsch HeikoSchäfer 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). Quite slow and due to be replaced by ffmpeg's mp3 decoder. 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) object 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, 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. xine plugins are basically shared libraries that export one public function init_*_plugin (exact function name depends on plugin type). This function returns a pointer to freshly malloced struct containing mainly function pointers, the "methods" of the plugin. If you think this is pretty much an object-oriented aproach, you're right. You'll find exact definitions of public functions and plugin structs in the appropriate header files (e.g. demux/demux.h, input/input_plugin.h, xine-engine/video_out.h,...). Most plugins will need some additional "private" data fields. These should be simply added at the end of the plugin struct, e.g. a demuxer plugin called "foo" with two private fields "xine" and "count" would have a plugin struct like typedef struct { /* public fields "inherited" from demux.h */ demux_plugin_t demux_plugin; xine_t *xine; int count; } demux_foo_t; 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). 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); /* * 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. 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).