# [node b93cc1068c00e43c9f6cc4ea2fcae0f49d614793 part 1]
diff -r ef1592a76f8d7af3930135d4ffa966be6c309cc5 -r
b93cc1068c00e43c9f6cc4ea2fcae0f49d614793 doc/hackersguide/library.sgml
--- a/doc/hackersguide/library.sgml Sun Jun 10 14:43:00 2007 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,410 +0,0 @@
-<chapter id="xine-library">
- <title>Using the xine library</title>
-
- <sect1>
- <title>xine architecture as visible to libxine clients</title>
- <para>
- 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.
- </para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="library.png" format="PNG">
- </imageobject>
- <imageobject>
- <imagedata fileref="library.eps" format="EPS">
- </imageobject>
- <caption>
- <para>outside view on xine components</para>
- </caption>
- </mediaobject>
- <para>
- The function are named just to give you an overview of what is actually
- there. It is all thoroughly documented in the plublic header
- <filename>xine.h</filename>, which is the main and preferably the only xine
- header, clients should include. (xine/xineutils.h and the XML parser might
- make an exception.)
- </para>
- <para>
- Details on the OSD feature can be found in the <link linkend="osd">OSD
section</link>.
- </para>
- </sect1>
-
- <sect1>
- <title>Writing a new frontend to xine</title>
- <para>
- 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.
- </para>
- <para>
- One important thing to note is that any X11 based xine-lib frontend
- must call <function>XInitThreads()</function> before calling the
- first Xlib function, because xine will access the display from
- within a different thread than the frontend.
- </para>
- <sect2>
- <title>Source code of a simple X11 frontend</title>
- <programlisting>
-/*
-** Copyright (C) 2003 Daniel Caujolle-Bert <[EMAIL PROTECTED]>
-**
-** 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;
[... 158 lines omitted ...]
- 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;
-}</programlisting>
- </sect2>
- </sect1>
-
-</chapter>
diff -r ef1592a76f8d7af3930135d4ffa966be6c309cc5 -r
b93cc1068c00e43c9f6cc4ea2fcae0f49d614793 doc/hackersguide/output.sgml
--- a/doc/hackersguide/output.sgml Sun Jun 10 14:43:00 2007 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,668 +0,0 @@
-<chapter id="output">
- <title>xine's output layer</title>
-
- <sect1>
- <title>Post plugin layer</title>
- <para>
- In this section you will learn, how the powerful post plugin architecture
- works and how to write post plugins.
- </para>
- <sect2>
- <title>General principle of post plugins</title>
- <para>
- 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
- <function>xine_post_wire()</function> is used by frontends to form such
- connections.
- </para>
- <para>
- 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
<filename>xine.h</filename>
- as <varname>XINE_POST_DATA_*</varname> defines.
- </para>
- <para>
- Some terminology used in the following explanations:
- <itemizedlist>
- <listitem>
- <para>
- <varname>down direction</varname>:
- 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.
- </para>
- </listitem>
- <listitem>
- <para>
- <varname>up direction</varname>:
- The direction from the output to the decoders. This is the way some
video or audio
- metadata like metronom timestamps travel through the engine.
- </para>
- </listitem>
- <listitem>
- <para>
- <varname>interception</varname>:
- 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.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect2>
- <sect2>
- <title>Writing a xine post plugin</title>
- <para>
- The post plugin API is declared in
<filename>src/xine-engine/post.h</filename>
- The plugin info of post plugins contains the post plugin type, which is
one of the
- <varname>XINE_POST_TYPE_*</varname> defines and the init_class function of
the plugin.
- </para>
- <para>
- <programlisting> post_plugin_t *open_plugin(post_class_t
*class_gen, int inputs, xine_audio_port_t **audio_target, xine_video_port_t
**video_target);</programlisting>
- Returns an instance of the plugin. Some post plugins evaluate
<varname>inputs</varname>
- 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 <type>post_plugin_t</type>,
which you are
- encouraged to use: <function>_x_post_init()</function>.
- </para>
- <para>
- <programlisting> char *get_identifier(post_class_t
*class_gen);</programlisting>
- This function returns a short identifier describing the plugin.
- </para>
- <para>
- <programlisting> char *get_description(post_class_t
*class_gen);</programlisting>
- This function returns a plaintext, one-line string describing the plugin.
- </para>
- <para>
- <programlisting> void dispose(post_class_t
*class_gen);</programlisting>
- This function frees the memory used by the video out plugin class object.
- </para>
- <para>
- The <type>post_plugin_t</type> 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 <function>dispose()</function> function and some internal stuff which
- plugins do not have to worry about.
- </para>
- <para>
- <programlisting> void dispose(post_plugin_t
*this_gen);</programlisting>
- 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 <function>dispose()</function> is being
called.
- They maintain a usage counter to detect that. To check for such a
condition, you
- should use the <function>_x_post_dispose()</function> helper function like
that:
- <programlisting>
- if (_x_post_dispose(this))
- really_free(this);</programlisting>
- <function>_x_post_dispose()</function> frees any ressources allocated by
any of the
- post plugin helper functions and returns boolean true, if the plugin is
not needed
- any more.
- </para>
- </sect2>
- <sect2>
[... 416 lines omitted ...]
- <para>
- Most important, the ability to render/copy a given
- frame to the output device.
- </para>
- </listitem>
- <listitem>
- <para>
- 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).
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- 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.
- </para>
- <sect2>
- <title>Writing a xine video out plugin</title>
- <para>
- The video out plugin API is declared in
<filename>src/xine-engine/video_out.h</filename>
- The plugin info of video out plugins contains the visual type, priority,
- and the init_class function of the plugin.
- </para>
- <para>
- The <varname>visual_type</varname> 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
- <function>open_plugin()</function> function as its
<varname>visual</varname> parameter.
- </para>
- <para>
- <programlisting> char
*get_description(video_driver_class_t *this_gen);</programlisting>
- This function returns a plaintext, one-line string describing the plugin.
- </para>
- <para>
- <programlisting> char
*get_identifier(video_driver_class_t *this_gen);</programlisting>
- This function returns a shorter identifier describing the plugin.
- </para>
- <para>
- <programlisting> void dispose(video_driver_class_t
*this_gen);</programlisting>
- This function frees the memory used by the video out plugin class object.
- </para>
- <para>
- <programlisting> vo_driver_t
*get_instance(video_driver_class_t *class_gen, const void
*visual);</programlisting>
- Returns an instance of the plugin.
- The <varname>visual</varname> 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 <type>x11_visual_t</type>, which amongst other things hold the
- <type>Display</type> 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.
- </para>
- <para>
- <programlisting> uint32_t get_capabilities(vo_driver_t
*this_gen);</programlisting>
- Returns a bit mask describing the output plugin's capabilities.
- You may logically OR the <varname>VO_CAP_*</varname> constants together to
get
- a suitable bit-mask (via the '|' operator).
- </para>
- <para>
- <programlisting>
- 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);</programlisting>
- Handle the getting, setting of properties and define their bounds.
- Valid property IDs can be found in the <filename>video_out.h</filename>
- header file.
- </para>
- <para>
- <programlisting> int gui_data_exchange(vo_driver_t *self,
int data_type, void *data);</programlisting>
- 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.
- </para>
- <para>
- <programlisting> vo_frame_t *alloc_frame(vo_driver_t
*self);</programlisting>
- Returns a pointer to a xine video frame.
- Typically the video plugin will add private fields to the end of the
- <type>vo_frame_t</type> structure which are used for internal purposes by
the plugin.
- </para>
- <para>
- 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.
- </para>
- <para>
- <programlisting> void update_frame_format(vo_driver_t
*self, vo_frame_t *img, uint32_t width, uint32_t height, double ratio, int
format, int flags);</programlisting>
- 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 <varname>base</varname> field
of the
- frame and perform any driver-specific changes.
- </para>
- <para>
- <programlisting> void display_frame(vo_driver_t *self,
vo_frame_t *vo_img);</programlisting>
- Renders a given frame to the output device.
- </para>
- <para>
- <programlisting>
- 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);</programlisting>
- These are used to blend overlays on frames.
<function>overlay_begin()</function> is called,
- when the overlay appears for the first time,
<function>overlay_blend()</function> is then
- called for every subsequent frame and <function>overlay_end()</function>
is called, when
- the overlay should disappear again.
- </para>
- <para>
- <programlisting> int redraw_needed(vo_driver_t
*self);</programlisting>
- Queries the driver, if the current frame needs to be drawn again.
- </para>
- <para>
- <programlisting> void dispose(vo_driver_t
*self);</programlisting>
- Releases all resources and frees the plugin.
- </para>
- </sect2>
- </sect1>
-
-</chapter>
diff -r ef1592a76f8d7af3930135d4ffa966be6c309cc5 -r
b93cc1068c00e43c9f6cc4ea2fcae0f49d614793 doc/hackersguide/overlays.fig
--- a/doc/hackersguide/overlays.fig Sun Jun 10 14:43:00 2007 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -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 -r ef1592a76f8d7af3930135d4ffa966be6c309cc5 -r
b93cc1068c00e43c9f6cc4ea2fcae0f49d614793 doc/hackersguide/overview.sgml
--- a/doc/hackersguide/overview.sgml Sun Jun 10 14:43:00 2007 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,811 +0,0 @@
-<chapter id="overview">
- <title>xine code overview</title>
-
- <sect1>
- <title>Walking the source tree</title>
- <para>
- The <filename>src/</filename> directory in xine-lib contains several
- modules, this should give you a quick overview on where
- to find what sources.
- </para>
- <para>
- 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.
- </para>
- <para>
- <variablelist>
- <varlistentry>
- <term><filename>audio_out</filename></term>
- <listitem>
- <para>
- 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).
- </para>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>demuxers</filename></term>
- <listitem>
- <para>
- 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.
- </para>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>dxr3</filename></term>
- <listitem>
- <para>
- Code to support the DXR3 / hollywood+ hardware mpeg decoder.
- </para>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>input</filename></term>
- <listitem>
- <para>
- Input plugins encapsulate the origin of the data. Data sources like
- ordinary files, DVDs, CDA or streaming media are handled here.
- </para>
- <para>
- <variablelist>
- <varlistentry>
- <term><filename>dvb</filename></term>
- <listitem>
- <para>
- Some headers for Digital Video Broadcast.
- </para>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>libdvdnav</filename> (imported)</term>
- <listitem>
- <para>
- The libdvdnav library for DVD navigation is used
- by xine's DVD input plugin.
- </para>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>libreal</filename>,
<filename>librtsp</filename></term>
- <listitem>
- <para>
- Support for RealMedia streaming as used by the RTSP input plugin.
- </para>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>vcd</filename></term>
- <listitem>
- <para>
- The enhanced VCD input plugin which also handles VCD navigation.
- </para>
- <para>
- <variablelist>
- <varlistentry>
- <term><filename>libcdio</filename>, <filename>libvcd</filename>
(imported)</term>
- <listitem>
- <para>
- Libraries used by the enhanced VCD plugin.
- </para>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>liba52</filename> (imported)</term>
- <listitem>
- <para>
- A52 (aka AC3, aka Dolby Digital) audio decoder library and xine plugin.
- </para>
[... 559 lines omitted ...]
- </para>
- </listitem>
- <listitem>
- <para>
- use something like
- <programlisting> printf("module:
..."[,...]);</programlisting>
- for console output. All console output goes to stdout and
- must be prefixed by the module name which generates the
- output (see example above).
- </para>
- </listitem>
- <listitem>
- <para>
- Refer to emac's C-mode for all questions of proper indentiation.
- That first of all means: indent with two spaces.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect1>
-
- <sect1>
- <title>The xine logging system</title>
- <para>
- 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.
- </para>
- <sect2>
- <title>xine_log</title>
- <para>
- Output which is done thru this function will be
- displayed for the end user by the frontend.
- If <varname>xine->verbosity</varname> 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.
- <programlisting> xine_log(xine_t *xine, int buf, const
char *format, ...);</programlisting>
- <varname>buf</varname> is either XINE_LOG_MSG for general messages or
- XINE_LOG_PLUGIN for messages about plugins.
- </para>
- </sect2>
- <sect2>
- <title>xprintf</title>
- <para>
- This macro uses the <varname>xine->verbosity</varname> 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 <parameter>--verbose=[1,2]</parameter> options.
- This function should be used for information which the
- user should only read up on request.
- <programlisting> xprintf(xine_t *xine, int verbosity,
const char *format, ...);</programlisting>
- </para>
- </sect2>
- <sect2>
- <title>lprintf/llprintf</title>
- <para>
- 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.
- <programlisting>
- lprintf(const char *format, ...);
- llprintf(bool, const char *format, ...);</programlisting>
- <varname>bool</varname> is a flag which enables or disables this logging.
- </para>
- <para>
- <function>lprintf</function> can be enabled by defining LOG at the top of
the source file.
- <function>llprintf</function> can be used for more than one categorie
- per file by using diffent lables:
- <programlisting>
- #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);</programlisting>
- </para>
- <para>
- In this case only the first messages is printed. To enable/disable change
the defines.
- </para>
- <para>
- LOG_MODULE should be used to set the modulename for
xprintf/lprintf/llprintf.
- Each output line will start with "modulename: ".
- <programlisting> #define LOG_MODULE
"modulename"</programlisting>
- </para>
- <para>
- LOG_VERBOSE can be defined to enable the logging of functionname and
linenumbers.
- Then the output will be: "modulename: (function_name:42) message".
- </para>
- </sect2>
- <sect2>
- <title>_x_assert/_x_abort</title>
- <para>
- 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.
- </para>
- <para>
- <function>_x_assert()</function> 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.
- </para>
- <para>
- <function>_x_abort()</function> always terminates the application after
printing a note.
- </para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>How to contribute</title>
- <para>
- 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).
- </para>
- </sect1>
-
-</chapter>
diff -r ef1592a76f8d7af3930135d4ffa966be6c309cc5 -r
b93cc1068c00e43c9f6cc4ea2fcae0f49d614793 doc/hackersguide/post_frame.fig
--- a/doc/hackersguide/post_frame.fig Sun Jun 10 14:43:00 2007 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -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
[... 95 lines omitted ...]
-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 -r ef1592a76f8d7af3930135d4ffa966be6c309cc5 -r
b93cc1068c00e43c9f6cc4ea2fcae0f49d614793 doc/hackersguide/stream.sgml
--- a/doc/hackersguide/stream.sgml Sun Jun 10 14:43:00 2007 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,656 +0,0 @@
-<chapter id="stream">
- <title>xine's stream layer</title>
-
- <sect1>
- <title>Input layer</title>
- <para>
- 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:
- <itemizedlist>
- <listitem>
- <para>
- Validation of Media Resource Locators (MRLs).
- </para>
- </listitem>
- <listitem>
- <para>
- MRL specific session management (e.g. opening and closing local files).
- </para>
- </listitem>
- <listitem>
- <para>
- Reading blocks/specific numbers of bytes from the input device.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- 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).
- </para>
- <para>
- 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.
- </para>
- <sect2>
- <title>Writing a xine input plugin</title>
- <para>
- 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 <filename>input/input_plugin.h</filename>.
- </para>
- <para>
- An input plugin exports a public function of the form:
- <programlisting> void *input_init_plugin(xine_t *xine,
void *data);</programlisting>
- This function initializes an input plugin class object with the
- following functions:
- </para>
- <para>
- <programlisting> char *get_description(input_class_t
*this_gen);</programlisting>
- This function returns a plaintext, one-line string describing the plugin.
- </para>
- <para>
- <programlisting> char *get_identifier(input_class_t
*this_gen);</programlisting>
- This function returns a shorter identifier describing the plugin.
- </para>
- <para>
- <programlisting> xine_mrl_t **get_dir(input_class_t
*this_gen, const char *filename, int *nFiles);</programlisting>
- Retrieves a directory listing from the plugin. This function is optional.
- </para>
- <para>
- <programlisting> char **get_autoplay_list(input_class_t
*this_gen, int *num_files);</programlisting>
- Retrieves the autoplay playlist from the plugin. This function is optional.
- </para>
- <para>
- <programlisting> int eject_media(input_class_t
*this_gen);</programlisting>
- Ejects the medium. This function is optional.
- </para>
- <para>
- <programlisting> void dispose(input_class_t
*this_gen);</programlisting>
- This function frees the memory used by the input plugin class object.
- </para>
- <para>
- <programlisting> input_plugin_t
*get_instance(input_class_t *class_gen, xine_stream_t *stream, const char
*mrl);</programlisting>
- 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.
- </para>
- <para>
- <programlisting> int open(input_plugin_t
*this_gen);</programlisting>
- You should do any device-specific initialisation within this function.
- </para>
- <para>
- <programlisting> uint32_t get_capabilities(input_plugin_t
*this_gen);</programlisting>
- Returns a bit mask describing the input device's capabilities.
- You may logically OR the <varname>INPUT_CAP_*</varname> constants together
to get
- a suitable bit-mask (via the '|' operator).
- </para>
- <para>
- <programlisting> off_t read(input_plugin_t *this_gen,
char *buf, off_t nlen);</programlisting>
- Reads a specified number of bytes into a buffer and returns the number of
bytes actually copied.
- </para>
- <para>
- <programlisting> buf_element_t *read_block(input_plugin_t
*this_gen, fifo_buffer_t *fifo, off_t len);</programlisting>
- 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.
- </para>
- <para>
- <programlisting> off_t seek(input_plugin_t *this_gen,
off_t offset, int origin);</programlisting>
- This function is called by xine when it is required that subsequent
- reads come from another part of the stream.
- </para>
- <para>
- <programlisting> off_t get_current_pos(input_plugin_t
*this_gen);</programlisting>
- Returns the current position within a finite length stream.
- </para>
- <para>
[... 404 lines omitted ...]
- </para>
- <para>
- <programlisting> char
*get_identifier(video_decoder_class_t *this);</programlisting>
- <programlisting> char
*get_identifier(audio_decoder_class_t *this);</programlisting>
- This function returns a brief character string identifying the plugin.
- </para>
- <para>
- <programlisting> char
*get_description(video_decoder_class_t *this);</programlisting>
- <programlisting> char
*get_description(audio_decoder_class_t *this);</programlisting>
- This function returns a slightly longer description of the plugin.
- </para>
- <para>
- <programlisting> void dispose_class(video_decoder_class_t
*this);</programlisting>
- <programlisting> void dispose_class(audio_decoder_class_t
*this);</programlisting>
- This function frees the resources allocated by the plugin class.
- </para>
- <para>
- <programlisting> video_decoder_t
*open_plugin(video_decoder_class_t *class_gen, xine_stream_t
*stream);</programlisting>
- <programlisting> audio_decoder_t
*open_plugin(audio_decoder_class_t *class_gen, xine_stream_t
*stream);</programlisting>
- 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:
- </para>
- <para>
- <programlisting> void decode_data(video_decoder_t
*this_gen, buf_element_t *buf);</programlisting>
- <programlisting> void decode_data(audio_decoder_t
*this_gen, buf_element_t *buf);</programlisting>
- 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 <function>open()</function> and
- <function>close()</function> functions of <type>xine_video_port_t</type>
- and <type>xine_audio_port_t</type>.)
- </para>
- <para>
- A buffer has a <varname>decoder_flags</varname> 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).
- </para>
- <para>
- 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.
- </para>
- <para>
- <programlisting> void flush(video_decoder_t
*this_gen);</programlisting>
- <programlisting> void flush(audio_decoder_t
*this_gen);</programlisting>
- 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.
- </para>
- <para>
- <programlisting> void reset(video_decoder_t
*this_gen);</programlisting>
- <programlisting> void reset(audio_decoder_t
*this_gen);</programlisting>
- 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.
- </para>
- <para>
- <programlisting> void discontinuity(video_decoder_t
*this_gen);</programlisting>
- <programlisting> void discontinuity(audio_decoder_t
*this_gen);</programlisting>
- 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.
- </para>
- <para>
- <programlisting> void dispose(video_decoder_t
*this_gen);</programlisting>
- <programlisting> void dispose(audio_decoder_t
*this_gen);</programlisting>
- This function frees the resources used by the decoder plugin.
- </para>
- </sect2>
- <sect2>
- <title>SPU decoder</title>
- <para>
- A lot written above also applies for subpicture unit (SPU) decoders. The
- SPU decoder API is declared in
<filename>src/xine-engine/spu_decoder.h</filename>.
- Details on the data, SPU decoders are expected to output, see the section
on
- <link linkend="osd">overlays and OSD</link>.
- </para>
- <para>
- 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:
- <programlisting> vpts =
metronom->got_spu_packet(metronom, buf->pts);</programlisting>
- </para>
- <para>
- Another difference is that while both audio and video decoders are
automatically
- blocked in their
<function>get_buffer()</function>/<function>get_frame()</function>
- 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 <function>_x_spu_decoder_sleep()</function> 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.
- </para>
- <para>
- There are also two functions in the SPU decoder API, which have not been
discussed above:
- </para>
- <para>
- <programlisting> int get_interact_info(spu_decoder_t
*this_gen, void *data);</programlisting>
- Since SPUs are sometimes (on DVDs for example) used for user interaction
like menu
- highlights, this function can be called to get <varname>data</varname>
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.
- </para>
- <para>
- <programlisting> void set_button(spu_decoder_t *this_gen,
int32_t button, int32_t mode);</programlisting>
- Also for interaction, you can ask the decoder here to change the
- current highlighting.
- </para>
- </sect2>
- </sect1>
-
-</chapter>
-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Xine-cvslog mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/xine-cvslog
