From f01d9c7d6b37f3a345cdc4c839ae047e3c69ecea Mon Sep 17 00:00:00 2001 From: Siggi Langauf Date: Tue, 5 Feb 2002 16:15:02 +0000 Subject: =?UTF-8?q?added=20G=C3=BCnter's=20hackersguide=20update?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CVS patchset: 1474 CVS date: 2002/02/05 16:15:02 --- doc/hackersguide/hackersguide.sgml | 389 +++++++++++++++++++++++++++++++++++-- 1 file changed, 375 insertions(+), 14 deletions(-) diff --git a/doc/hackersguide/hackersguide.sgml b/doc/hackersguide/hackersguide.sgml index 2f3b8c153..b600b7c65 100644 --- a/doc/hackersguide/hackersguide.sgml +++ b/doc/hackersguide/hackersguide.sgml @@ -12,7 +12,7 @@ - 2001 + 2001-2002 the xine project team @@ -33,16 +33,158 @@ Overview - Modules - - - - Which module does what - + Source modules + The source directory in xine-lib contains several + modules, this should give you a quick overview on where + to find what sources: + + + xine-engine + 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_out + + 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). + + + + demuxers + + Demuxer plugins that handle various system layer file formats + like avi, asf or mpeg. + + + + dxr3 + + Code specific to the dxr3 / hollywood+ hardware mpeg decoder. + + + + liba52 + + Dolby digital audio decoder plugin. + + + + libdivx4 + + Video decoder plugin using libdivx4linux if it is installed. + + + + libdts + + 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. + + + + libffmpeg + + Various Audio/Video decoder plugins based on ffmpeg; most + importantly this contains a free mpeg-4 video decoder. + + + + liblpcm + + Audio decoder plugin that "decodes" raw PCM data; most notably + endianess-conversions are done here. + + + + libmad + + Mpeg audio decoder plugin (i.e. mp3 decoding). Quite slow and + due to be replaced by ffmpeg's mp3 decoder. + + + + libmpeg2 + + Most important mpeg video decoder plugin, provides fast and + high-precision mpeg-1/2 video decoding. + + + + libspucc, libspudec, libsputext + + Various subtitle (spu: subpicture, dvd slang) decoder plugins. + + + + libvorbis + + Vorbis audio decoder plugin. + + + + libw32dll + + Video/Audio decoder plugins that exploit some wine code + to use win32 (media player) codecs in xine. Works on x86 platforms + only. + + + + video_out + + 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. + + + + xine-utils + + collection of utility functions and platform abstractions. + + + + libac3, libmpg123, libvfill + + deprecated. + + - Information flow - + Architecture and data flow + + + + + + 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. + Library interfaces @@ -53,7 +195,34 @@ xine internals What is this metronom thingy ? - + + 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 engine from inside @@ -61,14 +230,141 @@ Plugin architecture - + + 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,...). + + + The public + + + 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; + + Extending xine's input Adding support for a new file format (writing a demuxer) - + + 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. + Adding support for a new audio/video format @@ -104,10 +400,75 @@ <chapter id="misc"><title>misc - Coding style - + Coding style and guidelines + + 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 names on all public interfaces. + + + + + 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 (//) + + + + + + + How to contribute + + 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). + + + -- cgit v1.2.3