1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
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>
|
