diff options
Diffstat (limited to 'doc/hackersguide/output.sgml')
| -rw-r--r-- | doc/hackersguide/output.sgml | 153 |
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> 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> |