From 545fc065802302d017b95e3b4f5dbc1fcd91cb31 Mon Sep 17 00:00:00 2001 From: Rich J Wareham Date: Sat, 9 Feb 2002 13:23:26 +0000 Subject: Added details on writing a video output plugin CVS patchset: 1488 CVS date: 2002/02/09 13:23:26 --- doc/hackersguide/hackersguide.sgml | 282 ++++++++++++++++++++++++++++++++++++- 1 file changed, 281 insertions(+), 1 deletion(-) diff --git a/doc/hackersguide/hackersguide.sgml b/doc/hackersguide/hackersguide.sgml index 70a018b62..b0ae908e0 100644 --- a/doc/hackersguide/hackersguide.sgml +++ b/doc/hackersguide/hackersguide.sgml @@ -9,6 +9,7 @@ GünterBartsch HeikoSchäfer + RichardWareham @@ -463,7 +464,286 @@ struct demux_plugin_s Adding support for a new type of video output (e.g. framebuffer device) - + + The xine plugin system makes it easy to create a new video + output target for xine. Video output plugins, like all + plugins are installed in a special xine plugins directory + which can be found using the + xine-config --plugindir + command. + + + In order to allow for device-dependant acceleration features, xine + calls on the video output plugin for more than just displaying + images. The tasks performed by the video plugins are: + + + + + Allocation of a vo_frame_s structure and its + 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 importantly, the ability to render/copy a given + frame to the output device. + + + + (Optional) 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 scalaing 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. + + + All video plugins take the form of a shared library which exports at least + the functions init_video_out_plugin() and + get_video_out_plugin_info() which + returns a pointer to a vo_info_s. This structure has the + following declaration: + + + struct vo_info_s { + int interface_version; /* plugin interface version */ + char *id; /* id of this plugin */ + char *description; /* human-readable description of this plugin */ + int visual_type; /* visual type supported by this plugin */ + int priority; /* priority of this plugin for auto-probing */ + }; + + At the time of writing, the current interface version was `3' but + you may wish to look at an existing plugin's source-code to check. + + + The visual_type field is used by the Xine UI to + determine if it is supported by the UI (e.g. X11 output plugins require + the GUI to be running under the X Windowing system) and also to + determine the information passed to the + init_video_out_plugin() function. + The library must also export this function and it has the following + declaration: + + + vo_driver_t *init_video_out_plugin (config_values_t *config, void *visual_gen) + + The arguments to the function are as follows + + + + config -- A pointer to an object which + allows you to register, change and access configuration information. + See elsewhere in this document for more information. + + + visual_gen -- 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 the Display variable associated with the + X-server xine is running under. See plugin source-code for other + VISUAL_TYPE_... constants and associated structures. Note that this + field is provided by the UI and so if you wish to add another visual + type you will either need to extend an existing UI or write a new + one. + + + + The function creates and returns a pointer to a vo_driver_s + structure which contains the following function pointers: + + +struct vo_driver_s { + + uint32_t (*get_capabilities) (vo_driver_t *this); /* for constants see above */ + + /* + * allocate an vo_frame_t struct, + * the driver must supply the copy, field and dispose functions + */ + vo_frame_t* (*alloc_frame) (vo_driver_t *this); + + + /* + * check if the given image fullfills the format specified + * (re-)allocate memory if necessary + */ + void (*update_frame_format) (vo_driver_t *this, vo_frame_t *img, + uint32_t width, uint32_t height, + int ratio_code, int format, int flags); + + /* display a given frame */ + void (*display_frame) (vo_driver_t *this, vo_frame_t *vo_img); + + /* overlay functions */ + void (*overlay_blend) (vo_driver_t *this, vo_frame_t *vo_img, vo_overlay_t *overlay); + + /* + * these can be used by the gui directly: + */ + + int (*get_property) (vo_driver_t *this, int property); + int (*set_property) (vo_driver_t *this, + int property, int value); + void (*get_property_min_max) (vo_driver_t *this, + int property, int *min, int *max); + + /* + * general purpose communication channel between gui and driver + * + * this should be used to propagate events, display data, window sizes + * etc. to the driver + */ + + int (*gui_data_exchange) (vo_driver_t *this, int data_type, + void *data); + + void (*exit) (vo_driver_t *this); + vo_info_t* (*get_info) (); + +}; + + The get_info field is simply a pointer to the + get_video_out_plugin_info() function described + above. + + + The get_capbilities field points to a function + which returns a bit-wise ORed combination of the following constants + which reflects the video output plugin's capabilities. + + +#define VO_CAP_COPIES_IMAGE 0x00000001 /* driver will copy image rather than providing */ + /* a buffer for xine to write the image into */ + +#define VO_CAP_RGB 0x00000002 /* driver can handle 24bit rgb pictures */ +#define VO_CAP_YV12 0x00000004 /* driver can handle YUV 4:2:0 pictures */ +#define VO_CAP_YUY2 0x00000008 /* driver can handle YUY2 pictures */ + +#define VO_CAP_HUE 0x00000010 /* driver can set HUE value */ +#define VO_CAP_SATURATION 0x00000020 /* driver can set SATURATION value */ +#define VO_CAP_BRIGHTNESS 0x00000040 /* driver can set BRIGHTNESS value */ +#define VO_CAP_CONTRAST 0x00000080 /* driver can set CONTRAST value */ +#define VO_CAP_COLORKEY 0x00000100 /* driver can set COLORKEY value */ +#define VO_CAP_AUTOPAINT_COLORKEY 0x00000200 /* driver can set AUTOPAINT_COLORKEY value */ + + A plugin should use the VO_CAP_COPIES_IMAGE flag if it wishes to provide a + copy function to perform on-the-fly colour-space conversion and + scaling. + + + The get_property, set_proprty and + get_property_min_max fields point to functions which + handle the getting, setting of properties and define their bounds. + Valid property IDs can be found in the video_out.h + header file. + + + The gui_data_exchange field points to a function which can + accept 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. + + + The alloc_frame field points to a function which returns + a pointer to a vo_frame_s structure which is defined as: + + +/* public part, video drivers may add private fields */ +struct vo_frame_s { + struct vo_frame_s *next; + + uint32_t PTS; + uint32_t pts_corrector; /* Repeat first field tricks */ + uint32_t SCR; + int bad_frame; /* e.g. frame skipped or based on skipped frame */ + int drawn; + uint8_t *base[3]; + + + /* additional information to be able to duplicate frames: */ + int width, height; + int ratio, format; + int duration; + int aspect_ratio; + int frame_rate_code; + int progressive_sequence; + int top_field_first; + int repeat_first_field; + int progressive_frame; + int picture_coding_type; + int bitrate; + + int display_locked, decoder_locked, driver_locked; + pthread_mutex_t mutex; /* so the various locks will be serialized */ + + vo_instance_t *instance; + + /* + * member functions + */ + + /* this frame is no longer used by decoder */ + void (*free) (vo_frame_t *vo_img); + + /* tell video driver to copy/convert a slice of this frame */ + void (*copy) (vo_frame_t *vo_img, uint8_t **src); + + /* tell video driver that the decoder starts a new field */ + void (*field) (vo_frame_t *vo_img, int which_field); + + /* append this frame to the display queue, + returns number of frames to skip if decoder is late */ + int (*draw) (vo_frame_t *vo_img); + + /* this frame is no longer used by the video driver */ + void (*displayed) (vo_frame_t *vo_img); + + /* free memory/resources for this frame */ + void (*dispose) (vo_frame_t *vo_img); +} + + Typically the video plugin will add private fields to the end of this structure + which are used for internal purposes by the plugin. + + + The function pointers within the frame structure provides 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. + + + Returning to the vo_driver_s structure, the + update_frame_format field points to a function which 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 and driver-specific changes. + + + The display_frame field points to a function to render a + given frame to the output device. + + + The overlay_blend field points to a function which accepts + an association between a frame and overlay which will result in the latter + being overlayed on the former. + Adding support for a new type of audio output -- cgit v1.2.3