From 2a4dbb619807a5da276e21463eee3c1fc07840e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 19:32:52 +0200 Subject: Rename the sgml files to docbook (xml). --HG-- rename : doc/hackersguide/hackersguide.sgml => doc/hackersguide/hackersguide.docbook rename : doc/hackersguide/internals.sgml => doc/hackersguide/internals.docbook rename : doc/hackersguide/intro.sgml => doc/hackersguide/intro.docbook rename : doc/hackersguide/library.sgml => doc/hackersguide/library.docbook rename : doc/hackersguide/output.sgml => doc/hackersguide/output.docbook rename : doc/hackersguide/overview.sgml => doc/hackersguide/overview.docbook rename : doc/hackersguide/stream.sgml => doc/hackersguide/stream.docbook --- doc/hackersguide/hackersguide.docbook | 47 ++ doc/hackersguide/hackersguide.sgml | 47 -- doc/hackersguide/internals.docbook | 762 ++++++++++++++++++++++++++++++++ doc/hackersguide/internals.sgml | 762 -------------------------------- doc/hackersguide/intro.docbook | 54 +++ doc/hackersguide/intro.sgml | 54 --- doc/hackersguide/library.docbook | 410 +++++++++++++++++ doc/hackersguide/library.sgml | 410 ----------------- doc/hackersguide/output.docbook | 668 ++++++++++++++++++++++++++++ doc/hackersguide/output.sgml | 668 ---------------------------- doc/hackersguide/overview.docbook | 811 ++++++++++++++++++++++++++++++++++ doc/hackersguide/overview.sgml | 811 ---------------------------------- doc/hackersguide/stream.docbook | 656 +++++++++++++++++++++++++++ doc/hackersguide/stream.sgml | 656 --------------------------- 14 files changed, 3408 insertions(+), 3408 deletions(-) create mode 100644 doc/hackersguide/hackersguide.docbook delete mode 100644 doc/hackersguide/hackersguide.sgml create mode 100644 doc/hackersguide/internals.docbook delete mode 100644 doc/hackersguide/internals.sgml create mode 100644 doc/hackersguide/intro.docbook delete mode 100644 doc/hackersguide/intro.sgml create mode 100644 doc/hackersguide/library.docbook delete mode 100644 doc/hackersguide/library.sgml create mode 100644 doc/hackersguide/output.docbook delete mode 100644 doc/hackersguide/output.sgml create mode 100644 doc/hackersguide/overview.docbook delete mode 100644 doc/hackersguide/overview.sgml create mode 100644 doc/hackersguide/stream.docbook delete mode 100644 doc/hackersguide/stream.sgml (limited to 'doc') diff --git a/doc/hackersguide/hackersguide.docbook b/doc/hackersguide/hackersguide.docbook new file mode 100644 index 000000000..ebc42d4c7 --- /dev/null +++ b/doc/hackersguide/hackersguide.docbook @@ -0,0 +1,47 @@ + + + + + + +]> + + + + + The xine hacker's guide + hackersguide + + GünterBartsch + HeikoSchäfer + RichardWareham + MiguelFreitas + JamesCourtier-Dutton + SiggiLangauf + MarcoZühlke + MikeMelanson + MichaelRoitzsch + + + 2001-2003 + 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; + &library; + &overview; + &internals; + &stream; + &output; + + diff --git a/doc/hackersguide/hackersguide.sgml b/doc/hackersguide/hackersguide.sgml deleted file mode 100644 index ebc42d4c7..000000000 --- a/doc/hackersguide/hackersguide.sgml +++ /dev/null @@ -1,47 +0,0 @@ - - - - - - -]> - - - - - The xine hacker's guide - hackersguide - - GünterBartsch - HeikoSchäfer - RichardWareham - MiguelFreitas - JamesCourtier-Dutton - SiggiLangauf - MarcoZühlke - MikeMelanson - MichaelRoitzsch - - - 2001-2003 - 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; - &library; - &overview; - &internals; - &stream; - &output; - - diff --git a/doc/hackersguide/internals.docbook b/doc/hackersguide/internals.docbook new file mode 100644 index 000000000..9bd1ec684 --- /dev/null +++ b/doc/hackersguide/internals.docbook @@ -0,0 +1,762 @@ + + xine internals + + + Engine architecture and data flow + + + + + + + + + xine engine architecture + + + + Media streams usually consist of audio and video data 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 stream fifo. + + + From the other end of these fifos the audio and video decoder threads + consume 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 output layer. The buffer holding the encoded + data is no longer needed and thus released to the global buffer pool. + + + In the output layer, the video frames and audio samples pass through a + post plugin tree, which can apply effects or other operations to the data. + When reaching the output loops, frames and samples are enqueued to be + displayed, when the presentation time has arrived. + + + A set of extra information travels with the data. Starting at the input and + demuxer level, where this information is generated, the data is attached to + the buffers as they wait in the fifo. The decoder loops copy the data to + a storage of their own. From there, every frame and audio buffer leaving + the stream layer is tagged with the data the decoder loop storage currently + holds. + + + + + Plugin system + + The plugin system enables some of xine's most valuable features: + + + + drop-in extensiability + + + + + support parallel installation of multiple (incompatible) libxine versions + + + + + support for multiple plugin directories + ($prefix/lib/xine/plugins, + $HOME/.xine/plugins, ...) + + + + + support for recursive plugin directories + (plugins are found even in subdirectories of the plugin directories) + + + + + version management + (On start, xine finds all plugins in its plugin (sub)directories and + chooses an appropriate version (usually the newest) for each plugin.) + + + + + simplification + (Plugins don't have to follow any special naming convention, + and any plugin may contain an arbitrary subset of input, demuxer, + decoder or output plugins.) + + + + + + Essentally, plugins are just shared objects, ie dynamic libraries. In + contrast to normal dynamic libraries, they are stored outside of the + system's library PATHs and libxine does its own bookkeeping, which + enables most advanced features mentioned above. + + + Plugin location and filesystem layout + + The primary goal for this new plugin mechanism was the need to support + simultaneous installation of several (most likely incompatible) + libxine versions without them overwriting each other's + plugins. Therefore, we have this simple layout: + + + Plugins are installed below XINE_PLUGINDIR + (/usr/local/lib/xine/plugins by default). + Note that plugins are never directly installed into XINE_PLUGINDIR. + Instead, a separate subdirectory is created for each "plugin + provider". A plugin provider is equivalent with the exact version of + one source package. Typical examples include "xine-lib-0.9.11" or + "xine-vcdnav-1.0". Every source package is free to install an + arbitrary number of plugins in its own, private directory. If a + package installs several plugins, they may optionally be organized + further into subdirectories. + + + So you will finally end up with something like this: + +   /usr/local/lib/xine/plugins +    xine-lib-0.9.11 +    demux_mpeg_block.so +    decode_mpeg.so +    video_out_xv.so +    ... +    xine-vcdnav-0.9.11 +    input_vcdnav.so +    xine-lib-1.2 +    input +    file.so +    stdin_fifo.so +    vcd.so +    demuxers +    fli.so +    avi.so +    ... +    decoders +    ffmpeg.so +    mpeg.so (may contain mpeg 1/2 audio and video decoders) +    pcm.so +    ... +    output +    video_xv.so +    audio_oss.so +    ... +    xine-lib-3.0 +    avi.so (avi demuxer) +    mpeg.so (contains mpeg demuxers and audio/video decoders) +    video_out_xv.so (Xv video out) +    ... + + + As you can see, every package is free to organize plugins at will + below its own plugin provider directory. + Additionally, administrators may choose to put plugins directly into + XINE_PLUGINDIR, or in a "local" subdirectory. + Users may wish to put additional plugins in ~/.xine/plugins/. + Again, there may be subdirectories to help organize the plugins. + + + The default value for XINE_PLUGINDIR can be obtained using the + xine-config --plugindir command. + + + + Plugin Content: What's inside the .so? + + Each plugin library (.so file) contains an arbitrary number of (virtual) + plugins. Typically, it will contain exactly one plugin. However, it + may be useful to put a set of related plugins in one library, so they + can share common code. + + + First of all, what is a virtual plugin? + A virtual plugin is essentially a structure that is defined by the + xine engine. This structure typically contains lots of function + pointers to the actual API functions. + For each plugin API, there are several API versions, and each API + version may specify a new, incompatible structure. Therefore, it is + essential that only those plugins are loaded that support current + libxine's API, so the .so file needs a plugin list that + provides libxine with the version information, even before it tries to + load any of the plugins. + + + This plugin list is held in an array named xine_plugin_info": + +   plugin_info_t xine_plugin_info[] = { +    /* type, API, "name", version, special_info, init_function */ +    { PLUGIN_DEMUX, 20, "flac", XINE_VERSION_CODE, NULL, demux_flac_init_class }, +    { PLUGIN_AUDIO_DECODER, 13, "flacdec", XINE_VERSION_CODE, &dec_info_audio, init_plugin }, +    { PLUGIN_NONE, 0, "", 0, NULL, NULL } +   }; + + + The structure of xine_plugin_info may never be changed. + If it ever needs to be changed, it must be renamed to avoid + erraneous loading of incompatible plugins. + + + xine_plugin_info can contain any number of plugins + and must be terminated with a PLUGIN_NONE entry. Available plugin + types are: + +   #define PLUGIN_NONE 0 +   #define PLUGIN_INPUT 1 +   #define PLUGIN_DEMUX 2 +   #define PLUGIN_AUDIO_DECODER 3 +   #define PLUGIN_VIDEO_DECODER 4 +   #define PLUGIN_SPU_DECODER 5 +   #define PLUGIN_AUDIO_OUT 6 +   #define PLUGIN_VIDEO_OUT 7 +   #define PLUGIN_POST 8 + + + The plugin version number is generated from xine-lib's version number + like this: MAJOR * 10000 + MINOR * 100 + SUBMINOR. + This is not required, but it's an easy way to ensure that the version + increases for every release. + + + Every entry in xine_plugin_info has an initialization + function for the plugin class context. + This function returns a pointer to freshly allocated (typically + via malloc()) structure containing mainly function + pointers; these are the "methods" of the plugin class. + + + The "plugin class" is not what we call to do the job yet (like decoding + a video or something), it must be instantiated. One reason for having the + class is to hold any global settings that must be accessed by every + instance. Remember that xine library is multistream capable: multible + videos can be decoded at the same time, thus several instances of the + same plugin are possible. + + + If you think this is pretty much an object-oriented aproach, + then you're right. + + + A fictitious file input plugin that supports input plugin API 12 and + 13, found in xine-lib 2.13.7 would then define this plugin list: + +   #include <xine/plugin.h> +   ... +   plugin_t *init_api12(void) { +    input_plugin_t *this; +    +    this = malloc(sizeof(input_plugin_t)); +    ... +    return (plugin_t *)this; +   } +   /* same thing, with different initialization for API 13 */ +    +   const plugin_info_t xine_plugin_info[] = { +    { PLUGIN_INPUT, 12, "file", 21307, init_api12 }, +    { PLUGIN_INPUT, 13, "file", 21307, init_api13 }, +    { PLUGIN_NONE, 0, "", 0, NULL } +   } + This input plugin supports two APIs, other plugins might provide a + mixture of demuxer and decoder plugins that belong together somehow + (ie. share common code). + + + You'll find exact definitions of public functions and plugin structs + in the appropriate header files for each plugin type: + input/input_plugin.h for input plugins, + demuxers/demux.h for demuxer plugins, + xine-engine/video_decoder.h for video decoder plugins, + xine-engine/audio_decoder.h for audio decoder plugins, + xine-engine/post.h for post plugins, + xine-engine/video_out.h for video out plugins, + xine-engine/audio_out.h for audio out plugins. + Additional information will also be given in the dedicated sections below. + + + 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 members via the + demux_plugin field and private fields directly. + + + Summary: Plugins consist of two C-style classes, each representing a different context. + + + + The first is the so called "plugin class" context. This is a singleton context, + which means it will exist either not at all or at most once per xine context. + This plugin class context is a C-style class which is subclassing the related + class from the xine plugin headers. This contains functions, which are + independent of the actual instance of the plugin. Most prominently, it contains + a factory method to instantiate the next context. + + + + + The second context is the instance context. This is another C-style class, which + is constructed and disposed withing the plugin class context. This one does + the actual work and subclasses the related plugin struct from the xine plugin + headers. It is instantiated for every separate running instance of the plugin + + + + + + + + + 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 (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". + + + + + How does xine synchronize audio and video? + + 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. Unfortunately the same isn't true for audio: all sound + systems 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 + especially true for most sound servers like ESD or aRts and explain why in such + cases the sync is far from perfect. + + + Another problem xine must handle is the sound card clock drift. vpts are + compared to the system clock (or even to a different clock provided by a scr plugin) + for presentation but sound card is sampling audio by it's own clocking + mechanism, so a small drift may occur. As the playback goes on this + error will accumulate possibly resulting in audio gaps or audio drops. To avoid that + annoying effect, two countermeasures are available (switchable with xine config + option audio.synchronization.av_sync_method): + + + + 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 audio is stretched or squeezed a slight bit by resampling, thus compensating + the drift: The next comment in audio_out.c explains: + +   /* Alternative for metronom feedback: fix sound card clock drift +    * by resampling all audio data, so that the sound card keeps in +    * sync with the system clock. This may help, if one uses a DXR3/H+ +    * decoder board. Those have their own clock (which serves as xine's +    * master clock) and can only operate at fixed frame rates (if you +    * want smooth playback). Resampling then avoids A/V sync problems, +    * gaps filled with 0-frames and jerky video playback due to different +    * clock speeds of the sound card and DXR3/H+. +    */ + + + + + + + + Overlays and OSD + + The roots of xine overlay 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's 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 + + + + Overlay Manager + + The overlay manager interface is available to any xine plugin. It's a bit unlikely + to be used directly, anyway here's a code snippet 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 = your_rle; +   event.object.overlay->data_size = your_size; +   event.object.overlay->num_rle = your_rle_count; +    +   /* palette must contain YUV values for each color index */ +   memcpy(event.object.overlay->clip_color, color, sizeof(color)); +    +   /* this table contains transparency levels 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, &event); + + + + OSD Renderer + + OSD is a general API for rendering 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 the OSD can be any kind of bitmap. Font + files are searched and loaded during initialization from + $prefix/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 or the public header. + + + OSD palette notes + + 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); + + + OSD text and palette FAQ + + Q: What is the format of the color palette entries? + + + A: It's the same as used by overlay blending code (YUV). + + + Q: What is the relation between a text palette and a palette + I set with xine_osd_set_palette? + + + A: xine_osd_set_palette will set the entire 256 color palette + to be used when we blend the osd image. + "text palette" is a sequence of 11 colors from palette to be + used to render text. that is, by calling osd_render_text() + with color_base=100 will render text using colors 100-110. + + + Q: Can I render text with colors in my own palette? + + + A: Sure. Just pass the color_base to osd_render_text() + + + Q: Has a text palette change effects on already drawed text? + + + A: osd_set_text_palette() will overwrite some colors on palette + with pre-defined ones. So yes, it will change the color + on already drawed text (if you do it before calling osd_show, + of course). + If you don't want to change the colors of drawed text just + use different color_base values. + + + Q: What about the shadows of osd-objects? Can I turn them off + or are they hardcoded? + + + A: osd objects have no shadows by itself, but fonts use 11 + colors to produce an anti-aliased effect. + if you set a "text palette" with entries 0-9 being transparent + and 10 being foreground you will get rid of any borders or + anti-aliasing. + + + + + + + MRLs + + This section defines a draft for a syntactic specification of MRLs as + used by xine-lib. The language of MRLs is designed to be a true subset + of the language of URIs as given in RFC2396. A type 2 grammar for the + language of MRLs is given in EBNF below. + + + Semantically, MRLs consist of two distinct parts that are evaluated by + different components of the xine architecture. The first part, + derivable from the symbol <input_source> in the given grammar, is + completely handed to the input plugins, with input plugins signaling + if they can handle the MRL. + + + The second part, derivable from <stream_setup> and delimited from the + first by a crosshatch ('#') contains parameters that modify the + initialization and playback behaviour of the stream to which the MRL + is passed. The possible parameters are mentioned in the manpage to + xine-ui. + + + The following definition should be regarded as a guideline only. + Of course any given input plugin only understands a subset of all + possible MRLs. On the other hand, invalid MRLs according to this + definition might be understood for convenience reasons. + Some user awareness is required at this point. + + + EBNF grammar for MRLs: + +   <mrl> ::= <input_source>[#<stream_setup>] +   <input_source> ::= (<absolute_mrl>|<relative_mrl>) +   <absolute_mrl> ::= <input>:(<hierarch_part>|<opaque_part>) +   <hierarch_part> ::= (<net_path>|<abs_path>)[?<query>] +   <opaque_part> ::= (<unreserved>|<escaped>|;|?|:|@|&|=|+|$|,){<mrl_char>} +   <relative_mrl> ::= (<abs_path>|<rel_path>) +   <net_path> ::= //<authority>[<abs_path>] +   <abs_path> ::= /<path_segments> +   <rel_path> ::= <rel_segment>[<abs_path>] +   <rel_segment> ::= <rel_char>{<rel_char>} +   <rel_char> ::= (<unreserved>|<escaped>|;|@|&|=|+|$|,) +   <input> ::= <alpha>{(<alpha>|<digit>|+|-|.)} +   <authority> ::= (<server>|<reg_name>) +   <server> ::= [[<userinfo>@]<host>[:<port>]] +   <userinfo> ::= {(<unreserved>|<escaped>|;|:|&|=|+|$|,)} +   <host> ::= (<hostname>|<ipv4_address>|<ipv6_reference>) +   <hostname> ::= {<domainlabel>.}<toplabel>[.] +   <domainlabel> ::= (<alphanum>|<alphanum>{(<alphanum>|-)}<alphanum>) +   <toplabel> ::= (<alpha>|<alpha>{(<alphanum>|-)}<alphanum>) +   <ipv4_address> ::= <digit>{<digit>}.<digit>{<digit>}.<digit>{<digit>}.<digit>{<digit>} +   <port> ::= {<digit>} +   <reg_name> ::= <reg_char>{<reg_char>} +   <reg_char> ::= (<unreserved>|<escaped>|;|:|@|&|=|+|$|,) +   <path_segments> ::= <segment>{/<segment>} +   <segment> ::= {<path_char>}{;<param>} +   <param> ::= {<path_char>} +   <path_char> ::= (<unreserved>|<escaped>|:|@|&|=|+|$|,) +   <query> ::= {<mrl_char>} +   <stream_setup> ::= <stream_option>;{<stream_option>} +   <stream_option> ::= (<configoption>|<engine_option>|novideo|noaudio|nospu) +   <configoption> ::= <configentry>:<configvalue> +   <configentry> ::= <unreserved>{<unreserved>} +   <configvalue> ::= <stream_char>{<stream_char>} +   <engine_option> ::= <unreserved>{<unreserved>}:<stream_char>{<stream_char>} +   <stream_char> ::= (<unreserved>|<escaped>|:|@|&|=|+|$|,) +   <mrl_char> ::= (<reserved>|<unreserved>|<escaped>) +   <reserved> ::= (;|/|?|:|@|&|=|+|$|,|[|]) +   <unreserved> ::= (<alphanum>|<mark>) +   <mark> ::= (-|_|.|!|~|*|'|(|)) +   <escaped> ::= %<hex><hex> +   <hex> ::= (<digit>|A|B|C|D|E|F|a|b|c|d|e|f) +   <alphanum> ::= (<alpha>|<digit>) +   <alpha> ::= (<lowalpha>|<upalpha>) +   <lowalpha> ::= (a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z) +   <upalpha> ::= (A|B|C|D|E|F|G|H|I|J|K|L|M|N|O|P|Q|R|S|T|U|V|W|X|Y|Z) +   <digit> ::= (0|1|2|3|4|5|6|7|8|9) + With <ipv6_reference> being an IPv6 address enclosed in [ and ] as defined in RFC2732. + + + + diff --git a/doc/hackersguide/internals.sgml b/doc/hackersguide/internals.sgml deleted file mode 100644 index 9bd1ec684..000000000 --- a/doc/hackersguide/internals.sgml +++ /dev/null @@ -1,762 +0,0 @@ - - xine internals - - - Engine architecture and data flow - - - - - - - - - xine engine architecture - - - - Media streams usually consist of audio and video data 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 stream fifo. - - - From the other end of these fifos the audio and video decoder threads - consume 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 output layer. The buffer holding the encoded - data is no longer needed and thus released to the global buffer pool. - - - In the output layer, the video frames and audio samples pass through a - post plugin tree, which can apply effects or other operations to the data. - When reaching the output loops, frames and samples are enqueued to be - displayed, when the presentation time has arrived. - - - A set of extra information travels with the data. Starting at the input and - demuxer level, where this information is generated, the data is attached to - the buffers as they wait in the fifo. The decoder loops copy the data to - a storage of their own. From there, every frame and audio buffer leaving - the stream layer is tagged with the data the decoder loop storage currently - holds. - - - - - Plugin system - - The plugin system enables some of xine's most valuable features: - - - - drop-in extensiability - - - - - support parallel installation of multiple (incompatible) libxine versions - - - - - support for multiple plugin directories - ($prefix/lib/xine/plugins, - $HOME/.xine/plugins, ...) - - - - - support for recursive plugin directories - (plugins are found even in subdirectories of the plugin directories) - - - - - version management - (On start, xine finds all plugins in its plugin (sub)directories and - chooses an appropriate version (usually the newest) for each plugin.) - - - - - simplification - (Plugins don't have to follow any special naming convention, - and any plugin may contain an arbitrary subset of input, demuxer, - decoder or output plugins.) - - - - - - Essentally, plugins are just shared objects, ie dynamic libraries. In - contrast to normal dynamic libraries, they are stored outside of the - system's library PATHs and libxine does its own bookkeeping, which - enables most advanced features mentioned above. - - - Plugin location and filesystem layout - - The primary goal for this new plugin mechanism was the need to support - simultaneous installation of several (most likely incompatible) - libxine versions without them overwriting each other's - plugins. Therefore, we have this simple layout: - - - Plugins are installed below XINE_PLUGINDIR - (/usr/local/lib/xine/plugins by default). - Note that plugins are never directly installed into XINE_PLUGINDIR. - Instead, a separate subdirectory is created for each "plugin - provider". A plugin provider is equivalent with the exact version of - one source package. Typical examples include "xine-lib-0.9.11" or - "xine-vcdnav-1.0". Every source package is free to install an - arbitrary number of plugins in its own, private directory. If a - package installs several plugins, they may optionally be organized - further into subdirectories. - - - So you will finally end up with something like this: - -   /usr/local/lib/xine/plugins -    xine-lib-0.9.11 -    demux_mpeg_block.so -    decode_mpeg.so -    video_out_xv.so -    ... -    xine-vcdnav-0.9.11 -    input_vcdnav.so -    xine-lib-1.2 -    input -    file.so -    stdin_fifo.so -    vcd.so -    demuxers -    fli.so -    avi.so -    ... -    decoders -    ffmpeg.so -    mpeg.so (may contain mpeg 1/2 audio and video decoders) -    pcm.so -    ... -    output -    video_xv.so -    audio_oss.so -    ... -    xine-lib-3.0 -    avi.so (avi demuxer) -    mpeg.so (contains mpeg demuxers and audio/video decoders) -    video_out_xv.so (Xv video out) -    ... - - - As you can see, every package is free to organize plugins at will - below its own plugin provider directory. - Additionally, administrators may choose to put plugins directly into - XINE_PLUGINDIR, or in a "local" subdirectory. - Users may wish to put additional plugins in ~/.xine/plugins/. - Again, there may be subdirectories to help organize the plugins. - - - The default value for XINE_PLUGINDIR can be obtained using the - xine-config --plugindir command. - - - - Plugin Content: What's inside the .so? - - Each plugin library (.so file) contains an arbitrary number of (virtual) - plugins. Typically, it will contain exactly one plugin. However, it - may be useful to put a set of related plugins in one library, so they - can share common code. - - - First of all, what is a virtual plugin? - A virtual plugin is essentially a structure that is defined by the - xine engine. This structure typically contains lots of function - pointers to the actual API functions. - For each plugin API, there are several API versions, and each API - version may specify a new, incompatible structure. Therefore, it is - essential that only those plugins are loaded that support current - libxine's API, so the .so file needs a plugin list that - provides libxine with the version information, even before it tries to - load any of the plugins. - - - This plugin list is held in an array named xine_plugin_info": - -   plugin_info_t xine_plugin_info[] = { -    /* type, API, "name", version, special_info, init_function */ -    { PLUGIN_DEMUX, 20, "flac", XINE_VERSION_CODE, NULL, demux_flac_init_class }, -    { PLUGIN_AUDIO_DECODER, 13, "flacdec", XINE_VERSION_CODE, &dec_info_audio, init_plugin }, -    { PLUGIN_NONE, 0, "", 0, NULL, NULL } -   }; - - - The structure of xine_plugin_info may never be changed. - If it ever needs to be changed, it must be renamed to avoid - erraneous loading of incompatible plugins. - - - xine_plugin_info can contain any number of plugins - and must be terminated with a PLUGIN_NONE entry. Available plugin - types are: - -   #define PLUGIN_NONE 0 -   #define PLUGIN_INPUT 1 -   #define PLUGIN_DEMUX 2 -   #define PLUGIN_AUDIO_DECODER 3 -   #define PLUGIN_VIDEO_DECODER 4 -   #define PLUGIN_SPU_DECODER 5 -   #define PLUGIN_AUDIO_OUT 6 -   #define PLUGIN_VIDEO_OUT 7 -   #define PLUGIN_POST 8 - - - The plugin version number is generated from xine-lib's version number - like this: MAJOR * 10000 + MINOR * 100 + SUBMINOR. - This is not required, but it's an easy way to ensure that the version - increases for every release. - - - Every entry in xine_plugin_info has an initialization - function for the plugin class context. - This function returns a pointer to freshly allocated (typically - via malloc()) structure containing mainly function - pointers; these are the "methods" of the plugin class. - - - The "plugin class" is not what we call to do the job yet (like decoding - a video or something), it must be instantiated. One reason for having the - class is to hold any global settings that must be accessed by every - instance. Remember that xine library is multistream capable: multible - videos can be decoded at the same time, thus several instances of the - same plugin are possible. - - - If you think this is pretty much an object-oriented aproach, - then you're right. - - - A fictitious file input plugin that supports input plugin API 12 and - 13, found in xine-lib 2.13.7 would then define this plugin list: - -   #include <xine/plugin.h> -   ... -   plugin_t *init_api12(void) { -    input_plugin_t *this; -    -    this = malloc(sizeof(input_plugin_t)); -    ... -    return (plugin_t *)this; -   } -   /* same thing, with different initialization for API 13 */ -    -   const plugin_info_t xine_plugin_info[] = { -    { PLUGIN_INPUT, 12, "file", 21307, init_api12 }, -    { PLUGIN_INPUT, 13, "file", 21307, init_api13 }, -    { PLUGIN_NONE, 0, "", 0, NULL } -   } - This input plugin supports two APIs, other plugins might provide a - mixture of demuxer and decoder plugins that belong together somehow - (ie. share common code). - - - You'll find exact definitions of public functions and plugin structs - in the appropriate header files for each plugin type: - input/input_plugin.h for input plugins, - demuxers/demux.h for demuxer plugins, - xine-engine/video_decoder.h for video decoder plugins, - xine-engine/audio_decoder.h for audio decoder plugins, - xine-engine/post.h for post plugins, - xine-engine/video_out.h for video out plugins, - xine-engine/audio_out.h for audio out plugins. - Additional information will also be given in the dedicated sections below. - - - 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 members via the - demux_plugin field and private fields directly. - - - Summary: Plugins consist of two C-style classes, each representing a different context. - - - - The first is the so called "plugin class" context. This is a singleton context, - which means it will exist either not at all or at most once per xine context. - This plugin class context is a C-style class which is subclassing the related - class from the xine plugin headers. This contains functions, which are - independent of the actual instance of the plugin. Most prominently, it contains - a factory method to instantiate the next context. - - - - - The second context is the instance context. This is another C-style class, which - is constructed and disposed withing the plugin class context. This one does - the actual work and subclasses the related plugin struct from the xine plugin - headers. It is instantiated for every separate running instance of the plugin - - - - - - - - - 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 (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". - - - - - How does xine synchronize audio and video? - - 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. Unfortunately the same isn't true for audio: all sound - systems 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 - especially true for most sound servers like ESD or aRts and explain why in such - cases the sync is far from perfect. - - - Another problem xine must handle is the sound card clock drift. vpts are - compared to the system clock (or even to a different clock provided by a scr plugin) - for presentation but sound card is sampling audio by it's own clocking - mechanism, so a small drift may occur. As the playback goes on this - error will accumulate possibly resulting in audio gaps or audio drops. To avoid that - annoying effect, two countermeasures are available (switchable with xine config - option audio.synchronization.av_sync_method): - - - - 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 audio is stretched or squeezed a slight bit by resampling, thus compensating - the drift: The next comment in audio_out.c explains: - -   /* Alternative for metronom feedback: fix sound card clock drift -    * by resampling all audio data, so that the sound card keeps in -    * sync with the system clock. This may help, if one uses a DXR3/H+ -    * decoder board. Those have their own clock (which serves as xine's -    * master clock) and can only operate at fixed frame rates (if you -    * want smooth playback). Resampling then avoids A/V sync problems, -    * gaps filled with 0-frames and jerky video playback due to different -    * clock speeds of the sound card and DXR3/H+. -    */ - - - - - - - - Overlays and OSD - - The roots of xine overlay 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's 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 - - - - Overlay Manager - - The overlay manager interface is available to any xine plugin. It's a bit unlikely - to be used directly, anyway here's a code snippet 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 = your_rle; -   event.object.overlay->data_size = your_size; -   event.object.overlay->num_rle = your_rle_count; -    -   /* palette must contain YUV values for each color index */ -   memcpy(event.object.overlay->clip_color, color, sizeof(color)); -    -   /* this table contains transparency levels 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, &event); - - - - OSD Renderer - - OSD is a general API for rendering 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 the OSD can be any kind of bitmap. Font - files are searched and loaded during initialization from - $prefix/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 or the public header. - - - OSD palette notes - - 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); - - - OSD text and palette FAQ - - Q: What is the format of the color palette entries? - - - A: It's the same as used by overlay blending code (YUV). - - - Q: What is the relation between a text palette and a palette - I set with xine_osd_set_palette? - - - A: xine_osd_set_palette will set the entire 256 color palette - to be used when we blend the osd image. - "text palette" is a sequence of 11 colors from palette to be - used to render text. that is, by calling osd_render_text() - with color_base=100 will render text using colors 100-110. - - - Q: Can I render text with colors in my own palette? - - - A: Sure. Just pass the color_base to osd_render_text() - - - Q: Has a text palette change effects on already drawed text? - - - A: osd_set_text_palette() will overwrite some colors on palette - with pre-defined ones. So yes, it will change the color - on already drawed text (if you do it before calling osd_show, - of course). - If you don't want to change the colors of drawed text just - use different color_base values. - - - Q: What about the shadows of osd-objects? Can I turn them off - or are they hardcoded? - - - A: osd objects have no shadows by itself, but fonts use 11 - colors to produce an anti-aliased effect. - if you set a "text palette" with entries 0-9 being transparent - and 10 being foreground you will get rid of any borders or - anti-aliasing. - - - - - - - MRLs - - This section defines a draft for a syntactic specification of MRLs as - used by xine-lib. The language of MRLs is designed to be a true subset - of the language of URIs as given in RFC2396. A type 2 grammar for the - language of MRLs is given in EBNF below. - - - Semantically, MRLs consist of two distinct parts that are evaluated by - different components of the xine architecture. The first part, - derivable from the symbol <input_source> in the given grammar, is - completely handed to the input plugins, with input plugins signaling - if they can handle the MRL. - - - The second part, derivable from <stream_setup> and delimited from the - first by a crosshatch ('#') contains parameters that modify the - initialization and playback behaviour of the stream to which the MRL - is passed. The possible parameters are mentioned in the manpage to - xine-ui. - - - The following definition should be regarded as a guideline only. - Of course any given input plugin only understands a subset of all - possible MRLs. On the other hand, invalid MRLs according to this - definition might be understood for convenience reasons. - Some user awareness is required at this point. - - - EBNF grammar for MRLs: - -   <mrl> ::= <input_source>[#<stream_setup>] -   <input_source> ::= (<absolute_mrl>|<relative_mrl>) -   <absolute_mrl> ::= <input>:(<hierarch_part>|<opaque_part>) -   <hierarch_part> ::= (<net_path>|<abs_path>)[?<query>] -   <opaque_part> ::= (<unreserved>|<escaped>|;|?|:|@|&|=|+|$|,){<mrl_char>} -   <relative_mrl> ::= (<abs_path>|<rel_path>) -   <net_path> ::= //<authority>[<abs_path>] -   <abs_path> ::= /<path_segments> -   <rel_path> ::= <rel_segment>[<abs_path>] -   <rel_segment> ::= <rel_char>{<rel_char>} -   <rel_char> ::= (<unreserved>|<escaped>|;|@|&|=|+|$|,) -   <input> ::= <alpha>{(<alpha>|<digit>|+|-|.)} -   <authority> ::= (<server>|<reg_name>) -   <server> ::= [[<userinfo>@]<host>[:<port>]] -   <userinfo> ::= {(<unreserved>|<escaped>|;|:|&|=|+|$|,)} -   <host> ::= (<hostname>|<ipv4_address>|<ipv6_reference>) -   <hostname> ::= {<domainlabel>.}<toplabel>[.] -   <domainlabel> ::= (<alphanum>|<alphanum>{(<alphanum>|-)}<alphanum>) -   <toplabel> ::= (<alpha>|<alpha>{(<alphanum>|-)}<alphanum>) -   <ipv4_address> ::= <digit>{<digit>}.<digit>{<digit>}.<digit>{<digit>}.<digit>{<digit>} -   <port> ::= {<digit>} -   <reg_name> ::= <reg_char>{<reg_char>} -   <reg_char> ::= (<unreserved>|<escaped>|;|:|@|&|=|+|$|,) -   <path_segments> ::= <segment>{/<segment>} -   <segment> ::= {<path_char>}{;<param>} -   <param> ::= {<path_char>} -   <path_char> ::= (<unreserved>|<escaped>|:|@|&|=|+|$|,) -   <query> ::= {<mrl_char>} -   <stream_setup> ::= <stream_option>;{<stream_option>} -   <stream_option> ::= (<configoption>|<engine_option>|novideo|noaudio|nospu) -   <configoption> ::= <configentry>:<configvalue> -   <configentry> ::= <unreserved>{<unreserved>} -   <configvalue> ::= <stream_char>{<stream_char>} -   <engine_option> ::= <unreserved>{<unreserved>}:<stream_char>{<stream_char>} -   <stream_char> ::= (<unreserved>|<escaped>|:|@|&|=|+|$|,) -   <mrl_char> ::= (<reserved>|<unreserved>|<escaped>) -   <reserved> ::= (;|/|?|:|@|&|=|+|$|,|[|]) -   <unreserved> ::= (<alphanum>|<mark>) -   <mark> ::= (-|_|.|!|~|*|'|(|)) -   <escaped> ::= %<hex><hex> -   <hex> ::= (<digit>|A|B|C|D|E|F|a|b|c|d|e|f) -   <alphanum> ::= (<alpha>|<digit>) -   <alpha> ::= (<lowalpha>|<upalpha>) -   <lowalpha> ::= (a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v|w|x|y|z) -   <upalpha> ::= (A|B|C|D|E|F|G|H|I|J|K|L|M|N|O|P|Q|R|S|T|U|V|W|X|Y|Z) -   <digit> ::= (0|1|2|3|4|5|6|7|8|9) - With <ipv6_reference> being an IPv6 address enclosed in [ and ] as defined in RFC2732. - - - - diff --git a/doc/hackersguide/intro.docbook b/doc/hackersguide/intro.docbook new file mode 100644 index 000000000..c7dce6254 --- /dev/null +++ b/doc/hackersguide/intro.docbook @@ -0,0 +1,54 @@ + + Introduction + + + Where am I? + + You are currently looking at a piece of documentation for xine. + xine is a free video player. It lives on + http://xinehq.de/. Specifically + this document goes under the moniker of the "xine Hackers' Guide". + + + + + What does this text do? + + 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. It has been written by a number of people who work + on xine themselves and is intended to provide the important concepts and + methods used within xine. Readers should not consider this document to be + an exhausative description of the internals of xine. As with all projects + which provide access, the source-code should be considered the definitive + source of information. + + + + + New versions of this document + + This document is being developed in the xine-lib cvs repository within + the directory doc/hackersguide/. If you are + unsure what to do with the stuff in that directory, please read the + README file located there. + + + New versions of this document can also be obtained from the xine web site: + http://xinehq.de/. + + + + + Feedback + + All comments, error reports, additional information and criticism + concerning this document should be directed to the xine documentations + mailing list xine-docs@lists.sourceforge.net. + Questions about xine hacking in general should be sent to the + developer mailing list xine-devel@lists.sourceforge.net. + + + + diff --git a/doc/hackersguide/intro.sgml b/doc/hackersguide/intro.sgml deleted file mode 100644 index c7dce6254..000000000 --- a/doc/hackersguide/intro.sgml +++ /dev/null @@ -1,54 +0,0 @@ - - Introduction - - - Where am I? - - You are currently looking at a piece of documentation for xine. - xine is a free video player. It lives on - http://xinehq.de/. Specifically - this document goes under the moniker of the "xine Hackers' Guide". - - - - - What does this text do? - - 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. It has been written by a number of people who work - on xine themselves and is intended to provide the important concepts and - methods used within xine. Readers should not consider this document to be - an exhausative description of the internals of xine. As with all projects - which provide access, the source-code should be considered the definitive - source of information. - - - - - New versions of this document - - This document is being developed in the xine-lib cvs repository within - the directory doc/hackersguide/. If you are - unsure what to do with the stuff in that directory, please read the - README file located there. - - - New versions of this document can also be obtained from the xine web site: - http://xinehq.de/. - - - - - Feedback - - All comments, error reports, additional information and criticism - concerning this document should be directed to the xine documentations - mailing list xine-docs@lists.sourceforge.net. - Questions about xine hacking in general should be sent to the - developer mailing list xine-devel@lists.sourceforge.net. - - - - diff --git a/doc/hackersguide/library.docbook b/doc/hackersguide/library.docbook new file mode 100644 index 000000000..1d987d259 --- /dev/null +++ b/doc/hackersguide/library.docbook @@ -0,0 +1,410 @@ + + Using the xine library + + + xine architecture as visible to libxine clients + + The following drawing shows the components of xine as outside applications + see them. For every component, the functions for creating and destroying it + are given. Every other function works in the context it is enclosed in. + Functions that facilitate the connection of the individual components are + also given. + + + + + + + + + + outside view on xine components + + + + The function are named just to give you an overview of what is actually + there. It is all thoroughly documented in the plublic header + xine.h, which is the main and preferably the only xine + header, clients should include. (xine/xineutils.h and the XML parser might + make an exception.) + + + Details on the OSD feature can be found in the OSD section. + + + + + Writing a new frontend to xine + + The best way to explain this seems to be actual code. Below you + will find a very easy and hopefully self-explaining xine frontend + to give you a start. + + + One important thing to note is that any X11 based xine-lib frontend + must call XInitThreads() before calling the + first Xlib function, because xine will access the display from + within a different thread than the frontend. + + + Source code of a simple X11 frontend + +/* +** Copyright (C) 2003 Daniel Caujolle-Bert <segfault@club-internet.fr> +** +** This program is free software; you can redistribute it and/or modify +** it under the terms of the GNU General Public License as published by +** the Free Software Foundation; either version 2 of the License, or +** (at your option) any later version. +** +** This program is distributed in the hope that it will be useful, +** but WITHOUT ANY WARRANTY; without even the implied warranty of +** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +** GNU General Public License for more details. +** +** You should have received a copy of the GNU General Public License +** along with this program; if not, write to the Free Software +** Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +** +*/ + +/* + * compile-command: "gcc -Wall -O2 `xine-config --cflags` `xine-config --libs` -L/usr/X11R6/lib -lX11 -lm -o xinimin xinimin.c" + */ + +#include <stdio.h> +#include <string.h> +#include <math.h> + +#include <X11/X.h> +#include <X11/Xlib.h> +#include <X11/Xutil.h> +#include <X11/keysym.h> +#include <X11/Xatom.h> +#include <X11/Xutil.h> +#include <X11/extensions/XShm.h> + +#include <xine.h> +#include <xine/xineutils.h> + + +#define MWM_HINTS_DECORATIONS (1L << 1) +#define PROP_MWM_HINTS_ELEMENTS 5 +typedef struct { + uint32_t flags; + uint32_t functions; + uint32_t decorations; + int32_t input_mode; + uint32_t status; +} MWMHints; + +static xine_t *xine; +static xine_stream_t *stream; +static xine_video_port_t *vo_port; +static xine_audio_port_t *ao_port; +static xine_event_queue_t *event_queue; + +static Display *display; +static int screen; +static Window window[2]; +static int xpos, ypos, width, height, fullscreen; +static double pixel_aspect; + +static int running = 1; + +#define INPUT_MOTION (ExposureMask | ButtonPressMask | KeyPressMask | \ + ButtonMotionMask | StructureNotifyMask | \ + PropertyChangeMask | PointerMotionMask) + +/* this will be called by xine, if it wants to know the target size of a frame */ +static void dest_size_cb(void *data, int video_width, int video_height, double video_pixel_aspect, + int *dest_width, int *dest_height, double *dest_pixel_aspect) { + *dest_width = width; + *dest_height = height; + *dest_pixel_aspect = pixel_aspect; +} + +/* this will be called by xine when it's about to draw the frame */ +static void frame_output_cb(void *data, int video_width, int video_height, + double video_pixel_aspect, int *dest_x, int *dest_y, + int *dest_width, int *dest_height, + double *dest_pixel_aspect, int *win_x, int *win_y) { + *dest_x = 0; + *dest_y = 0; + *win_x = xpos; + *win_y = ypos; + *dest_width = width; + *dest_height = height; + *dest_pixel_aspect = pixel_aspect; +} + +static void event_listener(void *user_data, const xine_event_t *event) { + switch(event->type) { + case XINE_EVENT_UI_PLAYBACK_FINISHED: + running = 0; + break; + + case XINE_EVENT_PROGRESS: + { + xine_progress_data_t *pevent = (xine_progress_data_t *) event->data; + + printf("%s [%d%%]\n", pevent->description, pevent->percent); + } + break; + + /* you can handle a lot of other interesting events here */ + } +} + +int main(int argc, char **argv) { + char configfile[2048]; + x11_visual_t vis; + double res_h, res_v; + char *vo_driver = "auto"; + char *ao_driver = "auto"; + char *mrl = NULL; + int i; + Atom XA_NO_BORDER; + MWMHints mwmhints; + + /* parsing command line */ + for (i = 1; i < argc; i++) { + if (strcmp(argv[i], "-vo") == 0) { + vo_driver = argv[++i]; + } + else if (strcmp(argv[i], "-ao") == 0) { + ao_driver = argv[++i]; + } + else + mrl = argv[i]; + } + + if (!mrl) { + printf("specify an mrl\n"); + return 1; + } + printf("mrl: '%s'\n", mrl); + + if (!XInitThreads()) { + printf("XInitThreads() failed\n"); + return 1; + } + + /* load xine config file and init xine */ + xine = xine_new(); + snprintf(configfile, sizeof(configfile), "%s%s", xine_get_homedir(), "/.xine/config"); + xine_config_load(xine, configfile); + xine_init(xine); + + display = XOpenDisplay(NULL); + screen = XDefaultScreen(display); + xpos = 0; + ypos = 0; + width = 320; + height = 200; + + /* some initalization for the X11 Window we will be showing video in */ + XLockDisplay(display); + fullscreen = 0; + window[0] = XCreateSimpleWindow(display, XDefaultRootWindow(display), + xpos, ypos, width, height, 1, 0, 0); + + window[1] = XCreateSimpleWindow(display, XDefaultRootWindow(display), + 0, 0, (DisplayWidth(display, screen)), + (DisplayHeight(display, screen)), 0, 0, 0); + + XSelectInput(display, window[0], INPUT_MOTION); + + XSelectInput(display, window[1], INPUT_MOTION); + + XA_NO_BORDER = XInternAtom(display, "_MOTIF_WM_HINTS", False); + mwmhints.flags = MWM_HINTS_DECORATIONS; + mwmhints.decorations = 0; + XChangeProperty(display, window[1], + XA_NO_BORDER, XA_NO_BORDER, 32, PropModeReplace, (unsigned char *) &mwmhints, + PROP_MWM_HINTS_ELEMENTS); + + XMapRaised(display, window[fullscreen]); + + res_h = (DisplayWidth(display, screen) * 1000 / DisplayWidthMM(display, screen)); + res_v = (DisplayHeight(display, screen) * 1000 / DisplayHeightMM(display, screen)); + XSync(display, False); + XUnlockDisplay(display); + + /* filling in the xine visual struct */ + vis.display = display; + vis.screen = screen; + vis.d = window[fullscreen]; + vis.dest_size_cb = dest_size_cb; + vis.frame_output_cb = frame_output_cb; + vis.user_data = NULL; + pixel_aspect = res_v / res_h; + + /* opening xine output ports */ + vo_port = xine_open_video_driver(xine, vo_driver, XINE_VISUAL_TYPE_X11, (void *)&vis); + ao_port = xine_open_audio_driver(xine , ao_driver, NULL); + + /* open a xine stream connected to these ports */ + stream = xine_stream_new(xine, ao_port, vo_port); + /* hook our event handler into the streams events */ + event_queue = xine_event_new_queue(stream); + xine_event_create_listener_thread(event_queue, event_listener, NULL); + + /* make the video window visible to xine */ + xine_port_send_gui_data(vo_port, XINE_GUI_SEND_DRAWABLE_CHANGED, (void *) window[fullscreen]); + xine_port_send_gui_data(vo_port, XINE_GUI_SEND_VIDEOWIN_VISIBLE, (void *) 1); + + /* start playback */ + if (!xine_open(stream, mrl) || !xine_play(stream, 0, 0)) { + printf("Unable to open mrl '%s'\n", mrl); + return 1; + } + + while (running) { + XEvent xevent; + int got_event; + + XLockDisplay(display); + got_event = XPending(display); + if( got_event ) + XNextEvent(display, &xevent); + XUnlockDisplay(display); + + if( !got_event ) { + xine_usec_sleep(20000); + continue; + } + + switch(xevent.type) { + + case KeyPress: + { + XKeyEvent kevent; + KeySym ksym; + char kbuf[256]; + int len; + + kevent = xevent.xkey; + + XLockDisplay(display); + len = XLookupString(&kevent, kbuf, sizeof(kbuf), &ksym, NULL); + XUnlockDisplay(display); + + switch (ksym) { + + case XK_q: + case XK_Q: + /* user pressed q => quit */ + running = 0; + break; + + case XK_f: + case XK_F: + { + /* user pressed f => toggle fullscreen */ + Window tmp_win; + + XLockDisplay(display); + XUnmapWindow(display, window[fullscreen]); + fullscreen = !fullscreen; + XMapRaised(display, window[fullscreen]); + XSync(display, False); + XTranslateCoordinates(display, window[fullscreen], + DefaultRootWindow(display), + 0, 0, &xpos, &ypos, &tmp_win); + XUnlockDisplay(display); + + xine_port_send_gui_data(vo_port, XINE_GUI_SEND_DRAWABLE_CHANGED, + (void*) window[fullscreen]); + } + break; + + case XK_Up: + /* cursor up => increase volume */ + xine_set_param(stream, XINE_PARAM_AUDIO_VOLUME, + (xine_get_param(stream, XINE_PARAM_AUDIO_VOLUME) + 1)); + break; + + case XK_Down: + /* cursor down => decrease volume */ + xine_set_param(stream, XINE_PARAM_AUDIO_VOLUME, + (xine_get_param(stream, XINE_PARAM_AUDIO_VOLUME) - 1)); + break; + + case XK_plus: + /* plus => next audio channel */ + xine_set_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL, + (xine_get_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL) + 1)); + break; + + case XK_minus: + /* minus => previous audio channel */ + xine_set_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL, + (xine_get_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL) - 1)); + break; + + case XK_space: + /* space => toggle pause mode */ + if (xine_get_param(stream, XINE_PARAM_SPEED) != XINE_SPEED_PAUSE) + xine_set_param(stream, XINE_PARAM_SPEED, XINE_SPEED_PAUSE); + else + xine_set_param(stream, XINE_PARAM_SPEED, XINE_SPEED_NORMAL); + break; + + } + } + break; + + case Expose: + /* this handles (partial) occlusion of our video window */ + if (xevent.xexpose.count != 0) + break; + xine_port_send_gui_data(vo_port, XINE_GUI_SEND_EXPOSE_EVENT, &xevent); + break; + + case ConfigureNotify: + { + XConfigureEvent *cev = (XConfigureEvent *) &xevent; + Window tmp_win; + + width = cev->width; + height = cev->height; + + if ((cev->x == 0) && (cev->y == 0)) { + XLockDisplay(display); + XTranslateCoordinates(display, cev->window, + DefaultRootWindow(cev->display), + 0, 0, &xpos, &ypos, &tmp_win); + XUnlockDisplay(display); + } else { + xpos = cev->x; + ypos = cev->y; + } + } + break; + + } + } + + /* cleanup */ + xine_close(stream); + xine_event_dispose_queue(event_queue); + xine_dispose(stream); + xine_close_audio_driver(xine, ao_port); + xine_close_video_driver(xine, vo_port); + xine_exit(xine); + + XLockDisplay(display); + XUnmapWindow(display, window[fullscreen]); + XDestroyWindow(display, window[0]); + XDestroyWindow(display, window[1]); + XUnlockDisplay(display); + + XCloseDisplay (display); + + return 0; +} + + + + diff --git a/doc/hackersguide/library.sgml b/doc/hackersguide/library.sgml deleted file mode 100644 index 1d987d259..000000000 --- a/doc/hackersguide/library.sgml +++ /dev/null @@ -1,410 +0,0 @@ - - Using the xine library - - - xine architecture as visible to libxine clients - - The following drawing shows the components of xine as outside applications - see them. For every component, the functions for creating and destroying it - are given. Every other function works in the context it is enclosed in. - Functions that facilitate the connection of the individual components are - also given. - - - - - - - - - - outside view on xine components - - - - The function are named just to give you an overview of what is actually - there. It is all thoroughly documented in the plublic header - xine.h, which is the main and preferably the only xine - header, clients should include. (xine/xineutils.h and the XML parser might - make an exception.) - - - Details on the OSD feature can be found in the OSD section. - - - - - Writing a new frontend to xine - - The best way to explain this seems to be actual code. Below you - will find a very easy and hopefully self-explaining xine frontend - to give you a start. - - - One important thing to note is that any X11 based xine-lib frontend - must call XInitThreads() before calling the - first Xlib function, because xine will access the display from - within a different thread than the frontend. - - - Source code of a simple X11 frontend - -/* -** Copyright (C) 2003 Daniel Caujolle-Bert <segfault@club-internet.fr> -** -** This program is free software; you can redistribute it and/or modify -** it under the terms of the GNU General Public License as published by -** the Free Software Foundation; either version 2 of the License, or -** (at your option) any later version. -** -** This program is distributed in the hope that it will be useful, -** but WITHOUT ANY WARRANTY; without even the implied warranty of -** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -** GNU General Public License for more details. -** -** You should have received a copy of the GNU General Public License -** along with this program; if not, write to the Free Software -** Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -** -*/ - -/* - * compile-command: "gcc -Wall -O2 `xine-config --cflags` `xine-config --libs` -L/usr/X11R6/lib -lX11 -lm -o xinimin xinimin.c" - */ - -#include <stdio.h> -#include <string.h> -#include <math.h> - -#include <X11/X.h> -#include <X11/Xlib.h> -#include <X11/Xutil.h> -#include <X11/keysym.h> -#include <X11/Xatom.h> -#include <X11/Xutil.h> -#include <X11/extensions/XShm.h> - -#include <xine.h> -#include <xine/xineutils.h> - - -#define MWM_HINTS_DECORATIONS (1L << 1) -#define PROP_MWM_HINTS_ELEMENTS 5 -typedef struct { - uint32_t flags; - uint32_t functions; - uint32_t decorations; - int32_t input_mode; - uint32_t status; -} MWMHints; - -static xine_t *xine; -static xine_stream_t *stream; -static xine_video_port_t *vo_port; -static xine_audio_port_t *ao_port; -static xine_event_queue_t *event_queue; - -static Display *display; -static int screen; -static Window window[2]; -static int xpos, ypos, width, height, fullscreen; -static double pixel_aspect; - -static int running = 1; - -#define INPUT_MOTION (ExposureMask | ButtonPressMask | KeyPressMask | \ - ButtonMotionMask | StructureNotifyMask | \ - PropertyChangeMask | PointerMotionMask) - -/* this will be called by xine, if it wants to know the target size of a frame */ -static void dest_size_cb(void *data, int video_width, int video_height, double video_pixel_aspect, - int *dest_width, int *dest_height, double *dest_pixel_aspect) { - *dest_width = width; - *dest_height = height; - *dest_pixel_aspect = pixel_aspect; -} - -/* this will be called by xine when it's about to draw the frame */ -static void frame_output_cb(void *data, int video_width, int video_height, - double video_pixel_aspect, int *dest_x, int *dest_y, - int *dest_width, int *dest_height, - double *dest_pixel_aspect, int *win_x, int *win_y) { - *dest_x = 0; - *dest_y = 0; - *win_x = xpos; - *win_y = ypos; - *dest_width = width; - *dest_height = height; - *dest_pixel_aspect = pixel_aspect; -} - -static void event_listener(void *user_data, const xine_event_t *event) { - switch(event->type) { - case XINE_EVENT_UI_PLAYBACK_FINISHED: - running = 0; - break; - - case XINE_EVENT_PROGRESS: - { - xine_progress_data_t *pevent = (xine_progress_data_t *) event->data; - - printf("%s [%d%%]\n", pevent->description, pevent->percent); - } - break; - - /* you can handle a lot of other interesting events here */ - } -} - -int main(int argc, char **argv) { - char configfile[2048]; - x11_visual_t vis; - double res_h, res_v; - char *vo_driver = "auto"; - char *ao_driver = "auto"; - char *mrl = NULL; - int i; - Atom XA_NO_BORDER; - MWMHints mwmhints; - - /* parsing command line */ - for (i = 1; i < argc; i++) { - if (strcmp(argv[i], "-vo") == 0) { - vo_driver = argv[++i]; - } - else if (strcmp(argv[i], "-ao") == 0) { - ao_driver = argv[++i]; - } - else - mrl = argv[i]; - } - - if (!mrl) { - printf("specify an mrl\n"); - return 1; - } - printf("mrl: '%s'\n", mrl); - - if (!XInitThreads()) { - printf("XInitThreads() failed\n"); - return 1; - } - - /* load xine config file and init xine */ - xine = xine_new(); - snprintf(configfile, sizeof(configfile), "%s%s", xine_get_homedir(), "/.xine/config"); - xine_config_load(xine, configfile); - xine_init(xine); - - display = XOpenDisplay(NULL); - screen = XDefaultScreen(display); - xpos = 0; - ypos = 0; - width = 320; - height = 200; - - /* some initalization for the X11 Window we will be showing video in */ - XLockDisplay(display); - fullscreen = 0; - window[0] = XCreateSimpleWindow(display, XDefaultRootWindow(display), - xpos, ypos, width, height, 1, 0, 0); - - window[1] = XCreateSimpleWindow(display, XDefaultRootWindow(display), - 0, 0, (DisplayWidth(display, screen)), - (DisplayHeight(display, screen)), 0, 0, 0); - - XSelectInput(display, window[0], INPUT_MOTION); - - XSelectInput(display, window[1], INPUT_MOTION); - - XA_NO_BORDER = XInternAtom(display, "_MOTIF_WM_HINTS", False); - mwmhints.flags = MWM_HINTS_DECORATIONS; - mwmhints.decorations = 0; - XChangeProperty(display, window[1], - XA_NO_BORDER, XA_NO_BORDER, 32, PropModeReplace, (unsigned char *) &mwmhints, - PROP_MWM_HINTS_ELEMENTS); - - XMapRaised(display, window[fullscreen]); - - res_h = (DisplayWidth(display, screen) * 1000 / DisplayWidthMM(display, screen)); - res_v = (DisplayHeight(display, screen) * 1000 / DisplayHeightMM(display, screen)); - XSync(display, False); - XUnlockDisplay(display); - - /* filling in the xine visual struct */ - vis.display = display; - vis.screen = screen; - vis.d = window[fullscreen]; - vis.dest_size_cb = dest_size_cb; - vis.frame_output_cb = frame_output_cb; - vis.user_data = NULL; - pixel_aspect = res_v / res_h; - - /* opening xine output ports */ - vo_port = xine_open_video_driver(xine, vo_driver, XINE_VISUAL_TYPE_X11, (void *)&vis); - ao_port = xine_open_audio_driver(xine , ao_driver, NULL); - - /* open a xine stream connected to these ports */ - stream = xine_stream_new(xine, ao_port, vo_port); - /* hook our event handler into the streams events */ - event_queue = xine_event_new_queue(stream); - xine_event_create_listener_thread(event_queue, event_listener, NULL); - - /* make the video window visible to xine */ - xine_port_send_gui_data(vo_port, XINE_GUI_SEND_DRAWABLE_CHANGED, (void *) window[fullscreen]); - xine_port_send_gui_data(vo_port, XINE_GUI_SEND_VIDEOWIN_VISIBLE, (void *) 1); - - /* start playback */ - if (!xine_open(stream, mrl) || !xine_play(stream, 0, 0)) { - printf("Unable to open mrl '%s'\n", mrl); - return 1; - } - - while (running) { - XEvent xevent; - int got_event; - - XLockDisplay(display); - got_event = XPending(display); - if( got_event ) - XNextEvent(display, &xevent); - XUnlockDisplay(display); - - if( !got_event ) { - xine_usec_sleep(20000); - continue; - } - - switch(xevent.type) { - - case KeyPress: - { - XKeyEvent kevent; - KeySym ksym; - char kbuf[256]; - int len; - - kevent = xevent.xkey; - - XLockDisplay(display); - len = XLookupString(&kevent, kbuf, sizeof(kbuf), &ksym, NULL); - XUnlockDisplay(display); - - switch (ksym) { - - case XK_q: - case XK_Q: - /* user pressed q => quit */ - running = 0; - break; - - case XK_f: - case XK_F: - { - /* user pressed f => toggle fullscreen */ - Window tmp_win; - - XLockDisplay(display); - XUnmapWindow(display, window[fullscreen]); - fullscreen = !fullscreen; - XMapRaised(display, window[fullscreen]); - XSync(display, False); - XTranslateCoordinates(display, window[fullscreen], - DefaultRootWindow(display), - 0, 0, &xpos, &ypos, &tmp_win); - XUnlockDisplay(display); - - xine_port_send_gui_data(vo_port, XINE_GUI_SEND_DRAWABLE_CHANGED, - (void*) window[fullscreen]); - } - break; - - case XK_Up: - /* cursor up => increase volume */ - xine_set_param(stream, XINE_PARAM_AUDIO_VOLUME, - (xine_get_param(stream, XINE_PARAM_AUDIO_VOLUME) + 1)); - break; - - case XK_Down: - /* cursor down => decrease volume */ - xine_set_param(stream, XINE_PARAM_AUDIO_VOLUME, - (xine_get_param(stream, XINE_PARAM_AUDIO_VOLUME) - 1)); - break; - - case XK_plus: - /* plus => next audio channel */ - xine_set_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL, - (xine_get_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL) + 1)); - break; - - case XK_minus: - /* minus => previous audio channel */ - xine_set_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL, - (xine_get_param(stream, XINE_PARAM_AUDIO_CHANNEL_LOGICAL) - 1)); - break; - - case XK_space: - /* space => toggle pause mode */ - if (xine_get_param(stream, XINE_PARAM_SPEED) != XINE_SPEED_PAUSE) - xine_set_param(stream, XINE_PARAM_SPEED, XINE_SPEED_PAUSE); - else - xine_set_param(stream, XINE_PARAM_SPEED, XINE_SPEED_NORMAL); - break; - - } - } - break; - - case Expose: - /* this handles (partial) occlusion of our video window */ - if (xevent.xexpose.count != 0) - break; - xine_port_send_gui_data(vo_port, XINE_GUI_SEND_EXPOSE_EVENT, &xevent); - break; - - case ConfigureNotify: - { - XConfigureEvent *cev = (XConfigureEvent *) &xevent; - Window tmp_win; - - width = cev->width; - height = cev->height; - - if ((cev->x == 0) && (cev->y == 0)) { - XLockDisplay(display); - XTranslateCoordinates(display, cev->window, - DefaultRootWindow(cev->display), - 0, 0, &xpos, &ypos, &tmp_win); - XUnlockDisplay(display); - } else { - xpos = cev->x; - ypos = cev->y; - } - } - break; - - } - } - - /* cleanup */ - xine_close(stream); - xine_event_dispose_queue(event_queue); - xine_dispose(stream); - xine_close_audio_driver(xine, ao_port); - xine_close_video_driver(xine, vo_port); - xine_exit(xine); - - XLockDisplay(display); - XUnmapWindow(display, window[fullscreen]); - XDestroyWindow(display, window[0]); - XDestroyWindow(display, window[1]); - XUnlockDisplay(display); - - XCloseDisplay (display); - - return 0; -} - - - - diff --git a/doc/hackersguide/output.docbook b/doc/hackersguide/output.docbook new file mode 100644 index 000000000..806e89d0a --- /dev/null +++ b/doc/hackersguide/output.docbook @@ -0,0 +1,668 @@ + + xine's output layer + + + Post plugin layer + + In this section you will learn, how the powerful post plugin architecture + works and how to write post plugins. + + + General principle of post plugins + + The name "post plugin" comes from "postprocessing" which already describes + what these plugins are supposed to do: they take video frames, audio + buffers or subpicture planes as they leave the decoders and apply arbitrary + processing to them. Then they pass processed elements on to the output + loops. Post plugins can not only be chained to process the predecessor's + output and advance the data to their successor, they can form arbitrary trees, + since post plugins can have any number of inputs and outputs. Additionally, + the interconnection of the plugins currently inserted in such a tree can + be changed on the fly during playback. The public function + xine_post_wire() is used by frontends to form such + connections. + + + Due to the variety of possible applications, the interface post plugins have + to implement is just the basic foundation. The complexity comes from hooking + your post plugin into the engine data paths for video frames and audio buffers, + intercepting the data and performing your operation on them. This is done by + taking the interface of a video or audio port, replacing some of the functions + with your own ones and passing the interface to the decoder or predecessor + post plugin that is going to feed you with data by accessing this interface + and by doing that, calling the functions you provide. From there you can do + almost anything you want. Constructing video frames from audio buffers to + visualize sound is possible as well as just outputting an integer giving the + average brightness of an image. It is also possible to invent post plugins + with no output (not very useful, unless the plugin has some side-effect) or + no input at all; for the latter you have to create your own pthread, otherwise + your plugin will not do anything. An audio signal generator could be + implemented like this. The various data types, post plugins can + accept as input or offer as output are defined in xine.h + as XINE_POST_DATA_* defines. + + + Some terminology used in the following explanations: + + + + down direction: + The direction from the decoders to the output. This is the way video or audio + data (actual content and meta information) usually travels through the engine. + + + + + up direction: + The direction from the output to the decoders. This is the way some video or audio + metadata like metronom timestamps travel through the engine. + + + + + interception: + Post plugins are inserted into the engine data paths by the means of the decorator + design pattern. This works by taking engine structures with member funtions like + video or audio ports, video frames or overlay managers and inserting your own functions + into a copy of this structure. This is called interception. This modified structure + is then passed up to the plugin that uses it and thus calls your replaced functions. + + + + + + + Writing a xine post plugin + + The post plugin API is declared in src/xine-engine/post.h + The plugin info of post plugins contains the post plugin type, which is one of the + XINE_POST_TYPE_* defines and the init_class function of the plugin. + + +    post_plugin_t *open_plugin(post_class_t *class_gen, int inputs, xine_audio_port_t **audio_target, xine_video_port_t **video_target); + Returns an instance of the plugin. Some post plugins evaluate inputs + to open a variable number of inputs. Since almost all post plugins have audio or video + outputs, you can hand in a NULL-terminated array of ports to connect to these outputs. + In this function you can also intercept these ports so that your plugin is actually used. + There is a helper function to initialize a post_plugin_t, which you are + encouraged to use: _x_post_init(). + + +    char *get_identifier(post_class_t *class_gen); + This function returns a short identifier describing the plugin. + + +    char *get_description(post_class_t *class_gen); + This function returns a plaintext, one-line string describing the plugin. + + +    void dispose(post_class_t *class_gen); + This function frees the memory used by the video out plugin class object. + + + The post_plugin_t structure contains the publicly visible + part of the post plugin with the audio and video inputs and the type of + the post plugin. Not publicly visible are the lists of all inputs and outputs, + the dispose() function and some internal stuff which + plugins do not have to worry about. + + +    void dispose(post_plugin_t *this_gen); + This function frees the memory used by the plugin instance, but not necessarily + immediately. Since post plugins enter their own functions into engine structures, + they might still be needed when dispose() is being called. + They maintain a usage counter to detect that. To check for such a condition, you + should use the _x_post_dispose() helper function like that: + +   if (_x_post_dispose(this)) +     really_free(this); + _x_post_dispose() frees any ressources allocated by any of the + post plugin helper functions and returns boolean true, if the plugin is not needed + any more. + + + + Interception + + Currently, we have four engine structures which can be intercepted by post plugins: + video ports, video frames, overlay managers and audio ports. You could do this + interception manually, but since this is quite a complex process, there are helper + functions to assist you and their usage is encouraged. + + + Intercepting a video port + + +   post_video_port_t *_x_post_intercept_video_port(post_plugin_t *post, +     xine_video_port_t *port, post_in_t **input, post_out_t **output); + This function will intercept port and returns a structure + for you to pass up. All functions in the port will be replaced with dummy + pass through functions that do nothing but relaying the call down to the original + port. If you want (that is, input or output are + not NULL), this function will also create the input and output descriptors complete + with rewiring functions and add them to the relevant lists. + This is required, if you want this port to be advertised by the plugin to the outside world. + + + post_video_port_t makes a variety of interception schemes very easy. + If you want to replace any of the default functions with your own, just enter it + into new_port. You can use original_port + from within your function to propagate calls down to the original port. + The constraint is that your functions have to ensure that every original + port held open scores one usage counter point, so that opened ports are always + closed before the plugin is disposed. Therefore, you should use the macro + _x_post_inc_usage() before calling + original_port->open() and use the macro + _x_post_dec_usage() after calling + original_port->close(). Note that _x_post_dec_usage() + might dispose the plugin, when dispose() has been called + earlier and usage count drops to zero, so do never touch plugin structures after + _x_post_dec_usage(). In addition, you must never call a port + function of the original port when the port is not open. + + + Intercepting video frames or the overlay manager of the port is even easier. + You do not have to reimplement get_frame() or + get_overlay_manager(). Just enter a intercept_frame + or intercept_ovl function which returns boolean true, if + you want to intercept. The functions to insert in the intercepted frame or overlay + manager are taken from new_frame and new_manager + respectively. Note that the defaults are reversed: If you do not enter such a + decision function for either one, all frames and no overlay manager will be intercepted. + + + For convenience post_video_port_t also contains pointers to the + current stream and to the current post plugin and a user_data pointer, where you + can put in anything you need in addition. If your port is used by more than one + thread, you can also enforce locking on the port, frame or overlay manager level + by entering a lock into port_lock, frame_lock or + manager_lock respectively. + + + + Intercepting an audio port + + Audio port interception is just a stripped down version of video port interception. + Everything related to frames and overlay manager is not needed and audio buffers + do not need to be intercepted, since they have no member functions. Everything else + of the above still applies. + + + + Intercepting overlay manager + +    void _x_post_intercept_overlay_manager(video_overlay_manager_t *original, post_video_port_t *port); + Interception of the overlay manager is done automatically when your + intercept_ovl() decision function returns boolean true. + Should you ever decide not to use that, interception can be done with this helper + function, which simply creates an intercepted overlay manager with dummy + pass through functions in port->new_manager and stores the original + manager in port->original_manager. + + + No matter how you intercepted the overlay manager, your own replacement + functions will receive port->new_manager as the overlay manager + argument. But you most likely want to have access to the post_video_port_t + from within your functions. For that, there exists a pointer retrieval function: +    post_video_port_t *_x_post_ovl_manager_to_port(video_overlay_manager_t *manager); + + + + Intercepting a video frame + + +   vo_frame_t *_x_post_intercept_video_frame(vo_frame_t *frame, post_video_port_t *port); +   vo_frame_t *_x_post_restore_video_frame(vo_frame_t *frame, post_video_port_t *port); + Interception of video frames is done automatically when your + intercept_frame() decision function returns boolean true or + when there is no such function in post_video_port_t. + Should you ever decide not to use that, interception can be done with the helper + function _x_post_intercept_video_frame(). + + + Since the same video frame can be in use in the decoder and in the output and in + any post plugin in between at the same time, simply modifying the frame + structure does not work, because every user of the frame needs to see his version + and the frame must always travel along the same path through the plugins for its + entire lifetime. To ensure that, _x_post_intercept_video_frame() + provides a shallow copy of the frame structure with the original frame attached to + copy->next. This copy will be filled with your own + frame functions from port->new_frame and with dummy pass + through functions for those you did not provide. This way, every part of xine + using this frame will see its own frame structure with a list of frame + contexts from down the data path attached to frame->next. + _x_post_restore_video_frame() reverses this and should be + used when the frame is freed or disposed. + + + Your own replacement functions will receive the copied frame as as argument. + But you most likely want to have access to the post_video_port_t + from within your functions. For that, there exists a pointer retrieval function: +    post_video_port_t *_x_post_video_frame_to_port(vo_frame_t *frame); + The constraint is that your functions have to ensure that every intercepted + frame scores one usage counter point, so that these frames are always + freed or disposed before the plugin is disposed. Therefore, you should use the macro + _x_post_inc_usage() before calling + _x_post_intercept_video_frame() and use the macro + _x_post_dec_usage() after calling + _x_post_restore_video_frame(). Note that _x_post_dec_usage() + might dispose the plugin, when dispose() has been called + earlier and usage count drops to zero, so do never touch plugin structures after + _x_post_dec_usage(). + + + From within your own frame functions, you can propagate calls to the original + frame by calling a function on frame->next. Since + modifications to the frame can travel both upwards and downwards (decoders and + output can modify the frame), changes need to be copied between the frame + structure contexts. You should use the _x_post_frame_copy_down() + and _x_post_frame_copy_up() helper functions like that: + +   _x_post_frame_copy_down(frame, frame->next); +   frame->next->draw(frame->next, stream); +   _x_post_frame_copy_up(frame, frame->next); + + + If your post plugin modifies the content of the frame, you have to modify + a deep copy of the frame, because the decoder might still use the frame as + a reference frame for future decoding. The usual procedure is: + +   modified_frame = port->original_port->get_frame(port->original_port, ...); +   _x_post_frame_copy_down(frame, modified_frame); +   copy_and_modify(frame, modified_frame); +   skip = modified_frame->draw(modified_frame, stream); +   _x_post_frame_copy_up(frame, modified_frame); +   modified_frame->free(modified_frame); + + + When the output receives a frame via draw(), + it usually receives the stream where the frame + originates as well and modifies the state of this stream by passing + the frame through the stream's metronom. Sometimes this is unwanted. + For example, when you pass the same frame to the output more than once, it + will confuse metronom. To solve this, you can call + frame->next->draw() with NULL as the stream. + You might also want to prevent frames from being passed down to the output + completely, because your post plugin creates something else from these frames, + but does not need them to be drawn. In both these situations, you have + to call the helper function _x_post_frame_u_turn() + when the frame is drawn, because this does some housekeeping which the + decoder might expect to take place. + + + The following diagram summarizes the situations of a video frame passing + through a post plugin: + + + + + + + + + + video frame passing through a post plugin + + + + + Summary of constraints + + + + Call _x_post_inc_usage() before port open() + before any other port function. + + + + + Call _x_post_inc_usage() before issueing an intercepted frame. + + + + + Call _x_post_dec_usage() after port close() + and do not call any port functions after that. + + + + + Call _x_post_dec_usage() after restoring a frame. + + + + + When a frame is drawn by your plugin, it must either be drawn on the original + port with the correct stream as argument or U-turned (or passed through a + private metronom manually). + + + + + If your post plugin keeps locked frames, release them when your input port is being + closed. + + + + + Do not assume your plugin is alive after _x_post_dec_usage(). + + + + + + + Rewiring and the ticket system + + Rewiring is the reconnection of one post plugin's outputs and another post plugin's + inputs. This can happen on the fly during playback, which makes this a very delicate + process. In one such input to output connection, only the output is active by either + writing data directly to the connected input or by calling functions there. Therefore + we have to notify only the output, when it is rewired. This is done by calling the + rewire() member function of the corresponding + xine_post_out_t when the frontend issues a rewiring on this output. + This is done from the frontend thread for the rewire operation to return synchroneously. + But since this can happen on the fly, we have to assure that no other thread is relying + on the connection while we modify it. For this, threads working within post plugins + have to be accounted and on demand suspended in safe positions. For this, xine offers + a synchronization facility called "tickets". + + + Ticket system principles and operations + + The idea of the ticket system is based on an extended read-write lock, where there can + be many readers in parallel, but only one exclusive writer. A certain interface might + require you to have a ticket before calling its functions. The ticket system now + allows multiple threads to operate within the component behind the interface by + granting as many tickets as needed. But should an outside operation require exclusive + access to the component, all granted tickets can be revoked and have to be given back + by the threads who hold them, which suspends the threads. After the exclusive + operation, tickets will be reissued so all suspended threads can continue where they + stopped. We will now look at the ticket primitives in detail: + + + + acquire() + + + You receive a new ticket. If the ticket is currently revoked, you can be blocked + until it is reissued. There is one exception to this: You can acquire a revoked + ticket, if you revoked it atomic yourself. You can also acquire a ticket irrevocably. + Between acquire and release of an irrevocable ticket, it is guaranteed that + you will not be blocked by ticket revocation. + + + + + release() + + + You give a ticket back when you do not need it any longer. If the ticket is + currently revoked, you can be blocked until it is reissued. If you acquired the + ticket irrevocably, you have to release it irrevocably as well. + + + + + renew() + + + You must only call this function, when the ticket has been revoked, so be + sure to check ticket_revoked before. You give the ticket + back and receive a new one. In between, you can be blocked until the ticket is + reissued. You have to renew irrevocably, if you cannot assure that the thread holds + no irrevocable tickets. If you can assure this, renew revocably. + + + + + revoke() + + + This function can only be called by the xine engine, plugins do not have access to it. + It revokes all tickets and after finite time, all threads will run into a + acquire(), release() or renew() + and will be suspended there. Then the revocation returns and you can modify structures + or call functions with the knowledge that all ticket holders will remain in safe + positions. When you additionally need exclusive access where no other revoker + can interfere, you have to revoke atomic. + + + + + issue() + + + This function can only be called by the xine engine, plugins do not have access to it. + It ends ticket revocation and hands out new tickets to all threads that applied with a + acquire() or renew(). If you revoked the + tickets atomic, you have to issue them atomic. + + + + + + When you use the ticket system in any way, you have to obey to the following rules: + + + + Assure to release irrevocable tickets ater a finite time. + + + + + Assure to release or renew revocable tickets ater a finite time. + + + + + Assure to reissue tickets you revoked atomic after a finite time. + + + + + Pair calls properly. + + + + + Never revoke a ticket you hold. + + + + + Never acquire a ticket you revoked atomic before. + + + + + Never acquire a ticket revocable more than once. + + + + + + + Ticket handling in decoder and post plugins + + The contract of the video and audio port interfaces is that you need to have + the port ticket, when you want to call functions of these interfaces. The decoder + plugins do not have to worry about this at all, since the decoder loops inside the + engine handle the ticketing. Post plugins get the ticket assigned by the engine, + but usually, a post plugin does not create a new thread, it is called by the + decoder thread and therefore already owns the necessary ticket. All port functions + are also ticket-safe as they follow all the rules given above. + + + You only have to remember that tickets need to be renewed as soon as possible, + when the are revoked. For this, the helper function + _x_post_rewire() should be used in prominent locations + where it is safe to be suspended. Candidates for such locations are at the + beginning of the port's open() and + get_frame()/get_buffer() functions. + The default pass through implementations for intercepted ports already do this. + + + The port tickets are revoked, whenever a rewiring takes place or the engine + switches into pause mode. The tickets are reissued, when the rewiring is finished + or the engine switches from pause mode into playback. Some post plugins might + contain critical parts, where they must not be interrupted by a rewire or pause. + These sections can be enclosed in _x_post_lock() and + _x_post_unlock(), which will simply acquire and release an + irrevocable ticket for you. As long as you hold such a ticket, it is guaranteed + that you will never be interrupted by a pause or rewire. + + + + + + + Video output + + 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 vo_frame_t structures and their + 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 important, the ability to render/copy a given + frame to the output device. + + + + + Optionally 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 scaling 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. + + + Writing a xine video out plugin + + The video out plugin API is declared in src/xine-engine/video_out.h + The plugin info of video out plugins contains the visual type, priority, + and the init_class function of the plugin. + + + The visual_type field is used by xine to + determine if the GUI used by the client is supported by the plugin + (e.g. X11 output plugins require the GUI to be running under the + X Windowing system) and also to determine the type of information passed to the + open_plugin() function as its visual parameter. + + +    char *get_description(video_driver_class_t *this_gen); + This function returns a plaintext, one-line string describing the plugin. + + +    char *get_identifier(video_driver_class_t *this_gen); + This function returns a shorter identifier describing the plugin. + + +    void dispose(video_driver_class_t *this_gen); + This function frees the memory used by the video out plugin class object. + + +    vo_driver_t *get_instance(video_driver_class_t *class_gen, const void *visual); + Returns an instance of the plugin. + The visual is 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 a x11_visual_t, which amongst other things hold the + Display variable associated with the + X-server xine should display to. See plugin source-code for other + VISUAL_TYPE_* constants and associated structures. Note that this + field is provided by the client application and so if you wish to add another visual + type you will either need to extend an existing client or write a new + one. + + +    uint32_t get_capabilities(vo_driver_t *this_gen); + Returns a bit mask describing the output plugin's capabilities. + You may logically OR the VO_CAP_* constants together to get + a suitable bit-mask (via the '|' operator). + + + +   int get_property(vo_driver_t *self, int property); +   int set_property(vo_driver_t *self, int property, int value); +   void get_property_min_max(vo_driver_t *self, int property, int *min, int *max); + Handle the getting, setting of properties and define their bounds. + Valid property IDs can be found in the video_out.h + header file. + + +    int gui_data_exchange(vo_driver_t *self, int data_type, void *data); + Accepts 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. + + +    vo_frame_t *alloc_frame(vo_driver_t *self); + Returns a pointer to a xine video frame. + Typically the video plugin will add private fields to the end of the + vo_frame_t structure which are used for internal purposes by the plugin. + + + The function pointers within the frame structure provide 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. + + +    void update_frame_format(vo_driver_t *self, vo_frame_t *img, uint32_t width, uint32_t height, double ratio, int format, int flags); + This function 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 any driver-specific changes. + + +    void display_frame(vo_driver_t *self, vo_frame_t *vo_img); + Renders a given frame to the output device. + + + +   void overlay_begin(vo_driver_t *self, vo_frame_t *vo_img, int changed); +   void overlay_blend(vo_driver_t *self, vo_frame_t *vo_img, vo_overlay_t *overlay); +   void overlay_end(vo_driver_t *self, vo_frame_t *vo_img); + These are used to blend overlays on frames. overlay_begin() is called, + when the overlay appears for the first time, overlay_blend() is then + called for every subsequent frame and overlay_end() is called, when + the overlay should disappear again. + + +    int redraw_needed(vo_driver_t *self); + Queries the driver, if the current frame needs to be drawn again. + + +    void dispose(vo_driver_t *self); + Releases all resources and frees the plugin. + + + + + diff --git a/doc/hackersguide/output.sgml b/doc/hackersguide/output.sgml deleted file mode 100644 index 806e89d0a..000000000 --- a/doc/hackersguide/output.sgml +++ /dev/null @@ -1,668 +0,0 @@ - - xine's output layer - - - Post plugin layer - - In this section you will learn, how the powerful post plugin architecture - works and how to write post plugins. - - - General principle of post plugins - - The name "post plugin" comes from "postprocessing" which already describes - what these plugins are supposed to do: they take video frames, audio - buffers or subpicture planes as they leave the decoders and apply arbitrary - processing to them. Then they pass processed elements on to the output - loops. Post plugins can not only be chained to process the predecessor's - output and advance the data to their successor, they can form arbitrary trees, - since post plugins can have any number of inputs and outputs. Additionally, - the interconnection of the plugins currently inserted in such a tree can - be changed on the fly during playback. The public function - xine_post_wire() is used by frontends to form such - connections. - - - Due to the variety of possible applications, the interface post plugins have - to implement is just the basic foundation. The complexity comes from hooking - your post plugin into the engine data paths for video frames and audio buffers, - intercepting the data and performing your operation on them. This is done by - taking the interface of a video or audio port, replacing some of the functions - with your own ones and passing the interface to the decoder or predecessor - post plugin that is going to feed you with data by accessing this interface - and by doing that, calling the functions you provide. From there you can do - almost anything you want. Constructing video frames from audio buffers to - visualize sound is possible as well as just outputting an integer giving the - average brightness of an image. It is also possible to invent post plugins - with no output (not very useful, unless the plugin has some side-effect) or - no input at all; for the latter you have to create your own pthread, otherwise - your plugin will not do anything. An audio signal generator could be - implemented like this. The various data types, post plugins can - accept as input or offer as output are defined in xine.h - as XINE_POST_DATA_* defines. - - - Some terminology used in the following explanations: - - - - down direction: - The direction from the decoders to the output. This is the way video or audio - data (actual content and meta information) usually travels through the engine. - - - - - up direction: - The direction from the output to the decoders. This is the way some video or audio - metadata like metronom timestamps travel through the engine. - - - - - interception: - Post plugins are inserted into the engine data paths by the means of the decorator - design pattern. This works by taking engine structures with member funtions like - video or audio ports, video frames or overlay managers and inserting your own functions - into a copy of this structure. This is called interception. This modified structure - is then passed up to the plugin that uses it and thus calls your replaced functions. - - - - - - - Writing a xine post plugin - - The post plugin API is declared in src/xine-engine/post.h - The plugin info of post plugins contains the post plugin type, which is one of the - XINE_POST_TYPE_* defines and the init_class function of the plugin. - - -    post_plugin_t *open_plugin(post_class_t *class_gen, int inputs, xine_audio_port_t **audio_target, xine_video_port_t **video_target); - Returns an instance of the plugin. Some post plugins evaluate inputs - to open a variable number of inputs. Since almost all post plugins have audio or video - outputs, you can hand in a NULL-terminated array of ports to connect to these outputs. - In this function you can also intercept these ports so that your plugin is actually used. - There is a helper function to initialize a post_plugin_t, which you are - encouraged to use: _x_post_init(). - - -    char *get_identifier(post_class_t *class_gen); - This function returns a short identifier describing the plugin. - - -    char *get_description(post_class_t *class_gen); - This function returns a plaintext, one-line string describing the plugin. - - -    void dispose(post_class_t *class_gen); - This function frees the memory used by the video out plugin class object. - - - The post_plugin_t structure contains the publicly visible - part of the post plugin with the audio and video inputs and the type of - the post plugin. Not publicly visible are the lists of all inputs and outputs, - the dispose() function and some internal stuff which - plugins do not have to worry about. - - -    void dispose(post_plugin_t *this_gen); - This function frees the memory used by the plugin instance, but not necessarily - immediately. Since post plugins enter their own functions into engine structures, - they might still be needed when dispose() is being called. - They maintain a usage counter to detect that. To check for such a condition, you - should use the _x_post_dispose() helper function like that: - -   if (_x_post_dispose(this)) -     really_free(this); - _x_post_dispose() frees any ressources allocated by any of the - post plugin helper functions and returns boolean true, if the plugin is not needed - any more. - - - - Interception - - Currently, we have four engine structures which can be intercepted by post plugins: - video ports, video frames, overlay managers and audio ports. You could do this - interception manually, but since this is quite a complex process, there are helper - functions to assist you and their usage is encouraged. - - - Intercepting a video port - - -   post_video_port_t *_x_post_intercept_video_port(post_plugin_t *post, -     xine_video_port_t *port, post_in_t **input, post_out_t **output); - This function will intercept port and returns a structure - for you to pass up. All functions in the port will be replaced with dummy - pass through functions that do nothing but relaying the call down to the original - port. If you want (that is, input or output are - not NULL), this function will also create the input and output descriptors complete - with rewiring functions and add them to the relevant lists. - This is required, if you want this port to be advertised by the plugin to the outside world. - - - post_video_port_t makes a variety of interception schemes very easy. - If you want to replace any of the default functions with your own, just enter it - into new_port. You can use original_port - from within your function to propagate calls down to the original port. - The constraint is that your functions have to ensure that every original - port held open scores one usage counter point, so that opened ports are always - closed before the plugin is disposed. Therefore, you should use the macro - _x_post_inc_usage() before calling - original_port->open() and use the macro - _x_post_dec_usage() after calling - original_port->close(). Note that _x_post_dec_usage() - might dispose the plugin, when dispose() has been called - earlier and usage count drops to zero, so do never touch plugin structures after - _x_post_dec_usage(). In addition, you must never call a port - function of the original port when the port is not open. - - - Intercepting video frames or the overlay manager of the port is even easier. - You do not have to reimplement get_frame() or - get_overlay_manager(). Just enter a intercept_frame - or intercept_ovl function which returns boolean true, if - you want to intercept. The functions to insert in the intercepted frame or overlay - manager are taken from new_frame and new_manager - respectively. Note that the defaults are reversed: If you do not enter such a - decision function for either one, all frames and no overlay manager will be intercepted. - - - For convenience post_video_port_t also contains pointers to the - current stream and to the current post plugin and a user_data pointer, where you - can put in anything you need in addition. If your port is used by more than one - thread, you can also enforce locking on the port, frame or overlay manager level - by entering a lock into port_lock, frame_lock or - manager_lock respectively. - - - - Intercepting an audio port - - Audio port interception is just a stripped down version of video port interception. - Everything related to frames and overlay manager is not needed and audio buffers - do not need to be intercepted, since they have no member functions. Everything else - of the above still applies. - - - - Intercepting overlay manager - -    void _x_post_intercept_overlay_manager(video_overlay_manager_t *original, post_video_port_t *port); - Interception of the overlay manager is done automatically when your - intercept_ovl() decision function returns boolean true. - Should you ever decide not to use that, interception can be done with this helper - function, which simply creates an intercepted overlay manager with dummy - pass through functions in port->new_manager and stores the original - manager in port->original_manager. - - - No matter how you intercepted the overlay manager, your own replacement - functions will receive port->new_manager as the overlay manager - argument. But you most likely want to have access to the post_video_port_t - from within your functions. For that, there exists a pointer retrieval function: -    post_video_port_t *_x_post_ovl_manager_to_port(video_overlay_manager_t *manager); - - - - Intercepting a video frame - - -   vo_frame_t *_x_post_intercept_video_frame(vo_frame_t *frame, post_video_port_t *port); -   vo_frame_t *_x_post_restore_video_frame(vo_frame_t *frame, post_video_port_t *port); - Interception of video frames is done automatically when your - intercept_frame() decision function returns boolean true or - when there is no such function in post_video_port_t. - Should you ever decide not to use that, interception can be done with the helper - function _x_post_intercept_video_frame(). - - - Since the same video frame can be in use in the decoder and in the output and in - any post plugin in between at the same time, simply modifying the frame - structure does not work, because every user of the frame needs to see his version - and the frame must always travel along the same path through the plugins for its - entire lifetime. To ensure that, _x_post_intercept_video_frame() - provides a shallow copy of the frame structure with the original frame attached to - copy->next. This copy will be filled with your own - frame functions from port->new_frame and with dummy pass - through functions for those you did not provide. This way, every part of xine - using this frame will see its own frame structure with a list of frame - contexts from down the data path attached to frame->next. - _x_post_restore_video_frame() reverses this and should be - used when the frame is freed or disposed. - - - Your own replacement functions will receive the copied frame as as argument. - But you most likely want to have access to the post_video_port_t - from within your functions. For that, there exists a pointer retrieval function: -    post_video_port_t *_x_post_video_frame_to_port(vo_frame_t *frame); - The constraint is that your functions have to ensure that every intercepted - frame scores one usage counter point, so that these frames are always - freed or disposed before the plugin is disposed. Therefore, you should use the macro - _x_post_inc_usage() before calling - _x_post_intercept_video_frame() and use the macro - _x_post_dec_usage() after calling - _x_post_restore_video_frame(). Note that _x_post_dec_usage() - might dispose the plugin, when dispose() has been called - earlier and usage count drops to zero, so do never touch plugin structures after - _x_post_dec_usage(). - - - From within your own frame functions, you can propagate calls to the original - frame by calling a function on frame->next. Since - modifications to the frame can travel both upwards and downwards (decoders and - output can modify the frame), changes need to be copied between the frame - structure contexts. You should use the _x_post_frame_copy_down() - and _x_post_frame_copy_up() helper functions like that: - -   _x_post_frame_copy_down(frame, frame->next); -   frame->next->draw(frame->next, stream); -   _x_post_frame_copy_up(frame, frame->next); - - - If your post plugin modifies the content of the frame, you have to modify - a deep copy of the frame, because the decoder might still use the frame as - a reference frame for future decoding. The usual procedure is: - -   modified_frame = port->original_port->get_frame(port->original_port, ...); -   _x_post_frame_copy_down(frame, modified_frame); -   copy_and_modify(frame, modified_frame); -   skip = modified_frame->draw(modified_frame, stream); -   _x_post_frame_copy_up(frame, modified_frame); -   modified_frame->free(modified_frame); - - - When the output receives a frame via draw(), - it usually receives the stream where the frame - originates as well and modifies the state of this stream by passing - the frame through the stream's metronom. Sometimes this is unwanted. - For example, when you pass the same frame to the output more than once, it - will confuse metronom. To solve this, you can call - frame->next->draw() with NULL as the stream. - You might also want to prevent frames from being passed down to the output - completely, because your post plugin creates something else from these frames, - but does not need them to be drawn. In both these situations, you have - to call the helper function _x_post_frame_u_turn() - when the frame is drawn, because this does some housekeeping which the - decoder might expect to take place. - - - The following diagram summarizes the situations of a video frame passing - through a post plugin: - - - - - - - - - - video frame passing through a post plugin - - - - - Summary of constraints - - - - Call _x_post_inc_usage() before port open() - before any other port function. - - - - - Call _x_post_inc_usage() before issueing an intercepted frame. - - - - - Call _x_post_dec_usage() after port close() - and do not call any port functions after that. - - - - - Call _x_post_dec_usage() after restoring a frame. - - - - - When a frame is drawn by your plugin, it must either be drawn on the original - port with the correct stream as argument or U-turned (or passed through a - private metronom manually). - - - - - If your post plugin keeps locked frames, release them when your input port is being - closed. - - - - - Do not assume your plugin is alive after _x_post_dec_usage(). - - - - - - - Rewiring and the ticket system - - Rewiring is the reconnection of one post plugin's outputs and another post plugin's - inputs. This can happen on the fly during playback, which makes this a very delicate - process. In one such input to output connection, only the output is active by either - writing data directly to the connected input or by calling functions there. Therefore - we have to notify only the output, when it is rewired. This is done by calling the - rewire() member function of the corresponding - xine_post_out_t when the frontend issues a rewiring on this output. - This is done from the frontend thread for the rewire operation to return synchroneously. - But since this can happen on the fly, we have to assure that no other thread is relying - on the connection while we modify it. For this, threads working within post plugins - have to be accounted and on demand suspended in safe positions. For this, xine offers - a synchronization facility called "tickets". - - - Ticket system principles and operations - - The idea of the ticket system is based on an extended read-write lock, where there can - be many readers in parallel, but only one exclusive writer. A certain interface might - require you to have a ticket before calling its functions. The ticket system now - allows multiple threads to operate within the component behind the interface by - granting as many tickets as needed. But should an outside operation require exclusive - access to the component, all granted tickets can be revoked and have to be given back - by the threads who hold them, which suspends the threads. After the exclusive - operation, tickets will be reissued so all suspended threads can continue where they - stopped. We will now look at the ticket primitives in detail: - - - - acquire() - - - You receive a new ticket. If the ticket is currently revoked, you can be blocked - until it is reissued. There is one exception to this: You can acquire a revoked - ticket, if you revoked it atomic yourself. You can also acquire a ticket irrevocably. - Between acquire and release of an irrevocable ticket, it is guaranteed that - you will not be blocked by ticket revocation. - - - - - release() - - - You give a ticket back when you do not need it any longer. If the ticket is - currently revoked, you can be blocked until it is reissued. If you acquired the - ticket irrevocably, you have to release it irrevocably as well. - - - - - renew() - - - You must only call this function, when the ticket has been revoked, so be - sure to check ticket_revoked before. You give the ticket - back and receive a new one. In between, you can be blocked until the ticket is - reissued. You have to renew irrevocably, if you cannot assure that the thread holds - no irrevocable tickets. If you can assure this, renew revocably. - - - - - revoke() - - - This function can only be called by the xine engine, plugins do not have access to it. - It revokes all tickets and after finite time, all threads will run into a - acquire(), release() or renew() - and will be suspended there. Then the revocation returns and you can modify structures - or call functions with the knowledge that all ticket holders will remain in safe - positions. When you additionally need exclusive access where no other revoker - can interfere, you have to revoke atomic. - - - - - issue() - - - This function can only be called by the xine engine, plugins do not have access to it. - It ends ticket revocation and hands out new tickets to all threads that applied with a - acquire() or renew(). If you revoked the - tickets atomic, you have to issue them atomic. - - - - - - When you use the ticket system in any way, you have to obey to the following rules: - - - - Assure to release irrevocable tickets ater a finite time. - - - - - Assure to release or renew revocable tickets ater a finite time. - - - - - Assure to reissue tickets you revoked atomic after a finite time. - - - - - Pair calls properly. - - - - - Never revoke a ticket you hold. - - - - - Never acquire a ticket you revoked atomic before. - - - - - Never acquire a ticket revocable more than once. - - - - - - - Ticket handling in decoder and post plugins - - The contract of the video and audio port interfaces is that you need to have - the port ticket, when you want to call functions of these interfaces. The decoder - plugins do not have to worry about this at all, since the decoder loops inside the - engine handle the ticketing. Post plugins get the ticket assigned by the engine, - but usually, a post plugin does not create a new thread, it is called by the - decoder thread and therefore already owns the necessary ticket. All port functions - are also ticket-safe as they follow all the rules given above. - - - You only have to remember that tickets need to be renewed as soon as possible, - when the are revoked. For this, the helper function - _x_post_rewire() should be used in prominent locations - where it is safe to be suspended. Candidates for such locations are at the - beginning of the port's open() and - get_frame()/get_buffer() functions. - The default pass through implementations for intercepted ports already do this. - - - The port tickets are revoked, whenever a rewiring takes place or the engine - switches into pause mode. The tickets are reissued, when the rewiring is finished - or the engine switches from pause mode into playback. Some post plugins might - contain critical parts, where they must not be interrupted by a rewire or pause. - These sections can be enclosed in _x_post_lock() and - _x_post_unlock(), which will simply acquire and release an - irrevocable ticket for you. As long as you hold such a ticket, it is guaranteed - that you will never be interrupted by a pause or rewire. - - - - - - - Video output - - 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 vo_frame_t structures and their - 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 important, the ability to render/copy a given - frame to the output device. - - - - - Optionally 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 scaling 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. - - - Writing a xine video out plugin - - The video out plugin API is declared in src/xine-engine/video_out.h - The plugin info of video out plugins contains the visual type, priority, - and the init_class function of the plugin. - - - The visual_type field is used by xine to - determine if the GUI used by the client is supported by the plugin - (e.g. X11 output plugins require the GUI to be running under the - X Windowing system) and also to determine the type of information passed to the - open_plugin() function as its visual parameter. - - -    char *get_description(video_driver_class_t *this_gen); - This function returns a plaintext, one-line string describing the plugin. - - -    char *get_identifier(video_driver_class_t *this_gen); - This function returns a shorter identifier describing the plugin. - - -    void dispose(video_driver_class_t *this_gen); - This function frees the memory used by the video out plugin class object. - - -    vo_driver_t *get_instance(video_driver_class_t *class_gen, const void *visual); - Returns an instance of the plugin. - The visual is 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 a x11_visual_t, which amongst other things hold the - Display variable associated with the - X-server xine should display to. See plugin source-code for other - VISUAL_TYPE_* constants and associated structures. Note that this - field is provided by the client application and so if you wish to add another visual - type you will either need to extend an existing client or write a new - one. - - -    uint32_t get_capabilities(vo_driver_t *this_gen); - Returns a bit mask describing the output plugin's capabilities. - You may logically OR the VO_CAP_* constants together to get - a suitable bit-mask (via the '|' operator). - - - -   int get_property(vo_driver_t *self, int property); -   int set_property(vo_driver_t *self, int property, int value); -   void get_property_min_max(vo_driver_t *self, int property, int *min, int *max); - Handle the getting, setting of properties and define their bounds. - Valid property IDs can be found in the video_out.h - header file. - - -    int gui_data_exchange(vo_driver_t *self, int data_type, void *data); - Accepts 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. - - -    vo_frame_t *alloc_frame(vo_driver_t *self); - Returns a pointer to a xine video frame. - Typically the video plugin will add private fields to the end of the - vo_frame_t structure which are used for internal purposes by the plugin. - - - The function pointers within the frame structure provide 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. - - -    void update_frame_format(vo_driver_t *self, vo_frame_t *img, uint32_t width, uint32_t height, double ratio, int format, int flags); - This function 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 any driver-specific changes. - - -    void display_frame(vo_driver_t *self, vo_frame_t *vo_img); - Renders a given frame to the output device. - - - -   void overlay_begin(vo_driver_t *self, vo_frame_t *vo_img, int changed); -   void overlay_blend(vo_driver_t *self, vo_frame_t *vo_img, vo_overlay_t *overlay); -   void overlay_end(vo_driver_t *self, vo_frame_t *vo_img); - These are used to blend overlays on frames. overlay_begin() is called, - when the overlay appears for the first time, overlay_blend() is then - called for every subsequent frame and overlay_end() is called, when - the overlay should disappear again. - - -    int redraw_needed(vo_driver_t *self); - Queries the driver, if the current frame needs to be drawn again. - - -    void dispose(vo_driver_t *self); - Releases all resources and frees the plugin. - - - - - diff --git a/doc/hackersguide/overview.docbook b/doc/hackersguide/overview.docbook new file mode 100644 index 000000000..d405ac18c --- /dev/null +++ b/doc/hackersguide/overview.docbook @@ -0,0 +1,811 @@ + + 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. If some xine specific + adaptation of the code is absolutely necessary, a patch containing + the changes should be stored in Mercurial to not lose the changes the + next time we sync with the external project. + + + + + 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. + + + + + + vcd + + + The enhanced VCD input plugin which also handles VCD navigation. + + + + + libcdio, libvcd (imported) + + + Libraries used by the enhanced VCD 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. + + + + + + libdts (imported) + + + AC5 (aka DTS) audio decoder library and xine plugin, which is capable + of software decoding as well as digital passthrough. + + + + + + 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. + + + + + + + + + + + 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. + + + + + + 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. + + + + + audio + + + Some audio effects as xine audio filter posts. + + + + + + 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; +   } + + + The part added to the derived class is private, because when + defining the new structure directly in the .c file, where it will + be used, outside modules have no way of seeing the definition + of the derived class. A public derivation is possible by defining + the above structure in a .h file for others to include. + + + Something similar to a protected, package or friend visibility is also + possible: + +   struct my_stack_s { +    void (*push)(my_stack_t *this, int i); +    void (*add)(my_stack_t *this); +    int (*pop)(my_stack_t *this); +    +   #ifdef STACK_INTERNAL +    void (*flush)(my_stack_t *this); +   #endif +   }; + All modules, who need to access the internal part have to add +    #define STACK_INTERNAL + before including the header with the definition. It is clear that only + those friend modules can derive from this class. + + + 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; +   } + + + Why not using C++? + + After all these considerations about object oriented C, you might + ask, why we do not use C++ after all? The easy answer would be: xine wants + to be as fast as possible and C++ is simply too slow. But this is only the + easy answer and it is not entirely true any more. Thoughtfully applied, you + can write very fast C++ code with today's compilers, but these compilers might + not be available on all platforms in the necessary quality. Even with + a sophisticated compiler, C++ is much harder to optimize than plain C and thus + C compiles much faster. Another big problem is that the C++ ABI is not as + well-defined as the C ABI. With C, you can easily mix libraries and + applications built by different compilers. With C++, this is unlikely to work. + But the final argument is that xine does not really need C++. xine's + inheritance hierarchy is very flat, mostly one level only and does not need + things like multiple or virtual inheritance. Most of the external projects + that are used by xine are plain C as well and using more than one language + complicates the build system. As we saw above, we can emulate + object orientation reduced to our real needs in plain C. + + + + + + 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". + + + + _x_assert/_x_abort + + These are not purely logging functions, but despite their original C library versions, + they always output debugging text, which is why usage of these functions is preferred. + + + _x_assert() checks a condition and prints a note, + when the condition is false. In addition, a debug build and only a debug build will + terminate the application, when the condition is false. Release versions will only + print the note, but try to continue. + + + _x_abort() always terminates the application after printing a note. + + + + + + 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). + + + + diff --git a/doc/hackersguide/overview.sgml b/doc/hackersguide/overview.sgml deleted file mode 100644 index d405ac18c..000000000 --- a/doc/hackersguide/overview.sgml +++ /dev/null @@ -1,811 +0,0 @@ - - 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. If some xine specific - adaptation of the code is absolutely necessary, a patch containing - the changes should be stored in Mercurial to not lose the changes the - next time we sync with the external project. - - - - - 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. - - - - - - vcd - - - The enhanced VCD input plugin which also handles VCD navigation. - - - - - libcdio, libvcd (imported) - - - Libraries used by the enhanced VCD 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. - - - - - - libdts (imported) - - - AC5 (aka DTS) audio decoder library and xine plugin, which is capable - of software decoding as well as digital passthrough. - - - - - - 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. - - - - - - - - - - - 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. - - - - - - 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. - - - - - audio - - - Some audio effects as xine audio filter posts. - - - - - - 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; -   } - - - The part added to the derived class is private, because when - defining the new structure directly in the .c file, where it will - be used, outside modules have no way of seeing the definition - of the derived class. A public derivation is possible by defining - the above structure in a .h file for others to include. - - - Something similar to a protected, package or friend visibility is also - possible: - -   struct my_stack_s { -    void (*push)(my_stack_t *this, int i); -    void (*add)(my_stack_t *this); -    int (*pop)(my_stack_t *this); -    -   #ifdef STACK_INTERNAL -    void (*flush)(my_stack_t *this); -   #endif -   }; - All modules, who need to access the internal part have to add -    #define STACK_INTERNAL - before including the header with the definition. It is clear that only - those friend modules can derive from this class. - - - 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; -   } - - - Why not using C++? - - After all these considerations about object oriented C, you might - ask, why we do not use C++ after all? The easy answer would be: xine wants - to be as fast as possible and C++ is simply too slow. But this is only the - easy answer and it is not entirely true any more. Thoughtfully applied, you - can write very fast C++ code with today's compilers, but these compilers might - not be available on all platforms in the necessary quality. Even with - a sophisticated compiler, C++ is much harder to optimize than plain C and thus - C compiles much faster. Another big problem is that the C++ ABI is not as - well-defined as the C ABI. With C, you can easily mix libraries and - applications built by different compilers. With C++, this is unlikely to work. - But the final argument is that xine does not really need C++. xine's - inheritance hierarchy is very flat, mostly one level only and does not need - things like multiple or virtual inheritance. Most of the external projects - that are used by xine are plain C as well and using more than one language - complicates the build system. As we saw above, we can emulate - object orientation reduced to our real needs in plain C. - - - - - - 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". - - - - _x_assert/_x_abort - - These are not purely logging functions, but despite their original C library versions, - they always output debugging text, which is why usage of these functions is preferred. - - - _x_assert() checks a condition and prints a note, - when the condition is false. In addition, a debug build and only a debug build will - terminate the application, when the condition is false. Release versions will only - print the note, but try to continue. - - - _x_abort() always terminates the application after printing a note. - - - - - - 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). - - - - diff --git a/doc/hackersguide/stream.docbook b/doc/hackersguide/stream.docbook new file mode 100644 index 000000000..d05bbba65 --- /dev/null +++ b/doc/hackersguide/stream.docbook @@ -0,0 +1,656 @@ + + xine's stream layer + + + Input layer + + 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 specialized medium + (e.g. DVD), etc. To allow you to access all 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 recognizes. + 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. + + + Writing a xine input plugin + + An input plugin provides API functions which allow the engine to + access the data source the plugin encapsulates. The input plugin API + is declared in input/input_plugin.h. + + + An input plugin exports a public function of the form: +    void *input_init_plugin(xine_t *xine, void *data); + This function initializes an input plugin class object with the + following functions: + + +    char *get_description(input_class_t *this_gen); + This function returns a plaintext, one-line string describing the plugin. + + +    char *get_identifier(input_class_t *this_gen); + This function returns a shorter identifier describing the plugin. + + +    xine_mrl_t **get_dir(input_class_t *this_gen, const char *filename, int *nFiles); + Retrieves a directory listing from the plugin. This function is optional. + + +    char **get_autoplay_list(input_class_t *this_gen, int *num_files); + Retrieves the autoplay playlist from the plugin. This function is optional. + + +    int eject_media(input_class_t *this_gen); + Ejects the medium. This function is optional. + + +    void dispose(input_class_t *this_gen); + This function frees the memory used by the input plugin class object. + + +    input_plugin_t *get_instance(input_class_t *class_gen, xine_stream_t *stream, const char *mrl); + The plugin should try, if it can handle the specified MRL and return an + instance of itself if so. If not, NULL should be returned. When a new MRL + is to be played, xine engine asks all the available input plugins one by + one if they can handle the MRL. + Note that input plugins are not guaranteed to be queried + in any particular order and the first input plugin to claim an MRL + gets control so try not to duplicate MRLs already found within xine. + + +    int open(input_plugin_t *this_gen); + You should do any device-specific initialisation within this function. + + +    uint32_t get_capabilities(input_plugin_t *this_gen); + Returns a bit mask describing the input device's capabilities. + You may logically OR the INPUT_CAP_* constants together to get + a suitable bit-mask (via the '|' operator). + + +    off_t read(input_plugin_t *this_gen, char *buf, off_t nlen); + Reads a specified number of bytes into a buffer and returns the number of bytes actually copied. + + +    buf_element_t *read_block(input_plugin_t *this_gen, fifo_buffer_t *fifo, off_t len); + Should the input plugin set the block-oriented hint and if the + demuxer supports it, this function will be called to read a block directly + into a xine buffer from the buffer pool. + + +    off_t seek(input_plugin_t *this_gen, off_t offset, int origin); + This function is called by xine when it is required that subsequent + reads come from another part of the stream. + + +    off_t get_current_pos(input_plugin_t *this_gen); + Returns the current position within a finite length stream. + + +    off_t get_length(input_plugin_t *this_gen); + Similarly this function returns the length of the stream. + + +    uint32_t get_blocksize(input_plugin_t *this_gen); + Returns the device's prefered block-size if applicable. + + +    char *get_mrl(input_plugin_t *this_gen); + Returns the current MRL. + + +    int get_optional_data(input_plugin_t *this_gen, void *data, int data_type); + This function allows the input to advertise extra information that is + not available through other API functions. See INPUT_OPTIONAL_* defines. + + +    void dispose(input_plugin_t *this_gen); + This function closes all resources and frees the input_plugin_t object. + + + + + + Demuxer layer + + This section is designed to familiarize a programmer with general demuxer + concepts and how they apply to the xine multimedia library. + + + Introduction to demuxer theory + + xine's demuxer layer is responsible for taking apart multimedia files or + streams so that the engine can decode them and present them to the user. + "Demuxer" is short for demultiplexor, which is the opposite of + multiplexing. This refers to the process of combining 2 or more things + into one. Multimedia streams usually, at a minimum, multiplex an audio + stream and a video stream together into one stream. Sometimes, there are + multiple audio streams (e.g., for multiple language tracks). Sometimes, + there is a subtitle data stream multiplexed into the multimedia stream. + + + There are many different multimedia formats in existence and there are + varying strategies for demuxing different types of multimedia files. + Formats in the MPEG family, for example, are designed to allow easy + playback from almost any place within the file. Many formats cannot deal + with this circumstance and at least need to be demuxed from the beginning + of the stream and played through to the end. Some formats, such as MPEG and + AVI, have marker information before every chunk in the stream. Other + formats, such as Apple Quicktime, are required to have a master index that + contains all information for taking apart a file. Many game-oriented + multimedia formats are designed strictly for playing from start to finish + without any regard to random seeking within the file. + + + + Input considerations + + A xine demuxer interacts with xine's input layer in order to receive + data. The underlying input plugin might be a file, a network stream, or + a block-oriented disc storage device like a DVD. A file input offers the + most flexibility in being able to read either blocks of data or individual + bytes, and being able to seek freely. Other input plugins may not allow the + demuxer to seek (such as stdin or certain network streams). Some input + plugins only allow the demuxer to read blocks of data and not individual + bytes (such as the CD-DA input plugin). The demuxer needs to check the + capabilities of the underlying input plugin before attempting to seek + around. + + + + Seeking Policy + + If possible, it is desirable that a demuxer can seek randomly through + the stream. This is easier for some file formats and essentially impossible + for other formats. xine's seeking API function allows a seek target to be + specified in terms of a ratio from 0 to 65535, or time in milliseconds from 0. + Time-based seeking is useful for specifying, e.g., a 1-minute jump forward + or backward in a stream. With the ratio-based seeking, the demuxer can + interpret the ratio value in the domain he sees most fit. This can also be + some sort of time or a simple file offset. + + + If a multimedia stream has video, there generally needs to be a way to + identify keyframes in the stream in order to facilitate seeking. Many + game-oriented formats fall over in this area as they carry no keyframe + information aside from the implicit assumption that the first frame is a + keyframe. + + + In a stream with video, a seek operation should always jump to a keyframe. + xine Policy: When the seek target is between 2 keyframes, jump to the + earlier keyframe. E.g., if there are keyframes at stream offsets 10000 and + 20000, and the user requests a seek to offset 18000, choose the keyframe + at offset 10000. + + + Note that there can be difficulties when the audio and video streams are + not tightly interleaved. In many formats, the audio frames are several + time units ahead of the video frames for the purpose of pre-buffering. + This is a typical scenario in the middle of a stream: + +   audio frame @ time 10 +   video frame @ time 8 +   audio frame @ time 11 +   video frame @ time 9 +   audio frame @ time 12 +    keyframe @ time 10 +   audio frame @ time 13 + If the demuxer seeks to the keyframe @ time 10, the next audio chunk will + have a timestamp of 13, which is well ahead of where the video is. While + the xine engine will eventually recover, it will make playback choppy for + a few seconds after the seek. One strategy for dealing with this situation + is to seek back to the nearest keyframe before the requested seek and then + seek back to find the audio frame with the nearest timestamp before the + keyframe. In this example, that would mean seeking back to [af@time 10]. + Then, demux the chunks in order, but skip the video frames until the next + keyframe is encountered. + + + + Writing a xine demuxer + + A demuxer plugin provides API functions which allow the engine to + initialize demuxing, dispatch data chunks to the engine, seek within the + stream, get the stream length, among other functions. The demuxer API + is declared in demuxers/demux.h. + + + Writing a new xine demuxer is largely a process of using other demuxers as + references and understanding how they interact with the engine. This + section will give a brief overview of each API function. + + + A demuxer plugin exports a public function of the form: +    void *demux_wc3movie_init_plugin(xine_t *xine, void *data); + This function initializes a demuxer plugin class object with 6 + demuxer-specific functions. These functions mainly provide information + that a frontend can use to build user-friendly features. These functions + include: + + +    char *get_description(demux_class_t *this_gen); + This function returns a plaintext, one-line string describing the plugin. + + +    char *get_identifier(demux_class_t *this_gen); + This function returns a shorter identifier describing the plugin. + + +    char *get_extensions(demux_class_t *this_gen); + This function returns a string with the file extensions that this demuxer + is known to use. For example, Microsoft .WAV files use "wav". If there are + multiple known extensions, separate each extension with a space. For + example, Apple Quicktime has the extensions "mov qt mp4". + + +    char *get_mimetypes(demux_class_t *this_gen) + This function returns a string with the MIME types that this demuxer is + known to use. Multiple MIME type specifications should be separated with a + semicolon (;). For example, Apple Quicktime uses several MIME types: + +   return "video/quicktime: mov,qt: Quicktime animation;" +    "video/x-quicktime: mov,qt: Quicktime animation;" +    "application/x-quicktimeplayer: qtl: Quicktime list;"; + + +    void class_dispose(demux_class_t *this_gen); + This function frees the memory used by the demuxer plugin class object. + + +    demux_plugin_t *open_plugin(demux_class_t *class_gen, xine_stream_t *stream, input_plugin_t *input_gen); + This function is invoked by the xine engine to determine if the demuxer is + able to handle a particular multimedia stream. The engine can specify if + the demuxer is supposed to check the stream by content (validate the actual + stream data and see if it is of the expected type), by extension (check the + name of the MRL and see if the file extension is correct), or explicitly + (the engine is passing on a user request to force this demuxer to be used). + + + The order in which the engine queries the available demuxers is determined + by the priority stated in the demuxer_info_t, which is attached to every + demuxer's plugin info structure. Demuxers with higher priority values are + called before those with lower priority. The order amongst demuxers of + equal priority is undefined. The idea behind this is to have the demuxers + for high-level container formats have high priorities, while the raw format + demuxers have low priorities. This way, a stream of a high-level container + format with a beginning that happens to look like a low-level raw format is + still handled by the correct demuxer, because it is queried first. + + + NOTE: In the course of checking the stream by content, care must be taken + not to consume bytes out of a non-seekable stream. If the stream is + non-seekable, use the input plugin's preview buffer facility to get a cache + of the first few bytes. If the stream is seekable, reset the stream before + operating on the data (you do not know where some other demuxer left the + stream positioned). + + + If the demuxer can handle the stream, it creates a new demux_plugin_t + structure and initializes the main demuxer functions which are called by + the engine to do the tough demuxing duty. These functions include: + + +    void demux_send_headers(demux_plugin_t *this_gen); + This function generally reads the headers of the stream, does whatever it + has to do to figure out what audio and video codecs are used in the file, + and asks the xine engine to initialize the correct decoders with the + proper parameters (like width and height for video, sample rate and + channels for audio). + + +    int demux_send_chunk(demux_plugin_t *this_gen); + This function reads data from the stream and sends it to the appropriate + decoder. This is where the bulk of the demuxing work is performed. Despite + the name, the function is actually free to send as much data as it wants + to, or as much as it can. A good policy is to send an entire chunk of + compressed audio or video data and then return. The chunk is likely large + enough that it will have to be broken up into multiple xine buffers. If + a chunk of audio is 20000 bytes large, and the engine is returning + 4096-byte buffers, send 4 full buffers and 1 partial buffer to the audio + decoder and then return. + + +    int demux_seek(demux_plugin_t *this_gen, off_t start_pos, int start_time, int playing); + This function is called by the engine to request stream repositioning. + This function should be implemented if possible. See the section on + "Seeking Policy" for more information. A seek operation should reposition + the demuxer's internal accounting variables to be ready to start + dispatching chunks from the new position when the xine engine calls + demux_send_chunk() again. If seeking is not feasible, the function quietly + returns and the demuxer's position is unaffected. + + +    void demux_dispose(demux_plugin_t *this_gen); + This function frees the demux_plugin_t object. + + +    int demux_get_status(demux_plugin_t *this_gen); + This function returns the current internal status of the demuxer. There + are 2 states: DEMUX_OK, for when the demuxer is demuxing or ready to demux, + and DEMUX_FINISHED, for when the demuxer has reached the end of the stream + or has encountered some sort of error. + + +    int demux_get_stream_length(demux_plugin_t *this_gen); + This function returns the length (time duration) of the stream in + milliseconds. If the length of the stream cannot be determined, return 0. + + +    uint32_t demux_get_capabilities(demux_plugin_t *this_gen); + This function returns an array of bit flags indicating special features of + the demuxer. See DEMUX_CAP_* defines. + + +    int demux_get_optional_data(demux_plugin_t *this_gen, void *data, int data_type); + This function allows the demuxer to advertise extra information that is + not available through other API functions. See DEMUX_OPTIONAL_* defines. + + + + Buffer types + + Demuxer must send data to decoders using two fifos names video_fifo + and audio_fifo. Both are available at stream + level. The following code fragment shows how it's done. + + +   buf_element_t *buf; +    +   buf = stream->video_fifo->buffer_pool_alloc(stream->video_fifo); +   buf->type = BUF_CONTROL_START; +   stream->video_fifo->put(stream->video_fifo, buf); + + Buffers must have set the type field as shown. All buffer types are + defined in xine-engine/buffer.h. + + + The control buffer types are very important and must be sent by all kinds 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 + byffer type: +    buf->type = fourcc_to_buf_video((void*)this->avi->bih.biCompression); + + + + + + Decoder layer + + This section is designed to familiarize a programmer with basic audio + and video decoding concepts and how they apply to the xine decoder API. + + + Audio and video decoders + + Audio and video data requires an enormous amount of storage. Thus, the + raw data is encoded using a variety of compression techniques which + drastically reduces the amount of space required to transmit and store the + data. Before playback, the compressed data needs to be decoded. + + + The process of decoding data is rather straightforward in a computer + science sense: An array of encoded data is fed into a decoder and the + decoder outputs an array of decoded data which is ready to be presented + to the user (either displayed on the screen or played through the + speakers). + + + + Video output formats + + Raw video data comes in a variety of formats, most commonly in RGB and + YUV. xine's output layer currently only accepts data in YV12 format (a.k.a. + YUV 4:2:0 planar) or YUY2 format (a.k.a. YUV 4:2:2 packed). If the output + format is a RGB space, the data must be converted to an acceptable YUV + format before being dispatched to the video output unit. xine has a number + of support functions to facilitate converting RGB to YUV. + + + + Audio output formats + + Raw audio data equates to uncompressed PCM audio. xine's audio output + modules expect 8-bit PCM data to be unsigned and 16-bit PCM data to be + signed and in little endian format. When there is more than one channel, + the channel data is interleaved. For example, stereo data is interleaved + as left sample, right sample: LRLRLRLR. If there are 4 or 6 channels, the + same interleaving applies: 123456123456. + + + + Writing a xine decoder + + Writing a new xine decoder for an audio or video format entails + accumulating a buffer of encoded data, performing the necessary operations + for decoding and then passing it on the appropriate output module. The + best reference for understanding the decoder API is the various decoding + modules available. In particular, xine has example video and audio + decoders named src/libxinevdec/foovideo.c and + src/libxineadec/fooaudio.c, respectively. + + + This section will give a brief overview of each API function. + The decoder API is declared in src/xine-engine/video_decoder.h + and src/xine-engine/audio_decoder.h. + + + A decoder plugin must, like every plugin, export a public array of + plugin_info_t types. The array usually has 2 entries: The first contains + the plugin information regarding the decoder and the second entry is + a terminating NULL entry. However, there may be more entries. + Each entry contains 6 fields: + + + + plugin type: Either PLUGIN_VIDEO_DECODER or PLUGIN_AUDIO_DECODER. + + + + + API: The plugin API revision that this plugin adheres to. + + + + + name: A character string that identifies the plugin. + + + + + version: #define'd as XINE_VERSION_CODE. + + + + + supported types: A structure that defines the buffer types that this plugin can handle. + + + + + init function: The function that the xine engine calls in order to initialize this decoder plugin. + + + + The supported types field is a decoder_info_t structure. This struct + combines a list of buffer types that the plugin can handle, along with + a relative default priority. The priority allows xine to have multiple + plugins that can handle one data type and the plugin with the highest + priority takes precedence. The code defines the default priority, which + can be overriden by the user. + The list of buffer types is an array of uint32_t types from the list of + buffer types defined in src/xine-engine/buffer.h. + + +    void *init_plugin(xine_t *xine, void *data); + This function allocates a plugin class and initializes a set of functions + for the xine engine to invoke. These functions include: + + +    char *get_identifier(video_decoder_class_t *this); +    char *get_identifier(audio_decoder_class_t *this); + This function returns a brief character string identifying the plugin. + + +    char *get_description(video_decoder_class_t *this); +    char *get_description(audio_decoder_class_t *this); + This function returns a slightly longer description of the plugin. + + +    void dispose_class(video_decoder_class_t *this); +    void dispose_class(audio_decoder_class_t *this); + This function frees the resources allocated by the plugin class. + + +    video_decoder_t *open_plugin(video_decoder_class_t *class_gen, xine_stream_t *stream); +    audio_decoder_t *open_plugin(audio_decoder_class_t *class_gen, xine_stream_t *stream); + This function initializes the decoder plugin's private state. It also + initializes and returns either an audio_decoder_t or a video_decoder_t for + the engine. The decoder_t contains a number of functions that the plugin + invokes to handle data decoding. These functions include: + + +    void decode_data(video_decoder_t *this_gen, buf_element_t *buf); +    void decode_data(audio_decoder_t *this_gen, buf_element_t *buf); + This function performs the bulk of the decoding work. The xine engine + delivers buffers (xine_buffer_t data types) to this function and it is up + to this function to assemble the parts of the buffer, decode the data, and + send the decoded data to the proper output unit. The constraint is that + you must never call a port function of the output port when the port has + not been opened by you. (See the open() and + close() functions of xine_video_port_t + and xine_audio_port_t.) + + + A buffer has a decoder_flags field which can have + a number of flags set. The first buffer that a decoder receives ought + to have the BUF_FLAG_HEADER flag set. This indicates that the buffer + content contains the essential setup information for decoding + (width, height, etc. for video; sample rate, channels, etc. for audio). + + + If the BUF_FLAG_HEADER flag is not set, the content of the buffer should + be accumulated in a private buffer until a buffer with a + BUF_FLAG_FRAME_END flag is set. This indicates that the entire chunk has + been transmitted to the decoder and is ready to be decoded. Fetch either + an empty video frame or audio buffer from the appropriate output unit. Perform + the appropriate decoding operations and set the pts for the output buffer + (and the duration, a.k.a. video_step, for video). Dispatch the decoded + data to the output and reset the internal buffer accumulation accounting. + + +    void flush(video_decoder_t *this_gen); +    void flush(audio_decoder_t *this_gen); + This function is called when either the xine engine flushes the stream, e.g., + after a seek operation or when decoding runs too slow and frames arrive in + the output loops fast enough. Decoders should release everything they have + already decoded, drop the rest and wait for new input. + + +    void reset(video_decoder_t *this_gen); +    void reset(audio_decoder_t *this_gen); + This function is called when the xine engine resets the stream. + Decoders should get ready to receive data that has nothing to do + with the one it worked on up to now. + + +    void discontinuity(video_decoder_t *this_gen); +    void discontinuity(audio_decoder_t *this_gen); + This function is called when the xine engine encounters a pts + discontinuity. Decoders should forget all timestamping information + they might have accumulated from the stream to not confuse metronom. + + +    void dispose(video_decoder_t *this_gen); +    void dispose(audio_decoder_t *this_gen); + This function frees the resources used by the decoder plugin. + + + + SPU decoder + + A lot written above also applies for subpicture unit (SPU) decoders. The + SPU decoder API is declared in src/xine-engine/spu_decoder.h. + Details on the data, SPU decoders are expected to output, see the section on + overlays and OSD. + + + However, there are some differences to consider. At first, unlike audio and + video, subtitles do not form a continuous stream. The decoder will therefore + only be called once in a while. The metronom call for timestamping, + which for audio and video is done by the engine, has to be done manually for SPU: +    vpts = metronom->got_spu_packet(metronom, buf->pts); + + + Another difference is that while both audio and video decoders are automatically + blocked in their get_buffer()/get_frame() + methods when the output cannot take any more data, this does not work for SPU, + because it could take minutes before the next free slot becomes available and we must not + block the decoder thread for that long since it might be shared with a video decoder. + But when a SPU decoder does not share the thread and we let it run without any + blocking, it will overflow the available overlay slots very soon. Since SPU + decoders should not have to know, whether they share the thread or not, a helper + function _x_spu_decoder_sleep() is provided, which, when told + the timestamp of the next overlay, will wait long enough to not overflow the + overlay slots, but short enough to not hinder a video decoder in the same thread. + + + There are also two functions in the SPU decoder API, which have not been discussed above: + + +    int get_interact_info(spu_decoder_t *this_gen, void *data); + Since SPUs are sometimes (on DVDs for example) used for user interaction like menu + highlights, this function can be called to get data filled with + the current interaction information. The caller and the decoder have to agree on + what this is exactly. With DVDs, you can get a copy of the current NAV packet here. + + +    void set_button(spu_decoder_t *this_gen, int32_t button, int32_t mode); + Also for interaction, you can ask the decoder here to change the + current highlighting. + + + + + diff --git a/doc/hackersguide/stream.sgml b/doc/hackersguide/stream.sgml deleted file mode 100644 index d05bbba65..000000000 --- a/doc/hackersguide/stream.sgml +++ /dev/null @@ -1,656 +0,0 @@ - - xine's stream layer - - - Input layer - - 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 specialized medium - (e.g. DVD), etc. To allow you to access all 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 recognizes. - 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. - - - Writing a xine input plugin - - An input plugin provides API functions which allow the engine to - access the data source the plugin encapsulates. The input plugin API - is declared in input/input_plugin.h. - - - An input plugin exports a public function of the form: -    void *input_init_plugin(xine_t *xine, void *data); - This function initializes an input plugin class object with the - following functions: - - -    char *get_description(input_class_t *this_gen); - This function returns a plaintext, one-line string describing the plugin. - - -    char *get_identifier(input_class_t *this_gen); - This function returns a shorter identifier describing the plugin. - - -    xine_mrl_t **get_dir(input_class_t *this_gen, const char *filename, int *nFiles); - Retrieves a directory listing from the plugin. This function is optional. - - -    char **get_autoplay_list(input_class_t *this_gen, int *num_files); - Retrieves the autoplay playlist from the plugin. This function is optional. - - -    int eject_media(input_class_t *this_gen); - Ejects the medium. This function is optional. - - -    void dispose(input_class_t *this_gen); - This function frees the memory used by the input plugin class object. - - -    input_plugin_t *get_instance(input_class_t *class_gen, xine_stream_t *stream, const char *mrl); - The plugin should try, if it can handle the specified MRL and return an - instance of itself if so. If not, NULL should be returned. When a new MRL - is to be played, xine engine asks all the available input plugins one by - one if they can handle the MRL. - Note that input plugins are not guaranteed to be queried - in any particular order and the first input plugin to claim an MRL - gets control so try not to duplicate MRLs already found within xine. - - -    int open(input_plugin_t *this_gen); - You should do any device-specific initialisation within this function. - - -    uint32_t get_capabilities(input_plugin_t *this_gen); - Returns a bit mask describing the input device's capabilities. - You may logically OR the INPUT_CAP_* constants together to get - a suitable bit-mask (via the '|' operator). - - -    off_t read(input_plugin_t *this_gen, char *buf, off_t nlen); - Reads a specified number of bytes into a buffer and returns the number of bytes actually copied. - - -    buf_element_t *read_block(input_plugin_t *this_gen, fifo_buffer_t *fifo, off_t len); - Should the input plugin set the block-oriented hint and if the - demuxer supports it, this function will be called to read a block directly - into a xine buffer from the buffer pool. - - -    off_t seek(input_plugin_t *this_gen, off_t offset, int origin); - This function is called by xine when it is required that subsequent - reads come from another part of the stream. - - -    off_t get_current_pos(input_plugin_t *this_gen); - Returns the current position within a finite length stream. - - -    off_t get_length(input_plugin_t *this_gen); - Similarly this function returns the length of the stream. - - -    uint32_t get_blocksize(input_plugin_t *this_gen); - Returns the device's prefered block-size if applicable. - - -    char *get_mrl(input_plugin_t *this_gen); - Returns the current MRL. - - -    int get_optional_data(input_plugin_t *this_gen, void *data, int data_type); - This function allows the input to advertise extra information that is - not available through other API functions. See INPUT_OPTIONAL_* defines. - - -    void dispose(input_plugin_t *this_gen); - This function closes all resources and frees the input_plugin_t object. - - - - - - Demuxer layer - - This section is designed to familiarize a programmer with general demuxer - concepts and how they apply to the xine multimedia library. - - - Introduction to demuxer theory - - xine's demuxer layer is responsible for taking apart multimedia files or - streams so that the engine can decode them and present them to the user. - "Demuxer" is short for demultiplexor, which is the opposite of - multiplexing. This refers to the process of combining 2 or more things - into one. Multimedia streams usually, at a minimum, multiplex an audio - stream and a video stream together into one stream. Sometimes, there are - multiple audio streams (e.g., for multiple language tracks). Sometimes, - there is a subtitle data stream multiplexed into the multimedia stream. - - - There are many different multimedia formats in existence and there are - varying strategies for demuxing different types of multimedia files. - Formats in the MPEG family, for example, are designed to allow easy - playback from almost any place within the file. Many formats cannot deal - with this circumstance and at least need to be demuxed from the beginning - of the stream and played through to the end. Some formats, such as MPEG and - AVI, have marker information before every chunk in the stream. Other - formats, such as Apple Quicktime, are required to have a master index that - contains all information for taking apart a file. Many game-oriented - multimedia formats are designed strictly for playing from start to finish - without any regard to random seeking within the file. - - - - Input considerations - - A xine demuxer interacts with xine's input layer in order to receive - data. The underlying input plugin might be a file, a network stream, or - a block-oriented disc storage device like a DVD. A file input offers the - most flexibility in being able to read either blocks of data or individual - bytes, and being able to seek freely. Other input plugins may not allow the - demuxer to seek (such as stdin or certain network streams). Some input - plugins only allow the demuxer to read blocks of data and not individual - bytes (such as the CD-DA input plugin). The demuxer needs to check the - capabilities of the underlying input plugin before attempting to seek - around. - - - - Seeking Policy - - If possible, it is desirable that a demuxer can seek randomly through - the stream. This is easier for some file formats and essentially impossible - for other formats. xine's seeking API function allows a seek target to be - specified in terms of a ratio from 0 to 65535, or time in milliseconds from 0. - Time-based seeking is useful for specifying, e.g., a 1-minute jump forward - or backward in a stream. With the ratio-based seeking, the demuxer can - interpret the ratio value in the domain he sees most fit. This can also be - some sort of time or a simple file offset. - - - If a multimedia stream has video, there generally needs to be a way to - identify keyframes in the stream in order to facilitate seeking. Many - game-oriented formats fall over in this area as they carry no keyframe - information aside from the implicit assumption that the first frame is a - keyframe. - - - In a stream with video, a seek operation should always jump to a keyframe. - xine Policy: When the seek target is between 2 keyframes, jump to the - earlier keyframe. E.g., if there are keyframes at stream offsets 10000 and - 20000, and the user requests a seek to offset 18000, choose the keyframe - at offset 10000. - - - Note that there can be difficulties when the audio and video streams are - not tightly interleaved. In many formats, the audio frames are several - time units ahead of the video frames for the purpose of pre-buffering. - This is a typical scenario in the middle of a stream: - -   audio frame @ time 10 -   video frame @ time 8 -   audio frame @ time 11 -   video frame @ time 9 -   audio frame @ time 12 -    keyframe @ time 10 -   audio frame @ time 13 - If the demuxer seeks to the keyframe @ time 10, the next audio chunk will - have a timestamp of 13, which is well ahead of where the video is. While - the xine engine will eventually recover, it will make playback choppy for - a few seconds after the seek. One strategy for dealing with this situation - is to seek back to the nearest keyframe before the requested seek and then - seek back to find the audio frame with the nearest timestamp before the - keyframe. In this example, that would mean seeking back to [af@time 10]. - Then, demux the chunks in order, but skip the video frames until the next - keyframe is encountered. - - - - Writing a xine demuxer - - A demuxer plugin provides API functions which allow the engine to - initialize demuxing, dispatch data chunks to the engine, seek within the - stream, get the stream length, among other functions. The demuxer API - is declared in demuxers/demux.h. - - - Writing a new xine demuxer is largely a process of using other demuxers as - references and understanding how they interact with the engine. This - section will give a brief overview of each API function. - - - A demuxer plugin exports a public function of the form: -    void *demux_wc3movie_init_plugin(xine_t *xine, void *data); - This function initializes a demuxer plugin class object with 6 - demuxer-specific functions. These functions mainly provide information - that a frontend can use to build user-friendly features. These functions - include: - - -    char *get_description(demux_class_t *this_gen); - This function returns a plaintext, one-line string describing the plugin. - - -    char *get_identifier(demux_class_t *this_gen); - This function returns a shorter identifier describing the plugin. - - -    char *get_extensions(demux_class_t *this_gen); - This function returns a string with the file extensions that this demuxer - is known to use. For example, Microsoft .WAV files use "wav". If there are - multiple known extensions, separate each extension with a space. For - example, Apple Quicktime has the extensions "mov qt mp4". - - -    char *get_mimetypes(demux_class_t *this_gen) - This function returns a string with the MIME types that this demuxer is - known to use. Multiple MIME type specifications should be separated with a - semicolon (;). For example, Apple Quicktime uses several MIME types: - -   return "video/quicktime: mov,qt: Quicktime animation;" -    "video/x-quicktime: mov,qt: Quicktime animation;" -    "application/x-quicktimeplayer: qtl: Quicktime list;"; - - -    void class_dispose(demux_class_t *this_gen); - This function frees the memory used by the demuxer plugin class object. - - -    demux_plugin_t *open_plugin(demux_class_t *class_gen, xine_stream_t *stream, input_plugin_t *input_gen); - This function is invoked by the xine engine to determine if the demuxer is - able to handle a particular multimedia stream. The engine can specify if - the demuxer is supposed to check the stream by content (validate the actual - stream data and see if it is of the expected type), by extension (check the - name of the MRL and see if the file extension is correct), or explicitly - (the engine is passing on a user request to force this demuxer to be used). - - - The order in which the engine queries the available demuxers is determined - by the priority stated in the demuxer_info_t, which is attached to every - demuxer's plugin info structure. Demuxers with higher priority values are - called before those with lower priority. The order amongst demuxers of - equal priority is undefined. The idea behind this is to have the demuxers - for high-level container formats have high priorities, while the raw format - demuxers have low priorities. This way, a stream of a high-level container - format with a beginning that happens to look like a low-level raw format is - still handled by the correct demuxer, because it is queried first. - - - NOTE: In the course of checking the stream by content, care must be taken - not to consume bytes out of a non-seekable stream. If the stream is - non-seekable, use the input plugin's preview buffer facility to get a cache - of the first few bytes. If the stream is seekable, reset the stream before - operating on the data (you do not know where some other demuxer left the - stream positioned). - - - If the demuxer can handle the stream, it creates a new demux_plugin_t - structure and initializes the main demuxer functions which are called by - the engine to do the tough demuxing duty. These functions include: - - -    void demux_send_headers(demux_plugin_t *this_gen); - This function generally reads the headers of the stream, does whatever it - has to do to figure out what audio and video codecs are used in the file, - and asks the xine engine to initialize the correct decoders with the - proper parameters (like width and height for video, sample rate and - channels for audio). - - -    int demux_send_chunk(demux_plugin_t *this_gen); - This function reads data from the stream and sends it to the appropriate - decoder. This is where the bulk of the demuxing work is performed. Despite - the name, the function is actually free to send as much data as it wants - to, or as much as it can. A good policy is to send an entire chunk of - compressed audio or video data and then return. The chunk is likely large - enough that it will have to be broken up into multiple xine buffers. If - a chunk of audio is 20000 bytes large, and the engine is returning - 4096-byte buffers, send 4 full buffers and 1 partial buffer to the audio - decoder and then return. - - -    int demux_seek(demux_plugin_t *this_gen, off_t start_pos, int start_time, int playing); - This function is called by the engine to request stream repositioning. - This function should be implemented if possible. See the section on - "Seeking Policy" for more information. A seek operation should reposition - the demuxer's internal accounting variables to be ready to start - dispatching chunks from the new position when the xine engine calls - demux_send_chunk() again. If seeking is not feasible, the function quietly - returns and the demuxer's position is unaffected. - - -    void demux_dispose(demux_plugin_t *this_gen); - This function frees the demux_plugin_t object. - - -    int demux_get_status(demux_plugin_t *this_gen); - This function returns the current internal status of the demuxer. There - are 2 states: DEMUX_OK, for when the demuxer is demuxing or ready to demux, - and DEMUX_FINISHED, for when the demuxer has reached the end of the stream - or has encountered some sort of error. - - -    int demux_get_stream_length(demux_plugin_t *this_gen); - This function returns the length (time duration) of the stream in - milliseconds. If the length of the stream cannot be determined, return 0. - - -    uint32_t demux_get_capabilities(demux_plugin_t *this_gen); - This function returns an array of bit flags indicating special features of - the demuxer. See DEMUX_CAP_* defines. - - -    int demux_get_optional_data(demux_plugin_t *this_gen, void *data, int data_type); - This function allows the demuxer to advertise extra information that is - not available through other API functions. See DEMUX_OPTIONAL_* defines. - - - - Buffer types - - Demuxer must send data to decoders using two fifos names video_fifo - and audio_fifo. Both are available at stream - level. The following code fragment shows how it's done. - - -   buf_element_t *buf; -    -   buf = stream->video_fifo->buffer_pool_alloc(stream->video_fifo); -   buf->type = BUF_CONTROL_START; -   stream->video_fifo->put(stream->video_fifo, buf); - - Buffers must have set the type field as shown. All buffer types are - defined in xine-engine/buffer.h. - - - The control buffer types are very important and must be sent by all kinds 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 - byffer type: -    buf->type = fourcc_to_buf_video((void*)this->avi->bih.biCompression); - - - - - - Decoder layer - - This section is designed to familiarize a programmer with basic audio - and video decoding concepts and how they apply to the xine decoder API. - - - Audio and video decoders - - Audio and video data requires an enormous amount of storage. Thus, the - raw data is encoded using a variety of compression techniques which - drastically reduces the amount of space required to transmit and store the - data. Before playback, the compressed data needs to be decoded. - - - The process of decoding data is rather straightforward in a computer - science sense: An array of encoded data is fed into a decoder and the - decoder outputs an array of decoded data which is ready to be presented - to the user (either displayed on the screen or played through the - speakers). - - - - Video output formats - - Raw video data comes in a variety of formats, most commonly in RGB and - YUV. xine's output layer currently only accepts data in YV12 format (a.k.a. - YUV 4:2:0 planar) or YUY2 format (a.k.a. YUV 4:2:2 packed). If the output - format is a RGB space, the data must be converted to an acceptable YUV - format before being dispatched to the video output unit. xine has a number - of support functions to facilitate converting RGB to YUV. - - - - Audio output formats - - Raw audio data equates to uncompressed PCM audio. xine's audio output - modules expect 8-bit PCM data to be unsigned and 16-bit PCM data to be - signed and in little endian format. When there is more than one channel, - the channel data is interleaved. For example, stereo data is interleaved - as left sample, right sample: LRLRLRLR. If there are 4 or 6 channels, the - same interleaving applies: 123456123456. - - - - Writing a xine decoder - - Writing a new xine decoder for an audio or video format entails - accumulating a buffer of encoded data, performing the necessary operations - for decoding and then passing it on the appropriate output module. The - best reference for understanding the decoder API is the various decoding - modules available. In particular, xine has example video and audio - decoders named src/libxinevdec/foovideo.c and - src/libxineadec/fooaudio.c, respectively. - - - This section will give a brief overview of each API function. - The decoder API is declared in src/xine-engine/video_decoder.h - and src/xine-engine/audio_decoder.h. - - - A decoder plugin must, like every plugin, export a public array of - plugin_info_t types. The array usually has 2 entries: The first contains - the plugin information regarding the decoder and the second entry is - a terminating NULL entry. However, there may be more entries. - Each entry contains 6 fields: - - - - plugin type: Either PLUGIN_VIDEO_DECODER or PLUGIN_AUDIO_DECODER. - - - - - API: The plugin API revision that this plugin adheres to. - - - - - name: A character string that identifies the plugin. - - - - - version: #define'd as XINE_VERSION_CODE. - - - - - supported types: A structure that defines the buffer types that this plugin can handle. - - - - - init function: The function that the xine engine calls in order to initialize this decoder plugin. - - - - The supported types field is a decoder_info_t structure. This struct - combines a list of buffer types that the plugin can handle, along with - a relative default priority. The priority allows xine to have multiple - plugins that can handle one data type and the plugin with the highest - priority takes precedence. The code defines the default priority, which - can be overriden by the user. - The list of buffer types is an array of uint32_t types from the list of - buffer types defined in src/xine-engine/buffer.h. - - -    void *init_plugin(xine_t *xine, void *data); - This function allocates a plugin class and initializes a set of functions - for the xine engine to invoke. These functions include: - - -    char *get_identifier(video_decoder_class_t *this); -    char *get_identifier(audio_decoder_class_t *this); - This function returns a brief character string identifying the plugin. - - -    char *get_description(video_decoder_class_t *this); -    char *get_description(audio_decoder_class_t *this); - This function returns a slightly longer description of the plugin. - - -    void dispose_class(video_decoder_class_t *this); -    void dispose_class(audio_decoder_class_t *this); - This function frees the resources allocated by the plugin class. - - -    video_decoder_t *open_plugin(video_decoder_class_t *class_gen, xine_stream_t *stream); -    audio_decoder_t *open_plugin(audio_decoder_class_t *class_gen, xine_stream_t *stream); - This function initializes the decoder plugin's private state. It also - initializes and returns either an audio_decoder_t or a video_decoder_t for - the engine. The decoder_t contains a number of functions that the plugin - invokes to handle data decoding. These functions include: - - -    void decode_data(video_decoder_t *this_gen, buf_element_t *buf); -    void decode_data(audio_decoder_t *this_gen, buf_element_t *buf); - This function performs the bulk of the decoding work. The xine engine - delivers buffers (xine_buffer_t data types) to this function and it is up - to this function to assemble the parts of the buffer, decode the data, and - send the decoded data to the proper output unit. The constraint is that - you must never call a port function of the output port when the port has - not been opened by you. (See the open() and - close() functions of xine_video_port_t - and xine_audio_port_t.) - - - A buffer has a decoder_flags field which can have - a number of flags set. The first buffer that a decoder receives ought - to have the BUF_FLAG_HEADER flag set. This indicates that the buffer - content contains the essential setup information for decoding - (width, height, etc. for video; sample rate, channels, etc. for audio). - - - If the BUF_FLAG_HEADER flag is not set, the content of the buffer should - be accumulated in a private buffer until a buffer with a - BUF_FLAG_FRAME_END flag is set. This indicates that the entire chunk has - been transmitted to the decoder and is ready to be decoded. Fetch either - an empty video frame or audio buffer from the appropriate output unit. Perform - the appropriate decoding operations and set the pts for the output buffer - (and the duration, a.k.a. video_step, for video). Dispatch the decoded - data to the output and reset the internal buffer accumulation accounting. - - -    void flush(video_decoder_t *this_gen); -    void flush(audio_decoder_t *this_gen); - This function is called when either the xine engine flushes the stream, e.g., - after a seek operation or when decoding runs too slow and frames arrive in - the output loops fast enough. Decoders should release everything they have - already decoded, drop the rest and wait for new input. - - -    void reset(video_decoder_t *this_gen); -    void reset(audio_decoder_t *this_gen); - This function is called when the xine engine resets the stream. - Decoders should get ready to receive data that has nothing to do - with the one it worked on up to now. - - -    void discontinuity(video_decoder_t *this_gen); -    void discontinuity(audio_decoder_t *this_gen); - This function is called when the xine engine encounters a pts - discontinuity. Decoders should forget all timestamping information - they might have accumulated from the stream to not confuse metronom. - - -    void dispose(video_decoder_t *this_gen); -    void dispose(audio_decoder_t *this_gen); - This function frees the resources used by the decoder plugin. - - - - SPU decoder - - A lot written above also applies for subpicture unit (SPU) decoders. The - SPU decoder API is declared in src/xine-engine/spu_decoder.h. - Details on the data, SPU decoders are expected to output, see the section on - overlays and OSD. - - - However, there are some differences to consider. At first, unlike audio and - video, subtitles do not form a continuous stream. The decoder will therefore - only be called once in a while. The metronom call for timestamping, - which for audio and video is done by the engine, has to be done manually for SPU: -    vpts = metronom->got_spu_packet(metronom, buf->pts); - - - Another difference is that while both audio and video decoders are automatically - blocked in their get_buffer()/get_frame() - methods when the output cannot take any more data, this does not work for SPU, - because it could take minutes before the next free slot becomes available and we must not - block the decoder thread for that long since it might be shared with a video decoder. - But when a SPU decoder does not share the thread and we let it run without any - blocking, it will overflow the available overlay slots very soon. Since SPU - decoders should not have to know, whether they share the thread or not, a helper - function _x_spu_decoder_sleep() is provided, which, when told - the timestamp of the next overlay, will wait long enough to not overflow the - overlay slots, but short enough to not hinder a video decoder in the same thread. - - - There are also two functions in the SPU decoder API, which have not been discussed above: - - -    int get_interact_info(spu_decoder_t *this_gen, void *data); - Since SPUs are sometimes (on DVDs for example) used for user interaction like menu - highlights, this function can be called to get data filled with - the current interaction information. The caller and the decoder have to agree on - what this is exactly. With DVDs, you can get a copy of the current NAV packet here. - - -    void set_button(spu_decoder_t *this_gen, int32_t button, int32_t mode); - Also for interaction, you can ask the decoder here to change the - current highlighting. - - - - - -- cgit v1.2.3 From e7e047b720d82991637f229ee14cbbc8a8c0496a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 19:33:51 +0200 Subject: Update the doctype and rename entities. --- doc/hackersguide/hackersguide.docbook | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/hackersguide/hackersguide.docbook b/doc/hackersguide/hackersguide.docbook index ebc42d4c7..353430991 100644 --- a/doc/hackersguide/hackersguide.docbook +++ b/doc/hackersguide/hackersguide.docbook @@ -1,10 +1,11 @@ - - - - - - + + + + + + + ]> -- cgit v1.2.3 From 80751a1ece262617bd07a70b23c63dfb79867ec9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 19:34:45 +0200 Subject: Use UTF-8 encoding. --- doc/hackersguide/hackersguide.docbook | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/hackersguide/hackersguide.docbook b/doc/hackersguide/hackersguide.docbook index 353430991..f743260d0 100644 --- a/doc/hackersguide/hackersguide.docbook +++ b/doc/hackersguide/hackersguide.docbook @@ -14,13 +14,13 @@ The xine hacker's guide hackersguide - GünterBartsch - HeikoSchäfer + GünterBartsch + HeikoSchäfer RichardWareham MiguelFreitas JamesCourtier-Dutton SiggiLangauf - MarcoZühlke + MarcoZühlke MikeMelanson MichaelRoitzsch -- cgit v1.2.3 From 6c444a564e57da5da66018835222e365f24a0114 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 19:35:23 +0200 Subject: Update copyright year and add my name to authors. --- doc/hackersguide/hackersguide.docbook | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/hackersguide/hackersguide.docbook b/doc/hackersguide/hackersguide.docbook index f743260d0..203e8e782 100644 --- a/doc/hackersguide/hackersguide.docbook +++ b/doc/hackersguide/hackersguide.docbook @@ -23,9 +23,10 @@ MarcoZühlke MikeMelanson MichaelRoitzsch + DiegoPettenò - 2001-2003 + 2001-2007 the xine project team -- cgit v1.2.3 From a1cebdf816465524b3bd9933f13c809a6f212700 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 19:37:33 +0200 Subject: Rename the .sgml to .docbook. --- doc/hackersguide/Makefile.am | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/hackersguide/Makefile.am b/doc/hackersguide/Makefile.am index 35d96ca9a..b147501e9 100644 --- a/doc/hackersguide/Makefile.am +++ b/doc/hackersguide/Makefile.am @@ -1,12 +1,12 @@ include $(top_srcdir)/misc/Makefile.common -hackersguide_sgml = hackersguide.sgml \ - intro.sgml \ - library.sgml \ - overview.sgml \ - internals.sgml \ - stream.sgml \ - output.sgml +hackersguide_docbook = hackersguide.docbook \ + intro.docbook \ + library.docbook \ + overview.docbook \ + internals.docbook \ + stream.docbook \ + output.docbook hackersguide_fig = architecture.fig \ library.fig \ overlays.fig \ @@ -15,7 +15,7 @@ hackersguide_fig = architecture.fig \ hackersguide_DATA = hackersguide.html \ architecture.png library.png overlays.png post_frame.png -EXTRA_DIST = README $(hackersguide_sgml) $(hackersguide_fig) \ +EXTRA_DIST = README $(hackersguide_docbook) $(hackersguide_fig) \ $(hackersguide_DATA) hackersguidedir = $(htmldir)/hackersguide -- cgit v1.2.3 From 3384501fddd058d34ea28d26b637566aaede63b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 19:39:52 +0200 Subject: Remove the copy of original sgml files. --- doc/hackersguide/Makefile.am | 8 -------- 1 file changed, 8 deletions(-) (limited to 'doc') diff --git a/doc/hackersguide/Makefile.am b/doc/hackersguide/Makefile.am index b147501e9..03a634038 100644 --- a/doc/hackersguide/Makefile.am +++ b/doc/hackersguide/Makefile.am @@ -24,16 +24,8 @@ docs: $(hackersguide_DATA) distclean-local: clean-docs -docs-prepare: $(addprefix $(srcdir)/, $(hackersguide_sgml)) - if test "$(srcdir)" != "." -a "$(srcdir)" != "`pwd`"; then \ - for file in $(hackersguide_sgml) ; do \ - test -f ./$$file -a ./$$file -nt $(srcdir)/$$file || cp $(srcdir)/$$file .; \ - done ; \ - fi - clean-docs: rm -f $(hackersguide_DATA) - test "x$(srcdir)" = x. || rm -f $(hackersguide_sgml) *.fig dist-hook: @if test x"$(distcheck_lax)" = x ; then \ -- cgit v1.2.3 From 89de608ef6e547a747e55da6a5a832e0da0afe9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 19:43:33 +0200 Subject: Don't create a distclean-local hook when you can just use DISTCLEANFILES variable. --- doc/hackersguide/Makefile.am | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/hackersguide/Makefile.am b/doc/hackersguide/Makefile.am index 03a634038..5dd6f5c25 100644 --- a/doc/hackersguide/Makefile.am +++ b/doc/hackersguide/Makefile.am @@ -20,12 +20,7 @@ EXTRA_DIST = README $(hackersguide_docbook) $(hackersguide_fig) \ hackersguidedir = $(htmldir)/hackersguide -docs: $(hackersguide_DATA) - -distclean-local: clean-docs - -clean-docs: - rm -f $(hackersguide_DATA) +DISTCLEANFILES = $(hackersguide_DATA) dist-hook: @if test x"$(distcheck_lax)" = x ; then \ -- cgit v1.2.3 From 79244eca1dde680dd469e732937f2a75895b5b3e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 19:51:49 +0200 Subject: Add missing line. --- doc/hackersguide/hackersguide.docbook | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/hackersguide/hackersguide.docbook b/doc/hackersguide/hackersguide.docbook index 203e8e782..c311f3fe2 100644 --- a/doc/hackersguide/hackersguide.docbook +++ b/doc/hackersguide/hackersguide.docbook @@ -1,5 +1,6 @@ -- cgit v1.2.3 From 77948a92b71a1eb0ecd806ead31cb25112ec7c90 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 19:54:25 +0200 Subject: Make the docbook valid XML. --- doc/hackersguide/internals.docbook | 12 ++++++------ doc/hackersguide/library.docbook | 4 ++-- doc/hackersguide/output.docbook | 4 ++-- 3 files changed, 10 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/hackersguide/internals.docbook b/doc/hackersguide/internals.docbook index 9bd1ec684..7018f3202 100644 --- a/doc/hackersguide/internals.docbook +++ b/doc/hackersguide/internals.docbook @@ -5,10 +5,10 @@ Engine architecture and data flow - + - + xine engine architecture @@ -398,7 +398,7 @@     *     * audio buf ---> metronom --> audio fifo --> (buf->vpts - hw_vpts)     * (vpts_offset + error) gap -    * <---------- control --------------| +    * <---------- control --------------|     *     * Unfortunately audio fifo adds a large delay to our closed loop.     * @@ -410,7 +410,7 @@     * - 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 +    * errors < 1% nominal rate. For bigger errors (bad streams) audio     * buffers may be dropped or gaps filled with silence.     */ @@ -468,10 +468,10 @@ - + - + overlays architecture diff --git a/doc/hackersguide/library.docbook b/doc/hackersguide/library.docbook index 1d987d259..de27f9e46 100644 --- a/doc/hackersguide/library.docbook +++ b/doc/hackersguide/library.docbook @@ -12,10 +12,10 @@ - + - + outside view on xine components diff --git a/doc/hackersguide/output.docbook b/doc/hackersguide/output.docbook index 806e89d0a..bd5ff200e 100644 --- a/doc/hackersguide/output.docbook +++ b/doc/hackersguide/output.docbook @@ -295,10 +295,10 @@ - + - + video frame passing through a post plugin -- cgit v1.2.3 From 95160592434ddc3b5e6537295bb8df1d36ee8979 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:01:29 +0200 Subject: Add a new rule to build hackersguide.html from the docbook version. --- doc/hackersguide/Makefile.am | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) (limited to 'doc') diff --git a/doc/hackersguide/Makefile.am b/doc/hackersguide/Makefile.am index 5dd6f5c25..cb95b8ad3 100644 --- a/doc/hackersguide/Makefile.am +++ b/doc/hackersguide/Makefile.am @@ -29,23 +29,8 @@ dist-hook: $(MAKE) docs ; \ fi -if HAVE_SGMLTOOLS -hackersguide.html: $(hackersguide_sgml) - @$(MAKE) docs-prepare - $(SGMLTOOLS) -b onehtml hackersguide.sgml; -else -hackersguide.html: $(hackersguide_sgml) - @$(MAKE) docs-prepare - if test x"$(fail_if_missing)" = x"yes"; then \ - echo "Please install sgmltools-lite."; \ - exit 1; \ - fi - if test x"$(fail_if_missing)" != x"yes"; then \ - touch $@; \ - sleep 1; \ - touch $(notdir $^); \ - fi -endif +hackersguide.html: $(hackersguide_docbook) + xmlto html-nochunks $(srcdir)/hackersguide.docbook if HAVE_FIG2DEV fig.png: -- cgit v1.2.3 From 88d3a205d0a9fcebfc82ced0c0e49e5d7384262f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:03:02 +0200 Subject: Assume presence of fig2dev command while doing make dist or make install from Hg. --- doc/hackersguide/Makefile.am | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) (limited to 'doc') diff --git a/doc/hackersguide/Makefile.am b/doc/hackersguide/Makefile.am index cb95b8ad3..d98a69250 100644 --- a/doc/hackersguide/Makefile.am +++ b/doc/hackersguide/Makefile.am @@ -32,20 +32,7 @@ dist-hook: hackersguide.html: $(hackersguide_docbook) xmlto html-nochunks $(srcdir)/hackersguide.docbook -if HAVE_FIG2DEV -fig.png: - $(FIG2DEV) -L png -S 4 $< $@; -else .fig.png: - if test x"$(fail_if_missing)" = x"yes"; then \ - echo "Please install fig2dev."; \ - exit 1; \ - fi - if test x"$(fail_if_missing)" != x"yes"; then \ - touch $@; \ - sleep 1; \ - touch $(notdir $^); \ - fi -endif + fig2dev -L png -S 4 $< $@; SUFFIXES = .png .fig -- cgit v1.2.3 From 1434e7472a7de962f205440d9d30bb2c88e19d11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:05:48 +0200 Subject: Update the doctype to DocBook XML. --- doc/faq/faq.sgml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/faq/faq.sgml b/doc/faq/faq.sgml index db1762f51..aee488701 100644 --- a/doc/faq/faq.sgml +++ b/doc/faq/faq.sgml @@ -1,4 +1,6 @@ - + + -- cgit v1.2.3 From 68e6d7031b438ab376d2a5f8298628d06d5a874a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:05:57 +0200 Subject: Update copyright year. --- doc/faq/faq.sgml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/faq/faq.sgml b/doc/faq/faq.sgml index aee488701..568ac533a 100644 --- a/doc/faq/faq.sgml +++ b/doc/faq/faq.sgml @@ -8,7 +8,7 @@ The xine engine FAQ xine FAQ - 2001-2003 + 2001-2007 the xine project team -- cgit v1.2.3 From e1f7855d284ddd922b930438863feebe29ded210 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:06:21 +0200 Subject: Remove the dist-hook. --- doc/hackersguide/Makefile.am | 7 ------- 1 file changed, 7 deletions(-) (limited to 'doc') diff --git a/doc/hackersguide/Makefile.am b/doc/hackersguide/Makefile.am index d98a69250..7cd4cf2cc 100644 --- a/doc/hackersguide/Makefile.am +++ b/doc/hackersguide/Makefile.am @@ -22,13 +22,6 @@ hackersguidedir = $(htmldir)/hackersguide DISTCLEANFILES = $(hackersguide_DATA) -dist-hook: - @if test x"$(distcheck_lax)" = x ; then \ - $(MAKE) fail_if_missing=yes docs ; \ - else \ - $(MAKE) docs ; \ - fi - hackersguide.html: $(hackersguide_docbook) xmlto html-nochunks $(srcdir)/hackersguide.docbook -- cgit v1.2.3 From 4ac3580f6a163548f494b406a860d91dd6ce06c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:06:44 +0200 Subject: Remove docs-prepare target. --- doc/faq/Makefile.am | 5 ----- 1 file changed, 5 deletions(-) (limited to 'doc') diff --git a/doc/faq/Makefile.am b/doc/faq/Makefile.am index 6090fd272..198358d95 100644 --- a/doc/faq/Makefile.am +++ b/doc/faq/Makefile.am @@ -9,11 +9,6 @@ docs: $(doc_DATA) $(html_DATA) distclean-local: clean-docs -docs-prepare: $(srcdir)/faq.sgml - if test "$(srcdir)" != "." -a "$(srcdir)" != "`pwd`"; then \ - test -f ./faq.sgml -a ./faq.sgml -nt $(srcdir)/faq.sgml || cp $^ . ; \ - fi - clean-docs: rm -f $(doc_DATA) $(html_DATA) test "x$(srcdir)" = x. || rm -f faq.sgml -- cgit v1.2.3 From 8645fb2f7a6daab8e1bd7de179bdf862de22bbb5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:07:46 +0200 Subject: Replace the distclean-local hook with a proper DISTCLEANFILES usage. --- doc/faq/Makefile.am | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/faq/Makefile.am b/doc/faq/Makefile.am index 198358d95..a43e6e97c 100644 --- a/doc/faq/Makefile.am +++ b/doc/faq/Makefile.am @@ -5,13 +5,9 @@ html_DATA = faq.html EXTRA_DIST = README faq.sgml $(doc_DATA) $(html_DATA) -docs: $(doc_DATA) $(html_DATA) - -distclean-local: clean-docs +DISTCLEANFILES = $(doc_DATA) $(html_DATA) -clean-docs: - rm -f $(doc_DATA) $(html_DATA) - test "x$(srcdir)" = x. || rm -f faq.sgml +docs: $(doc_DATA) $(html_DATA) dist-hook: @if test x"$(distcheck_lax)" = x ; then \ -- cgit v1.2.3 From f52ef371ea21fb7a050aa71bba9156784e1a7672 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:08:31 +0200 Subject: Rename the faq SGML file to DocBook. --HG-- rename : doc/faq/faq.sgml => doc/faq/faq.docbook --- doc/faq/faq.docbook | 2285 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/faq/faq.sgml | 2285 --------------------------------------------------- 2 files changed, 2285 insertions(+), 2285 deletions(-) create mode 100644 doc/faq/faq.docbook delete mode 100644 doc/faq/faq.sgml (limited to 'doc') diff --git a/doc/faq/faq.docbook b/doc/faq/faq.docbook new file mode 100644 index 000000000..568ac533a --- /dev/null +++ b/doc/faq/faq.docbook @@ -0,0 +1,2285 @@ + + + + + + + The xine engine FAQ + xine FAQ + + 2001-2007 + the xine project team + + + +
+ + General questions about xine and this document + + + What is the xine engine? + + The xine engine is a free media player engine. It comes in the form of + a shared libarary and is typically used by media player frontends + and other multimedia applications for playback of multimedia streams + such as movies, radio/tv network streams, DVDs, VCDs. + + + Since there are several frontends for the xine library available, + this document has a problem when it comes to examples. + The two most common frontends xine-ui and gxine are mixed in command + line examples throughout this FAQ. When you use a different + frontend, some of these will not work for you. The filename of + the config file also varies amongst frontends. If you get confused, + I recommend you try with one of xine-ui or gxine. + + + + + What's the aim and scope of this text? + + The primary goal of this FAQ is to cover all recurring questions related + to the xine engine. Frontend specific questions are usually not covered here. + + + + + My question is not yet covered here - where can I ask for help? + + First of all be sure that your question is really not covered here and + that you haven't just been a bit too lazy to read through all of this + text. ;-). Also check out the documentation specific to + the frontend (e.g. xine-ui or gxine or + totem). + + + That said - you are welcome to mail to our user mailing list: + xine-user@lists.sourceforge.net + Please provide some info about your setup so people have a chance to + help you, e.g. include information about your audio/video hardware + and drivers you use, operating system, cpu type and some console + output/any error messages. Also include command line parameters you + have specified and information about the type of stream you're + trying to play back. Also very important is the version of xine + you're using and information about any additional plugins you + may have installed on your system. + + + + + How do I pronounce "xine"? + + As long as people know what you are talking about, you are free to + pronounce it the way you like, but the official pronounciation is + [ksi:n], like the name "Maxine" with the "Ma" removed. + + + + + What are those xine-lib, xine-ui, gnome-xine, ... modules in cvs for? + + Some time ago xine just became too complex to be just one big program. + Therefore it was split into two major parts. + + + xine-lib is simply speaking the engine of xine. It contains all basic plugins + and is necessary to run anything that relies on xine. (This is the part that + is covered in this FAQ.) + + + Then there are frontends - applications that use xine. The most + common frontend is that of a media player. There are currently + two frontends being developed in the xine project, xine-ui (skinned + dvd-player style frontend directly based on xlib) and gxine, + a desktop media-player style frontend using the standard gtk widget set + and comes with a mozilla browser plugin. + External projects like kaffeine, sinek and totem develop additional frontends. + In the future you will likely see more and different types of applications + being developed which will use the xine engine for video processing + and other multimedia purposes. + + + If you simply want a media/dvd player, you'll need to install xine-lib + first and then choose and install a player frontend like xine-ui or gxine. + + + Other modules in CVS are: xine-plugin a mozilla browser plugin + for streaming media playback using xine, + xine_www the + xine project website sources. + + + + + Where and how do I get the latest development version? + + Be advised that end-users should stick to the official xine releases. + The CVS and Mercurial repositories are only intended for developers and for others who know why they use it. + + + Checking out xine modules from Mercurial + + The repositories are listed at http://hg.debian.org/hg/; + however, this is a list of all repositories which are kept there, not just the + xine project's (which are the ones which begin with xine-lib/). To check one out: +    hg clone http://hg.debian.org/hg/repository local_copy + e.g. +    hg clone http://hg.debian.org/hg/xine-lib/xine-lib xine-lib + + + Currently, only xine-lib and gxine are present here. + + + + Checking out xine modules from CVS + + To check out xine modules from CVS, first do this: +    cvs -d :pserver:anonymous@xine.cvs.sourceforge.net:/cvsroot/xine login + The password is empty, just press Enter. + + + Then, to check out individual modules (e.g. xine-lib or xine-ui): +    cvs -d :pserver:anonymous@xine.cvs.sourceforge.net:/cvsroot/xine co <modulename> + + + If you want xine-lib or gxine, you should use Mercurial instead. + The CVS repositories for these are not maintained. + + + + + + How do I submit patches? + + First, make sure that you're using a current development version + (see above) or at least the current release version. Then, once you're + ready to send the patch... + + + Generate your patch using either cvs diff -u > + my.patch or hg diff > my.patch (as + appropriate). Make sure that your message subject briefly describes the + patch; your message body should contain a longer description of the + patch. Your patch should be applicable using patch -p0 -i + my.patch or, preferably, patch -p1 -i + my.patch from the top-level directory in the source tree + (i.e. where configure.ac is) - this is fairly important for our + Mercurial-based repositories since it makes importing your patch that + much easier (hg import defaults to -p1). + + + Alternatively, if you've been hacking away at a module which is + maintained using mercurial, you can make them available as diffs - use + hg export or, if you have several patches, you could + use hg bundle instead (both require extra + parameters; hg help export and hg help + bundle for more details) - or via HTTP by using hg + serve. In the latter case, you'll need to post a URL from + which a developer can pull the changes. + + + Patches should normally be sent to the xine-devel mailing list, + xine-devel@lists.sourceforge.net. + + + + + Why is gxine's CVS module named "gnome-xine"? + + Historical reasons: gxine was originally named gnome-xine. + + + + + Where can I find pre-compiled binaries, e.g. RPMs? + + The xine project does not provide pre-compiled binaries for legal + reasons (some parts of xine may be covered by patents in some countries). + Some OS projects/vendors (e.g. debian, freebsd, ...) offer binaries + for their distributions - please contact them or use their package search + tools for further info. + You can also find links to third parties providing xine RPMs on + the xine homepage at + http://xinehq.de/index.php/releases. + + + See the next section of this FAQ for instructions on how to build xine + from source. + + + + + + + Building and installing xine from source + + + What do I need to compile everything properly? + + First of all an official and stable release of gcc. Also be aware + that patched gcc versions may break parts of xine and are therefore + not supported by the xine project. + + + Furthermore you'll have to use GNU make to compile xine. On most GNU/Linux + systems "make" is GNU make - on other platforms use "gmake" instead. + Also, zlib is required (including the appropriate header files, which are + often found in a package called zlib-devel or similar.) + + + If you want to compile xine from CVS, you'll need to have the autobuild tools + installed (automake, autoconf and libtool - in recent versions). + + + Frontends might need additional libraries, e.g. for gxine you'll need to have + GTK2 installed. Make sure you have not only the shared libraries themselves + but also the header files (often packaged seperately as so-called -dev packages) + on your system. + + + Some plugins that come with the xine engine need additional libraries (otherwise + they will not be built). For example, libogg and libvorbis (plus their include files) + are needed for ogg/vorbis support. Most notably, if you want to see any video + on your X11 desktop (and that's what you're here for, isn't it?), you need the + X developer packages as well. + + + Don't worry about this too much right now, xine's configure + (see below) will check for all the stuff needed and will tell you what's missing + (which means that you should check the output it produces carefully ;) ). + + + + + How do I compile xine? + + Simple build instructions for beginners + + Download the latest xine-lib and gxine/xine-ui tarballs, then follow + these instruction. To unpack a tarball, use: +    tar xfvz tarballname.tar.gz + + + The following instructions will install xine in /usr/local + where it will be visible for all users. You need root privileges to do this on most systems. + + + After unpacking xine-lib, issue: + +   ./configure +   make install + + + Make sure your /etc/ld.so.conf contains + /usr/local/lib and continue with: +    ldconfig + + + Now unpack your frontend (gxine or xine-ui or ...), then: + +   ./configure +   make install + + + + Complete build instructions + + The build process is the same for all of the xine modules. + + + You have to start with xine-lib. If built and installed successfully, you + can continue with the frontend(s). + + + If you have installed xine-lib to a non-standard prefix, make sure + that you have $prefix/bin in your PATH and that your linker finds + libs in $prefix/lib - otherwise trying to build modules that + rely on xine-lib will fail with configure complaining about not + finding certain parts of libxine. Using bash you can do something like: + +   export PATH="$prefix/bin:$PATH" +   export LD_LIBRARY_PATH="$prefix/lib:$LD_LIBRARY_PATH" + to make sure libxine can be found by the frontend(s). + + + Last but not least. Here the build instructions. As stated earlier, + those are the same for every xine module. + +   ./autogen.sh [-> *only* if you checked your sources out of CVS] +   ./configure +   make +   make install + + + + + + Making your own RPM packages (xine-lib, xine-ui, gxine) + + Basically you will only have to issue one command, if you have just + downloaded a source tarball from our web site: +    rpmbuild -ta <THE_NAME_OF_YOUR_SOURCE_TAR_BALL> + (Older versions of RPM use rpm instead of rpmbuild.) + + + This will start the binary and source RPM building. After compiling is + finished, a binary rpm is placed in your rpm binary directory which is + something like /usr/src/RPM/RPMS/<YOUR_ARCHITECTURE> + and a source RPM is written to your rpm source dir + (e.g. /usr/src/RPM/SRPMS). + + + In case that you have a fresh CVS checkout, you will need to do the + following first in order to get a tarball release out of it which you + can later use with the rpmbuild -ta command above: +    ./autogen.sh && make clean && make dist + + + In any case, please keep in mind that you have to build and install + xine-lib first before you can proceed with xine-ui. + + + + + Making your own .deb packages (xine-lib, xine-ui, gxine) + + You'll need a CVS or HG snapshot tarball or source checked out from the repository. + + + First, make sure that the "devscripts" package is installed. You'll + then need the following commands (the first one isn't needed unless you're using a snapshot tarball): + +   tar xzf <PACKAGE-VER.tar.gz> +   cd <PACKAGE-VER> +   ./autogen.sh noconfig +   debuild binary + + (If debuild complains about unmet dependencies, then + install them using aptitude install <PACKAGES> (as root) then re-run + debuild binary. + + + Once the build has been successfully completed, you'll have some new .debs. + +   cd .. +   ls *.deb +   su - -c 'cd '"`pwd`"' && dpkg -i <DEB_PACKAGES>' + + Ubuntu users will probably want to use this instead of that su: + +   sudo dpkg -i <DEB_PACKAGES> + + + + In any case, please keep in mind that you have to build and install + xine-lib first before you can proceed with xine-ui or gxine. + + + + + Can I provide additional CFLAGS for compilation? + + Yes, you can do so by setting the CFLAGS variable and then running + configure again. You can even pass them to + configure directly. Example: +    ./configure CFLAGS="-march=i686" + + + Other user variables configure respects are: + + + + CC to specify the compiler executable + + + + + CPP to specify the C preprocessor executable + + + + + LD to specify the linker executable + + + + + CPPFLAGS to pass additional include paths or other + preprocessor options + + + + + LDFLAGS to pass additional library paths or other + linker options + + + + + + An example combining some of these would look like: +    ./configure CC="/opt/intel/bin/icc" LD="/opt/intel/bin/xild" \ +   CPPFLAGS="-I/usr/local/include/dvdnav" LDFLAGS="-L/home/guenter/xine_libs" + + + + + Are there binaries for my AMD K7 (Athlon™) available? Can I build them? + + If you have a recent gcc you can try to compile "more" k7 support in (esp. + better instruction scheduling). If the configure script should fail to + detect your processor/gcc correctly, try passing the canonical system name for + your machine to configure with the --host option, e.g. +    ./configure --host=k7-pc-linux-gnu + + + + + Build problems: xine engine (xine-lib) + + The package doesn't compile at all! + + In order to be able to compile xine-lib, you need (amongst other things) + the zlib compression library plus the appropriate headers, which are + often found in a package called zlib-devel or similar. + + + Read again carefully the output ./configure + produced and/or compiler warnings and error reports, they often contain + helpful information to find out what's going on. If you're stuck here + and decide to post your problem on the xine-user mailing list, + make sure you include these outputs. + + + + The Xv video-out plugin fails to compile! + + If you want to have Xv support compiled in, make sure you either have + a shared Xv library on your system, e.g. + ls /usr/X11R6/lib/libXv* + should give you some .so libs, like this: + +   /usr/X11R6/lib/libXv.a +   /usr/X11R6/lib/libXv.so +   /usr/X11R6/lib/libXv.so.1 + + + Alternatively you need to have libtool 1.4 or newer installed, then + libXv.a is sufficient. Otherwise you can create the shared versions yourself: + +   ld --whole-archive -shared -o libXv.so.1 libXv.a +   ln -s libXv.so.1 libXv.so +   ldconfig + + + Now you should be ready to build the Xv video-out plugin on your system. + + + + + + Build problems in frontends (gxine/xine-ui/...) + + I have installed xine-lib but the frontend complains about not finding it! + + First of all take a closer look at the compilation instructions above again. + You will probably find your answer there right away. + + + As stated there (there again that hint *grin*), make sure that you + have $prefix/bin in your path and that your + linker is able to find libraries installed in $prefix/lib + By the way, $prefix is where you installed your xine-lib to earlier + (yes, installing xine-lib with make install or + installing the corresponding distribution-provided -dev or -devel + package would be a good idea before trying to compile the frontend ;) + ). + + + + + + Can I install xine in my home directory (without being root)? + + Sure. First set up a subdir where you install your private software, eg. +    mkdir ~/xine + + + Then you have to set a few environment variables - it's probably a good + idea to add this to your ~/.bashrc (or somewhere similar): + +   export PATH="$HOME/xine/bin:$PATH" +   export LD_LIBRARY_PATH="$HOME/xine/lib:$LD_LIBRARY_PATH" + + + Now you can unpack tarballs e.g. in ~/xine/src + (mkdir ~/xine/src if necessary) and do a + +   ./configure --prefix=$HOME/xine +   make install + + + You also need to tell frontends using xine-lib, where to find it: +    ./configure --prefix=$HOME/xine --with-xine-prefix=$HOME/xine + + + + + How to compile xine for Windows? + + For compiling xine under Windows with MinGW, CygWin or MS Visual C see README.WIN32. + + + For cross-compiling xine under comfortable unix-like environment with MinGW see README.MINGWCROSS. + + + + + + + Playback of various stream types + + + DVD Playback with xine + + How do I play back DVDs with xine? + + Newer xine (1.0.x) releases come with a full-featured + DVD plugin that should be able to handle any unencrypted, + non-locked DVD with full menu navigation support. No external + plugins are required anymore here. + + + To get DVD playback working, first make sure you have + a symlink /dev/dvd pointing to your + DVD device on your system. For example, if your DVD drive + is the master ide drive on the second IDE channel, + /dev/dvd should point to + /dev/hdc. Please note that if you + are using the ide-scsi emulation on your system, it is + likely that your DVD drive got mapped to a scsi device + node even though it is an ide drive. In that case first + check out you boot/kernel logs (or run cdrecord -scanbus) + to find out which device it got mapped to and set the + symlink accordingly (should be something like /dev/scd0, + /dev/scd1, ... in that case). + Also make sure you (as a user) have sufficient (read and write) permissions + on your DVD drive. This could mean you either have to change the device + permissions or add your user to a special group + (e.g. addgroup cdrom username), + depending on your setup and/or distribution. + + + It is highly recommended to switch DMA mode on for your DVD drive + (without it even very recent machines will have trouble producing + smooth video output). Use a command like + hdparm -d 1 <device> + on your DVD device. Please note that even if you're using ide-scsi + you will have to set the dma flag on the ide device node (e.g. + /dev/hdc), not the mapped /dev/scd + scsi device. + + + To be able to play back encrypted DVDs you need to have + libdvdcss installed on your system (please check if this is legal where + you live). If you do not understand what the term "encrypted DVD" means + here: As a rule of thumb, every DVD you have to pay money for is most + likely encrypted. + + + To make matters worse, apart from encryption, there is another obstacle + to take: the region code. The DVD authorities decided to divide the world + into eight geographical regions. Have a look at + http://www.dvdforum.gr.jp/RegionMap.pdf + if you want to know which number has been assigned to your country. It is + now their idea, that you shall only play DVDs, which have been produced + for your region. If you take a DVD off the shelf in your local store, + you should find a little globe-like icon which shows the region code the + disc is for. + + + Newer (post-2000) DVD drives (so-called RPC-2 drives) check the DVD + region, which means they'll prevent you from playing back DVDs that have + a different region code from what the drive is set up for. Some drives + come with a factory setting of region 0 so they can play back + any DVD until a region code is set. Others refuse to play any DVD at all + until they are told a region. The easiest way to handle this is to use + the regionset utility from + + http://sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415 + . + + + Once you have everything set up, try something like + gxine dvd:/ or xine -p dvd:/ + to start dvd playback. Some frontend also offer so-called autoplay + buttons or menu entries that start dvd playback immediately. + + + Important: do not try to mount the DVD. Just insert it and hit the DVD autoplay + button or start xine from the command line. + + + If things do not work as expected, try running the xine-check + shellscript that comes with xine to see if this gives you further hints on + what could be wrong. + + + + DVD playback works, but it takes a long time until playback starts + + This points to a region code problem. Some versions of libdvdcss can play + back DVDs from other regions than the RPC-2 DVD drive is set up for, + but this usually means a cryptographic attack (which takes time) has + to be used to access the DVD. + + + You can download a tool to set the region code of RPC-Drives here: + + http://sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415 + . + + + Warning: Please be aware that the number of region code changes in RPC-2 + drives is limited (usually about 5 times), after that your drive will + stay locked to the region you last set it up for. + + + + I have problems setting up my RPC-2 drive for the right region! + + You can download a tool to set the region code of RPC-Drives here: + + http://sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415 + . + + + Warning: Please be aware that the number of region code changes in RPC-2 + drives is limited (usually about 5 times), after that your drive will + stay locked to the region you last set it up for. + + + + + + Can I watch Video CDs (VCDs)? SVCDS ? CD-i? + + xine supports VCD and SVCD playback out-of-the box. Similar to DVDs, + make sure you have a /dev/cdrom alias pointing + to your CDROM drive which you will use to play back the (S)VCD. + + + At the moment, CD-i formats are not supported by xine. + + + Do not try to mount the (S)VCD. Simply insert it into your CDROM drive + and hit the VCD autoplay button or start something like + gxine vcd:/ or xine vcd:/ + from the command line. + + + VideoCD troubleshooting guide + + This gives higher-level troubleshooting. More lower-level information is + given in the next section. + + + + + When you open the configuration dialog of your frontend, you should + see a vcd config section. An important setting is + default_device. If this is set to the empty string, + the VCD plugin will try to scan your drives for a suitable device if the + driver has the capability to scan for drives. However you can set + the device to something of your choosing. On GNU/Linux, this may be + /dev/cdrom and on Solaris it may be + /vol/dev/aliases/cdrom0. + + + If you set this field, make sure these are correct for your + particular setup. For example, I generally play out of the DVD + device and this is called /dev/dvd rather than /dev/cdrom. + + + + + + Your frontend should offer a VCD autoscan button or menu item. + If you select this, you should see your CD disk light go on if you have one. + And the CD should be read. You should get a playlist of what's on the VideoCD. + + + If not something's wrong, possibly you configured the wrong drive. + You might try to read a disk image of a VideoCD and thus elimate any problems + with hardware. You can get a test VideoCD disk image to test here: + + http://www.vcdimager.org/pub/vcdimager/examples/test_svcd/test_svcd_pal.zip + . + After unzipping this there should be files test_svcd_pal.cue and + test_svcd_pal.bin. Run xine with the MRL + + vcd:/test_svcd_pal.cue:E0. + If you see something playing then this is a hardware problem. + You might also want to try starting playback-control with + + vcd:/test_svcd_pal.cue:P1. + + + + + + There should be at least one "track", and one "entry" listed for + the VideoCD and the names of these in the MRL list will end with + "T1" and "E0" respectively. Often there are other playlist items, + and if you have menus or still frames there will be + "segments" as well. The simplest things to check are probably + "entries" and "tracks". If there are no entries listed or none of + the tracks or entries play, then there may be a problem with + that particular medium. So as in the step above, you can try a known good + sample and perhaps burn a CD from that. More likely if you get this + far, some of the items listed work and some do not. There are a + number of debugging switches that you can dynamically turn on and + off that may be able to help in isolating more specific problems. + See the section below. + + + + + + Something plays now, but you do not get any menus? Well, first is there + supposed to be a menu? In the last step you should have seen what is on + the VideoCD. Still frames are always "segments" so see if you can find one in the MRL + list and select that. + + + If there are no segments listed, there aren't any still-frame + menus. It's also possible to have menus in looping MPEG's. Use the + vcddump tool to find loops. vcddump is + also part of VCDImager. Another program that can help you examine the contents + of a VideoCD is vcdxrip. + + + To troubleshoot, start out with the known SVCD example that has a + still-frame menu at the beginning: + + http://www.vcdimager.org/pub/vcdimager/examples/test_svcd/test_svcd_pal.zip + + Inside this is a largish file called test_svcd_pal.bin and another + short text file called test_svcd_ntsc.cue. These are CD disk + images; that is, something that could be burned to a CD drive such + as with cdrdao. However you don't have to create a CD to view these + with the xine VCD plugin. You should be able to play the VideoCD by running the MRL + + vcd:/test_svcd_pal.cue. + If you see a still frame on startup. Great! If instead you see what + looks like the beginning of a movie (Blue Streak with Martin Lawrence) + then go to the next step. + + + + + + You have a VideoCD with menu and can see it, but there is no menu on startup? + If you have the VideoCD from the last step, then run the MRL + + vcd:/test_svcd_pal.cue:P1 + If this shows a still frame, but it just does not show when you + hit either the "VCD" autoscan button or give a MRL without the P1 at + the end then go to the next step. + + + If you have another VideoCD, from the MRL list, you should also see "playlist" + entries. Try selecting the one that ends "P1". If you don't see an entry with P1, + then your VideoCD does not have playback control (PBC) and although there may + be a still frame on the VideoCD it may have been authored so it is not easily + accessed. Again vcddump or vcdxrip can help here. + + + + + + You have a VideoCD with menu at beginning and can see it using an MRL + with P1 at the end, but you want to see it by hitting the "VCD" autoscan button + as well? Check to see that you have the configuration entry + media.vcd.autoplay set to playlist. + + + + + + VideoCD debugging + + To facilitate tracking down problems we let you see what's going on dynamically. + Various debugging settings will cause output to appear on xine's plugin log + and/or on standard error output. See the config entry media.vcd.debug + for details. + + + The tool vcd-info from the cdio branch of vcdimager can be used to + show the entire contents of a VideoCD or selected portions of that. Until the cdio + branch of vcdimager is completely merged with vcdimager, the cd-info branch version + has a few more features. (However consult vcdimager for complete version of the program.) + + + vcdxrip can be used to extract portions of a VideoCD and or create an + XML description file of the VideoCD. This XML file and the extracted + files can be used by vcdxbuild to recreate another VideoCD. + + + And finally see also tools cd-info and cd-read from libcdio. + + + + + + Can I watch Quicktime (.mov, .mp4) files using xine? + + Quicktime is just a system layer (container format) which can contain various + different audio and video formats. The system layer itself is fully supported + in xine. However, some quicktime audio/video codecs are not natively supported yet. + Luckily, if you are using a x86 compatible machine (any recent PC hardware should do) + you can install and use the original Quicktime DLLs and watch most streams + (trailers) that can be downloaded from the net. + + + Possibly the most convenient way to get the Quicktime DLLs is to download + them from the MPlayer website + + http://www.mplayerhq.hu/design7/dload.html + . + The package is called "essential". Unpack it and move everything you find + inside to /usr/lib/codecs (actually you can place them + anywhere you want, e.g. someplace in your home directory, but then you'll + have to set decoder.external.win32_codecs_path in your + xine config file accordingly). Restart xine then and you should be + able to watch Quicktime trailers. + + + + + Real Network files/streams + + Can I watch Real (.rm, .ram) files using xine? + + The situation with real files and streams is pretty similar to the situation + with Quicktime Streams (see above). The newer real audio and video formats + are only supported by using binary-only codecs which are not included in + xine. + + + Possibly the most convenient way to get the Real codecs is to download + them from the MPlayer website + + http://www.mplayerhq.hu/design7/dload.html + . + The package is called "essential". Unpack it and move everything you + find inside to /usr/lib/codecs and set the + decoder.external.real_codecs_path in your xine config file + to /usr/lib/codecs (actually you can place them + anywhere you want, e.g. someplace in your home directory, but then you'll + have to set decoder.external.real_codecs_path accordingly). + Restart xine then and you should be able to watch Real files/streams. + + + + What about (live) network streams (pnm://, rtsp:// style urls)? + + xine supports both pnm and rtsp streaming. However, digging out the actual + pnm/rtsp url can be tricky as they're often packed into heavy JavaScript and + HTML code on most websites. You can either use a combination of your + browser's "save source" function and wget or use a xine browser plugin + (currently the gxine frontend comes with a simple mozilla plugin, + for example). When you decided to dig out the url by hand don't get fooled + by the many redirectors that are often placed around the actual url. + Use wget to download any http://-style urls and use less to look inside + the downloaded .ra/.ram files where you will find the actual pnm/rtsp + url which can be opened using xine. + + + + + + Can I watch Windows Media (.asf/.wmv/.wma) files using xine? + + While the container format (system layer) ASF (wmv is just an alias) + is fully supported in xine, for newer windows media 9 based streams + you'll need to install windows binary codecs (.DLLs). + + + Possibly the most convenient way to get the Windows DLLs is to download + them from the MPlayer website + + http://www.mplayerhq.hu/design7/dload.html + . + The package is called "essential". Unpack it and move everything you find + inside to /usr/lib/codecs (actually you can place them + anywhere you want, e.g. someplace in your home directory, but then you'll + have to set decoder.external.win32_codecs_path in your + xine config file accordingly). Restart xine then and you should be + able to watch windows media streams. + + + + + Can I watch Digital TV (Digital Video Broadcast) using xine? + + At the time of this writing DVB support is a very new and experimental + feature in xine. The number of supported cards is pretty limited at the moment. + See doc/README.dvb (in the xine-lib tarball) for details. + + + + + How do I play streams from STDIN? + + Use something like: +    cat stream.mpg | gxine stdin:/ + + + + + How can I watch files with external AVI subtitles? + + In xine 0.9.13 this used to be: +    xine foo.avi%bar.sub + + + Latest xine-lib modules (1-beta3 or newer) support external subtitles + for any media file, not only AVI. In order to use it you can pass a + special MRL construction like: +    xine test.mpg#subtitle:file.sub + The external subtitles support can also be used by any xine frontend. + Currently xine-ui and kaffeine implement this feature with a subtitle + selection dialog. + + + + + + + Running xine + + + I have a lot of dropped frames - what can I do? + + Your hardware might be too slow for xine. Make sure you turn on all + speed optimizing options. A few things you should check (in order of + importance): + + + + First of all, run the xine-check script included in xine + package (probably already installed in your system). + xine-check will report several of the most common problems + listed here. Sample output from xine-check: + +   xine-check +   Please be patient, this script may take a while to run... +   [ good ] you're using Linux, doing specific tests +   [ good ] looks like you have a /proc filesystem mounted. +   [ good ] You seem to have a reasonable kernel version (2.4.18) +   [ good ] intel compatible processor, checking MTRR support +   [ good ] you have MTRR support and there are some ranges set. +   [ good ] found the player at /usr/local/bin/xine +   [ good ] /usr/local/bin/xine is in your PATH +   [ good ] found /usr/local/bin/xine-config in your PATH +   [ good ] plugin directory /usr/local/lib/xine/plugins exists. +   [ good ] found input plugins +   [ good ] found demux plugins +   [ good ] found decoder plugins +   [ good ] found video_out plugins +   [ good ] found audio_out plugins +   [ good ] skin directory /usr/local/share/xine/skins exists. +   [ good ] found logo in /usr/local/share/xine/skins +   [ good ] I even found some skins. +   [ good ] /dev/cdrom points to /dev/hdc +   [ good ] /dev/dvd points to /dev/hdc +   [ good ] DMA is enabled for your DVD drive +   [ good ] found xvinfo: X-Video Extension version 2.2 +   [ good ] your Xv extension supports YUV overlays (improves MPEG performance) +   [ good ] your Xv extension supports packed YUV overlays +   [ good ] Xv ports: YUY2 YV12 I420 UYVY + + + + + Try to use the Xv driver, it greatly improves performance and quality + because your graphics card does image scaling and colourspace conversion. The + video section contains important information + about several Xv drivers. + + + If Xv cannot be used for some reason, make sure your display is set up + to 16bpp, not 24 or higher (reduces memory bandwith). Some Xv drivers + may also have better performance with 16bpp. + + + + + Make sure the hard drive (or cdrom/dvd drive) which supplies the + video data is in DMA mode (if supported). + + + On most linux-based systems, you can use hdparm to check this: + +   hdparm /dev/hda +   [...] +   using_dma = 1 (on) +   [...] + + + You can enable DMA mode with the following command: +    hdparm -d1 device_of_your_drive_that_supplies_video_data + In some cases where this fails it helps to specify the dma mode + to use, for example: +    hdparm -d1 -X 66 device_of_your_drive_that_supplies_video_data + In RedHat 8.0 an additional entry in /etc/modules.conf +    options ide-cd dma=1 + should help (reboot for this change to take effect). + + + More information about this may be found here: + + http://oreilly.linux.com/pub/a/linux/2000/06/29/hdparm.html + . + + + + + Use a recent kernel which is optimized for your hardware. Old kernels + may lack support for accelerated instructions like SSE, for example. + + + + + Close other applications (use a tool like "top" to find out + what applications are using up CPU power). Programs that update the + system clock like ntp should also be disabled. + + + + + Enable MTRR support in your kernel. If you are still using XFree 3.x, + you'll have to tell the kernel yourself where the graphics memory is. + You'll find details about that in the linux dvd howto. + + + If you're using X.org or XFree 4.x, enabling MTRR support in your kernel should + be enough (use a recent kernel!). + + + Try a cat /proc/mtrr - if the file exists and you find an entry + corresponding to the amount of graphics memory you have, everything + should be fine. + + + + + Have your X-server (usually X.org or XFree86) running with higher priority. + Most recent linux distributions (like RedHat 8.0 or Mandrake 9.0) should + do that for you, improving not only xine but desktop responsiveness + in general. + + + Use the "top" utility and verify under the "NI" column if + the X process has a negative value, this indicates a higher priority. + See "The X Window User HOWTO - Performance considerations" for + further instructions + + http://www.tldp.org/HOWTO/XWindow-User-HOWTO/performance.html + . + + + + + Use the latest or a known-good gcc version and build an optimized xine-lib for + your architecture. + + + + + Besides boosting X-server priority, sometimes it's possible to avoid + discarding frames by making xine itself higher priority. This is not + a recommended pratice since it will require to run xine as root, + but you may give it a try if you want: +    nice --5 xine + + + + + xine needs high speed memory access which depends on your chip set. + Make sure you enable all speed-improving options. + + + Especially the via apollo pro chipset is known to be quite weird, + (most of all on my gigabyte board). If you can't configure the ram + access thoroughly using the bios you might want to try some really + nasty tricks, as explained on (for example): + + http://www.overclockers.com/tips105/index03.asp + + + + This website centers around a windows-tool to tweak the chipset, you + can do the same on FreeBSD with pciconf. + On some linux distributions there are similar tools. + + + + + a nice performance tuning tool can be found here: + http://powertweak.sourceforge.net + + + + + Set up and use raw devices for DVD access. Please note that the + actual performance gain during playback is very small if any, but + since raw devices are bypassing the kernel's buffer cache, Linux + will not try to cache the DVDs you play. This would not be useful, + because xine does its own caching and you usually play DVDs + sequentially, which means you won't reuse anything from the cache. + But the problem would be that Linux throws everything out of the + cache that might be in there. + + + Raw devices should be available in linux kernel 2.4.x and there are + patches for older kernels available from: + + ftp://ftp.kernel.org/pub/linux/kernel/people/sct/raw-io/ + + + + To use raw devices, first connect a free raw device to your dvd + device, use something like: +    raw /dev/raw1 /dev/dvd + + + Then create a link named "rdvd" pointing to that raw device: +    ln -s raw1 /dev/rdvd + + + + + For slow / high-latency dvd drives it might help to increase + the number of video buffers xine allocates. Try setting + engine.buffers.video_num_buffers:500 + to a higher value (e.g. 1000 or 2500). + + + + + + + + Oki, xine doesn't drop frames now but video output still is not really smooth! + + Video output can be further improved by tuning your linux kernel: + + + + Set HZ to 1000 in + /usr/src/linux/include/asm-i386/param.h + + + + + Try applying scheduler patches, especially the O(1) and the preemptive + patches have proven useful at the time of this writing (spring 2003). + + + + Linux 2.5/2.6 will probably have these improvements out of the box. + + + Miguel Freitas has written a nice + + article about his kernel multimedia experiments + . + + + + + I have problems when using xine on FreeBSD, Solaris, ... ! + + Check out the the corresponding README files in the directory xine-lib/doc. + + + + + What is aalib? How do I use it in xine? + + aalib is an ascii art library. xine comes with an aalib video output + plugin so you can watch movies in your xterm, on the console or on your + old vt100 - very cool ;> ... another nice option is to preview movies + on a remote server in your shell over ssh. + + + To use it make sure you have aalib installed correctly before you + configure/build xine-lib and xine-ui. In addition to the xine binary a + binary named aaxine should get built and installed. You can then use + something like: +    aaxine foo.mpg + to use aalib video output. + + + + + Does xine support my dxr3 / hollywood+ card? + + While xine's focus is clearly on software decoding, the dxr3 is supported. + + + You can find more information about using xine with the dxr3 + here + (also covers how to do tv output using the dxr3). + + + + + + + Audio related questions + + + What audio drivers does xine support? OSS? Alsa? Arts? Esd? + + Currently xine support audio output via OSS (kernel audio drivers), + ALSA 0.9.x (ALSA 0.5.x is no longer supported), arts (KDE's sound daemon) + and esound (esd, gnome's sound daemon - not recommended because it has + serious issues with a/v sync). + + + + + When I'm watching a movie, the sound effects are much higher in volume than the voices! + + Congratulations, you seem to have an original movie audio track there. + + + Uhm. So you don't like it. Well, there are two things you can do: + + + + You can enable xine's audio compressor. Most frontends have + a settings window and in that you'll find a slider for the + compressor setting. The values are percent values, so a + slider setting of 200 means that xine will double the volume + of silent parts of the movie (loud parts stay the same). + + + If your frontend does not have such a compression slider, + you can pass the value with the MRL: +    xine dvd:/#compression:150 + + + + + If you have a dolby digital (AC3) soundtrack, you can try + to enable liba52's dynamic range compression setting + audio.a52.dynamic_range:1 + in your xine config file (or use some gui config dialog). + + + + + + + + When I play this stream, xine shows video but there's no audio! + + If this happens with any video, first try a different audio driver + (gxine -A oss, gxine -A arts, + xine -A alsa ...). + + + If this problem only occurs with one specific stream, maybe switching to + a different audio channel (using the gui) helps. Some DVD streams have + audio on strange channels. + + + If all this doesn't help, maybe you're missing an audio codec or you found + a bug. If you decide to post your problem on the xine-user mailing list, + make sure to include all console output xine produced and also clearly + state what type of stream you tried to play back or, even better, make + a test stream available somewhere for developers to download and try. + + + + + Can xine produce 4-/5-channel surround audio output? + + Yep, it can do that using OSS or ALSA drivers, provided that the driver + supports it. However, since xine cannot detect if there are actually speakers + connected to the additional channels, you'll have to activate that feature manually. + + + You can do this either in the config dialog while xine is running (press + the config button on the xine panel and go to the AUDIO tab) or have it + the complicated way by editing the config file yourself which is located + in your home directory in .config/gxine or + .xine: + +   audio.output.speaker_arrangement:Surround 4.0 +   audio.output.speaker_arrangement:Surround 4.1 +   audio.output.speaker_arrangement:Surround 5.1 + + + + + What about ac3 output via spdif to an external ac3 decoder? + + xine can do that too. Pretty much the same story as for 4-/5-channel + surround (see above). You can either use the config dialog or edit + the config file (~/.xine/config or + ~/.config/gxine/config) yourself: +    audio.output.speaker_arrangement:Pass Through + + + + + Getting SPDIF output from a SBLive 5.1 using OSS drivers + + The following explains how to get the above configuration + going with xine. Some parts of it may applicable to other + configurations (cards that use the EMU10k1 chip) as well. + + + Requirements + + + xine-lib >= 1.x.x + + + OSS driver + + + an external decoder + + + a cable to connect the SBLive to the external decoder + + + + The configuration described was tested using a Soundblaster live 5.1 (rev 7) + with a Yamaha DSP-AX620 external decoder. + + + + Retrieving the driver + + The OSS driver is maintained by creative and can be downloaded at + http://opensource.creative.com/. + The driver package contains documentation on how to install it. + Besides that I'd like to add the following notes. + + + In order to compile and install these drivers, you need a valid kernel + configuration file. For RedHat Linux's pre-compiled kernels these + configuration files can be found in + /usr/src/linux/configs. + After you've located the correct config file for your kernel, + you need to copy it to /usr/src/linux/.config + For example, when you run the 2.4.18-i686 kernel do : +    cp /usr/src/linux/configs/kernel-2.4.18-i686.config /usr/src/linux/.config + Make sure that the emu10k1 module that is currently installed is + not loaded. To unload the modules: +    /sbin/modprobe -rv emu10k1.o ac97_codec.o + If this mentions that the device is busy, some program is + using the driver. Some example could be a mixer application + or sound daemon like artsd. You'll need to close down the + applications before continuing. + At success it should print something like: + +   # delete emu10k1 +   # delete ac97_codec +   # delete soundcore + Run make in the directory where you unpacked the driver and follow the + instructions printed at the end of each step. + The last step should be: +    make install-tools + As the README of the driver package mentions the SPDIF AC3 + output doesn't work by default. In the directory + utils/scripts an emu10k1.conf + file can be found which need to be placed in the default + installation directory (/usr/local/etc). + After this the emu10k1.conf needs to be modified. + The following settings worked fine for me (I don't use the analog + outputs of the card): + +   CARD_IS_5_1=yes +   USE_DIGITAL_OUTPUT=yes +   ENABLE_TONE_CONTROL=yes +   AC3PASSTHROUGH=yes +   ENABLE_LIVEDRIVE_IR=no +   INVERT_REAR=no +   MULTICHANNEL=yes +   ROUTE_ALL_TO_SUB=no +   ANALOG_FRONT_BOOST=no +   SURROUND=no +   PROLOGIC=no +   ENABLE_CD_Spdif=yes +   ENABLE_OPTICAL_SPDIF=no +   ENABLE_LINE2_MIC2=no +   ENABLE_RCA_SPDIF=no +   ENABLE_RCA_AUX=no + After modifying the emu10k1.conf, + you need to modify your /etc/modules.conf and + make sure the following lines are in there. + +   alias sound-slot-0 emu10k1 +   post-install emu10k1 /usr/local/etc/emu-script + After saving the changes to modules.conf, run +    /sbin/depmod -a + Now, you're ready to load the new modules and set the correct + options for it. To load the modules run: +    /sbin/modprobe emu10k1 + + + + Setting up xine for SPDIF (AC3 passthrough) output + + You can either use the config dialog of your frontend or edit + the config file (~/.xine/config) yourself: +    audio.output.speaker_arrangement:Pass Through + In case the setting is not in the file you can add it. + + + + + The cable used for the SBLive can easily be self-made + or buy a stereo 3.5mm jack to dual RCA cable. + + + What you need to make the cable yourself: + + stereo 3.5mm jack plug + RCA plug + shielded cable (video coax 75 Ohm will do) + + Connect them as follows : + +   center pin jackplug ------|----- center pin RCA plug +    GND __|__ GND + + + In order to test it use a DVD with AC3 or DTS track + start xine and select the right audio track + from user interface or start xine as: +    xine dvd:/1 -a 0 + The external decoder should display something like + "Dolby Digital" in case the selected audio track contains + AC3 data or "DTS" in case the selected audio track + contains DTS data. Of course stereo audio also goes + through the SPDIF output, so the analog outputs of the + SBLive 5.1 are not needed anymore. + + + + + + Changing the volume with the GUI control has no effect! What's up!? + + Some xine drivers do not support volume changing although the GUI + will show the volume bar. Usually this is not xine's fault: aRts C + API, for example, doesn't offer any volume property to applications. + Similarly, with ac3 pass through it is not possible to set the volume. + + + Note that recently we added support to "simulate" volume in aRts by + changing sample values on-the-fly before delivering them to the driver. + Not as good as having access to sound card's mixer but at least users + will not complain about lacking of volume bar anymore! :) + + + + + Audio is stuttering and i see a lot of "metronom: fixing sound card drift by -2115 pts" on the console output + + Might be a soundcard problem, if it only comes in longer intervals. + Your soundcard does not keep it's sampling frequency accurately + enough, which results in audio and video + getting out of sync and xine has to compensate. If you see the message + only from time to time, you might remedy it by using the resampling sync + method. You can do this by setting the configuration entry + audio.synchronization.av_sync_method to resample. + + + If you receive the metronom message more often, + maybe switching to different drivers (alsa to oss or vise-versa) + can help here. It has also been reported that setting the configuration + entry audio.synchronization.force_rate to the native sampling + rate of your soundcard (try 44100 and 48000) helps sometimes. + + + Another, whole different possibility is that you have some background + process running which is messing with the clock (like some ntp client - + chronny, ntpd, ...). + + + Occasional messages of "fixing sound card drift" may happen on start and + when playing a long stream (like a movie). This is normal behaviour, + nothing to worry about. + + + + + xine seems to lose sound arbitrarily during playback, especially with DVDs + + You are using the OSS audio output plugin, right? In order to keep video and audio + in sync, xine regularly queries the audio driver for the amount of delay induced by + the current length of the driver's audio buffer. Unfortunately some OSS drivers seem + to be broken because the can return strange values here. This confuses the xine audio + subsystem and makes it drop audio. + + + You should try the various settings of the + configuration entry audio.oss_sync_method. The options + getodelay and getoptr ask the driver and + might therefore show the problem. But chances are that only one is broken and the other + works, so you should try them both first, since they are the most accurate. + The option probebuffer does not ask the driver directly but + tries to determine the buffer length from outside. This should work with any driver + and is the way to go, of the driver dependent methods fail. + softsync is the least accurate and should be used only in + emergency situations. + + + + + + + Video related questions + + + I can hear the audio - but I don't see a picture! + + Probably your hardware is simply too slow - see above for some + hints on how to speed things up. + + + Another possibility is that you using a buggy Xv driver, see the next + questions. + + + + + I only see a blue (or green or black) video image most of the time. + + You are either watching a very boring video (just kidding) or you are + suffering from a bug in the Xorg 6.7 implementation of X11. + + + The workaround is to add the line +    Option "XaaNoOffscreenPixmaps" + in the Device section of your X server configuration (usually + /etc/X11/xorg.conf or /etc/X11/XF86Config). + + + + + The image looks strange, it is shifted, cropped or shows weird lines! + + This points to a problem with the Xv extension, which is used by xine + to display the video image. To verify this, try running xine with the XShm + video output plugin: +    xine -V XShm + + + If that works fine, you just proved, that the Xv extension is buggy. xine will + remember the last used video output plugin, so the setting will stay at XShm. + You could simply continue using this, but XShm is a lot slower than Xv, so + read on and see if you can get it working. Usually you should look for + updated versions of the X driver module that belongs to your graphics card. + + + Other possibilites are limitations in either your X driver module or your + graphics hardware. If your card could somehow be running out of ressources (graphics + RAM perhaps) and displays an incorrect Xv overlay because of that, try reducing + the display resolution and/or colour depth. + + + Consult the next question for more details on Xv. + + + + + How can I make xine use the Xv extension and what drivers do I need? + + xine will normally use Xv by default if it is available. In some cases + you might need to choose Xv playback manually (when the ~/.xine/config + file for some reason says that you want to use XShm): +    xine -V Xv + + + If this doesn't work for you, it may be possible that Xv is not present + on your system. + + + First you need to install/use X.org or XFree 4.x. Once you got that you have to + make sure the X drivers you're using are supporting Xv on your + hardware. Here are some hints for individual gfx chips: + + + + 3Dfx: if all you get is a solid black window, upgrade to X.org or XFree 4.1.0 or later. + + + + + ATI: if you only get "half a picture", try lowering your resolution + or bit depth, disable DRI (looks like you ran out of video RAM) + + + + + Trident card: If you see vertical bands jumbled, upgrade to the latest + xfree/experimental trident drivers (for the CyberBlade XP + a driver exists here: + http://www.xfree86.org/~alanh/ ) + + + + + nVidia: With newer GeForce cards, Xv should work with XFree 4.2.0 or + newer, for older RivaTNT cards use the binary drivers from nvidia + (of course the binary drivers work as well for GeForce cards) + + + + + Mach64/Rage3D (not Rage128/Radeon) cards/chips get no XVideo with + standard drivers, try + GATOS drivers + instead + + + + + intel: i815 has Xv support in XFree 4.x, others unknown + + + + + Permedia 2/3 has Xv support in XFree 4.x + + + + + Savage: at least some older drivers tend to lock up the whole machine, + try the drivers available from + + http://www.probo.com/timr/savage40.html + . + + + + + SIS: certain controllers (more info needed!) have Xv support in XFree 4.x + + + + + Chips and Tech 6555x, 68554, 69000, 69030 have Xv support in XFree 4.x + + + + + NeoMagic: certain controllers (more info needed!) have Xv support in Xfree 4.x + + + + + SiliconMotion: certain controllers (more info needed!) have Xv support in Xfree 4.x + + + + + Matrox: G200 or newer (but not Parhelia) have Xv support in XFree 4.x. + For Parhelia, use the binary only drivers available from matrox' website. + + + + + + + + Some parts of my X Desktop get transparent when xine plays the video! + + Looks like some colours on your GUI match the colour key which Xv uses. You can + change the colour key value to avoid this. There should be a line like: +    video.XV_COLORKEY:2110 + in your ~/.xine/config file where you can change the colour that's used + by xine for the video overlay. + + + + + The aspect ratio of the video is wrong! + + Usually xine discovers the screen aspect ratio by + querying the X-server and then adjusts the video automatically + to make it look right. However, if that doesn't work try + pressing "a" to manually change the aspect ratio. + + + If you have a wide screen monitor, make sure the X-server + is correctly configured. The X-server must know the physical + size of the screen, which is independent of the resolution + being used. + + + For X.org, the screen size should be set in the "Monitor" + section in the file /etc/X11/xorg.conf, as in the example below: + +   Section "Monitor" +      Identifier "Monitor0" +      VendorName "Monitor Vendor" +      ModelName "DDC Probed Monitor - ViewSonic G773-2" +      DisplaySize 320 240 +      HorizSync 30.0 - 70.0 +      VertRefresh 50.0 - 180.0 +   EndSection + For XFree86, the filename is normally /etc/X11/XF86Config. + + + Where DisplaySize specifies, + in millimeters, the physical size of the monitor's picture area. + + + + + What is the difference between discarded and skipped frames? + + Sometimes xine will output a message like that: +    200 frames delivered, XX frames skipped, YY frames discarded + + + The difference between these counters is a little subtle for the non + developer. There are two threads running in order to display video: + the decoder thread will deliver frames to the video output thread. + The latter is responsible for scheduling the frames to be displayed at + the right time. + + + If your system can't keep up with decoding requirements, decoder will + deliver overdue frames. Imagine if it finished decoding the frame + tagged for displaying at 11:30 but xine clock marks 11:31. When this + situation is detected, xine will try to skip decoding a few frames + to recover. Not every decoder may support this feature. + + + When the frame is decoded to be shown somewhere in future but the + output thread doesn't get scheduled in time by the operating system + to complete the operation, the frame is discarded. One cause might + be the disk access operation, which may halt the system for a few + miliseconds without DMA. See performance section tips above. + + + Note that if a decoder can't skip frames for some reason, you would + never see frames skipped (they would be all discarded). + + + + + My xine is runing in black and white! / I only get a grey video output! + + This frequently happens with new Xv drivers or when switching to a + different video card. Background is that different Xv drivers often + use different ranges for the contrast/brightness/saturation settings. + + + To fix this, try opening the xine settings window and try adjusting + the sliders for contrast, brightness and saturation. + + + Please note that some frontends save these settings in their config file + so when you have found a working combination, make sure you exit + xine cleanly so the values are saved. + + + + + Which is the best video driver to use? + + xine supports several video drivers for outputing the image. These will + differ on how the frames are copied to the video card memory, whether + colourspace conversion and scaling is done in software or hardware, among + other things. They may also differ on ease of use and stability. + + + Most of the time, Xv should give the users a good trade-off between + quality, compatibility and ease of use. This is why xine tries to use + Xv by default. + + + However some users may want to explore better the available hardware + capabilities (eg. syncing frame drawing with monitor refresh). + Also some Xv drivers contain slow copies and accessing the video card + directly may yield performance gains. + + + Drivers that access hardware directly includes VIDIX (warning: requires + root priviledges or kernel helper) and SyncFB (requires kernel helper - Matrox only). + User may try one of those, but should be warned that with root access + they can cause the system to crash hard. The support is also limited to + a couple of graphics cards only. + + + Graphic workstations like SGI have usually a good support for OpenGL. + In that case, using OpenGL may be a better choice than XShm. However for + most desktop systems the performance of OpenGL will be quite bad. + + + + + + + OSD and overlay related questions + + + What is this "unscaled" OSD about? + + Since version 1-rc3 of xine-lib supports a new method for rendering OSD + (On Screen Display) and subtitles. This method uses a X11 extension + called XShape that allows using screen resolution instead of + stream resolution. It is called "unscaled" OSD because it does not + scales with the video being played. + + + Suppose you are watching a 320x200 video in full screen. Normal OSD + would be blended at 320x200 and then scaled to full screen (lets say, + 1024x768), resulting in big and ugly fonts. The unscaled overlay is + drawn directly to screen, creating a sharper and better looking OSD. + + + There are side effects too. Sometimes the unscaled overlay show some + glitch just before disappearing. Some people may be annoyed enough + by that and might want to disable the usage of unscaled overlay + altogether. + + + Unscaled OSD usage by subtitles and xine-ui is controlled by + the following settings (~/.xine/config or + ~/.config/gxine/config): +    gui.osd_use_unscaled:0 +    subtitles.separate.use_unscaled_osd:0 + + + + + I can't see the OSD or it leaves a black box over the image! + + If you are using xine-lib version 1-rc3 or newer, this is probably + due buggy XV drivers that do not support + unscaled OSD (the XShape + extension) properly. + + + There have being reports of some ATI drivers that don't allow + displaying anything over the video. The VIA Epia binary drivers + is reported to leave a black box where the OSD was displayed. + + + The problem may be fixed by either updating the video driver, + or disabling xine unscaled OSD support. + + + + + Why colours of overlays/subtitles seem to be "leaking"? + + xine blends most overlays, specially the ones from DVD discs, + directly over the image (scaled OSD). Unfortunately most codecs + (like MPEG2) use a subsampled image format (YV12) that makes + properly blending an interesting challenge. + + + In short, this is a known xine bug. There have being discussions + on improving the blending quality but, so far, nobody implemented + a better (scaled) overlay renderer. Contact developers if you want + to try doing something about it. + + + + + Why external subtitles look so ugly? + + You are probably using a xine-lib version older than 1-rc3. + Try upgrading your copy and read the + section about unscaled osd. + + + + + Why subtitles can't be displayed outside the video? + + It is possible, but older xine versions may not support it. There are two + alternatives for rendering the subtitles outside the video image: + + + + + + Use the "expand" post plugin to increase frame height adding + black bars to it. This will allow blending the subtitles + over the black bars, since they will be part of the video now. + + + + + Use unscaled OSD, as it + does not requires any video to render the subtitles on. + + + + + + Also notice that DVD overlays (including subtitles) are meant to + be displayed in a fixed position, this is how the DVD menu + highlighting works. xine does not support moving them. + + + + + What kinds of subtitle fonts does xine use? + + xine can use two kinds of fonts: + + + + TTF fonts + + + If xine is compiled with freetype library xine recognizes and uses TTF + fonts directly. + + + + + xine fonts + + + This is xine's native format. It's better because the font + generator utility implements more features than the "on the fly" TTF renderer. + + + + + + The font for text subtitles is selected via config option + subtitles.separate.font. You can specify xine font name + (sans, serif, ...) + or file name of the TTF font. The directories + $prefix/share/xine/libxine1/fonts and + ~/.xine/fonts are searched for the fonts, with + $prefix being the place xine-lib was installed to. + Usually this is /usr/local or /usr. + TTF fonts are also searched for in the current directory. + + + + + How to create own xine subtitle fonts? + + xine's native subtitle fonts can be generated from TTF fonts with the + utility xine-fontconv. It isn't compiled and installed by default but + you can make it manually. You'll need freetype and zlib packages together with + their versions for development plus a compiler, of course ;) + Here's how you build xine-fontconv: + + + + Get the source of xine-fontconv utility from the misc + directory within the xine-lib sources. + + + + + Compile it: +    gcc xine-fontconv.c -o xine-fontconv `freetype-config --cflags --libs` -lz + + + + You'll need some TTF font for generating. Characters in this font should + cover all codepages you want supported, otherwise you'll have missing characters. + + + Syntax is: +    ./xine-fontconf font.ttf font_name [encoding1 [encoding2 [...]]] + + + For example default font sans was generated with + following command: + +   ./xine-fontconv Aril_Bold.ttf sans iso-8859-1 iso-8859-2 iso-8859-5 \ +    iso-8859-9 iso-8859-15 cp1250 cp1251 + + + There are displayed messages about missing characters on the screen + during generating. It's OK if the missing characters are U+007f..U+009F. + These characters come from iso-8859-1 and they aren't displayable. + + + + + Encoding of external subtitles is bad. What is wrong? + + The encoding of the external subtitles is expected to be iso-8859-1 by + default. You need to set an appropriate encoding in the config option + subtitles.separate.src_encoding. Note that you also need + a font which contains all characters from the given encoding. + + + The default font sans and fonts + serif and mono cover these + encodings: + + iso-8859-1 + iso-8859-2 + iso-8859-5 + iso-8859-9 + iso-8859-15 + windows-1250 + windows-1251 + + + + + + + + Error Messages: What they mean and what you can do + + + Starting xine crashes X, I am logged out of my desktop! + + xine itself is unable to crash X, so when your X server just shuts down or + restarts with the login screen, there is something wrong with your X setup. + Most common are problems with the Xv extension. Try running xine with the XShm + video output plugin: +    xine -V XShm + + + If that works fine, you just proved, that the Xv extension is buggy. xine will + remember the last used video output plugin, so the setting will stay at XShm. + You could simply continue using this, but XShm is a lot slower than Xv, so + consult the section on Xv and see if you can + get it working. Usually you should look for updated versions of the X driver + module that belongs to your graphics card. + + + + + Starting xine fails with complains about audio drivers/devices! + + You can select the audio driver using the -A option. So try: +    xine -A null + If you have ALSA drivers installed, try: +    xine -A alsa + If you run ESD (not recommended), try: +    xine -A esd + If you run artsd, try: +    xine -A arts + + + + + "no video port found" + + You got the Xv extension, but your video card driver doesn't support it. + First try to find a driver that does support Xv on your hardware (check + your graphics card vendor). If your driver has Xv support but you can't + get it working, try at a lower resolution (1024x768 is enough even for + anamorphic DVDs). + + + If all that fails, you can still use plain X11/XShm: +    gxine -V XShm foo.vob + + + + + "Unable to open dvd drive (/dev/dvd)" + + You probably don't have /dev/dvd (check that). If so, simply create a + link /dev/dvd that points to your DVD device. Something like... +    ln -s hdc /dev/dvd + ...should do the job. Also make sure you have read and write access on + the device the symlink points to. + See the dvd playback section + for more information. + + + + + My drive doesn't work and the kernel says "status=0x51 { DriveReady SeekComplete Error }" + + This error can be fixed by recompiling your kernel with the option + "Use multi-mode by default" enabled in the IDE settings. + + + + + "demux error! 00 00 00 (should be 0x000001)" + + Probably xine can't access your input source. Most commonly this happens + when you're trying to play locked/encrypted DVDs. Remember that xine + can't play such DVDs out-of-the box for legal reasons (see above). + + + If it is legal where you live, you can try to install libdvdcss. Once + you have done that and re-start xine, it should automatically detect + and use it to play back encrypted DVDs. + + + Another reason could be that your (RPC-2) DVD drive isn't set up + for the right region (see above). + + + + + "audio driver 'oss' failed, using null driver instead" + + First of all, make sure that your OSS Audio drivers are working (i.e. + you can play music with other software). Maybe you're using alsa? + If so, try gxine -A alsa to see if this helps. + + + The most common reason for oss not working is that some other program is accesing + your audio device. If you're using linux, the command fuser /dev/dsp + should give you the PID of the process. + + + If you are using GNOME, chances are that this is caused by ESD. Now you + have two possibilities. Either deactivate ESD (temporarily) by right + clicking on the sound monitor applet and selecting "Place Esound in + standby" or just kill it. Then xine will use OSS audio output. The other + method is to make xine use ESD for audio output with: +    gxine -A esd + This may result in worse playback - exact syncronization is not possible + with esd, so using oss should be preferred. + + + If you are using KDE, there is the possibility that the aRts sound + daemon is currently running and thus blocking your sound device. You + can check that by starting the aRts control (in your KDE menu it should + be under Multimedia). If it is running, you can either use the aRts + audio output plugin: +    gxine -A arts + Or you suspend the aRts daemon by checking the appropriate option in + your aRts control. (recommended) + + + Newer versions of arts have an auto-suspend mode - this can lead to + some nondeterministic behaviour of xine if it is set up to use + the audio device directly. Using arts is recommended in that case; + however, you will lose the ability to do four/five channel audio output. + + + + + "video_out: throwing away image with pts xxx because it's too old" + + This is a performance related problem. + If you have a fast computer and this message is shown from time to + time when playing a DVD or CD, it's very likely that DMA is not enabled + for your drive. + + + + + "No video plugin available to decode 'xxxxxx'." + + You have tried to play a stream using a unknown or unhandled codec. + Possibly the file uses some obscure proprietary format and no + information is available on how to decode it. + + + If you're on an x86 platform (e.g. PC hardware) you might want to + try installing binary-only windows medial, real networks and + quicktime codecs (see above). + + + + + "w32codec: decoder failed to start. Is 'xxxxxx' installed?" + + You probably don't have the win32 dll needed to decode this file. + + + + + xine just crashed on me - i didn't get any error message + + OK, yes, that shouldn't happen and you're upset. We can understand that. + But, to help you and of course to fix this, we need some information. + So, let's go through the checklist and maybe prepare a nice bug report + for the xine-user mailing list: + + + + Did xine really crash (segfault) or did it hang (deadlock)? + + + + + Can you reproduce the bug? (e.g. do you remember what you + did and when you do it again it crashes again?) + + + + + Is that a specific media file or format which crashes xine? (Have you + tried other files types?) + + + + + Check the console output (and include it in a bug report), maybe earlier + there is some output that points to the problem. + + + + + Your X server just froze on you? unfortunately that's a known problem + with some chipsets and drivers (most commonly Savage chipsets) when + using Xv. You might want to try running gxine -V XShm + to see if the problem is related to the Xv driver. This will unfortunately + be much slower, as lots of things are now done in software instead of + hardware scaling/colour space conversion. + + + Maybe at the time you read this, there's an X upgrade which fixes + this for the Savage driver. If that works for you, please notify the xine crew at + xine-user@lists.sourceforge.net, so they can update this FAQ! + + + + + Even though we try to make each release as bug free as possible, xine is + still under heavy development (nice excuse, isn't it? *grin*). + + + If you write to the xine user mailing list + xine-user@lists.sourceforge.net + make sure you include a the above information (when applicable) + and also some information about your machine (operating system, cpu type and + speed, gfx card, sound card, ...) and please use a meaningfull subject + line ("xine bug" is bad, "xine fails to play this quicktime trailer in fullscreen mode" + ist much better). + + + Thanks for taking the time to help improve xine. + + + + + + + + +
+ + diff --git a/doc/faq/faq.sgml b/doc/faq/faq.sgml deleted file mode 100644 index 568ac533a..000000000 --- a/doc/faq/faq.sgml +++ /dev/null @@ -1,2285 +0,0 @@ - - - - - - - The xine engine FAQ - xine FAQ - - 2001-2007 - the xine project team - - - -
- - General questions about xine and this document - - - What is the xine engine? - - The xine engine is a free media player engine. It comes in the form of - a shared libarary and is typically used by media player frontends - and other multimedia applications for playback of multimedia streams - such as movies, radio/tv network streams, DVDs, VCDs. - - - Since there are several frontends for the xine library available, - this document has a problem when it comes to examples. - The two most common frontends xine-ui and gxine are mixed in command - line examples throughout this FAQ. When you use a different - frontend, some of these will not work for you. The filename of - the config file also varies amongst frontends. If you get confused, - I recommend you try with one of xine-ui or gxine. - - - - - What's the aim and scope of this text? - - The primary goal of this FAQ is to cover all recurring questions related - to the xine engine. Frontend specific questions are usually not covered here. - - - - - My question is not yet covered here - where can I ask for help? - - First of all be sure that your question is really not covered here and - that you haven't just been a bit too lazy to read through all of this - text. ;-). Also check out the documentation specific to - the frontend (e.g. xine-ui or gxine or - totem). - - - That said - you are welcome to mail to our user mailing list: - xine-user@lists.sourceforge.net - Please provide some info about your setup so people have a chance to - help you, e.g. include information about your audio/video hardware - and drivers you use, operating system, cpu type and some console - output/any error messages. Also include command line parameters you - have specified and information about the type of stream you're - trying to play back. Also very important is the version of xine - you're using and information about any additional plugins you - may have installed on your system. - - - - - How do I pronounce "xine"? - - As long as people know what you are talking about, you are free to - pronounce it the way you like, but the official pronounciation is - [ksi:n], like the name "Maxine" with the "Ma" removed. - - - - - What are those xine-lib, xine-ui, gnome-xine, ... modules in cvs for? - - Some time ago xine just became too complex to be just one big program. - Therefore it was split into two major parts. - - - xine-lib is simply speaking the engine of xine. It contains all basic plugins - and is necessary to run anything that relies on xine. (This is the part that - is covered in this FAQ.) - - - Then there are frontends - applications that use xine. The most - common frontend is that of a media player. There are currently - two frontends being developed in the xine project, xine-ui (skinned - dvd-player style frontend directly based on xlib) and gxine, - a desktop media-player style frontend using the standard gtk widget set - and comes with a mozilla browser plugin. - External projects like kaffeine, sinek and totem develop additional frontends. - In the future you will likely see more and different types of applications - being developed which will use the xine engine for video processing - and other multimedia purposes. - - - If you simply want a media/dvd player, you'll need to install xine-lib - first and then choose and install a player frontend like xine-ui or gxine. - - - Other modules in CVS are: xine-plugin a mozilla browser plugin - for streaming media playback using xine, - xine_www the - xine project website sources. - - - - - Where and how do I get the latest development version? - - Be advised that end-users should stick to the official xine releases. - The CVS and Mercurial repositories are only intended for developers and for others who know why they use it. - - - Checking out xine modules from Mercurial - - The repositories are listed at http://hg.debian.org/hg/; - however, this is a list of all repositories which are kept there, not just the - xine project's (which are the ones which begin with xine-lib/). To check one out: -    hg clone http://hg.debian.org/hg/repository local_copy - e.g. -    hg clone http://hg.debian.org/hg/xine-lib/xine-lib xine-lib - - - Currently, only xine-lib and gxine are present here. - - - - Checking out xine modules from CVS - - To check out xine modules from CVS, first do this: -    cvs -d :pserver:anonymous@xine.cvs.sourceforge.net:/cvsroot/xine login - The password is empty, just press Enter. - - - Then, to check out individual modules (e.g. xine-lib or xine-ui): -    cvs -d :pserver:anonymous@xine.cvs.sourceforge.net:/cvsroot/xine co <modulename> - - - If you want xine-lib or gxine, you should use Mercurial instead. - The CVS repositories for these are not maintained. - - - - - - How do I submit patches? - - First, make sure that you're using a current development version - (see above) or at least the current release version. Then, once you're - ready to send the patch... - - - Generate your patch using either cvs diff -u > - my.patch or hg diff > my.patch (as - appropriate). Make sure that your message subject briefly describes the - patch; your message body should contain a longer description of the - patch. Your patch should be applicable using patch -p0 -i - my.patch or, preferably, patch -p1 -i - my.patch from the top-level directory in the source tree - (i.e. where configure.ac is) - this is fairly important for our - Mercurial-based repositories since it makes importing your patch that - much easier (hg import defaults to -p1). - - - Alternatively, if you've been hacking away at a module which is - maintained using mercurial, you can make them available as diffs - use - hg export or, if you have several patches, you could - use hg bundle instead (both require extra - parameters; hg help export and hg help - bundle for more details) - or via HTTP by using hg - serve. In the latter case, you'll need to post a URL from - which a developer can pull the changes. - - - Patches should normally be sent to the xine-devel mailing list, - xine-devel@lists.sourceforge.net. - - - - - Why is gxine's CVS module named "gnome-xine"? - - Historical reasons: gxine was originally named gnome-xine. - - - - - Where can I find pre-compiled binaries, e.g. RPMs? - - The xine project does not provide pre-compiled binaries for legal - reasons (some parts of xine may be covered by patents in some countries). - Some OS projects/vendors (e.g. debian, freebsd, ...) offer binaries - for their distributions - please contact them or use their package search - tools for further info. - You can also find links to third parties providing xine RPMs on - the xine homepage at - http://xinehq.de/index.php/releases. - - - See the next section of this FAQ for instructions on how to build xine - from source. - - - - - - - Building and installing xine from source - - - What do I need to compile everything properly? - - First of all an official and stable release of gcc. Also be aware - that patched gcc versions may break parts of xine and are therefore - not supported by the xine project. - - - Furthermore you'll have to use GNU make to compile xine. On most GNU/Linux - systems "make" is GNU make - on other platforms use "gmake" instead. - Also, zlib is required (including the appropriate header files, which are - often found in a package called zlib-devel or similar.) - - - If you want to compile xine from CVS, you'll need to have the autobuild tools - installed (automake, autoconf and libtool - in recent versions). - - - Frontends might need additional libraries, e.g. for gxine you'll need to have - GTK2 installed. Make sure you have not only the shared libraries themselves - but also the header files (often packaged seperately as so-called -dev packages) - on your system. - - - Some plugins that come with the xine engine need additional libraries (otherwise - they will not be built). For example, libogg and libvorbis (plus their include files) - are needed for ogg/vorbis support. Most notably, if you want to see any video - on your X11 desktop (and that's what you're here for, isn't it?), you need the - X developer packages as well. - - - Don't worry about this too much right now, xine's configure - (see below) will check for all the stuff needed and will tell you what's missing - (which means that you should check the output it produces carefully ;) ). - - - - - How do I compile xine? - - Simple build instructions for beginners - - Download the latest xine-lib and gxine/xine-ui tarballs, then follow - these instruction. To unpack a tarball, use: -    tar xfvz tarballname.tar.gz - - - The following instructions will install xine in /usr/local - where it will be visible for all users. You need root privileges to do this on most systems. - - - After unpacking xine-lib, issue: - -   ./configure -   make install - - - Make sure your /etc/ld.so.conf contains - /usr/local/lib and continue with: -    ldconfig - - - Now unpack your frontend (gxine or xine-ui or ...), then: - -   ./configure -   make install - - - - Complete build instructions - - The build process is the same for all of the xine modules. - - - You have to start with xine-lib. If built and installed successfully, you - can continue with the frontend(s). - - - If you have installed xine-lib to a non-standard prefix, make sure - that you have $prefix/bin in your PATH and that your linker finds - libs in $prefix/lib - otherwise trying to build modules that - rely on xine-lib will fail with configure complaining about not - finding certain parts of libxine. Using bash you can do something like: - -   export PATH="$prefix/bin:$PATH" -   export LD_LIBRARY_PATH="$prefix/lib:$LD_LIBRARY_PATH" - to make sure libxine can be found by the frontend(s). - - - Last but not least. Here the build instructions. As stated earlier, - those are the same for every xine module. - -   ./autogen.sh [-> *only* if you checked your sources out of CVS] -   ./configure -   make -   make install - - - - - - Making your own RPM packages (xine-lib, xine-ui, gxine) - - Basically you will only have to issue one command, if you have just - downloaded a source tarball from our web site: -    rpmbuild -ta <THE_NAME_OF_YOUR_SOURCE_TAR_BALL> - (Older versions of RPM use rpm instead of rpmbuild.) - - - This will start the binary and source RPM building. After compiling is - finished, a binary rpm is placed in your rpm binary directory which is - something like /usr/src/RPM/RPMS/<YOUR_ARCHITECTURE> - and a source RPM is written to your rpm source dir - (e.g. /usr/src/RPM/SRPMS). - - - In case that you have a fresh CVS checkout, you will need to do the - following first in order to get a tarball release out of it which you - can later use with the rpmbuild -ta command above: -    ./autogen.sh && make clean && make dist - - - In any case, please keep in mind that you have to build and install - xine-lib first before you can proceed with xine-ui. - - - - - Making your own .deb packages (xine-lib, xine-ui, gxine) - - You'll need a CVS or HG snapshot tarball or source checked out from the repository. - - - First, make sure that the "devscripts" package is installed. You'll - then need the following commands (the first one isn't needed unless you're using a snapshot tarball): - -   tar xzf <PACKAGE-VER.tar.gz> -   cd <PACKAGE-VER> -   ./autogen.sh noconfig -   debuild binary - - (If debuild complains about unmet dependencies, then - install them using aptitude install <PACKAGES> (as root) then re-run - debuild binary. - - - Once the build has been successfully completed, you'll have some new .debs. - -   cd .. -   ls *.deb -   su - -c 'cd '"`pwd`"' && dpkg -i <DEB_PACKAGES>' - - Ubuntu users will probably want to use this instead of that su: - -   sudo dpkg -i <DEB_PACKAGES> - - - - In any case, please keep in mind that you have to build and install - xine-lib first before you can proceed with xine-ui or gxine. - - - - - Can I provide additional CFLAGS for compilation? - - Yes, you can do so by setting the CFLAGS variable and then running - configure again. You can even pass them to - configure directly. Example: -    ./configure CFLAGS="-march=i686" - - - Other user variables configure respects are: - - - - CC to specify the compiler executable - - - - - CPP to specify the C preprocessor executable - - - - - LD to specify the linker executable - - - - - CPPFLAGS to pass additional include paths or other - preprocessor options - - - - - LDFLAGS to pass additional library paths or other - linker options - - - - - - An example combining some of these would look like: -    ./configure CC="/opt/intel/bin/icc" LD="/opt/intel/bin/xild" \ -   CPPFLAGS="-I/usr/local/include/dvdnav" LDFLAGS="-L/home/guenter/xine_libs" - - - - - Are there binaries for my AMD K7 (Athlon™) available? Can I build them? - - If you have a recent gcc you can try to compile "more" k7 support in (esp. - better instruction scheduling). If the configure script should fail to - detect your processor/gcc correctly, try passing the canonical system name for - your machine to configure with the --host option, e.g. -    ./configure --host=k7-pc-linux-gnu - - - - - Build problems: xine engine (xine-lib) - - The package doesn't compile at all! - - In order to be able to compile xine-lib, you need (amongst other things) - the zlib compression library plus the appropriate headers, which are - often found in a package called zlib-devel or similar. - - - Read again carefully the output ./configure - produced and/or compiler warnings and error reports, they often contain - helpful information to find out what's going on. If you're stuck here - and decide to post your problem on the xine-user mailing list, - make sure you include these outputs. - - - - The Xv video-out plugin fails to compile! - - If you want to have Xv support compiled in, make sure you either have - a shared Xv library on your system, e.g. - ls /usr/X11R6/lib/libXv* - should give you some .so libs, like this: - -   /usr/X11R6/lib/libXv.a -   /usr/X11R6/lib/libXv.so -   /usr/X11R6/lib/libXv.so.1 - - - Alternatively you need to have libtool 1.4 or newer installed, then - libXv.a is sufficient. Otherwise you can create the shared versions yourself: - -   ld --whole-archive -shared -o libXv.so.1 libXv.a -   ln -s libXv.so.1 libXv.so -   ldconfig - - - Now you should be ready to build the Xv video-out plugin on your system. - - - - - - Build problems in frontends (gxine/xine-ui/...) - - I have installed xine-lib but the frontend complains about not finding it! - - First of all take a closer look at the compilation instructions above again. - You will probably find your answer there right away. - - - As stated there (there again that hint *grin*), make sure that you - have $prefix/bin in your path and that your - linker is able to find libraries installed in $prefix/lib - By the way, $prefix is where you installed your xine-lib to earlier - (yes, installing xine-lib with make install or - installing the corresponding distribution-provided -dev or -devel - package would be a good idea before trying to compile the frontend ;) - ). - - - - - - Can I install xine in my home directory (without being root)? - - Sure. First set up a subdir where you install your private software, eg. -    mkdir ~/xine - - - Then you have to set a few environment variables - it's probably a good - idea to add this to your ~/.bashrc (or somewhere similar): - -   export PATH="$HOME/xine/bin:$PATH" -   export LD_LIBRARY_PATH="$HOME/xine/lib:$LD_LIBRARY_PATH" - - - Now you can unpack tarballs e.g. in ~/xine/src - (mkdir ~/xine/src if necessary) and do a - -   ./configure --prefix=$HOME/xine -   make install - - - You also need to tell frontends using xine-lib, where to find it: -    ./configure --prefix=$HOME/xine --with-xine-prefix=$HOME/xine - - - - - How to compile xine for Windows? - - For compiling xine under Windows with MinGW, CygWin or MS Visual C see README.WIN32. - - - For cross-compiling xine under comfortable unix-like environment with MinGW see README.MINGWCROSS. - - - - - - - Playback of various stream types - - - DVD Playback with xine - - How do I play back DVDs with xine? - - Newer xine (1.0.x) releases come with a full-featured - DVD plugin that should be able to handle any unencrypted, - non-locked DVD with full menu navigation support. No external - plugins are required anymore here. - - - To get DVD playback working, first make sure you have - a symlink /dev/dvd pointing to your - DVD device on your system. For example, if your DVD drive - is the master ide drive on the second IDE channel, - /dev/dvd should point to - /dev/hdc. Please note that if you - are using the ide-scsi emulation on your system, it is - likely that your DVD drive got mapped to a scsi device - node even though it is an ide drive. In that case first - check out you boot/kernel logs (or run cdrecord -scanbus) - to find out which device it got mapped to and set the - symlink accordingly (should be something like /dev/scd0, - /dev/scd1, ... in that case). - Also make sure you (as a user) have sufficient (read and write) permissions - on your DVD drive. This could mean you either have to change the device - permissions or add your user to a special group - (e.g. addgroup cdrom username), - depending on your setup and/or distribution. - - - It is highly recommended to switch DMA mode on for your DVD drive - (without it even very recent machines will have trouble producing - smooth video output). Use a command like - hdparm -d 1 <device> - on your DVD device. Please note that even if you're using ide-scsi - you will have to set the dma flag on the ide device node (e.g. - /dev/hdc), not the mapped /dev/scd - scsi device. - - - To be able to play back encrypted DVDs you need to have - libdvdcss installed on your system (please check if this is legal where - you live). If you do not understand what the term "encrypted DVD" means - here: As a rule of thumb, every DVD you have to pay money for is most - likely encrypted. - - - To make matters worse, apart from encryption, there is another obstacle - to take: the region code. The DVD authorities decided to divide the world - into eight geographical regions. Have a look at - http://www.dvdforum.gr.jp/RegionMap.pdf - if you want to know which number has been assigned to your country. It is - now their idea, that you shall only play DVDs, which have been produced - for your region. If you take a DVD off the shelf in your local store, - you should find a little globe-like icon which shows the region code the - disc is for. - - - Newer (post-2000) DVD drives (so-called RPC-2 drives) check the DVD - region, which means they'll prevent you from playing back DVDs that have - a different region code from what the drive is set up for. Some drives - come with a factory setting of region 0 so they can play back - any DVD until a region code is set. Others refuse to play any DVD at all - until they are told a region. The easiest way to handle this is to use - the regionset utility from - - http://sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415 - . - - - Once you have everything set up, try something like - gxine dvd:/ or xine -p dvd:/ - to start dvd playback. Some frontend also offer so-called autoplay - buttons or menu entries that start dvd playback immediately. - - - Important: do not try to mount the DVD. Just insert it and hit the DVD autoplay - button or start xine from the command line. - - - If things do not work as expected, try running the xine-check - shellscript that comes with xine to see if this gives you further hints on - what could be wrong. - - - - DVD playback works, but it takes a long time until playback starts - - This points to a region code problem. Some versions of libdvdcss can play - back DVDs from other regions than the RPC-2 DVD drive is set up for, - but this usually means a cryptographic attack (which takes time) has - to be used to access the DVD. - - - You can download a tool to set the region code of RPC-Drives here: - - http://sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415 - . - - - Warning: Please be aware that the number of region code changes in RPC-2 - drives is limited (usually about 5 times), after that your drive will - stay locked to the region you last set it up for. - - - - I have problems setting up my RPC-2 drive for the right region! - - You can download a tool to set the region code of RPC-Drives here: - - http://sourceforge.net/project/showfiles.php?group_id=31346&release_id=168415 - . - - - Warning: Please be aware that the number of region code changes in RPC-2 - drives is limited (usually about 5 times), after that your drive will - stay locked to the region you last set it up for. - - - - - - Can I watch Video CDs (VCDs)? SVCDS ? CD-i? - - xine supports VCD and SVCD playback out-of-the box. Similar to DVDs, - make sure you have a /dev/cdrom alias pointing - to your CDROM drive which you will use to play back the (S)VCD. - - - At the moment, CD-i formats are not supported by xine. - - - Do not try to mount the (S)VCD. Simply insert it into your CDROM drive - and hit the VCD autoplay button or start something like - gxine vcd:/ or xine vcd:/ - from the command line. - - - VideoCD troubleshooting guide - - This gives higher-level troubleshooting. More lower-level information is - given in the next section. - - - - - When you open the configuration dialog of your frontend, you should - see a vcd config section. An important setting is - default_device. If this is set to the empty string, - the VCD plugin will try to scan your drives for a suitable device if the - driver has the capability to scan for drives. However you can set - the device to something of your choosing. On GNU/Linux, this may be - /dev/cdrom and on Solaris it may be - /vol/dev/aliases/cdrom0. - - - If you set this field, make sure these are correct for your - particular setup. For example, I generally play out of the DVD - device and this is called /dev/dvd rather than /dev/cdrom. - - - - - - Your frontend should offer a VCD autoscan button or menu item. - If you select this, you should see your CD disk light go on if you have one. - And the CD should be read. You should get a playlist of what's on the VideoCD. - - - If not something's wrong, possibly you configured the wrong drive. - You might try to read a disk image of a VideoCD and thus elimate any problems - with hardware. You can get a test VideoCD disk image to test here: - - http://www.vcdimager.org/pub/vcdimager/examples/test_svcd/test_svcd_pal.zip - . - After unzipping this there should be files test_svcd_pal.cue and - test_svcd_pal.bin. Run xine with the MRL - - vcd:/test_svcd_pal.cue:E0. - If you see something playing then this is a hardware problem. - You might also want to try starting playback-control with - - vcd:/test_svcd_pal.cue:P1. - - - - - - There should be at least one "track", and one "entry" listed for - the VideoCD and the names of these in the MRL list will end with - "T1" and "E0" respectively. Often there are other playlist items, - and if you have menus or still frames there will be - "segments" as well. The simplest things to check are probably - "entries" and "tracks". If there are no entries listed or none of - the tracks or entries play, then there may be a problem with - that particular medium. So as in the step above, you can try a known good - sample and perhaps burn a CD from that. More likely if you get this - far, some of the items listed work and some do not. There are a - number of debugging switches that you can dynamically turn on and - off that may be able to help in isolating more specific problems. - See the section below. - - - - - - Something plays now, but you do not get any menus? Well, first is there - supposed to be a menu? In the last step you should have seen what is on - the VideoCD. Still frames are always "segments" so see if you can find one in the MRL - list and select that. - - - If there are no segments listed, there aren't any still-frame - menus. It's also possible to have menus in looping MPEG's. Use the - vcddump tool to find loops. vcddump is - also part of VCDImager. Another program that can help you examine the contents - of a VideoCD is vcdxrip. - - - To troubleshoot, start out with the known SVCD example that has a - still-frame menu at the beginning: - - http://www.vcdimager.org/pub/vcdimager/examples/test_svcd/test_svcd_pal.zip - - Inside this is a largish file called test_svcd_pal.bin and another - short text file called test_svcd_ntsc.cue. These are CD disk - images; that is, something that could be burned to a CD drive such - as with cdrdao. However you don't have to create a CD to view these - with the xine VCD plugin. You should be able to play the VideoCD by running the MRL - - vcd:/test_svcd_pal.cue. - If you see a still frame on startup. Great! If instead you see what - looks like the beginning of a movie (Blue Streak with Martin Lawrence) - then go to the next step. - - - - - - You have a VideoCD with menu and can see it, but there is no menu on startup? - If you have the VideoCD from the last step, then run the MRL - - vcd:/test_svcd_pal.cue:P1 - If this shows a still frame, but it just does not show when you - hit either the "VCD" autoscan button or give a MRL without the P1 at - the end then go to the next step. - - - If you have another VideoCD, from the MRL list, you should also see "playlist" - entries. Try selecting the one that ends "P1". If you don't see an entry with P1, - then your VideoCD does not have playback control (PBC) and although there may - be a still frame on the VideoCD it may have been authored so it is not easily - accessed. Again vcddump or vcdxrip can help here. - - - - - - You have a VideoCD with menu at beginning and can see it using an MRL - with P1 at the end, but you want to see it by hitting the "VCD" autoscan button - as well? Check to see that you have the configuration entry - media.vcd.autoplay set to playlist. - - - - - - VideoCD debugging - - To facilitate tracking down problems we let you see what's going on dynamically. - Various debugging settings will cause output to appear on xine's plugin log - and/or on standard error output. See the config entry media.vcd.debug - for details. - - - The tool vcd-info from the cdio branch of vcdimager can be used to - show the entire contents of a VideoCD or selected portions of that. Until the cdio - branch of vcdimager is completely merged with vcdimager, the cd-info branch version - has a few more features. (However consult vcdimager for complete version of the program.) - - - vcdxrip can be used to extract portions of a VideoCD and or create an - XML description file of the VideoCD. This XML file and the extracted - files can be used by vcdxbuild to recreate another VideoCD. - - - And finally see also tools cd-info and cd-read from libcdio. - - - - - - Can I watch Quicktime (.mov, .mp4) files using xine? - - Quicktime is just a system layer (container format) which can contain various - different audio and video formats. The system layer itself is fully supported - in xine. However, some quicktime audio/video codecs are not natively supported yet. - Luckily, if you are using a x86 compatible machine (any recent PC hardware should do) - you can install and use the original Quicktime DLLs and watch most streams - (trailers) that can be downloaded from the net. - - - Possibly the most convenient way to get the Quicktime DLLs is to download - them from the MPlayer website - - http://www.mplayerhq.hu/design7/dload.html - . - The package is called "essential". Unpack it and move everything you find - inside to /usr/lib/codecs (actually you can place them - anywhere you want, e.g. someplace in your home directory, but then you'll - have to set decoder.external.win32_codecs_path in your - xine config file accordingly). Restart xine then and you should be - able to watch Quicktime trailers. - - - - - Real Network files/streams - - Can I watch Real (.rm, .ram) files using xine? - - The situation with real files and streams is pretty similar to the situation - with Quicktime Streams (see above). The newer real audio and video formats - are only supported by using binary-only codecs which are not included in - xine. - - - Possibly the most convenient way to get the Real codecs is to download - them from the MPlayer website - - http://www.mplayerhq.hu/design7/dload.html - . - The package is called "essential". Unpack it and move everything you - find inside to /usr/lib/codecs and set the - decoder.external.real_codecs_path in your xine config file - to /usr/lib/codecs (actually you can place them - anywhere you want, e.g. someplace in your home directory, but then you'll - have to set decoder.external.real_codecs_path accordingly). - Restart xine then and you should be able to watch Real files/streams. - - - - What about (live) network streams (pnm://, rtsp:// style urls)? - - xine supports both pnm and rtsp streaming. However, digging out the actual - pnm/rtsp url can be tricky as they're often packed into heavy JavaScript and - HTML code on most websites. You can either use a combination of your - browser's "save source" function and wget or use a xine browser plugin - (currently the gxine frontend comes with a simple mozilla plugin, - for example). When you decided to dig out the url by hand don't get fooled - by the many redirectors that are often placed around the actual url. - Use wget to download any http://-style urls and use less to look inside - the downloaded .ra/.ram files where you will find the actual pnm/rtsp - url which can be opened using xine. - - - - - - Can I watch Windows Media (.asf/.wmv/.wma) files using xine? - - While the container format (system layer) ASF (wmv is just an alias) - is fully supported in xine, for newer windows media 9 based streams - you'll need to install windows binary codecs (.DLLs). - - - Possibly the most convenient way to get the Windows DLLs is to download - them from the MPlayer website - - http://www.mplayerhq.hu/design7/dload.html - . - The package is called "essential". Unpack it and move everything you find - inside to /usr/lib/codecs (actually you can place them - anywhere you want, e.g. someplace in your home directory, but then you'll - have to set decoder.external.win32_codecs_path in your - xine config file accordingly). Restart xine then and you should be - able to watch windows media streams. - - - - - Can I watch Digital TV (Digital Video Broadcast) using xine? - - At the time of this writing DVB support is a very new and experimental - feature in xine. The number of supported cards is pretty limited at the moment. - See doc/README.dvb (in the xine-lib tarball) for details. - - - - - How do I play streams from STDIN? - - Use something like: -    cat stream.mpg | gxine stdin:/ - - - - - How can I watch files with external AVI subtitles? - - In xine 0.9.13 this used to be: -    xine foo.avi%bar.sub - - - Latest xine-lib modules (1-beta3 or newer) support external subtitles - for any media file, not only AVI. In order to use it you can pass a - special MRL construction like: -    xine test.mpg#subtitle:file.sub - The external subtitles support can also be used by any xine frontend. - Currently xine-ui and kaffeine implement this feature with a subtitle - selection dialog. - - - - - - - Running xine - - - I have a lot of dropped frames - what can I do? - - Your hardware might be too slow for xine. Make sure you turn on all - speed optimizing options. A few things you should check (in order of - importance): - - - - First of all, run the xine-check script included in xine - package (probably already installed in your system). - xine-check will report several of the most common problems - listed here. Sample output from xine-check: - -   xine-check -   Please be patient, this script may take a while to run... -   [ good ] you're using Linux, doing specific tests -   [ good ] looks like you have a /proc filesystem mounted. -   [ good ] You seem to have a reasonable kernel version (2.4.18) -   [ good ] intel compatible processor, checking MTRR support -   [ good ] you have MTRR support and there are some ranges set. -   [ good ] found the player at /usr/local/bin/xine -   [ good ] /usr/local/bin/xine is in your PATH -   [ good ] found /usr/local/bin/xine-config in your PATH -   [ good ] plugin directory /usr/local/lib/xine/plugins exists. -   [ good ] found input plugins -   [ good ] found demux plugins -   [ good ] found decoder plugins -   [ good ] found video_out plugins -   [ good ] found audio_out plugins -   [ good ] skin directory /usr/local/share/xine/skins exists. -   [ good ] found logo in /usr/local/share/xine/skins -   [ good ] I even found some skins. -   [ good ] /dev/cdrom points to /dev/hdc -   [ good ] /dev/dvd points to /dev/hdc -   [ good ] DMA is enabled for your DVD drive -   [ good ] found xvinfo: X-Video Extension version 2.2 -   [ good ] your Xv extension supports YUV overlays (improves MPEG performance) -   [ good ] your Xv extension supports packed YUV overlays -   [ good ] Xv ports: YUY2 YV12 I420 UYVY - - - - - Try to use the Xv driver, it greatly improves performance and quality - because your graphics card does image scaling and colourspace conversion. The - video section contains important information - about several Xv drivers. - - - If Xv cannot be used for some reason, make sure your display is set up - to 16bpp, not 24 or higher (reduces memory bandwith). Some Xv drivers - may also have better performance with 16bpp. - - - - - Make sure the hard drive (or cdrom/dvd drive) which supplies the - video data is in DMA mode (if supported). - - - On most linux-based systems, you can use hdparm to check this: - -   hdparm /dev/hda -   [...] -   using_dma = 1 (on) -   [...] - - - You can enable DMA mode with the following command: -    hdparm -d1 device_of_your_drive_that_supplies_video_data - In some cases where this fails it helps to specify the dma mode - to use, for example: -    hdparm -d1 -X 66 device_of_your_drive_that_supplies_video_data - In RedHat 8.0 an additional entry in /etc/modules.conf -    options ide-cd dma=1 - should help (reboot for this change to take effect). - - - More information about this may be found here: - - http://oreilly.linux.com/pub/a/linux/2000/06/29/hdparm.html - . - - - - - Use a recent kernel which is optimized for your hardware. Old kernels - may lack support for accelerated instructions like SSE, for example. - - - - - Close other applications (use a tool like "top" to find out - what applications are using up CPU power). Programs that update the - system clock like ntp should also be disabled. - - - - - Enable MTRR support in your kernel. If you are still using XFree 3.x, - you'll have to tell the kernel yourself where the graphics memory is. - You'll find details about that in the linux dvd howto. - - - If you're using X.org or XFree 4.x, enabling MTRR support in your kernel should - be enough (use a recent kernel!). - - - Try a cat /proc/mtrr - if the file exists and you find an entry - corresponding to the amount of graphics memory you have, everything - should be fine. - - - - - Have your X-server (usually X.org or XFree86) running with higher priority. - Most recent linux distributions (like RedHat 8.0 or Mandrake 9.0) should - do that for you, improving not only xine but desktop responsiveness - in general. - - - Use the "top" utility and verify under the "NI" column if - the X process has a negative value, this indicates a higher priority. - See "The X Window User HOWTO - Performance considerations" for - further instructions - - http://www.tldp.org/HOWTO/XWindow-User-HOWTO/performance.html - . - - - - - Use the latest or a known-good gcc version and build an optimized xine-lib for - your architecture. - - - - - Besides boosting X-server priority, sometimes it's possible to avoid - discarding frames by making xine itself higher priority. This is not - a recommended pratice since it will require to run xine as root, - but you may give it a try if you want: -    nice --5 xine - - - - - xine needs high speed memory access which depends on your chip set. - Make sure you enable all speed-improving options. - - - Especially the via apollo pro chipset is known to be quite weird, - (most of all on my gigabyte board). If you can't configure the ram - access thoroughly using the bios you might want to try some really - nasty tricks, as explained on (for example): - - http://www.overclockers.com/tips105/index03.asp - - - - This website centers around a windows-tool to tweak the chipset, you - can do the same on FreeBSD with pciconf. - On some linux distributions there are similar tools. - - - - - a nice performance tuning tool can be found here: - http://powertweak.sourceforge.net - - - - - Set up and use raw devices for DVD access. Please note that the - actual performance gain during playback is very small if any, but - since raw devices are bypassing the kernel's buffer cache, Linux - will not try to cache the DVDs you play. This would not be useful, - because xine does its own caching and you usually play DVDs - sequentially, which means you won't reuse anything from the cache. - But the problem would be that Linux throws everything out of the - cache that might be in there. - - - Raw devices should be available in linux kernel 2.4.x and there are - patches for older kernels available from: - - ftp://ftp.kernel.org/pub/linux/kernel/people/sct/raw-io/ - - - - To use raw devices, first connect a free raw device to your dvd - device, use something like: -    raw /dev/raw1 /dev/dvd - - - Then create a link named "rdvd" pointing to that raw device: -    ln -s raw1 /dev/rdvd - - - - - For slow / high-latency dvd drives it might help to increase - the number of video buffers xine allocates. Try setting - engine.buffers.video_num_buffers:500 - to a higher value (e.g. 1000 or 2500). - - - - - - - - Oki, xine doesn't drop frames now but video output still is not really smooth! - - Video output can be further improved by tuning your linux kernel: - - - - Set HZ to 1000 in - /usr/src/linux/include/asm-i386/param.h - - - - - Try applying scheduler patches, especially the O(1) and the preemptive - patches have proven useful at the time of this writing (spring 2003). - - - - Linux 2.5/2.6 will probably have these improvements out of the box. - - - Miguel Freitas has written a nice - - article about his kernel multimedia experiments - . - - - - - I have problems when using xine on FreeBSD, Solaris, ... ! - - Check out the the corresponding README files in the directory xine-lib/doc. - - - - - What is aalib? How do I use it in xine? - - aalib is an ascii art library. xine comes with an aalib video output - plugin so you can watch movies in your xterm, on the console or on your - old vt100 - very cool ;> ... another nice option is to preview movies - on a remote server in your shell over ssh. - - - To use it make sure you have aalib installed correctly before you - configure/build xine-lib and xine-ui. In addition to the xine binary a - binary named aaxine should get built and installed. You can then use - something like: -    aaxine foo.mpg - to use aalib video output. - - - - - Does xine support my dxr3 / hollywood+ card? - - While xine's focus is clearly on software decoding, the dxr3 is supported. - - - You can find more information about using xine with the dxr3 - here - (also covers how to do tv output using the dxr3). - - - - - - - Audio related questions - - - What audio drivers does xine support? OSS? Alsa? Arts? Esd? - - Currently xine support audio output via OSS (kernel audio drivers), - ALSA 0.9.x (ALSA 0.5.x is no longer supported), arts (KDE's sound daemon) - and esound (esd, gnome's sound daemon - not recommended because it has - serious issues with a/v sync). - - - - - When I'm watching a movie, the sound effects are much higher in volume than the voices! - - Congratulations, you seem to have an original movie audio track there. - - - Uhm. So you don't like it. Well, there are two things you can do: - - - - You can enable xine's audio compressor. Most frontends have - a settings window and in that you'll find a slider for the - compressor setting. The values are percent values, so a - slider setting of 200 means that xine will double the volume - of silent parts of the movie (loud parts stay the same). - - - If your frontend does not have such a compression slider, - you can pass the value with the MRL: -    xine dvd:/#compression:150 - - - - - If you have a dolby digital (AC3) soundtrack, you can try - to enable liba52's dynamic range compression setting - audio.a52.dynamic_range:1 - in your xine config file (or use some gui config dialog). - - - - - - - - When I play this stream, xine shows video but there's no audio! - - If this happens with any video, first try a different audio driver - (gxine -A oss, gxine -A arts, - xine -A alsa ...). - - - If this problem only occurs with one specific stream, maybe switching to - a different audio channel (using the gui) helps. Some DVD streams have - audio on strange channels. - - - If all this doesn't help, maybe you're missing an audio codec or you found - a bug. If you decide to post your problem on the xine-user mailing list, - make sure to include all console output xine produced and also clearly - state what type of stream you tried to play back or, even better, make - a test stream available somewhere for developers to download and try. - - - - - Can xine produce 4-/5-channel surround audio output? - - Yep, it can do that using OSS or ALSA drivers, provided that the driver - supports it. However, since xine cannot detect if there are actually speakers - connected to the additional channels, you'll have to activate that feature manually. - - - You can do this either in the config dialog while xine is running (press - the config button on the xine panel and go to the AUDIO tab) or have it - the complicated way by editing the config file yourself which is located - in your home directory in .config/gxine or - .xine: - -   audio.output.speaker_arrangement:Surround 4.0 -   audio.output.speaker_arrangement:Surround 4.1 -   audio.output.speaker_arrangement:Surround 5.1 - - - - - What about ac3 output via spdif to an external ac3 decoder? - - xine can do that too. Pretty much the same story as for 4-/5-channel - surround (see above). You can either use the config dialog or edit - the config file (~/.xine/config or - ~/.config/gxine/config) yourself: -    audio.output.speaker_arrangement:Pass Through - - - - - Getting SPDIF output from a SBLive 5.1 using OSS drivers - - The following explains how to get the above configuration - going with xine. Some parts of it may applicable to other - configurations (cards that use the EMU10k1 chip) as well. - - - Requirements - - - xine-lib >= 1.x.x - - - OSS driver - - - an external decoder - - - a cable to connect the SBLive to the external decoder - - - - The configuration described was tested using a Soundblaster live 5.1 (rev 7) - with a Yamaha DSP-AX620 external decoder. - - - - Retrieving the driver - - The OSS driver is maintained by creative and can be downloaded at - http://opensource.creative.com/. - The driver package contains documentation on how to install it. - Besides that I'd like to add the following notes. - - - In order to compile and install these drivers, you need a valid kernel - configuration file. For RedHat Linux's pre-compiled kernels these - configuration files can be found in - /usr/src/linux/configs. - After you've located the correct config file for your kernel, - you need to copy it to /usr/src/linux/.config - For example, when you run the 2.4.18-i686 kernel do : -    cp /usr/src/linux/configs/kernel-2.4.18-i686.config /usr/src/linux/.config - Make sure that the emu10k1 module that is currently installed is - not loaded. To unload the modules: -    /sbin/modprobe -rv emu10k1.o ac97_codec.o - If this mentions that the device is busy, some program is - using the driver. Some example could be a mixer application - or sound daemon like artsd. You'll need to close down the - applications before continuing. - At success it should print something like: - -   # delete emu10k1 -   # delete ac97_codec -   # delete soundcore - Run make in the directory where you unpacked the driver and follow the - instructions printed at the end of each step. - The last step should be: -    make install-tools - As the README of the driver package mentions the SPDIF AC3 - output doesn't work by default. In the directory - utils/scripts an emu10k1.conf - file can be found which need to be placed in the default - installation directory (/usr/local/etc). - After this the emu10k1.conf needs to be modified. - The following settings worked fine for me (I don't use the analog - outputs of the card): - -   CARD_IS_5_1=yes -   USE_DIGITAL_OUTPUT=yes -   ENABLE_TONE_CONTROL=yes -   AC3PASSTHROUGH=yes -   ENABLE_LIVEDRIVE_IR=no -   INVERT_REAR=no -   MULTICHANNEL=yes -   ROUTE_ALL_TO_SUB=no -   ANALOG_FRONT_BOOST=no -   SURROUND=no -   PROLOGIC=no -   ENABLE_CD_Spdif=yes -   ENABLE_OPTICAL_SPDIF=no -   ENABLE_LINE2_MIC2=no -   ENABLE_RCA_SPDIF=no -   ENABLE_RCA_AUX=no - After modifying the emu10k1.conf, - you need to modify your /etc/modules.conf and - make sure the following lines are in there. - -   alias sound-slot-0 emu10k1 -   post-install emu10k1 /usr/local/etc/emu-script - After saving the changes to modules.conf, run -    /sbin/depmod -a - Now, you're ready to load the new modules and set the correct - options for it. To load the modules run: -    /sbin/modprobe emu10k1 - - - - Setting up xine for SPDIF (AC3 passthrough) output - - You can either use the config dialog of your frontend or edit - the config file (~/.xine/config) yourself: -    audio.output.speaker_arrangement:Pass Through - In case the setting is not in the file you can add it. - - - - - The cable used for the SBLive can easily be self-made - or buy a stereo 3.5mm jack to dual RCA cable. - - - What you need to make the cable yourself: - - stereo 3.5mm jack plug - RCA plug - shielded cable (video coax 75 Ohm will do) - - Connect them as follows : - -   center pin jackplug ------|----- center pin RCA plug -    GND __|__ GND - - - In order to test it use a DVD with AC3 or DTS track - start xine and select the right audio track - from user interface or start xine as: -    xine dvd:/1 -a 0 - The external decoder should display something like - "Dolby Digital" in case the selected audio track contains - AC3 data or "DTS" in case the selected audio track - contains DTS data. Of course stereo audio also goes - through the SPDIF output, so the analog outputs of the - SBLive 5.1 are not needed anymore. - - - - - - Changing the volume with the GUI control has no effect! What's up!? - - Some xine drivers do not support volume changing although the GUI - will show the volume bar. Usually this is not xine's fault: aRts C - API, for example, doesn't offer any volume property to applications. - Similarly, with ac3 pass through it is not possible to set the volume. - - - Note that recently we added support to "simulate" volume in aRts by - changing sample values on-the-fly before delivering them to the driver. - Not as good as having access to sound card's mixer but at least users - will not complain about lacking of volume bar anymore! :) - - - - - Audio is stuttering and i see a lot of "metronom: fixing sound card drift by -2115 pts" on the console output - - Might be a soundcard problem, if it only comes in longer intervals. - Your soundcard does not keep it's sampling frequency accurately - enough, which results in audio and video - getting out of sync and xine has to compensate. If you see the message - only from time to time, you might remedy it by using the resampling sync - method. You can do this by setting the configuration entry - audio.synchronization.av_sync_method to resample. - - - If you receive the metronom message more often, - maybe switching to different drivers (alsa to oss or vise-versa) - can help here. It has also been reported that setting the configuration - entry audio.synchronization.force_rate to the native sampling - rate of your soundcard (try 44100 and 48000) helps sometimes. - - - Another, whole different possibility is that you have some background - process running which is messing with the clock (like some ntp client - - chronny, ntpd, ...). - - - Occasional messages of "fixing sound card drift" may happen on start and - when playing a long stream (like a movie). This is normal behaviour, - nothing to worry about. - - - - - xine seems to lose sound arbitrarily during playback, especially with DVDs - - You are using the OSS audio output plugin, right? In order to keep video and audio - in sync, xine regularly queries the audio driver for the amount of delay induced by - the current length of the driver's audio buffer. Unfortunately some OSS drivers seem - to be broken because the can return strange values here. This confuses the xine audio - subsystem and makes it drop audio. - - - You should try the various settings of the - configuration entry audio.oss_sync_method. The options - getodelay and getoptr ask the driver and - might therefore show the problem. But chances are that only one is broken and the other - works, so you should try them both first, since they are the most accurate. - The option probebuffer does not ask the driver directly but - tries to determine the buffer length from outside. This should work with any driver - and is the way to go, of the driver dependent methods fail. - softsync is the least accurate and should be used only in - emergency situations. - - - - - - - Video related questions - - - I can hear the audio - but I don't see a picture! - - Probably your hardware is simply too slow - see above for some - hints on how to speed things up. - - - Another possibility is that you using a buggy Xv driver, see the next - questions. - - - - - I only see a blue (or green or black) video image most of the time. - - You are either watching a very boring video (just kidding) or you are - suffering from a bug in the Xorg 6.7 implementation of X11. - - - The workaround is to add the line -    Option "XaaNoOffscreenPixmaps" - in the Device section of your X server configuration (usually - /etc/X11/xorg.conf or /etc/X11/XF86Config). - - - - - The image looks strange, it is shifted, cropped or shows weird lines! - - This points to a problem with the Xv extension, which is used by xine - to display the video image. To verify this, try running xine with the XShm - video output plugin: -    xine -V XShm - - - If that works fine, you just proved, that the Xv extension is buggy. xine will - remember the last used video output plugin, so the setting will stay at XShm. - You could simply continue using this, but XShm is a lot slower than Xv, so - read on and see if you can get it working. Usually you should look for - updated versions of the X driver module that belongs to your graphics card. - - - Other possibilites are limitations in either your X driver module or your - graphics hardware. If your card could somehow be running out of ressources (graphics - RAM perhaps) and displays an incorrect Xv overlay because of that, try reducing - the display resolution and/or colour depth. - - - Consult the next question for more details on Xv. - - - - - How can I make xine use the Xv extension and what drivers do I need? - - xine will normally use Xv by default if it is available. In some cases - you might need to choose Xv playback manually (when the ~/.xine/config - file for some reason says that you want to use XShm): -    xine -V Xv - - - If this doesn't work for you, it may be possible that Xv is not present - on your system. - - - First you need to install/use X.org or XFree 4.x. Once you got that you have to - make sure the X drivers you're using are supporting Xv on your - hardware. Here are some hints for individual gfx chips: - - - - 3Dfx: if all you get is a solid black window, upgrade to X.org or XFree 4.1.0 or later. - - - - - ATI: if you only get "half a picture", try lowering your resolution - or bit depth, disable DRI (looks like you ran out of video RAM) - - - - - Trident card: If you see vertical bands jumbled, upgrade to the latest - xfree/experimental trident drivers (for the CyberBlade XP - a driver exists here: - http://www.xfree86.org/~alanh/ ) - - - - - nVidia: With newer GeForce cards, Xv should work with XFree 4.2.0 or - newer, for older RivaTNT cards use the binary drivers from nvidia - (of course the binary drivers work as well for GeForce cards) - - - - - Mach64/Rage3D (not Rage128/Radeon) cards/chips get no XVideo with - standard drivers, try - GATOS drivers - instead - - - - - intel: i815 has Xv support in XFree 4.x, others unknown - - - - - Permedia 2/3 has Xv support in XFree 4.x - - - - - Savage: at least some older drivers tend to lock up the whole machine, - try the drivers available from - - http://www.probo.com/timr/savage40.html - . - - - - - SIS: certain controllers (more info needed!) have Xv support in XFree 4.x - - - - - Chips and Tech 6555x, 68554, 69000, 69030 have Xv support in XFree 4.x - - - - - NeoMagic: certain controllers (more info needed!) have Xv support in Xfree 4.x - - - - - SiliconMotion: certain controllers (more info needed!) have Xv support in Xfree 4.x - - - - - Matrox: G200 or newer (but not Parhelia) have Xv support in XFree 4.x. - For Parhelia, use the binary only drivers available from matrox' website. - - - - - - - - Some parts of my X Desktop get transparent when xine plays the video! - - Looks like some colours on your GUI match the colour key which Xv uses. You can - change the colour key value to avoid this. There should be a line like: -    video.XV_COLORKEY:2110 - in your ~/.xine/config file where you can change the colour that's used - by xine for the video overlay. - - - - - The aspect ratio of the video is wrong! - - Usually xine discovers the screen aspect ratio by - querying the X-server and then adjusts the video automatically - to make it look right. However, if that doesn't work try - pressing "a" to manually change the aspect ratio. - - - If you have a wide screen monitor, make sure the X-server - is correctly configured. The X-server must know the physical - size of the screen, which is independent of the resolution - being used. - - - For X.org, the screen size should be set in the "Monitor" - section in the file /etc/X11/xorg.conf, as in the example below: - -   Section "Monitor" -      Identifier "Monitor0" -      VendorName "Monitor Vendor" -      ModelName "DDC Probed Monitor - ViewSonic G773-2" -      DisplaySize 320 240 -      HorizSync 30.0 - 70.0 -      VertRefresh 50.0 - 180.0 -   EndSection - For XFree86, the filename is normally /etc/X11/XF86Config. - - - Where DisplaySize specifies, - in millimeters, the physical size of the monitor's picture area. - - - - - What is the difference between discarded and skipped frames? - - Sometimes xine will output a message like that: -    200 frames delivered, XX frames skipped, YY frames discarded - - - The difference between these counters is a little subtle for the non - developer. There are two threads running in order to display video: - the decoder thread will deliver frames to the video output thread. - The latter is responsible for scheduling the frames to be displayed at - the right time. - - - If your system can't keep up with decoding requirements, decoder will - deliver overdue frames. Imagine if it finished decoding the frame - tagged for displaying at 11:30 but xine clock marks 11:31. When this - situation is detected, xine will try to skip decoding a few frames - to recover. Not every decoder may support this feature. - - - When the frame is decoded to be shown somewhere in future but the - output thread doesn't get scheduled in time by the operating system - to complete the operation, the frame is discarded. One cause might - be the disk access operation, which may halt the system for a few - miliseconds without DMA. See performance section tips above. - - - Note that if a decoder can't skip frames for some reason, you would - never see frames skipped (they would be all discarded). - - - - - My xine is runing in black and white! / I only get a grey video output! - - This frequently happens with new Xv drivers or when switching to a - different video card. Background is that different Xv drivers often - use different ranges for the contrast/brightness/saturation settings. - - - To fix this, try opening the xine settings window and try adjusting - the sliders for contrast, brightness and saturation. - - - Please note that some frontends save these settings in their config file - so when you have found a working combination, make sure you exit - xine cleanly so the values are saved. - - - - - Which is the best video driver to use? - - xine supports several video drivers for outputing the image. These will - differ on how the frames are copied to the video card memory, whether - colourspace conversion and scaling is done in software or hardware, among - other things. They may also differ on ease of use and stability. - - - Most of the time, Xv should give the users a good trade-off between - quality, compatibility and ease of use. This is why xine tries to use - Xv by default. - - - However some users may want to explore better the available hardware - capabilities (eg. syncing frame drawing with monitor refresh). - Also some Xv drivers contain slow copies and accessing the video card - directly may yield performance gains. - - - Drivers that access hardware directly includes VIDIX (warning: requires - root priviledges or kernel helper) and SyncFB (requires kernel helper - Matrox only). - User may try one of those, but should be warned that with root access - they can cause the system to crash hard. The support is also limited to - a couple of graphics cards only. - - - Graphic workstations like SGI have usually a good support for OpenGL. - In that case, using OpenGL may be a better choice than XShm. However for - most desktop systems the performance of OpenGL will be quite bad. - - - - - - - OSD and overlay related questions - - - What is this "unscaled" OSD about? - - Since version 1-rc3 of xine-lib supports a new method for rendering OSD - (On Screen Display) and subtitles. This method uses a X11 extension - called XShape that allows using screen resolution instead of - stream resolution. It is called "unscaled" OSD because it does not - scales with the video being played. - - - Suppose you are watching a 320x200 video in full screen. Normal OSD - would be blended at 320x200 and then scaled to full screen (lets say, - 1024x768), resulting in big and ugly fonts. The unscaled overlay is - drawn directly to screen, creating a sharper and better looking OSD. - - - There are side effects too. Sometimes the unscaled overlay show some - glitch just before disappearing. Some people may be annoyed enough - by that and might want to disable the usage of unscaled overlay - altogether. - - - Unscaled OSD usage by subtitles and xine-ui is controlled by - the following settings (~/.xine/config or - ~/.config/gxine/config): -    gui.osd_use_unscaled:0 -    subtitles.separate.use_unscaled_osd:0 - - - - - I can't see the OSD or it leaves a black box over the image! - - If you are using xine-lib version 1-rc3 or newer, this is probably - due buggy XV drivers that do not support - unscaled OSD (the XShape - extension) properly. - - - There have being reports of some ATI drivers that don't allow - displaying anything over the video. The VIA Epia binary drivers - is reported to leave a black box where the OSD was displayed. - - - The problem may be fixed by either updating the video driver, - or disabling xine unscaled OSD support. - - - - - Why colours of overlays/subtitles seem to be "leaking"? - - xine blends most overlays, specially the ones from DVD discs, - directly over the image (scaled OSD). Unfortunately most codecs - (like MPEG2) use a subsampled image format (YV12) that makes - properly blending an interesting challenge. - - - In short, this is a known xine bug. There have being discussions - on improving the blending quality but, so far, nobody implemented - a better (scaled) overlay renderer. Contact developers if you want - to try doing something about it. - - - - - Why external subtitles look so ugly? - - You are probably using a xine-lib version older than 1-rc3. - Try upgrading your copy and read the - section about unscaled osd. - - - - - Why subtitles can't be displayed outside the video? - - It is possible, but older xine versions may not support it. There are two - alternatives for rendering the subtitles outside the video image: - - - - - - Use the "expand" post plugin to increase frame height adding - black bars to it. This will allow blending the subtitles - over the black bars, since they will be part of the video now. - - - - - Use unscaled OSD, as it - does not requires any video to render the subtitles on. - - - - - - Also notice that DVD overlays (including subtitles) are meant to - be displayed in a fixed position, this is how the DVD menu - highlighting works. xine does not support moving them. - - - - - What kinds of subtitle fonts does xine use? - - xine can use two kinds of fonts: - - - - TTF fonts - - - If xine is compiled with freetype library xine recognizes and uses TTF - fonts directly. - - - - - xine fonts - - - This is xine's native format. It's better because the font - generator utility implements more features than the "on the fly" TTF renderer. - - - - - - The font for text subtitles is selected via config option - subtitles.separate.font. You can specify xine font name - (sans, serif, ...) - or file name of the TTF font. The directories - $prefix/share/xine/libxine1/fonts and - ~/.xine/fonts are searched for the fonts, with - $prefix being the place xine-lib was installed to. - Usually this is /usr/local or /usr. - TTF fonts are also searched for in the current directory. - - - - - How to create own xine subtitle fonts? - - xine's native subtitle fonts can be generated from TTF fonts with the - utility xine-fontconv. It isn't compiled and installed by default but - you can make it manually. You'll need freetype and zlib packages together with - their versions for development plus a compiler, of course ;) - Here's how you build xine-fontconv: - - - - Get the source of xine-fontconv utility from the misc - directory within the xine-lib sources. - - - - - Compile it: -    gcc xine-fontconv.c -o xine-fontconv `freetype-config --cflags --libs` -lz - - - - You'll need some TTF font for generating. Characters in this font should - cover all codepages you want supported, otherwise you'll have missing characters. - - - Syntax is: -    ./xine-fontconf font.ttf font_name [encoding1 [encoding2 [...]]] - - - For example default font sans was generated with - following command: - -   ./xine-fontconv Aril_Bold.ttf sans iso-8859-1 iso-8859-2 iso-8859-5 \ -    iso-8859-9 iso-8859-15 cp1250 cp1251 - - - There are displayed messages about missing characters on the screen - during generating. It's OK if the missing characters are U+007f..U+009F. - These characters come from iso-8859-1 and they aren't displayable. - - - - - Encoding of external subtitles is bad. What is wrong? - - The encoding of the external subtitles is expected to be iso-8859-1 by - default. You need to set an appropriate encoding in the config option - subtitles.separate.src_encoding. Note that you also need - a font which contains all characters from the given encoding. - - - The default font sans and fonts - serif and mono cover these - encodings: - - iso-8859-1 - iso-8859-2 - iso-8859-5 - iso-8859-9 - iso-8859-15 - windows-1250 - windows-1251 - - - - - - - - Error Messages: What they mean and what you can do - - - Starting xine crashes X, I am logged out of my desktop! - - xine itself is unable to crash X, so when your X server just shuts down or - restarts with the login screen, there is something wrong with your X setup. - Most common are problems with the Xv extension. Try running xine with the XShm - video output plugin: -    xine -V XShm - - - If that works fine, you just proved, that the Xv extension is buggy. xine will - remember the last used video output plugin, so the setting will stay at XShm. - You could simply continue using this, but XShm is a lot slower than Xv, so - consult the section on Xv and see if you can - get it working. Usually you should look for updated versions of the X driver - module that belongs to your graphics card. - - - - - Starting xine fails with complains about audio drivers/devices! - - You can select the audio driver using the -A option. So try: -    xine -A null - If you have ALSA drivers installed, try: -    xine -A alsa - If you run ESD (not recommended), try: -    xine -A esd - If you run artsd, try: -    xine -A arts - - - - - "no video port found" - - You got the Xv extension, but your video card driver doesn't support it. - First try to find a driver that does support Xv on your hardware (check - your graphics card vendor). If your driver has Xv support but you can't - get it working, try at a lower resolution (1024x768 is enough even for - anamorphic DVDs). - - - If all that fails, you can still use plain X11/XShm: -    gxine -V XShm foo.vob - - - - - "Unable to open dvd drive (/dev/dvd)" - - You probably don't have /dev/dvd (check that). If so, simply create a - link /dev/dvd that points to your DVD device. Something like... -    ln -s hdc /dev/dvd - ...should do the job. Also make sure you have read and write access on - the device the symlink points to. - See the dvd playback section - for more information. - - - - - My drive doesn't work and the kernel says "status=0x51 { DriveReady SeekComplete Error }" - - This error can be fixed by recompiling your kernel with the option - "Use multi-mode by default" enabled in the IDE settings. - - - - - "demux error! 00 00 00 (should be 0x000001)" - - Probably xine can't access your input source. Most commonly this happens - when you're trying to play locked/encrypted DVDs. Remember that xine - can't play such DVDs out-of-the box for legal reasons (see above). - - - If it is legal where you live, you can try to install libdvdcss. Once - you have done that and re-start xine, it should automatically detect - and use it to play back encrypted DVDs. - - - Another reason could be that your (RPC-2) DVD drive isn't set up - for the right region (see above). - - - - - "audio driver 'oss' failed, using null driver instead" - - First of all, make sure that your OSS Audio drivers are working (i.e. - you can play music with other software). Maybe you're using alsa? - If so, try gxine -A alsa to see if this helps. - - - The most common reason for oss not working is that some other program is accesing - your audio device. If you're using linux, the command fuser /dev/dsp - should give you the PID of the process. - - - If you are using GNOME, chances are that this is caused by ESD. Now you - have two possibilities. Either deactivate ESD (temporarily) by right - clicking on the sound monitor applet and selecting "Place Esound in - standby" or just kill it. Then xine will use OSS audio output. The other - method is to make xine use ESD for audio output with: -    gxine -A esd - This may result in worse playback - exact syncronization is not possible - with esd, so using oss should be preferred. - - - If you are using KDE, there is the possibility that the aRts sound - daemon is currently running and thus blocking your sound device. You - can check that by starting the aRts control (in your KDE menu it should - be under Multimedia). If it is running, you can either use the aRts - audio output plugin: -    gxine -A arts - Or you suspend the aRts daemon by checking the appropriate option in - your aRts control. (recommended) - - - Newer versions of arts have an auto-suspend mode - this can lead to - some nondeterministic behaviour of xine if it is set up to use - the audio device directly. Using arts is recommended in that case; - however, you will lose the ability to do four/five channel audio output. - - - - - "video_out: throwing away image with pts xxx because it's too old" - - This is a performance related problem. - If you have a fast computer and this message is shown from time to - time when playing a DVD or CD, it's very likely that DMA is not enabled - for your drive. - - - - - "No video plugin available to decode 'xxxxxx'." - - You have tried to play a stream using a unknown or unhandled codec. - Possibly the file uses some obscure proprietary format and no - information is available on how to decode it. - - - If you're on an x86 platform (e.g. PC hardware) you might want to - try installing binary-only windows medial, real networks and - quicktime codecs (see above). - - - - - "w32codec: decoder failed to start. Is 'xxxxxx' installed?" - - You probably don't have the win32 dll needed to decode this file. - - - - - xine just crashed on me - i didn't get any error message - - OK, yes, that shouldn't happen and you're upset. We can understand that. - But, to help you and of course to fix this, we need some information. - So, let's go through the checklist and maybe prepare a nice bug report - for the xine-user mailing list: - - - - Did xine really crash (segfault) or did it hang (deadlock)? - - - - - Can you reproduce the bug? (e.g. do you remember what you - did and when you do it again it crashes again?) - - - - - Is that a specific media file or format which crashes xine? (Have you - tried other files types?) - - - - - Check the console output (and include it in a bug report), maybe earlier - there is some output that points to the problem. - - - - - Your X server just froze on you? unfortunately that's a known problem - with some chipsets and drivers (most commonly Savage chipsets) when - using Xv. You might want to try running gxine -V XShm - to see if the problem is related to the Xv driver. This will unfortunately - be much slower, as lots of things are now done in software instead of - hardware scaling/colour space conversion. - - - Maybe at the time you read this, there's an X upgrade which fixes - this for the Savage driver. If that works for you, please notify the xine crew at - xine-user@lists.sourceforge.net, so they can update this FAQ! - - - - - Even though we try to make each release as bug free as possible, xine is - still under heavy development (nice excuse, isn't it? *grin*). - - - If you write to the xine user mailing list - xine-user@lists.sourceforge.net - make sure you include a the above information (when applicable) - and also some information about your machine (operating system, cpu type and - speed, gfx card, sound card, ...) and please use a meaningfull subject - line ("xine bug" is bad, "xine fails to play this quicktime trailer in fullscreen mode" - ist much better). - - - Thanks for taking the time to help improve xine. - - - - - - - - -
- - -- cgit v1.2.3 From 4dcb0c990f8e12bbec8304eda669cf067149c110 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:08:44 +0200 Subject: Rename the file in EXTRA_DIST. --- doc/faq/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/faq/Makefile.am b/doc/faq/Makefile.am index a43e6e97c..e60fe1a18 100644 --- a/doc/faq/Makefile.am +++ b/doc/faq/Makefile.am @@ -3,7 +3,7 @@ include $(top_srcdir)/misc/Makefile.common doc_DATA = faq.txt html_DATA = faq.html -EXTRA_DIST = README faq.sgml $(doc_DATA) $(html_DATA) +EXTRA_DIST = README faq.docbook $(doc_DATA) $(html_DATA) DISTCLEANFILES = $(doc_DATA) $(html_DATA) -- cgit v1.2.3 From f516480d9432d3e8cd257f129829589f627e40e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:10:05 +0200 Subject: Replace the faq.html and faq.txt rules with new ones with xmlto. --- doc/faq/Makefile.am | 38 ++++---------------------------------- 1 file changed, 4 insertions(+), 34 deletions(-) (limited to 'doc') diff --git a/doc/faq/Makefile.am b/doc/faq/Makefile.am index e60fe1a18..643099888 100644 --- a/doc/faq/Makefile.am +++ b/doc/faq/Makefile.am @@ -16,38 +16,8 @@ dist-hook: $(MAKE) docs ; \ fi -if HAVE_SGMLTOOLS -faq.html: faq.sgml - @$(MAKE) docs-prepare - $(SGMLTOOLS) -b onehtml faq.sgml; -else -faq.html: faq.sgml - @$(MAKE) docs-prepare - if test x"$(fail_if_missing)" = x"yes"; then \ - echo "Please install sgmltools-lite."; \ - exit 1; \ - fi - if test x"$(fail_if_missing)" != x"yes"; then \ - touch $@; \ - sleep 1; \ - touch $(notdir $^); \ - fi -endif +faq.html: faq.docbook + xmlto html-nochunks $(srcdir)/faq.docbook -if HAVE_SGMLTOOLS -faq.txt: faq.sgml - @$(MAKE) docs-prepare - $(SGMLTOOLS) -b txt faq.sgml; -else -faq.txt: faq.sgml - @$(MAKE) docs-prepare - if test x"$(fail_if_missing)" = x"yes"; then \ - echo "Please install sgmltools-lite."; \ - exit 1; \ - fi - if test x"$(fail_if_missing)" != x"yes"; then \ - touch $@; \ - sleep 1; \ - touch $(notdir $^); \ - fi -endif +faq.txt: faq.docbook + xmlto txt $(srcdir)/faq.docbook -- cgit v1.2.3 From bd6f0e307ee992149d315094d28de42ea4220f6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:10:24 +0200 Subject: Remove dist-hook. --- doc/faq/Makefile.am | 7 ------- 1 file changed, 7 deletions(-) (limited to 'doc') diff --git a/doc/faq/Makefile.am b/doc/faq/Makefile.am index 643099888..34bd3a95a 100644 --- a/doc/faq/Makefile.am +++ b/doc/faq/Makefile.am @@ -9,13 +9,6 @@ DISTCLEANFILES = $(doc_DATA) $(html_DATA) docs: $(doc_DATA) $(html_DATA) -dist-hook: - @if test x"$(distcheck_lax)" = x ; then \ - $(MAKE) fail_if_missing=yes docs ; \ - else \ - $(MAKE) docs ; \ - fi - faq.html: faq.docbook xmlto html-nochunks $(srcdir)/faq.docbook -- cgit v1.2.3 From b1063945eef90ee69071be0d2fe97923da99babf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:10:42 +0200 Subject: Remove docs target. --- doc/faq/Makefile.am | 2 -- 1 file changed, 2 deletions(-) (limited to 'doc') diff --git a/doc/faq/Makefile.am b/doc/faq/Makefile.am index 34bd3a95a..49d22860f 100644 --- a/doc/faq/Makefile.am +++ b/doc/faq/Makefile.am @@ -7,8 +7,6 @@ EXTRA_DIST = README faq.docbook $(doc_DATA) $(html_DATA) DISTCLEANFILES = $(doc_DATA) $(html_DATA) -docs: $(doc_DATA) $(html_DATA) - faq.html: faq.docbook xmlto html-nochunks $(srcdir)/faq.docbook -- cgit v1.2.3 From 8720685a91816b4895a102adf70cd3bab80da95f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:10:58 +0200 Subject: Reorder hackersguidedir. --- doc/hackersguide/Makefile.am | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/hackersguide/Makefile.am b/doc/hackersguide/Makefile.am index 7cd4cf2cc..b2fce9040 100644 --- a/doc/hackersguide/Makefile.am +++ b/doc/hackersguide/Makefile.am @@ -12,14 +12,13 @@ hackersguide_fig = architecture.fig \ overlays.fig \ post_frame.fig +hackersguidedir = $(htmldir)/hackersguide hackersguide_DATA = hackersguide.html \ architecture.png library.png overlays.png post_frame.png EXTRA_DIST = README $(hackersguide_docbook) $(hackersguide_fig) \ $(hackersguide_DATA) -hackersguidedir = $(htmldir)/hackersguide - DISTCLEANFILES = $(hackersguide_DATA) hackersguide.html: $(hackersguide_docbook) -- cgit v1.2.3 From e30a07f08d506f8acaedb9fe18204385e05e55e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:16:05 +0200 Subject: Fix && -> && --- doc/faq/faq.docbook | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/faq/faq.docbook b/doc/faq/faq.docbook index 568ac533a..8c7f63905 100644 --- a/doc/faq/faq.docbook +++ b/doc/faq/faq.docbook @@ -333,7 +333,7 @@ In case that you have a fresh CVS checkout, you will need to do the following first in order to get a tarball release out of it which you can later use with the rpmbuild -ta command above: -    ./autogen.sh && make clean && make dist +    ./autogen.sh && make clean && make dist In any case, please keep in mind that you have to build and install @@ -364,7 +364,7 @@    cd ..    ls *.deb -   su - -c 'cd '"`pwd`"' && dpkg -i <DEB_PACKAGES>' +   su - -c 'cd '"`pwd`"' && dpkg -i <DEB_PACKAGES>' Ubuntu users will probably want to use this instead of that su: -- cgit v1.2.3 From df5fa8969966cb05704b7bbbd46d79b423adc23d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:49:01 +0200 Subject: Convert the figure files to SVG (with white background). --- doc/hackersguide/architecture.fig | 560 ---------- doc/hackersguide/architecture.svg | 2134 +++++++++++++++++++++++++++++++++++++ doc/hackersguide/library.fig | 313 ------ doc/hackersguide/library.svg | 1732 ++++++++++++++++++++++++++++++ doc/hackersguide/overlays.fig | 64 -- doc/hackersguide/overlays.svg | 256 +++++ doc/hackersguide/post_frame.fig | 347 ------ doc/hackersguide/post_frame.svg | 1564 +++++++++++++++++++++++++++ 8 files changed, 5686 insertions(+), 1284 deletions(-) delete mode 100644 doc/hackersguide/architecture.fig create mode 100644 doc/hackersguide/architecture.svg delete mode 100644 doc/hackersguide/library.fig create mode 100644 doc/hackersguide/library.svg delete mode 100644 doc/hackersguide/overlays.fig create mode 100644 doc/hackersguide/overlays.svg delete mode 100644 doc/hackersguide/post_frame.fig create mode 100644 doc/hackersguide/post_frame.svg (limited to 'doc') diff --git a/doc/hackersguide/architecture.fig b/doc/hackersguide/architecture.fig deleted file mode 100644 index cc035149d..000000000 --- a/doc/hackersguide/architecture.fig +++ /dev/null @@ -1,560 +0,0 @@ -#FIG 3.2 -Landscape -Center -Metric -A4 -100.00 -Single --2 -1200 2 -6 2520 3915 3555 4950 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 2520 3915 3555 3915 3555 4950 2520 4950 2520 3915 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 - 2520 4140 3555 4140 -4 0 0 50 0 20 11 0.0000 4 150 945 2565 4680 demuxer plugin\001 -4 0 0 50 0 20 11 0.0000 4 150 840 2655 4095 demuxer loop\001 --6 -6 4500 3735 6300 5355 -6 5715 4500 6075 4770 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 5715 4500 6075 4500 6075 4770 5715 4770 5715 4500 -4 0 0 50 0 20 11 0.0000 4 120 195 5805 4680 buf\001 --6 -6 4680 4005 5040 4275 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4680 4005 5040 4005 5040 4275 4680 4275 4680 4005 -4 0 0 50 0 20 11 0.0000 4 120 195 4770 4185 buf\001 --6 -6 4860 4320 5220 4590 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4860 4320 5220 4320 5220 4590 4860 4590 4860 4320 -4 0 0 50 0 20 11 0.0000 4 120 195 4950 4500 buf\001 --6 -6 5220 4680 5580 4950 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 5220 4680 5580 4680 5580 4950 5220 4950 5220 4680 -4 0 0 50 0 20 11 0.0000 4 120 195 5310 4860 buf\001 --6 -6 5355 4095 5715 4365 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 5355 4095 5715 4095 5715 4365 5355 4365 5355 4095 -4 0 0 50 0 20 11 0.0000 4 120 195 5445 4275 buf\001 --6 -6 4635 4635 4995 4905 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4635 4635 4995 4635 4995 4905 4635 4905 4635 4635 -4 0 0 50 0 20 11 0.0000 4 120 195 4725 4815 buf\001 --6 -6 5805 3960 6165 4230 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 5805 3960 6165 3960 6165 4230 5805 4230 5805 3960 -4 0 0 50 0 20 11 0.0000 4 120 195 5895 4140 buf\001 --6 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4500 3735 6300 3735 6300 5355 4500 5355 4500 3735 -4 0 0 50 0 20 11 0.0000 4 150 660 5085 5265 buffer pool\001 --6 -6 1260 4230 2160 4770 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 1260 4230 2160 4230 2160 4770 1260 4770 1260 4230 -4 0 0 50 0 20 11 0.0000 4 150 705 1350 4545 input plugin\001 --6 -6 1710 3735 2070 4005 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 1710 3735 2070 3735 2070 4005 1710 4005 1710 3735 -4 0 0 20 0 20 11 0.0000 4 120 195 1800 3915 buf\001 --6 -6 3915 4320 4275 4590 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 3915 4320 4275 4320 4275 4590 3915 4590 3915 4320 -4 0 0 20 0 20 11 0.0000 4 120 195 4005 4500 buf\001 --6 -6 6525 5130 6885 5400 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 6525 5130 6885 5130 6885 5400 6525 5400 6525 5130 -4 0 0 20 0 20 11 0.0000 4 120 195 6615 5310 buf\001 --6 -6 6525 3555 6885 3825 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 6525 3555 6885 3555 6885 3825 6525 3825 6525 3555 -4 0 0 20 0 20 11 0.0000 4 120 195 6615 3735 buf\001 --6 -6 7335 5265 7695 5535 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 7335 5265 7695 5265 7695 5535 7335 5535 7335 5265 -4 0 0 20 0 20 11 0.0000 4 120 255 7425 5445 disc\001 --6 -6 7290 3375 7650 3645 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 7290 3375 7650 3375 7650 3645 7290 3645 7290 3375 -4 0 0 20 0 20 11 0.0000 4 120 255 7380 3555 disc\001 --6 -6 8865 5085 9225 5355 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 8865 5085 9225 5085 9225 5355 8865 5355 8865 5085 -4 0 0 20 0 20 11 0.0000 4 150 195 8955 5265 pts\001 --6 -6 9180 5985 9540 6255 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 9180 5985 9540 5985 9540 6255 9180 6255 9180 5985 -4 0 0 20 0 20 11 0.0000 4 150 270 9270 6165 vpts\001 --6 -6 8910 3645 9270 3915 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 8910 3645 9270 3645 9270 3915 8910 3915 8910 3645 -4 0 0 20 0 20 11 0.0000 4 150 195 9000 3825 pts\001 --6 -6 7380 4050 8865 4950 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 7380 4050 8865 4050 8865 4950 7380 4950 7380 4050 -4 0 0 50 0 20 11 0.0000 4 120 630 7830 4545 metronom\001 --6 -6 8505 3555 8865 3825 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 8505 3555 8865 3555 8865 3825 8505 3825 8505 3555 -4 0 0 20 0 20 11 0.0000 4 150 195 8595 3735 pts\001 --6 -6 8010 3330 8370 3600 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 8010 3330 8370 3330 8370 3600 8010 3600 8010 3330 -4 0 0 20 0 20 11 0.0000 4 150 270 8100 3510 vpts\001 --6 -6 1170 1575 9900 7425 -2 2 0 2 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 9855 1620 1215 1620 1215 7380 9855 7380 9855 1620 -4 0 0 50 0 20 11 0.0000 4 135 735 1350 1800 xine stream\001 --6 -6 1215 270 9900 540 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 1215 270 9900 270 9900 540 1215 540 1215 270 -4 0 0 50 0 20 11 0.0000 4 150 780 4590 450 stream layer\001 --6 -6 6795 630 9900 900 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 6795 630 9900 630 9900 900 6795 900 6795 630 -4 0 0 50 0 20 11 0.0000 4 150 840 7965 810 decoder layer\001 --6 -6 3915 630 6705 900 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 3915 630 6705 630 6705 900 3915 900 3915 630 -4 0 0 50 0 20 11 0.0000 4 135 750 5040 810 stream fifos\001 --6 -6 2340 630 3825 900 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 2340 630 3825 630 3825 900 2340 900 2340 630 -4 0 0 50 0 20 11 0.0000 4 150 885 2655 810 demuxer layer\001 --6 -6 1215 630 2250 900 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 1215 630 2250 630 2250 900 1215 900 1215 630 -4 0 0 50 0 20 11 0.0000 4 150 645 1395 810 input layer\001 --6 -6 11295 4050 12780 4950 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 11295 4050 12780 4050 12780 4950 11295 4950 11295 4050 -2 1 0 1 0 7 50 0 -1 3.000 0 0 -1 0 0 2 - 12780 4500 11700 4500 -2 1 0 1 0 7 50 0 -1 3.000 0 0 -1 0 0 3 - 11700 4950 11700 4320 12780 4320 -4 0 0 50 0 20 11 0.0000 4 135 1005 11430 4275 metronom clock\001 -4 0 0 50 0 20 11 0.0000 4 150 975 11745 4455 clock sync loop\001 -4 0 0 50 0 20 11 0.0000 4 150 600 11745 4770 scr plugin\001 --6 -6 11295 5220 11655 5490 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 11295 5220 11655 5220 11655 5490 11295 5490 11295 5220 -4 0 0 20 0 20 11 0.0000 4 120 270 11385 5400 time\001 --6 -6 11295 3555 11655 3825 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 11295 3555 11655 3555 11655 3825 11295 3825 11295 3555 -4 0 0 20 0 20 11 0.0000 4 120 270 11385 3735 time\001 --6 -6 9990 270 12870 540 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 9990 270 12870 270 12870 540 9990 540 9990 270 -4 0 0 50 0 20 11 0.0000 4 150 735 11075 450 output layer\001 --6 -6 10035 1620 10845 7290 -6 10260 4275 10710 4680 -4 0 0 40 0 20 11 0.0000 4 150 270 10260 4410 post\001 -4 0 0 40 0 20 11 0.0000 4 150 435 10260 4635 plugins\001 --6 -2 2 0 1 0 7 50 0 20 0.000 0 0 -1 0 0 5 - 10125 1620 10845 1620 10845 7200 10125 7200 10125 1620 -2 2 0 1 0 7 60 0 20 0.000 0 0 -1 0 0 5 - 10080 1665 10800 1665 10800 7245 10080 7245 10080 1665 -2 2 0 1 0 7 70 0 20 0.000 0 0 -1 0 0 5 - 10035 1710 10755 1710 10755 7290 10035 7290 10035 1710 --6 -6 11070 900 12870 1620 -2 2 0 1 0 7 50 0 -1 3.000 0 0 -1 0 0 5 - 11070 1620 12870 1620 12870 900 11070 900 11070 1620 -2 1 0 1 0 7 50 0 -1 3.000 0 0 -1 0 0 2 - 11655 900 11655 1620 -4 0 0 50 0 20 11 0.0000 4 150 1035 11790 1305 overlay manager\001 -4 0 0 50 0 20 11 0.0000 4 120 300 11205 1305 OSD\001 --6 -6 11115 1845 11475 2115 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 11115 1845 11475 1845 11475 2115 11115 2115 11115 1845 -4 0 0 20 0 20 11 0.0000 4 120 225 11205 2025 spu\001 --6 -6 9360 4545 9720 4815 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 9360 4545 9720 4545 9720 4815 9360 4815 9360 4545 -4 0 0 20 0 20 11 0.0000 4 150 195 9450 4725 pts\001 --6 -6 8100 5130 8460 5400 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 8100 5130 8460 5130 8460 5400 8100 5400 8100 5130 -4 0 0 20 0 20 11 0.0000 4 150 270 8190 5310 vpts\001 --6 -6 9450 3150 9810 3420 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 9450 3150 9810 3150 9810 3420 9450 3420 9450 3150 -4 0 0 20 0 20 11 0.0000 4 150 270 9540 3330 vpts\001 --6 -6 7920 3645 8280 3915 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 7920 3645 8280 3645 8280 3915 7920 3915 7920 3645 -4 0 0 20 0 20 11 0.0000 4 150 270 8010 3825 vpts\001 --6 -6 9360 4140 9720 4410 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 9360 4140 9720 4140 9720 4410 9360 4410 9360 4140 -4 0 0 20 0 20 11 0.0000 4 150 195 9450 4320 pts\001 --6 -6 1485 8550 3375 8730 -2 1 2 1 0 7 50 0 -1 1.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 1485 8640 2025 8640 -4 0 0 50 0 20 11 0.0000 4 150 1170 2205 8685 extra info datapath\001 --6 -6 1485 8235 3285 8415 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 1485 8325 2025 8325 -4 0 0 50 0 20 11 0.0000 4 150 1065 2205 8370 detailed datapath\001 --6 -6 1485 7920 2745 8100 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 1485 8010 2025 8010 -4 0 0 50 0 20 11 0.0000 4 150 540 2205 8055 datapath\001 --6 -6 4095 7875 5445 8145 -6 4095 7875 4455 8145 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 4095 7875 4455 7875 4455 8145 4095 8145 4095 7875 -4 0 0 20 0 20 11 0.0000 4 120 195 4185 8055 buf\001 --6 -4 0 0 50 0 20 11 0.0000 4 135 660 4770 8055 xine buffer\001 --6 -6 4095 8190 5580 8460 -6 4095 8190 4455 8460 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 4095 8190 4455 8190 4455 8460 4095 8460 4095 8190 -4 0 0 20 0 20 11 0.0000 4 120 255 4185 8370 disc\001 --6 -4 0 0 50 0 20 11 0.0000 4 150 780 4770 8370 discontinuity\001 --6 -6 4095 8505 6255 8775 -6 4095 8505 4455 8775 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 4095 8505 4455 8505 4455 8775 4095 8775 4095 8505 -4 0 0 20 0 20 11 0.0000 4 150 195 4185 8685 pts\001 --6 -4 0 0 50 0 20 11 0.0000 4 150 1470 4770 8685 presentation timestamp\001 --6 -6 6930 7875 9495 8145 -6 6930 7875 7290 8145 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 6930 7875 7290 7875 7290 8145 6930 8145 6930 7875 -4 0 0 20 0 20 11 0.0000 4 150 270 7020 8055 vpts\001 --6 -4 0 0 50 0 20 11 0.0000 4 150 1890 7605 8055 virtual presentation timestamp\001 --6 -6 6930 8190 8550 8460 -6 6930 8190 7290 8460 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 6930 8190 7290 8190 7290 8460 6930 8460 6930 8190 -4 0 0 20 0 20 11 0.0000 4 120 225 7020 8370 spu\001 --6 -4 0 0 50 0 20 11 0.0000 4 150 915 7605 8370 subpicture unit\001 --6 -6 4230 2385 6390 3015 -6 4320 2430 4680 2700 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4320 2430 4680 2430 4680 2700 4320 2700 4320 2430 -4 0 0 50 0 20 11 0.0000 4 120 195 4410 2610 buf\001 --6 -6 5940 2430 6300 2700 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 5940 2430 6300 2430 6300 2700 5940 2700 5940 2430 -4 0 0 50 0 20 11 0.0000 4 120 195 6030 2610 buf\001 --6 -6 5220 2430 5580 2700 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 5220 2430 5580 2430 5580 2700 5220 2700 5220 2430 -4 0 0 50 0 20 11 0.0000 4 120 195 5310 2610 buf\001 --6 -6 4770 2430 5130 2700 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4770 2430 5130 2430 5130 2700 4770 2700 4770 2430 -4 0 0 50 0 20 11 0.0000 4 120 195 4860 2610 buf\001 --6 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 4365 2475 10 10 4355 2475 4375 2475 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 4815 2475 10 10 4805 2475 4825 2475 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 5265 2475 10 10 5255 2475 5275 2475 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 5985 2475 10 10 5975 2475 5995 2475 -2 2 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 5 - 4230 2385 6390 2385 6390 3015 4230 3015 4230 2385 -4 0 0 50 0 20 11 0.0000 4 135 570 5040 2925 video fifo\001 -4 0 0 50 0 20 11 0.0000 4 30 135 5715 2610 ...\001 --6 -6 4230 5985 6390 6615 -6 4320 6030 4680 6300 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4320 6030 4680 6030 4680 6300 4320 6300 4320 6030 -4 0 0 50 0 20 11 0.0000 4 120 195 4410 6210 buf\001 --6 -6 5940 6030 6300 6300 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 5940 6030 6300 6030 6300 6300 5940 6300 5940 6030 -4 0 0 50 0 20 11 0.0000 4 120 195 6030 6210 buf\001 --6 -6 5220 6030 5580 6300 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 5220 6030 5580 6030 5580 6300 5220 6300 5220 6030 -4 0 0 50 0 20 11 0.0000 4 120 195 5310 6210 buf\001 --6 -6 4770 6030 5130 6300 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4770 6030 5130 6030 5130 6300 4770 6300 4770 6030 -4 0 0 50 0 20 11 0.0000 4 120 195 4860 6210 buf\001 --6 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 4355 6075 10 10 4345 6075 4365 6075 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 4815 6075 10 10 4805 6075 4825 6075 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 5265 6075 10 10 5255 6075 5275 6075 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 5985 6075 10 10 5975 6075 5995 6075 -2 2 0 1 0 7 50 0 -1 4.000 0 0 -1 0 0 5 - 4230 5985 6390 5985 6390 6615 4230 6615 4230 5985 -4 0 0 50 0 20 11 0.0000 4 135 570 5040 6525 audio fifo\001 -4 0 0 50 0 20 11 0.0000 4 30 135 5715 6210 ...\001 --6 -6 3735 5310 4095 5580 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 3770 5355 10 10 3760 5355 3780 5355 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 3735 5310 4095 5310 4095 5580 3735 5580 3735 5310 -4 0 0 20 0 20 11 0.0000 4 120 195 3825 5490 buf\001 --6 -6 3735 3330 4095 3600 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 3780 3375 10 10 3770 3375 3790 3375 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 3735 3330 4095 3330 4095 3600 3735 3600 3735 3330 -4 0 0 20 0 20 11 0.0000 4 120 195 3825 3510 buf\001 --6 -6 6525 2565 6885 2835 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 6570 2600 10 10 6560 2600 6580 2600 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 6525 2565 6885 2565 6885 2835 6525 2835 6525 2565 -4 0 0 20 0 20 11 0.0000 4 120 195 6615 2745 buf\001 --6 -6 6525 6165 6885 6435 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 6570 6210 10 10 6560 6210 6580 6210 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 6525 6165 6885 6165 6885 6435 6525 6435 6525 6165 -4 0 0 20 0 20 11 0.0000 4 120 195 6615 6345 buf\001 --6 -6 7065 5850 8865 6750 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 7145 5895 10 10 7135 5895 7155 5895 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 7065 5850 8865 5850 8865 6750 7065 6750 7065 5850 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 7425 6750 7425 6120 8865 6120 -4 0 0 50 0 20 11 0.0000 4 150 1170 7200 6030 audio decoder loop\001 -4 0 0 50 0 20 11 0.0000 4 150 1275 7515 6480 audio decoder plugin\001 --6 -6 7065 2250 8865 3150 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 7110 2295 10 10 7100 2295 7120 2295 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 7065 2250 8865 2250 8865 3150 7065 3150 7065 2250 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 7425 3150 7425 2880 8865 2880 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 - 8865 2790 7425 2790 7425 2520 8865 2520 -4 0 0 50 0 20 11 0.0000 4 150 1170 7200 2430 video decoder loop\001 -4 0 0 50 0 20 11 0.0000 4 150 1170 7515 3060 spu decoder plugin\001 -4 0 0 50 0 20 11 0.0000 4 150 1275 7515 2700 video decoder plugin\001 --6 -6 9045 2340 9720 2610 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 9090 2385 10 10 9080 2385 9100 2385 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 9045 2340 9720 2340 9720 2610 9045 2610 9045 2340 -4 0 0 20 0 20 11 0.0000 4 120 435 9135 2520 frames\001 --6 -6 9045 6480 9720 6750 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 9080 6525 10 10 9070 6525 9090 6525 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 9045 6480 9720 6480 9720 6750 9045 6750 9045 6480 -4 0 0 20 0 20 11 0.0000 4 150 525 9135 6660 samples\001 --6 -6 11070 5850 12870 6750 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 11070 5850 12870 5850 12870 6750 11070 6750 11070 5850 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 11430 6750 11430 6120 12870 6120 -2 1 0 1 0 7 50 0 -1 1.000 0 0 -1 0 0 2 - 12240 5850 12240 6120 -4 0 0 50 0 20 11 0.0000 4 150 870 11205 6030 audio out loop\001 -4 0 0 50 0 20 11 0.0000 4 150 975 11520 6480 audio out plugin\001 -4 0 0 50 0 20 11 0.0000 4 135 435 12330 6030 out fifo\001 --6 -6 11070 2250 12870 3150 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 11070 2250 12870 2250 12870 3150 11070 3150 11070 2250 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 11430 3150 11430 2520 12870 2520 -2 1 0 1 0 7 50 0 -1 1.000 0 0 -1 0 0 2 - 12240 2250 12240 2520 -4 0 0 50 0 20 11 0.0000 4 150 870 11205 2430 video out loop\001 -4 0 0 50 0 20 11 0.0000 4 150 975 11520 2880 video out plugin\001 -4 0 0 50 0 20 11 0.0000 4 135 435 12330 2430 out fifo\001 --6 -6 11565 1620 12510 2250 -6 11700 1800 12375 2070 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 11700 1800 12375 1800 12375 2070 11700 2070 11700 1800 -4 0 0 20 0 20 11 0.0000 4 120 435 11790 1980 frames\001 --6 -3 2 0 1 0 7 50 0 -1 3.000 0 1 0 3 - 0 0 1.00 60.00 120.00 - 12060 2250 11565 1935 12060 1620 - 0.000 -1.000 0.000 -3 2 0 1 0 7 50 0 -1 3.000 0 1 0 3 - 0 0 1.00 60.00 120.00 - 12060 1620 12510 1935 12060 2250 - 0.000 -1.000 0.000 --6 -1 4 0 1 0 0 10 0 20 0.000 1 0.0000 7110 8640 10 10 7100 8640 7120 8640 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 7155 5850 6300 4500 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 4500 4500 3555 4500 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 2160 4500 2520 4500 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 57.26 114.51 - 3555 4500 4230 6300 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 6390 2700 7065 2700 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 57.26 114.51 - 3555 4500 4230 2700 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 6390 6300 7065 6300 -2 1 0 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 7155 3150 6300 4500 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 7290 3150 7965 4050 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 7290 5850 7965 4950 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 8550 3150 8550 4050 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 8325 4050 8325 3150 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 1215 1845 2205 1845 2205 1620 -2 1 2 1 0 7 50 0 -1 3.000 0 0 -1 0 0 2 - 2295 7560 2295 585 -2 1 2 1 0 7 50 0 -1 3.000 0 0 -1 0 0 2 - 3870 7560 3870 585 -2 1 2 1 0 7 50 0 -1 3.000 0 0 -1 0 0 2 - 6750 7560 6750 585 -2 1 1 1 0 7 50 0 -1 3.000 0 0 -1 0 0 2 - 9945 7560 9945 270 -2 1 0 1 0 7 50 0 -1 3.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 11520 4950 11250 5850 -2 1 0 1 0 7 50 0 -1 3.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 11520 4050 11250 3150 -2 1 0 1 0 7 50 0 -1 3.000 0 0 -1 1 1 2 - 0 0 1.00 60.00 120.00 - 0 0 1.00 60.00 120.00 - 8865 6570 11070 6570 -2 1 0 1 0 7 50 0 -1 3.000 0 0 -1 1 1 2 - 0 0 1.00 60.00 120.00 - 0 0 1.00 60.00 120.00 - 8865 2565 11070 2565 -2 1 0 1 0 7 50 0 -1 3.000 0 0 -1 1 1 3 - 0 0 1.00 60.00 120.00 - 0 0 1.00 60.00 120.00 - 8865 3060 9720 3060 11655 1620 -3 2 1 1 0 7 50 0 -1 4.000 0 1 0 5 - 0 0 1.00 60.00 120.00 - 4500 4365 3060 4365 2025 3915 1530 4275 2520 4365 - 0.000 -1.000 -1.000 -1.000 0.000 -3 2 0 1 0 7 50 0 -1 0.000 0 1 0 3 - 0 0 1.00 60.00 120.00 - 8865 6210 9290 5502 8865 4860 - 0.000 -1.000 0.000 -3 2 0 1 0 7 50 0 -1 0.000 0 0 1 3 - 0 0 1.00 60.00 120.00 - 8865 6390 9450 5490 8865 4725 - 0.000 -1.000 0.000 -3 2 0 1 0 7 50 0 -1 0.000 0 0 1 3 - 0 0 1.00 60.00 120.00 - 8865 4140 9405 3510 8865 2700 - 0.000 -1.000 0.000 -3 2 0 1 0 7 50 0 -1 0.000 0 0 1 3 - 0 0 1.00 60.00 120.00 - 8865 2610 9540 3510 8865 4275 - 0.000 -1.000 0.000 -3 2 1 1 0 7 50 0 -1 4.000 0 1 0 8 - 0 0 1.00 60.00 120.00 - 8865 6480 10485 6300 11160 5850 10890 5130 9720 4635 8730 4725 - 8190 5490 8595 6120 - 0.000 -1.000 -1.000 -1.000 -1.000 -1.000 -1.000 0.000 -3 2 1 1 0 7 50 0 -1 4.000 0 1 0 7 - 0 0 1.00 60.00 120.00 - 8865 2700 10665 2745 11160 3375 10215 4230 8730 4275 7920 3780 - 7740 3150 - 0.000 -1.000 -1.000 -1.000 -1.000 -1.000 0.000 -3 2 2 1 0 7 50 0 -1 1.000 0 1 0 3 - 0 0 1.00 60.00 120.00 - 3285 4950 3285 5445 3735 5355 - 0.000 -1.000 0.000 -3 2 2 1 0 7 50 0 -1 1.000 0 1 0 4 - 0 0 1.00 60.00 120.00 - 3555 4185 3735 3825 3330 3510 3780 3375 - 0.000 -1.000 -1.000 0.000 -3 2 2 1 0 7 50 0 -1 1.000 0 1 0 3 - 0 0 1.00 60.00 120.00 - 6570 6210 6570 5940 7065 5895 - 0.000 -1.000 0.000 -3 2 2 1 0 7 50 0 -1 1.000 0 1 0 3 - 0 0 1.00 60.00 120.00 - 6570 2610 6570 2295 7065 2295 - 0.000 -1.000 0.000 -3 2 2 1 0 7 50 0 -1 1.000 0 1 0 3 - 0 0 1.00 60.00 120.00 - 7155 2250 8190 1845 9090 2385 - 0.000 -1.000 0.000 -3 2 2 1 0 7 50 0 -1 1.000 0 1 0 4 - 0 0 1.00 60.00 120.00 - 7110 5940 6975 6795 8010 7290 9090 6570 - 0.000 -1.000 -1.000 0.000 -4 0 0 50 0 20 11 0.0000 4 135 585 7605 8685 extra info\001 diff --git a/doc/hackersguide/architecture.svg b/doc/hackersguide/architecture.svg new file mode 100644 index 000000000..2bc41c638 --- /dev/null +++ b/doc/hackersguide/architecture.svg @@ -0,0 +1,2134 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + + demuxer plugin + demuxer loop + + buf + + buf + + buf + + buf + + buf + + buf + + buf + + buffer pool + + input plugin + + metronom + + xine stream + + stream layer + + decoder layer + + stream fifos + + demuxer layer + + input layer + + + + metronom clock + clock sync loop + scr plugin + + output layer + + + + overlay manager + OSD + + + extra info datapath + + + detailed datapath + + + datapath + xine buffer + discontinuity + presentation timestamp + virtual presentation timestamp + subpicture unit + + buf + + buf + + buf + + buf + + video fifo + ... + + buf + + buf + + buf + + buf + + audio fifo + ... + + + audio decoder loop + audio decoder plugin + + + + video decoder loop + spu decoder plugin + video decoder plugin + + + + audio out loop + audio out plugin + out fifo + + + + video out loop + video out plugin + out fifo + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + extra info + post + plugins + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + buf + buf + buf + buf + disc + disc + pts + vpts + pts + pts + vpts + time + time + spu + pts + vpts + vpts + vpts + pts + buf + disc + pts + vpts + spu + buf + buf + buf + buf + frames + samples + frames + + + + + + + + + + + + + + + + + + + diff --git a/doc/hackersguide/library.fig b/doc/hackersguide/library.fig deleted file mode 100644 index 13dc79f0e..000000000 --- a/doc/hackersguide/library.fig +++ /dev/null @@ -1,313 +0,0 @@ -#FIG 3.2 -Landscape -Center -Metric -A4 -100.00 -Single --2 -1200 2 -6 900 405 1350 855 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 900 450 1080 450 1080 855 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 1170 855 1170 450 1350 450 --6 -6 1890 7470 3330 7965 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 1890 7470 3330 7470 3330 7965 1890 7965 1890 7470 -4 0 0 50 0 20 11 0.0000 4 150 885 2205 7740 xine_stream_t\001 --6 -6 3330 7335 4365 8055 -2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 7 - 3330 7695 3510 7335 4185 7335 4365 7695 4185 8055 3510 8055 - 3330 7695 -4 0 0 50 0 20 11 0.0000 4 165 930 3420 7740 xine_post_wire\001 --6 -6 3915 6210 7335 8235 -6 4770 6705 5220 7155 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 4770 6750 4950 6750 4950 7155 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 5040 7155 5040 6750 5220 6750 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 4635 7425 5445 7425 5445 7155 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4635 7155 7065 7155 7065 8235 4635 8235 4635 7155 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 - 4635 8235 4365 8235 4365 7155 4635 7155 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 - 7065 8235 7335 8235 7335 7155 7065 7155 -4 0 0 50 0 20 11 0.0000 4 165 1785 3915 6570 xine_list_post_plugins_typed\001 -4 0 0 50 0 20 11 0.0000 4 165 1365 3915 6345 xine_list_post_plugins\001 -4 0 0 50 0 20 11 0.0000 4 165 1155 5265 6795 xine_post_dispose\001 -4 0 0 50 0 20 11 0.0000 4 165 720 4680 7335 xine_post_t\001 -4 0 0 50 0 20 11 0.0000 4 165 855 3915 6795 xine_post_init\001 -4 0 0 50 0 20 11 1.5708 4 165 900 4545 8100 xine_post_in_t\001 -4 0 0 50 0 20 11 1.5708 4 165 990 7245 8145 xine_post_out_t\001 -4 0 0 50 0 20 11 0.0000 4 165 1065 6075 7875 xine_post_output\001 -4 0 0 50 0 20 11 0.0000 4 165 1395 4680 7875 xine_post_list_outputs\001 -4 0 0 50 0 20 11 0.0000 4 165 1305 4680 7650 xine_post_list_inputs\001 -4 0 0 50 0 20 11 0.0000 4 165 975 6075 7650 xine_post_input\001 --6 -6 7335 7335 8370 8055 -2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 7 - 7335 7695 7515 7335 8190 7335 8370 7695 8190 8055 7515 8055 - 7335 7695 -4 0 0 50 0 20 11 0.0000 4 165 930 7425 7740 xine_post_wire\001 --6 -6 8370 7425 9630 7920 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 8390 7438 9630 7438 9630 7920 8390 7920 8390 7438 -4 0 0 50 0 20 11 0.0000 4 165 720 8705 7708 xine_post_t\001 --6 -6 9630 7335 11520 8055 -2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 7 - 9630 7695 9810 7335 11340 7335 11520 7695 11340 8055 9810 8055 - 9630 7695 -4 0 0 50 0 20 11 0.0000 4 165 1650 9765 7740 xine_post_wire_video_port\001 --6 -6 11520 7425 12780 7920 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 11540 7438 12780 7438 12780 7920 11540 7920 11540 7438 -4 0 0 50 0 20 11 0.0000 4 165 1095 11655 7708 xine_video_port_t\001 --6 -6 2250 5580 2970 7470 -2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 7 - 2610 7470 2250 7290 2250 5760 2610 5580 2970 5760 2970 7290 - 2610 7470 -4 0 0 50 0 20 11 1.5708 4 150 1680 2655 7335 xine_stream_master_slave\001 --6 -6 10215 2565 13635 4005 -6 11655 2790 12105 3240 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 11655 2835 11835 2835 11835 3240 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 11925 3240 11925 2835 12105 2835 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 11520 3510 12690 3510 12690 3240 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 11520 3240 13590 3240 13590 4005 11520 4005 11520 3240 -4 0 0 50 0 20 11 0.0000 4 165 1890 10215 2700 xine_list_video_output_plugins\001 -4 0 0 50 0 20 11 0.0000 4 150 1485 12150 2880 xine_close_video_driver\001 -4 0 0 50 0 20 11 0.0000 4 165 1455 10215 2880 xine_open_video_driver\001 -4 0 0 50 0 20 11 0.0000 4 165 1095 11565 3420 xine_video_port_t\001 -4 0 0 50 0 20 11 0.0000 4 165 1545 11655 3780 xine_port_send_gui_data\001 --6 -6 9630 4995 11520 5715 -2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 7 - 9630 5355 9810 4995 11340 4995 11520 5355 11340 5715 9810 5715 - 9630 5355 -4 0 0 50 0 20 11 0.0000 4 165 1650 9765 5400 xine_post_wire_audio_port\001 --6 -6 8370 5085 9630 5580 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 8390 5098 9630 5098 9630 5580 8390 5580 8390 5098 -4 0 0 50 0 20 11 0.0000 4 165 720 8705 5368 xine_post_t\001 --6 -6 10215 4185 13635 5625 -6 11655 4410 12105 4860 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 11655 4455 11835 4455 11835 4860 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 11925 4860 11925 4455 12105 4455 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 11520 5130 12690 5130 12690 4860 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 11520 4860 13590 4860 13590 5625 11520 5625 11520 4860 -4 0 0 50 0 20 11 0.0000 4 165 1890 10215 4320 xine_list_audio_output_plugins\001 -4 0 0 50 0 20 11 0.0000 4 150 1485 12150 4500 xine_close_audio_driver\001 -4 0 0 50 0 20 11 0.0000 4 165 1455 10215 4500 xine_open_audio_driver\001 -4 0 0 50 0 20 11 0.0000 4 165 1095 11565 5040 xine_audio_port_t\001 --6 -6 945 3060 7290 5580 -6 2025 3105 2475 3555 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 2025 3150 2205 3150 2205 3555 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 2295 3555 2295 3150 2475 3150 --6 -6 7020 3555 7290 5580 -6 7065 3555 7245 4545 -4 0 0 50 0 20 11 1.5708 4 165 990 7200 4545 xine_post_out_t\001 --6 -6 7065 4545 7245 5535 -4 0 0 50 0 20 11 1.5708 4 165 990 7200 5535 xine_post_out_t\001 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 - 7020 4590 7290 4590 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 4 - 7020 5580 7290 5580 7290 3555 7020 3555 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 1890 3825 2835 3825 2835 3555 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 1890 3555 7020 3555 7020 5580 1890 5580 1890 3555 -4 0 0 50 0 20 11 0.0000 4 165 885 3015 4545 xine_get_error\001 -4 0 0 50 0 20 11 0.0000 4 165 990 3015 4770 xine_get_status\001 -4 0 0 50 0 20 11 0.0000 4 165 1275 3015 4995 xine_get_pos_length\001 -4 0 0 50 0 20 11 0.0000 4 165 1260 3015 5220 xine_get_audio_lang\001 -4 0 0 50 0 20 11 0.0000 4 165 1155 3015 5445 xine_get_spu_lang\001 -4 0 0 50 0 20 11 0.0000 4 165 630 2115 4095 xine_open\001 -4 0 0 50 0 20 11 0.0000 4 165 585 2115 4320 xine_play\001 -4 0 0 50 0 20 11 0.0000 4 165 600 2115 4545 xine_stop\001 -4 0 0 50 0 20 11 0.0000 4 150 660 2115 4770 xine_close\001 -4 0 0 50 0 20 11 0.0000 4 165 630 2115 4995 xine_eject\001 -4 0 0 50 0 20 11 0.0000 4 165 990 3015 4095 xine_set_param\001 -4 0 0 50 0 20 11 0.0000 4 165 990 3015 4320 xine_get_param\001 -4 0 0 50 0 20 11 0.0000 4 165 1320 2520 3195 xine_stream_dispose\001 -4 0 0 50 0 20 11 0.0000 4 150 885 1935 3735 xine_stream_t\001 -4 0 0 50 0 20 11 0.0000 4 150 1095 945 3195 xine_stream_new\001 -4 0 0 50 0 20 11 0.0000 4 165 1470 5535 4095 xine_get_current_frame\001 -4 0 0 50 0 20 11 0.0000 4 165 1380 5535 4320 xine_get_current_vpts\001 -4 0 0 50 0 20 11 0.0000 4 150 1020 5535 4545 xine_trick_mode\001 -4 0 0 50 0 20 11 0.0000 4 165 1425 5535 4995 xine_get_audio_source\001 -4 0 0 50 0 20 11 0.0000 4 165 1425 5535 5220 xine_get_video_source\001 -4 0 0 50 0 20 11 0.0000 4 165 1335 4185 4095 xine_get_stream_info\001 -4 0 0 50 0 20 11 0.0000 4 165 1215 4185 4320 xine_get_meta_info\001 --6 -6 945 1260 2430 1890 -4 0 0 50 0 20 11 0.0000 4 150 510 945 1395 xine_init\001 -4 0 0 50 0 20 11 0.0000 4 165 1470 945 1620 xine_engine_set_param\001 -4 0 0 50 0 20 11 0.0000 4 165 1470 945 1845 xine_engine_get_param\001 --6 -6 5850 1260 8055 2790 -4 0 0 50 0 20 11 0.0000 4 165 1395 5850 1395 xine_get_browse_mrls\001 -4 0 0 50 0 20 11 0.0000 4 165 2190 5850 1620 xine_get_autoplay_input_plugin_ids\001 -4 0 0 50 0 20 11 0.0000 4 165 1470 5850 1845 xine_get_autoplay_mrls\001 -4 0 0 50 0 20 11 0.0000 4 165 1530 5850 2070 xine_get_file_extensions\001 -4 0 0 50 0 20 11 0.0000 4 165 1365 5850 2295 xine_get_mime_types\001 -4 0 0 50 0 20 11 0.0000 4 165 2025 5850 2520 xine_get_demux_for_mime_type\001 -4 0 0 50 0 20 11 0.0000 4 165 2085 5850 2745 xine_get_input_plugin_description\001 --6 -6 3960 1260 5670 2340 -4 0 0 50 0 20 11 0.0000 4 165 1380 3960 1395 xine_config_register_*\001 -4 0 0 50 0 20 11 0.0000 4 165 1680 3960 1620 xine_config_get_first_entry\001 -4 0 0 50 0 20 11 0.0000 4 165 1710 3960 1845 xine_config_get_next_entry\001 -4 0 0 50 0 20 11 0.0000 4 165 1575 3960 2070 xine_config_lookup_entry\001 -4 0 0 50 0 20 11 0.0000 4 165 1590 3960 2295 xine_config_update_entry\001 --6 -6 2655 1260 3780 1890 -4 0 0 50 0 20 11 0.0000 4 165 1035 2655 1395 xine_config_load\001 -4 0 0 50 0 20 11 0.0000 4 165 1080 2655 1620 xine_config_save\001 -4 0 0 50 0 20 11 0.0000 4 165 1095 2655 1845 xine_config_reset\001 --6 -6 2655 9630 6345 12150 -6 4005 9675 4455 10125 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 4005 9720 4185 9720 4185 10125 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 4275 10125 4275 9720 4455 9720 --6 -6 3825 10485 6255 11295 -6 4725 10575 5175 11025 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 4725 10620 4905 10620 4905 11025 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 4995 11025 4995 10620 5175 10620 --6 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4455 11025 5445 11025 5445 11295 4455 11295 4455 11025 -4 0 0 50 0 20 11 0.0000 4 150 795 4590 11205 xine_event_t\001 -4 0 0 50 0 20 11 0.0000 4 150 990 5265 10665 xine_event_free\001 -4 0 0 50 0 20 11 0.0000 4 165 945 3825 10620 xine_event_get\001 -4 0 0 50 0 20 11 0.0000 4 150 1005 3825 10755 xine_event_wait\001 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 3690 10395 5085 10395 5085 10125 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 3690 10125 6345 10125 6345 11700 3690 11700 3690 10125 -4 0 0 50 0 20 11 0.0000 4 165 1455 2655 9765 xine_event_new_queue\001 -4 0 0 50 0 20 11 0.0000 4 165 1680 4545 9765 xine_event_dispose_queue\001 -4 0 0 50 0 20 11 0.0000 4 165 1245 3780 10305 xine_event_queue_t\001 -4 0 0 50 0 20 11 0.0000 4 150 2130 3825 11565 xine_event_create_listener_thread\001 -4 0 0 50 0 20 11 0.0000 4 150 1050 2655 12105 xine_event_send\001 --6 -6 8415 1260 10710 2340 -4 0 0 50 0 22 11 0.0000 4 165 1605 8415 1395 xine_list_input_plugins\001 -4 0 0 50 0 22 11 0.0000 4 165 1830 8415 1620 xine_list_demuxer_plugins\001 -4 0 0 50 0 22 11 0.0000 4 165 2250 8415 1845 xine_list_video_decoder_plugins\001 -4 0 0 50 0 22 11 0.0000 4 165 2265 8415 2070 xine_list_audio_decoder_plugins\001 -4 0 0 50 0 22 11 0.0000 4 165 1500 8415 2295 xine_list_spu_plugins\001 --6 -6 11115 1260 12870 2340 -4 0 0 50 0 20 11 0.0000 4 165 1725 11115 1395 xine_get_log_section_count\001 -4 0 0 50 0 20 11 0.0000 4 165 1275 11115 1620 xine_get_log_names\001 -4 0 0 50 0 20 11 0.0000 4 165 510 11115 1845 xine_log\001 -4 0 0 50 0 20 11 0.0000 4 165 780 11115 2070 xine_get_log\001 -4 0 0 50 0 20 11 0.0000 4 165 1275 11115 2295 xine_register_log_cb\001 --6 -6 6930 9630 11205 11925 -6 7785 9675 8235 10125 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 7785 9720 7965 9720 7965 10125 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 0 0 1.00 60.00 120.00 - 8055 10125 8055 9720 8235 9720 --6 -6 7605 10485 9225 11790 -4 0 0 50 0 20 11 0.0000 4 150 1065 7605 10620 xine_osd_draw_*\001 -4 0 0 50 0 20 11 0.0000 4 165 1455 7605 11520 xine_osd_set_encoding\001 -4 0 0 50 0 20 11 0.0000 4 150 1140 7605 11295 xine_osd_set_font\001 -4 0 0 50 0 20 11 0.0000 4 165 1470 7605 11070 xine_osd_get_text_size\001 -4 0 0 50 0 20 11 0.0000 4 165 1380 7605 11745 xine_osd_set_position\001 -4 0 0 50 0 20 11 0.0000 4 165 1590 7605 10845 xine_osd_get_capabilities\001 --6 -6 9405 10260 11070 11790 -4 0 0 50 0 20 11 0.0000 4 150 960 9405 10395 xine_osd_show\001 -4 0 0 50 0 20 11 0.0000 4 165 1320 9405 11520 xine_osd_get_palette\001 -4 0 0 50 0 20 11 0.0000 4 165 1635 9405 11295 xine_osd_set_text_palette\001 -4 0 0 50 0 20 11 0.0000 4 150 930 9405 11070 xine_osd_clear\001 -4 0 0 50 0 20 11 0.0000 4 150 885 9405 10845 xine_osd_hide\001 -4 0 0 50 0 20 11 0.0000 4 150 1590 9405 10620 xine_osd_show_unscaled\001 -4 0 0 50 0 20 11 0.0000 4 165 1320 9405 11745 xine_osd_set_palette\001 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 7470 10395 8325 10395 8325 10125 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 7470 10125 11205 10125 11205 11925 7470 11925 7470 10125 -4 0 0 50 0 20 11 0.0000 4 150 870 8325 9765 xine_osd_free\001 -4 0 0 50 0 20 11 0.0000 4 150 675 7560 10305 xine_osd_t\001 -4 0 0 50 0 20 11 0.0000 4 150 885 6930 9765 xine_osd_new\001 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 765 1125 1350 1125 1350 855 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 765 855 14085 855 14085 8595 765 8595 765 855 -2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 7 - 7290 3780 7470 3420 11340 3420 11520 3780 11340 4140 7470 4140 - 7290 3780 -2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 7 - 7290 5355 7470 4995 8190 4995 8370 5355 8190 5715 7470 5715 - 7290 5355 -2 1 2 1 0 7 50 0 -1 3.000 0 0 -1 0 0 2 - 2520 9000 1890 7470 -2 1 2 1 0 7 50 0 -1 3.000 0 0 -1 0 0 2 - 1890 7965 2520 12510 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 2520 9270 3555 9270 3555 9000 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 2520 9000 11745 9000 11745 12510 2520 12510 2520 9000 -4 0 0 50 0 20 11 0.0000 4 150 375 855 1035 xine_t\001 -4 0 0 50 0 20 11 0.0000 4 150 555 1395 495 xine_exit\001 -4 0 0 50 0 20 11 0.0000 4 150 585 315 495 xine_new\001 -4 0 0 50 0 20 11 0.0000 4 150 1155 2790 495 xine_health_check\001 -4 0 0 50 0 20 11 0.0000 4 150 885 2610 9180 xine_stream_t\001 diff --git a/doc/hackersguide/library.svg b/doc/hackersguide/library.svg new file mode 100644 index 000000000..d8a5728b2 --- /dev/null +++ b/doc/hackersguide/library.svg @@ -0,0 +1,1732 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + xine_stream_t + + xine_post_wire + + + + + + + + + xine_list_post_plugins_typed + xine_list_post_plugins + xine_post_dispose + xine_post_t + xine_post_init + + xine_post_in_t + + + xine_post_out_t + + xine_post_output + xine_post_list_outputs + xine_post_list_inputs + xine_post_input + + xine_post_wire + + xine_post_t + + xine_post_wire_video_port + + xine_video_port_t + + + xine_stream_master_slave + + + + + + + + xine_list_video_output_plugins + xine_close_video_driver + xine_open_video_driver + xine_video_port_t + xine_port_send_gui_data + + xine_post_wire_audio_port + + xine_post_t + + + + + + + xine_list_audio_output_plugins + xine_close_audio_driver + xine_open_audio_driver + xine_audio_port_t + + + + + + xine_post_out_t + + + xine_post_out_t + + + + + + xine_get_error + xine_get_status + xine_get_pos_length + xine_get_audio_lang + xine_get_spu_lang + xine_open + xine_play + xine_stop + xine_close + xine_eject + xine_set_param + xine_get_param + xine_stream_dispose + xine_stream_t + xine_stream_new + xine_get_current_frame + xine_get_current_vpts + xine_trick_mode + xine_get_audio_source + xine_get_video_source + xine_get_stream_info + xine_get_meta_info + xine_init + xine_engine_set_param + xine_engine_get_param + xine_get_browse_mrls + xine_get_autoplay_input_plugin_ids + xine_get_autoplay_mrls + xine_get_file_extensions + xine_get_mime_types + xine_get_demux_for_mime_type + xine_get_input_plugin_description + xine_config_register_* + xine_config_get_first_entry + xine_config_get_next_entry + xine_config_lookup_entry + xine_config_update_entry + xine_config_load + xine_config_save + xine_config_reset + + + + + + + + + + xine_event_t + xine_event_free + xine_event_get + xine_event_wait + + + xine_event_new_queue + xine_event_dispose_queue + xine_event_queue_t + xine_event_create_listener_thread + xine_event_send + xine_list_input_plugins + xine_list_demuxer_plugins + xine_list_video_decoder_plugins + xine_list_audio_decoder_plugins + xine_list_spu_plugins + xine_get_log_section_count + xine_get_log_names + xine_log + xine_get_log + xine_register_log_cb + + + + + xine_osd_draw_* + xine_osd_set_encoding + xine_osd_set_font + xine_osd_get_text_size + xine_osd_set_position + xine_osd_get_capabilities + xine_osd_show + xine_osd_get_palette + xine_osd_set_text_palette + xine_osd_clear + xine_osd_hide + xine_osd_show_unscaled + xine_osd_set_palette + + + xine_osd_free + xine_osd_t + xine_osd_new + + + + + + + + + xine_t + xine_exit + xine_new + xine_health_check + xine_stream_t + + diff --git a/doc/hackersguide/overlays.fig b/doc/hackersguide/overlays.fig deleted file mode 100644 index 0301aead2..000000000 --- a/doc/hackersguide/overlays.fig +++ /dev/null @@ -1,64 +0,0 @@ -#FIG 3.2 -Portrait -Center -Metric -A4 -100.00 -Single --2 -1200 2 -0 32 #ffffff -6 3600 2340 5670 3555 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 3600 2340 5670 2340 5670 3555 3600 3555 3600 2340 -4 0 0 50 0 20 14 0.0000 4 165 1050 4140 3015 OSD renderer\001 --6 -6 495 3825 2700 4365 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 495 3825 2700 3825 2700 4365 495 4365 495 3825 -4 0 0 50 0 20 14 0.0000 4 195 1320 900 4185 public libxine API\001 --6 -6 495 2880 2700 3420 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 495 2880 2700 2880 2700 3420 495 3420 495 2880 -4 0 0 50 0 20 14 0.0000 4 195 1830 675 3240 libsputext (text subtitles)\001 --6 -6 495 2160 2700 2700 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 495 2160 2700 2160 2700 2700 495 2700 495 2160 -4 0 0 50 0 20 14 0.0000 4 195 1965 585 2520 libspucc (closed captions)\001 --6 -6 6435 1575 8865 2790 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 6435 1575 8865 1575 8865 2790 6435 2790 6435 1575 -4 0 0 50 0 20 14 0.0000 4 210 1260 6975 2250 overlay manager\001 --6 -6 6435 3780 8865 4995 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 6435 3780 8865 3780 8865 4995 6435 4995 6435 3780 -4 0 0 50 0 20 14 0.0000 4 165 675 7290 4455 video out\001 --6 -6 495 1440 2700 1980 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 495 1440 2700 1440 2700 1980 495 1980 495 1440 -4 0 0 50 0 20 14 0.0000 4 195 1920 585 1800 libspudec (DVD subtitles)\001 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 4 - 0 0 1.00 60.00 120.00 - 2700 4095 3105 4095 3105 3375 3600 3375 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 2700 1710 6435 1710 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 2700 3150 3600 3150 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 1 2 - 0 0 1.00 60.00 120.00 - 0 0 1.00 60.00 120.00 - 7650 2790 7650 3780 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 5670 2565 6435 2565 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 2700 2430 3600 2430 diff --git a/doc/hackersguide/overlays.svg b/doc/hackersguide/overlays.svg new file mode 100644 index 000000000..af8cc3572 --- /dev/null +++ b/doc/hackersguide/overlays.svg @@ -0,0 +1,256 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + OSD renderer + + public libxine API + + libsputext (text subtitles) + + libspucc (closed captions) + + overlay manager + + video out + + libspudec (DVD subtitles) + + + + + + + + + + + + + + + diff --git a/doc/hackersguide/post_frame.fig b/doc/hackersguide/post_frame.fig deleted file mode 100644 index 4f576abdd..000000000 --- a/doc/hackersguide/post_frame.fig +++ /dev/null @@ -1,347 +0,0 @@ -#FIG 3.2 -Landscape -Center -Metric -A4 -100.00 -Single --2 -1200 2 -6 2970 585 9360 9945 -2 1 0 2 0 7 50 0 -1 0.000 0 0 -1 0 0 3 - 3015 900 3915 900 3915 630 -2 2 0 2 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 3015 630 9315 630 9315 9900 3015 9900 3015 630 -4 0 0 50 0 20 11 0.0000 4 165 675 3105 810 post plugin\001 --6 -6 5040 1125 7200 1530 -2 2 0 1 0 4 40 0 20 0.000 0 0 -1 0 0 5 - 5040 1125 7200 1125 7200 1530 5040 1530 5040 1125 -4 0 0 30 0 20 11 0.0000 4 165 1545 5220 1395 _x_post_intercept_frame\001 --6 -6 3645 990 4635 1620 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 3735 1080 4635 1080 4635 1620 3735 1620 3735 1080 -2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 - 3645 990 4545 990 4545 1530 3645 1530 3645 990 --6 -6 5040 2160 7200 2565 -2 2 0 1 0 7 40 0 20 0.000 0 0 -1 0 0 5 - 5040 2160 7200 2160 7200 2565 5040 2565 5040 2160 -4 0 0 30 0 20 11 0.0000 4 165 1710 5220 2430 _x_post_frame_copy_down\001 --6 -6 5040 3060 7200 3465 -2 2 0 1 0 7 40 0 20 0.000 0 0 -1 0 0 5 - 5040 3060 7200 3060 7200 3465 5040 3465 5040 3060 -4 0 0 30 0 20 11 0.0000 4 165 1530 5220 3330 _x_post_frame_copy_up\001 --6 -6 3645 2025 4635 2655 -2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 - 3645 2025 4545 2025 4545 2565 3645 2565 3645 2025 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 3735 2115 4635 2115 4635 2655 3735 2655 3735 2115 -4 0 0 20 0 18 25 0.0000 4 270 225 3825 2430 d\001 --6 -6 7830 2025 8820 2655 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 7920 2115 8820 2115 8820 2655 7920 2655 7920 2115 -2 2 0 1 0 4 30 0 -1 0.000 0 0 -1 0 0 5 - 7830 2025 8730 2025 8730 2565 7830 2565 7830 2025 -4 0 0 20 0 18 25 0.0000 4 270 225 8100 2520 d\001 --6 -6 7830 2925 8820 3555 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 7920 3015 8820 3015 8820 3555 7920 3555 7920 3015 -2 2 0 1 0 4 30 0 -1 0.000 0 0 -1 0 0 5 - 7830 2925 8730 2925 8730 3465 7830 3465 7830 2925 -4 0 0 20 0 18 25 0.0000 4 285 555 8100 3420 d u\001 --6 -6 3645 2925 4635 3555 -2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 - 3645 2925 4545 2925 4545 3465 3645 3465 3645 2925 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 3735 3015 4635 3015 4635 3555 3735 3555 3735 3015 -4 0 0 20 0 18 25 0.0000 4 285 555 3825 3330 d u\001 --6 -6 7875 4725 8775 5265 -2 2 0 1 0 3 40 0 15 0.000 0 0 -1 0 0 5 - 7875 4725 8775 4725 8775 5265 7875 5265 7875 4725 -4 0 0 20 0 18 25 0.0000 4 270 225 8055 5130 d\001 --6 -6 3645 4005 4635 4635 -2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 - 3645 4005 4545 4005 4545 4545 3645 4545 3645 4005 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 3735 4095 4635 4095 4635 4635 3735 4635 3735 4095 -4 0 0 20 0 18 25 0.0000 4 270 225 3825 4410 d\001 --6 -6 7875 6300 8775 6840 -2 2 0 1 0 3 40 0 15 0.000 0 0 -1 0 0 5 - 7875 6300 8775 6300 8775 6840 7875 6840 7875 6300 -4 0 0 20 0 18 25 0.0000 4 285 555 8055 6705 d u\001 --6 -6 7875 5625 8775 6165 -2 2 0 1 0 3 40 0 15 0.000 0 0 -1 0 0 5 - 7875 5625 8775 5625 8775 6165 7875 6165 7875 5625 -4 0 0 20 0 18 25 0.0000 4 285 555 8055 6030 d u\001 --6 -6 3645 7245 4635 7875 -2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 - 3645 7245 4545 7245 4545 7785 3645 7785 3645 7245 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 3735 7335 4635 7335 4635 7875 3735 7875 3735 7335 -4 0 0 20 0 18 25 0.0000 4 270 225 3825 7650 d\001 --6 -6 3645 8145 4635 8775 -2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 - 3645 8145 4545 8145 4545 8685 3645 8685 3645 8145 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 3735 8235 4635 8235 4635 8775 3735 8775 3735 8235 -4 0 0 20 0 18 25 0.0000 4 285 555 3825 8550 d u\001 --6 -6 5040 7830 7200 8235 -2 2 0 1 0 7 40 0 20 0.000 0 0 -1 0 0 5 - 5040 7830 7200 7830 7200 8235 5040 8235 5040 7830 -4 0 0 30 0 20 11 0.0000 4 165 1395 5220 8100 _x_post_frame_u_turn\001 --6 -6 990 1125 2340 1530 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 990 1125 2340 1125 2340 1530 990 1530 990 1125 -4 0 0 50 0 20 11 0.0000 4 165 630 1170 1395 get_frame\001 --6 -6 990 2025 2340 3510 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 990 2025 2340 2025 2340 3510 990 3510 990 2025 -4 0 0 50 0 20 11 0.0000 4 120 255 1170 2475 field\001 -4 0 0 50 0 20 11 0.0000 4 120 255 1170 2700 lock\001 -4 0 0 50 0 20 11 0.0000 4 165 705 1170 2925 proc_frame\001 -4 0 0 50 0 20 11 0.0000 4 165 630 1170 3150 proc_slice\001 -4 0 0 50 0 20 11 0.0000 4 165 1065 1170 3375 proc_macroblock\001 -4 0 0 50 0 20 11 0.0000 4 120 300 1170 2250 draw\001 --6 -6 990 4095 2340 6795 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 990 4095 2340 4095 2340 6795 990 6795 990 4095 -4 0 0 50 0 20 11 0.0000 4 120 255 1170 4555 field\001 -4 0 0 50 0 20 11 0.0000 4 120 255 1170 4761 lock\001 -4 0 0 50 0 20 11 0.0000 4 165 705 1170 4969 proc_frame\001 -4 0 0 50 0 20 11 0.0000 4 165 630 1170 5175 proc_slice\001 -4 0 0 50 0 20 11 0.0000 4 165 1065 1170 5383 proc_macroblock\001 -4 0 0 50 0 20 11 0.0000 4 120 300 1170 4347 draw\001 --6 -6 990 7335 2340 8640 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 990 7335 2340 7335 2340 8640 990 8640 990 7335 -4 0 0 50 0 20 11 0.0000 4 120 300 1170 7605 draw\001 --6 -6 9990 1125 11340 1530 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 9990 1125 11340 1125 11340 1530 9990 1530 9990 1125 -4 0 0 50 0 20 11 0.0000 4 165 630 10170 1395 get_frame\001 --6 -6 9990 2025 11340 3510 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 9990 2025 11340 2025 11340 3510 9990 3510 9990 2025 -4 0 0 50 0 20 11 0.0000 4 120 255 10170 2475 field\001 -4 0 0 50 0 20 11 0.0000 4 120 255 10170 2700 lock\001 -4 0 0 50 0 20 11 0.0000 4 165 705 10170 2925 proc_frame\001 -4 0 0 50 0 20 11 0.0000 4 165 630 10170 3150 proc_slice\001 -4 0 0 50 0 20 11 0.0000 4 165 1065 10170 3375 proc_macroblock\001 -4 0 0 50 0 20 11 0.0000 4 120 300 10170 2250 draw\001 --6 -6 9990 4140 11340 4545 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 9990 4140 11340 4140 11340 4545 9990 4545 9990 4140 -4 0 0 50 0 20 11 0.0000 4 165 630 10170 4410 get_frame\001 --6 -6 9990 4725 11340 6210 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 9990 4725 11340 4725 11340 6210 9990 6210 9990 4725 -4 0 0 50 0 20 11 0.0000 4 120 255 10170 5175 field\001 -4 0 0 50 0 20 11 0.0000 4 120 255 10170 5400 lock\001 -4 0 0 50 0 20 11 0.0000 4 165 705 10170 5625 proc_frame\001 -4 0 0 50 0 20 11 0.0000 4 165 630 10170 5850 proc_slice\001 -4 0 0 50 0 20 11 0.0000 4 165 1065 10170 6075 proc_macroblock\001 -4 0 0 50 0 20 11 0.0000 4 120 300 10170 4950 draw\001 --6 -6 9990 6390 11340 6795 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 9990 6390 11340 6390 11340 6795 9990 6795 9990 6390 -4 0 0 50 0 20 11 0.0000 4 120 240 10170 6660 free\001 --6 -6 180 585 765 1755 -2 2 0 2 0 7 20 0 -1 6.000 0 0 -1 0 0 5 - 225 630 720 630 720 1710 225 1710 225 630 -4 0 0 20 0 20 15 1.5708 4 210 960 540 1665 interception\001 --6 -6 180 1890 765 3735 -2 2 0 2 0 7 20 0 -1 6.000 0 0 -1 0 0 5 - 225 1935 720 1935 720 3690 225 3690 225 1935 -4 0 0 20 0 20 15 1.5708 4 225 1065 540 3375 pass through\001 --6 -6 180 3870 765 7020 -2 2 0 2 0 7 20 0 -1 6.000 0 0 -1 0 0 5 - 225 3915 720 3915 720 6975 225 6975 225 3915 -4 0 0 20 0 20 15 1.5708 4 225 1380 540 6165 modifying a copy\001 --6 -6 180 7155 765 8910 -2 2 0 2 0 7 20 0 -1 6.000 0 0 -1 0 0 5 - 225 7200 720 7200 720 8865 225 8865 225 7200 -4 0 0 20 0 20 15 1.5708 4 180 1245 540 8685 dead-end draw\001 --6 -6 180 9045 765 9945 -2 2 0 2 0 7 20 0 -1 6.000 0 0 -1 0 0 5 - 225 9090 720 9090 720 9900 225 9900 225 9090 -4 0 0 20 0 20 15 1.5708 4 225 570 540 9810 freeing\001 --6 -6 5040 4455 7200 4860 -2 2 0 1 0 7 40 0 20 0.000 0 0 -1 0 0 5 - 5040 4455 7200 4455 7200 4860 5040 4860 5040 4455 -4 0 0 30 0 20 11 0.0000 4 165 1710 5220 4725 _x_post_frame_copy_down\001 --6 -6 5040 6030 7200 6435 -2 2 0 1 0 7 40 0 20 0.000 0 0 -1 0 0 5 - 5040 6030 7200 6030 7200 6435 5040 6435 5040 6030 -4 0 0 30 0 20 11 0.0000 4 165 1530 5220 6300 _x_post_frame_copy_up\001 --6 -6 3645 6255 4635 6885 -2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 - 3645 6255 4545 6255 4545 6795 3645 6795 3645 6255 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 3735 6345 4635 6345 4635 6885 3735 6885 3735 6345 -4 0 0 20 0 18 25 0.0000 4 285 555 3825 6660 d u\001 --6 -6 5040 9270 7200 9675 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 5040 9270 7200 9270 7200 9675 5040 9675 5040 9270 -4 0 0 30 0 20 11 0.0000 4 165 1845 5220 9540 _x_post_restore_video_frame\001 --6 -6 990 9270 2340 9675 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 990 9270 2340 9270 2340 9675 990 9675 990 9270 -4 0 0 50 0 20 11 0.0000 4 165 855 1170 9540 free / dispose\001 --6 -6 9990 9270 11340 9675 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 9990 9270 11340 9270 11340 9675 9990 9675 9990 9270 -4 0 0 50 0 20 11 0.0000 4 165 855 10170 9540 free / dispose\001 --6 -6 6660 4995 7515 5580 -2 3 0 1 0 7 50 0 15 0.000 0 0 -1 0 0 4 - 7065 4995 6840 5220 7290 5220 7065 4995 -4 0 0 50 0 20 11 0.0000 4 150 825 6660 5400 modify frame\001 -4 0 0 50 0 20 11 0.0000 4 120 465 6840 5580 content\001 --6 -6 405 10170 2970 11250 -6 990 10170 1980 10800 -2 2 0 1 0 7 40 0 20 0.000 0 0 -1 0 0 5 - 1080 10260 1980 10260 1980 10800 1080 10800 1080 10260 -2 2 0 1 0 7 30 0 20 0.000 0 0 -1 0 0 5 - 990 10170 1890 10170 1890 10710 990 10710 990 10170 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 1 1 1.00 120.00 180.00 - 630 11025 630 10440 990 10440 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 1 1 1.00 120.00 180.00 - 2340 11025 2340 10530 1980 10530 -4 0 0 20 0 20 15 0.0000 4 165 465 405 11250 frame\001 -4 0 0 20 0 20 15 0.0000 4 165 975 1980 11250 frame->next\001 --6 -6 3375 10080 6300 11250 -2 2 0 1 0 4 40 0 20 0.000 0 0 -1 0 0 5 - 3375 10710 4275 10710 4275 11250 3375 11250 3375 10710 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 3375 10080 4275 10080 4275 10620 3375 10620 3375 10080 -4 0 0 50 0 20 15 0.0000 4 225 1890 4410 10440 frame from original port\001 -4 0 0 50 0 20 15 0.0000 4 210 1425 4410 11070 intercepted frame\001 --6 -6 6660 10035 11250 11295 -6 8505 10035 9405 10575 -2 2 0 1 0 3 40 0 -1 0.000 0 0 -1 0 0 5 - 8505 10035 9405 10035 9405 10575 8505 10575 8505 10035 -4 0 0 20 0 18 25 0.0000 4 285 555 8685 10440 d u\001 --6 -6 6660 10170 8055 11295 -4 2 0 50 0 20 15 0.0000 4 165 1005 8055 10350 downstream\001 -4 2 0 50 0 20 15 0.0000 4 165 1380 8055 10650 meta-information\001 -4 2 0 50 0 20 15 0.0000 4 180 1080 8055 10950 from decoder\001 -4 2 0 50 0 20 15 0.0000 4 210 705 8055 11250 to output\001 --6 -6 9855 10170 11250 11295 -4 0 0 50 0 20 15 0.0000 4 210 765 9855 10350 upstream\001 -4 0 0 50 0 20 15 0.0000 4 165 1380 9855 10650 meta-information\001 -4 0 0 50 0 20 15 0.0000 4 210 915 9855 10950 from output\001 -4 0 0 50 0 20 15 0.0000 4 180 870 9855 11250 to decoder\001 --6 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 1 1 1.00 120.00 180.00 - 8100 10800 8775 10800 8775 10485 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 3 - 1 1 1.00 120.00 180.00 - 9810 10800 9135 10800 9135 10485 --6 -6 3645 9135 4635 9765 -2 2 0 1 0 4 30 0 20 0.000 0 0 -1 0 0 5 - 3645 9135 4545 9135 4545 9675 3645 9675 3645 9135 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 3735 9225 4635 9225 4635 9765 3735 9765 3735 9225 -4 0 0 20 0 18 25 0.0000 4 270 225 3825 9540 d\001 --6 -6 7875 9180 8775 9720 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 7875 9180 8775 9180 8775 9720 7875 9720 7875 9180 -4 0 0 20 0 18 25 0.0000 4 270 225 8055 9585 d\001 --6 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 120.00 180.00 - 9990 1305 7200 1305 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 120.00 180.00 - 5040 1305 2340 1305 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 7875 1035 8775 1035 8775 1575 7875 1575 7875 1035 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 120.00 180.00 - 2340 2340 9990 2340 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 120.00 180.00 - 9990 3240 2340 3240 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 4 - 0 0 1.00 120.00 180.00 - 2340 4320 5625 4320 5625 6570 2340 6570 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 4 - 0 0 1.00 120.00 180.00 - 9990 5895 6570 5895 6570 6570 9990 6570 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 4 - 0 0 1.00 120.00 180.00 - 9990 4320 6570 4320 6570 4995 9990 4995 -2 2 0 1 0 3 40 0 20 0.000 0 0 -1 0 0 5 - 7875 4050 8775 4050 8775 4590 7875 4590 7875 4050 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 4 - 0 0 1.00 120.00 180.00 - 2340 7560 5625 7560 5625 8460 2340 8460 -2 1 1 1 0 7 50 0 -1 10.000 0 0 -1 0 0 2 - 0 1800 11610 1800 -2 1 1 1 0 7 50 0 -1 10.000 0 0 -1 0 0 2 - 0 3780 11610 3780 -2 1 1 1 0 7 50 0 -1 10.000 0 0 -1 0 0 2 - 0 7065 11610 7065 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 120.00 180.00 - 2340 9450 5040 9450 -2 1 1 1 0 7 50 0 -1 4.000 0 0 -1 1 0 2 - 0 0 1.00 120.00 180.00 - 7200 9450 9990 9450 -2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 6 - 6075 90 6075 540 3195 540 3015 315 3195 90 6075 90 -2 3 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 6 - 6165 90 6165 540 9135 540 9315 315 9135 90 6165 90 -2 1 1 1 0 7 50 0 -1 10.000 0 0 -1 0 0 2 - 0 8955 11610 8955 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 - 3195 9990 3195 11385 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2 - 6480 9990 6480 11385 -4 0 0 20 0 20 20 0.0000 4 210 270 5715 405 up\001 -4 0 0 20 0 20 20 0.0000 4 210 585 6300 405 down\001 diff --git a/doc/hackersguide/post_frame.svg b/doc/hackersguide/post_frame.svg new file mode 100644 index 000000000..3558fe605 --- /dev/null +++ b/doc/hackersguide/post_frame.svg @@ -0,0 +1,1564 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + post plugin + + get_frame + + field + lock + proc_frame + proc_slice + proc_macroblock + draw + + field + lock + proc_frame + proc_slice + proc_macroblock + draw + + draw + + get_frame + + field + lock + proc_frame + proc_slice + proc_macroblock + draw + + get_frame + + field + lock + proc_frame + proc_slice + proc_macroblock + draw + + free + + free / dispose + + free / dispose + + modify frame + content + + + + + frame from original port + intercepted frame + downstream + meta-information + from decoder + to output + upstream + meta-information + from output + to decoder + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + _x_post_intercept_frame + + _x_post_frame_copy_down + _x_post_frame_copy_up + + + + + + + + _x_post_frame_u_turn + _x_post_frame_copy_down + _x_post_frame_copy_up + + _x_post_restore_video_frame + + + d + d + d u + d u + d + d + d u + d u + d + d u + + + interception + + + + pass through + + + + modifying a copy + + + + dead-end draw + + + + freeing + + d u + frame + frame->next + d u + d + d + up + down + + -- cgit v1.2.3 From 1c25f30813a2c2638c7a942ab96b8b90f6a993c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:49:56 +0200 Subject: Convert the rule too. --- doc/hackersguide/Makefile.am | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/hackersguide/Makefile.am b/doc/hackersguide/Makefile.am index b2fce9040..abd208fc9 100644 --- a/doc/hackersguide/Makefile.am +++ b/doc/hackersguide/Makefile.am @@ -24,7 +24,7 @@ DISTCLEANFILES = $(hackersguide_DATA) hackersguide.html: $(hackersguide_docbook) xmlto html-nochunks $(srcdir)/hackersguide.docbook -.fig.png: - fig2dev -L png -S 4 $< $@; +.svg.png: + rsvg -f png $< $@ SUFFIXES = .png .fig -- cgit v1.2.3 From 5a0f828681473f5aec1add957e152437f4e5d8dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 2 Jun 2007 20:50:31 +0200 Subject: Rename the files. --- doc/hackersguide/Makefile.am | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/hackersguide/Makefile.am b/doc/hackersguide/Makefile.am index abd208fc9..4b5985599 100644 --- a/doc/hackersguide/Makefile.am +++ b/doc/hackersguide/Makefile.am @@ -7,16 +7,16 @@ hackersguide_docbook = hackersguide.docbook \ internals.docbook \ stream.docbook \ output.docbook -hackersguide_fig = architecture.fig \ - library.fig \ - overlays.fig \ - post_frame.fig +hackersguide_svg = architecture.svg \ + library.svg \ + overlays.svg \ + post_frame.svg hackersguidedir = $(htmldir)/hackersguide hackersguide_DATA = hackersguide.html \ architecture.png library.png overlays.png post_frame.png -EXTRA_DIST = README $(hackersguide_docbook) $(hackersguide_fig) \ +EXTRA_DIST = README $(hackersguide_docbook) $(hackersguide_svg) \ $(hackersguide_DATA) DISTCLEANFILES = $(hackersguide_DATA) -- cgit v1.2.3 From 66c71e8a5fe42190569912ad70ac04e98870654e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Mon, 4 Jun 2007 11:35:05 +0200 Subject: =?UTF-8?q?Use=20the=20=E2=84=A2=20symbol=20rather=20than=20the=20?= =?UTF-8?q?™=20entity.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/faq/faq.docbook | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/faq/faq.docbook b/doc/faq/faq.docbook index 8c7f63905..c1782bf00 100644 --- a/doc/faq/faq.docbook +++ b/doc/faq/faq.docbook @@ -425,7 +425,7 @@ - Are there binaries for my AMD K7 (Athlon™) available? Can I build them? + Are there binaries for my AMD K7 (Athlon™) available? Can I build them? If you have a recent gcc you can try to compile "more" k7 support in (esp. better instruction scheduling). If the configure script should fail to -- cgit v1.2.3 From daa5eada4a80ef482acb1ad8700498445134056b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Mon, 4 Jun 2007 11:36:33 +0200 Subject: Note that raw devices and 2.6 kernels don't get along well. --- doc/faq/faq.docbook | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc') diff --git a/doc/faq/faq.docbook b/doc/faq/faq.docbook index c1782bf00..da5128bb6 100644 --- a/doc/faq/faq.docbook +++ b/doc/faq/faq.docbook @@ -1150,6 +1150,10 @@ ftp://ftp.kernel.org/pub/linux/kernel/people/sct/raw-io/ + + For recent kernels (2.6.x series) the raw devices are neither + needed nor supported anymore, so don't bother. + To use raw devices, first connect a free raw device to your dvd device, use something like: -- cgit v1.2.3 From 2f360e81e09412ecff2e5991ee0c90a0f6ed59e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Mon, 4 Jun 2007 11:38:44 +0200 Subject: Update the note about which audio drivers are available. --- doc/faq/faq.docbook | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/faq/faq.docbook b/doc/faq/faq.docbook index da5128bb6..fa414f1e9 100644 --- a/doc/faq/faq.docbook +++ b/doc/faq/faq.docbook @@ -1249,10 +1249,13 @@ What audio drivers does xine support? OSS? Alsa? Arts? Esd? - Currently xine support audio output via OSS (kernel audio drivers), - ALSA 0.9.x (ALSA 0.5.x is no longer supported), arts (KDE's sound daemon) - and esound (esd, gnome's sound daemon - not recommended because it has - serious issues with a/v sync). + Currently xine support audio output via OSS (Linux 2.4 and most + *BSD audio drivers), + ALSA 0.9 and 1.0 (ALSA 0.5.x is no longer supported), aRTs (KDE + 3's sound daemon), ESounD (esd, gnome's sound daemon not + recommended because it has serious issues with a/v sync), JACK, + PulseAudio, plus platform-specific output through Sun devices for + Solaris and NetBSD and Irix output. -- cgit v1.2.3 From b6055c5fe61d918259d1c253aa32fa97dd3e5163 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Diego=20=27Flameeyes=27=20Petten=C3=B2?= Date: Sat, 9 Jun 2007 18:20:13 +0200 Subject: Resurrect the check for xmlto/rsvg (rather than sgmltools/fig2dev) so that the build can be done even without those installed. --- doc/faq/Makefile.am | 31 ++++++++++++++++++++++++++-- doc/hackersguide/Makefile.am | 48 ++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 73 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/faq/Makefile.am b/doc/faq/Makefile.am index 49d22860f..782f618c1 100644 --- a/doc/faq/Makefile.am +++ b/doc/faq/Makefile.am @@ -7,8 +7,35 @@ EXTRA_DIST = README faq.docbook $(doc_DATA) $(html_DATA) DISTCLEANFILES = $(doc_DATA) $(html_DATA) +docs: $(hackersguide_DATA) + +clean-docs: + rm -f $(hackersguide_DATA) + +dist-hook: + @if test x"$(distcheck_lax)" = x ; then \ + $(MAKE) fail_if_missing=yes docs ; \ + else \ + $(MAKE) docs ; \ + fi + +distclean-local: clean-docs + +if HAVE_XMLTO faq.html: faq.docbook - xmlto html-nochunks $(srcdir)/faq.docbook + xmlto html-nochunks $^ faq.txt: faq.docbook - xmlto txt $(srcdir)/faq.docbook + xmlto txt $^ +else +faq.html faq.txt: faq.docbook + if test x"$(fail_if_missing)" = x"yes"; then \ + echo "Please install xmlto."; \ + exit 1; \ + fi + if test x"$(fail_if_missing)" != x"yes"; then \ + touch $@; \ + sleep 1; \ + touch $^; \ + fi +endif diff --git a/doc/hackersguide/Makefile.am b/doc/hackersguide/Makefile.am index 4b5985599..025f4a1ec 100644 --- a/doc/hackersguide/Makefile.am +++ b/doc/hackersguide/Makefile.am @@ -21,10 +21,50 @@ EXTRA_DIST = README $(hackersguide_docbook) $(hackersguide_svg) \ DISTCLEANFILES = $(hackersguide_DATA) +SUFFIXES = .png .fig + +docs: $(hackersguide_DATA) + +clean-docs: + rm -f $(hackersguide_DATA) + +dist-hook: + @if test x"$(distcheck_lax)" = x ; then \ + $(MAKE) fail_if_missing=yes docs ; \ + else \ + $(MAKE) docs ; \ + fi + +distclean-local: clean-docs + +if HAVE_XMLTO +hackersguide.html: $(hackersguide_docbook) + xmlto html-nochunks $^ +else hackersguide.html: $(hackersguide_docbook) - xmlto html-nochunks $(srcdir)/hackersguide.docbook + if test x"$(fail_if_missing)" = x"yes"; then \ + echo "Please install xmlto."; \ + exit 1; \ + fi + if test x"$(fail_if_missing)" != x"yes"; then \ + touch $@; \ + sleep 1; \ + touch $^; \ + fi +endif +if HAVE_RSVG .svg.png: - rsvg -f png $< $@ - -SUFFIXES = .png .fig + rsvg -f png $^ $@ +else +.svg.png: + if test x"$(fail_if_missing)" = x"yes"; then \ + echo "Please install rsvg."; \ + exit 1; \ + fi + if test x"$(fail_if_missing)" != x"yes"; then \ + touch $@; \ + sleep 1; \ + touch $^; \ + fi +endif -- cgit v1.2.3