updated hackersguide:

* added some small pieces
* incorporated some former READMEs and Mike's fabulous demuxer and decoder doc
* splitted into multiple files
* made new drawings (hopefully I am not the only one to understand them)
* Makefile support for building a HTML version which is now
  installed in the user's doc directory

CVS patchset: 5494
CVS date: 2003/10/12 19:06:43

1 files changed, 153 insertions, 0 deletions

diff --git a/doc/hackersguide/output.sgml b/doc/hackersguide/output.sgml
new file mode 100644
index 000000000..97a54ce77
--- /dev/null
+++ b/doc/hackersguide/output.sgml
@@ -0,0 +1,153 @@
+<chapter id="output">
+ <title>xine's output layer</title>
+
+ <sect1>
+  <title>Video output</title>
+  <para>
+   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:
+   <itemizedlist>
+    <listitem>
+     <para>
+      Allocation of <type>vo_frame_t</type> structures and their
+      subsequent destruction.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      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).
+     </para>
+    </listitem>
+    <listitem>
+     <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>&nbsp;&nbsp;&nbsp;char *get_description(video_driver_class_t *this_gen);</programlisting>
+    This function returns a plaintext, one-line string describing the plugin.
+   </para>
+   <para>
+    <programlisting>&nbsp;&nbsp;&nbsp;char *get_identifier(video_driver_class_t *this_gen);</programlisting>
+    This function returns a shorter identifier describing the plugin.
+   </para>
+   <para>
+    <programlisting>&nbsp;&nbsp;&nbsp;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>&nbsp;&nbsp;&nbsp;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>&nbsp;&nbsp;&nbsp;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>
+&nbsp;&nbsp;&nbsp;int get_property(vo_driver_t *self, int property);
+&nbsp;&nbsp;&nbsp;int set_property(vo_driver_t *self, int property, int value);
+&nbsp;&nbsp;&nbsp;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>&nbsp;&nbsp;&nbsp;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>&nbsp;&nbsp;&nbsp;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>&nbsp;&nbsp;&nbsp;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>&nbsp;&nbsp;&nbsp;void display_frame(vo_driver_t *self, vo_frame_t *vo_img);</programlisting>
+    Renders a given frame to the output device.
+   </para>
+   <para>
+    <programlisting>
+&nbsp;&nbsp;&nbsp;void overlay_begin(vo_driver_t *self, vo_frame_t *vo_img, int changed);
+&nbsp;&nbsp;&nbsp;void overlay_blend(vo_driver_t *self, vo_frame_t *vo_img, vo_overlay_t *overlay);
+&nbsp;&nbsp;&nbsp;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>&nbsp;&nbsp;&nbsp;int redraw_needed(vo_driver_t *self);</programlisting>
+    Queries the driver, if the current frame needs to be drawn again.
+   </para>
+   <para>
+    <programlisting>&nbsp;&nbsp;&nbsp;void dispose(vo_driver_t *self);</programlisting>
+    Releases all resources and frees the plugin.
+   </para>
+  </sect2>
+ </sect1>
+
+</chapter>