From 60239a297dd0e7a6454dbd15de9d0186dea93c14 Mon Sep 17 00:00:00 2001 From: Michael Roitzsch Date: Sun, 12 Oct 2003 19:06:43 +0000 Subject: updated hackersguide: * added some small pieces * incorporated some former READMEs and Mike's fabulous demuxer and decoder doc * splitted into multiple files * made new drawings (hopefully I am not the only one to understand them) * Makefile support for building a HTML version which is now installed in the user's doc directory CVS patchset: 5494 CVS date: 2003/10/12 19:06:43 --- doc/hackersguide/overview.sgml | 751 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 751 insertions(+) create mode 100644 doc/hackersguide/overview.sgml (limited to 'doc/hackersguide/overview.sgml') diff --git a/doc/hackersguide/overview.sgml b/doc/hackersguide/overview.sgml new file mode 100644 index 000000000..2c0df0420 --- /dev/null +++ b/doc/hackersguide/overview.sgml @@ -0,0 +1,751 @@ + + xine code overview + + + Walking the source tree + + The src/ directory in xine-lib contains several + modules, this should give you a quick overview on where + to find what sources. + + + Directories marked with "(imported)" contain + code that is copied from an external project into xine-lib. + Everything below such a directory is up to this project. When modifying + code there, be sure to send the patches on. + + + + + audio_out + + + Audio output plugins. These provide a thin abstraction layer + around different types of audio output architectures or platforms. + Basically an audio output plugin provides functions to query and 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. The ideal demuxer know nothing about where the + data comes from and who decodes it. It should basically just unpack + it into chunks the rest of the engine can eat. + + + + + + dxr3 + + + Code to support the DXR3 / hollywood+ hardware mpeg decoder. + + + + + + input + + + Input plugins encapsulate the origin of the data. Data sources like + ordinary files, DVDs, CDA or streaming media are handled here. + + + + + dvb + + + Some headers for Digital Video Broadcast. + + + + + + libdvdnav (imported) + + + The libdvdnav library for DVD navigation is used + by xine's DVD input plugin. + + + + + + libreal, librtsp + + + Support for RealMedia streaming as used by the RTSP input plugin. + + + + + + + + + + + liba52 (imported) + + + A52 (aka AC3, aka Dolby Digital) audio decoder library and xine plugin. + + + We maintain some small integration improving differences between the + original liba52 and our copy in the file + diff_against_release.patch. + + + + + + libdivx4 + + + Video decoder plugin using libdivx4linux if it is installed. + Currently unmaintained and soon to be discontinued if noone cares to take over. + + + + + + libdts + + + Audio decoder plugin that does currently nothing but passing through + DTS (AC5) data to the audio output plugin. This is only usefull + when using an external hardware DTS decoder. James has started to + work on software DTS decoding, but has not succeeded so far. Anyone + giving him a hand? + + + + + + libfaad (imported) + + + The Free AAC Decoder library and xine plugin. + + + + + + libffmpeg + + + A xine decoder plugin using various audio and video decoders from the + ffmpeg decoder pack libavcodec. Their MPEG encoder is also for the DXR3. + + + To optimize the integration of libavcodec and the xine engine, we maintain + some differences between the original ffmpeg and our copy in the file + diff_to_ffmpeg_cvs.txt. + + + + + libavcodec (imported) + + + The libavcodec decoder pack as used by xine's ffmpeg plugin. + + + + + + + + + + + libflac + + + A xine demuxer and decoder plugin for the Free Lossless Audio Codec library, + which has to be installed separately. + + + + + + liblpcm + + + Audio decoder plugin that "decodes" raw PCM data; most notably + endianess-conversions are done here. + + + + + + libmad (imported) + + + Mpeg audio decoder plugin (i.e. mp2 and mp3 decoding). + ISO/IEC compliant decoder using fixed point math. + + + + + + libmpeg2 (imported) + + + Most important MPEG video decoder plugin, provides fast and + high-precision MPEG-1/2 video decoding. + + + Although this is an imported library, we have heavily modified + our internal copy to blend it as seamlessly as possible into + the xine engine in order to get the maximum MPEG decoding + performance. + + + + + + libmpeg2new + + + James started an effort to bring a recent and unmodified version + of libmpeg2 into xine to one day replace our current internal + modified libmpeg2 with one closer to the original. But since + the full feature catalog has not yet been achieved with the new + one, it is still disabled. + + + + + include, libmpeg2 (imported) + + + The code of the imported new libmpeg2. + + + + + + + + + + + libmpg123 (imported) + + + An MPEG audio decoder plugin baseg on mpg123 code. This plugin is disabled + because it is unmaintained. Some people said, it was faster than the libmad + decoder. But if noone starts to fix it, it will disappear soon. + + + + + + libreal + + + A thin wrapper around Real's binary codecs from the Linux RealPlayer to + use them as a xine plugin. + + + + + + libspeex + + + A xine decoder plugin for the speex library, + which has to be installed separately. + + + + + + libspucc + + + Closed caption subtitle decoder plugin. + + + + + + libspudec + + + DVD SPU subtitle decoder plugin. + + + + + + libsputext + + + Plain text subtitle decoder plugins. + + + + + + libtheora + + + A xine decoder plugin for the theora library, + which has to be installed separately. + + + + + + libvorbis + + + A xine decoder plugin for the ogg/vorbis library, + which has to be installed separately. + + + + + + libw32dll + + + Video and audio decoder plugins that exploit some wine code + to use win32 (media player and Quicktime) codecs in xine. + Works on x86 platforms only. + + + + + + DirectShow, dmo, + qtx, wine (imported) + + + + Stripped down version of wine to support Video for Windows DLLs + and additional code to use DirectShow, DMO and QuickTime DLLs. + + + + + + + + + + + libxineadec + + + xine's decoder pack of additional audio decoders. + + + + + gsm610 (imported) + + + The gsm610 audio decoder library as used by the related xine plugin. + + + + + + nosefart (imported) + + + The nosefart audio decoder library as used by the related xine plugin. + + + + + + + + + + + libxinevdec + + + xine's decoder pack of additional video decoders. + + + + + + libxvid + + + A xine decoder plugin for the xvid library, + which has to be installed separately. This plugin is + unmaintained and unless someone cares to update it, it will + be moved to the attic soon. + + + + + + post + + + Video and audio post effect plugins live here. Post plugins + modify streams of video frames or audio buffers as they leave + the decoder to provide conversion or effects. + + + + + deinterlace (imported) + + + The tvtime deinterlacer as a xine video filter post. + + + + + + goom (imported) + + + The goom audio visualizer as a xine visualizer post. + + + + + + mosaico + + + Some post plugins merging multiple frames into one. For example + picture in picture can be done with this. + + + + + + planar + + + Some simple 2D video effects as xine video filter posts. + + + + + + visualizations + + + Audio visualization post plugins. + + + + + + + + + + + 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. + + + + + libdha (imported) + + + A library for direct hardware access to the graphics card + as used by the vidix video out plugin. + + + + + + vidix (imported) + + + The vidix system for high performance video output + as used by the vidix video out plugin. + + + + + + + + + + + xine-engine + + + The heart of xine - it's engine. Contains code to + load and handle all the plugins, the configuration repository + as well as the generic decoding loops and code for synchronized output. + A lot of helper functions for plugins to use live here as well. + What's in the individual files should be guessable by the files' + names. This document is not going to explain the source, because + it simply changes too often. A look at the architectural drawing + in the internals section should + give you a pretty good idea, what to expect in this directory. + Basically, everything in this picture that is not called "plugin" + lives here. + + + + + + xine-utils + + + Collection of utility functions and platform abstractions. + Also contains a simple XML parser for frontend playlist handling. + + + + + + + + + + Object oriented programming in C + + 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 function pointers and public member data. + 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(void); + + + To derive from such a class, 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; +    this->values[MAX_STACK_SIZE - ++this->stack_size] = i; +   } + + + Finally the contructor malloc()s the data struct (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(void) { +    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; +    +    /* return public part */ +    return &this->stack; +   } + + + + + 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 even more appreciated if they do. + + + + Comment your interfaces directly in the header files. + No doxygen comments, ordinary C comments will do. + + + + + Use C-style comments (/* */), not C++-style (//). + + + + + When in doubt, use lower case. BTW: This thing is called xine, never Xine. + + + + + 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 unless they are really useful. Avoid gotos. + + + + + use something like +    printf("module: ..."[,...]); + for console output. All console output goes to stdout and + 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. + That first of all means: indent with two spaces. + + + + + + + + The xine logging system + + xine offers a wide range of possibilities to display + strings. This section should describe when to use + which way and how to do it right. + + + xine_log + + Output which is done thru this function will be + displayed for the end user by the frontend. + If xine->verbosity is not 0 the messages will also + be displayed on the console. Ideally these strings + are translated. + This function is for information which the user should + read always. +    xine_log(xine_t *xine, int buf, const char *format, ...); + buf is either XINE_LOG_MSG for general messages or + XINE_LOG_PLUGIN for messages about plugins. + + + + xprintf + + This macro uses the xine->verbosity value to decide + if the string should be printed to the console. Possible + values are XINE_VERBOSITY_NONE, XINE_VERBOSITY_LOG or + XINE_VERBOSITY_DEBUG. By default nothing is printed. + When you use xine-ui you can enable this output with + the --verbose=[1,2] options. + This function should be used for information which the + user should only read up on request. +    xprintf(xine_t *xine, int verbosity, const char *format, ...); + + + + lprintf/llprintf + + These macros are for debugging purpose only. Under normal + circumstances it is disabled. And can only be enabled by changing + a define statement and a recompilation. It has to be enabled for these + files that are of interest. + It should only be used for information which is intended for developers. + +   lprintf(const char *format, ...); +   llprintf(bool, const char *format, ...); + bool is a flag which enables or disables this logging. + + + lprintf can be enabled by defining LOG at the top of the source file. + llprintf can be used for more than one categorie + per file by using diffent lables: + +   #define LOG_LOAD 1 +   #define LOG_SAVE 0 +    +   llprintf(LOG_LOAD, "loading was successful\n"); +   llprintf(LOG_SAVE, "could not save to file %s\n", filename); + + + In this case only the first messages is printed. To enable/disable change the defines. + + + LOG_MODULE should be used to set the modulename for xprintf/lprintf/llprintf. + Each output line will start with "modulename: ". +    #define LOG_MODULE "modulename" + + + LOG_VERBOSE can be defined to enable the logging of functionname and linenumbers. + Then the output will be: "modulename: (function_name:42) message". + + + + + + 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 instructed otherwise + 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