1 <chapter> <title> The video output layer </title>
3 <sect1> <title> Data structures and main loop </title>
6 Important data structures are defined in <filename> include/video.h
7 </filename> and <filename> include/video_output.h</filename>. The main
8 data structure is <type> picture_t</type>, which describes everything a
9 video decoder thread needs. Please refer to this file for more
10 information. Typically, <parameter> p_data </parameter> will be a
11 pointer to YUV planar picture.
15 Note also the <type> subpicture_t </type> structure. In fact the VLC SPU
16 decoder only parses the SPU header, and converts the SPU graphical data
17 to an internal format which can be rendered much faster. So a part of
18 the "real" SPU decoder lies in
19 <filename> src/video_output/video_spu.c</filename>.
23 The <type> vout_thread_t </type> structure is much more complex, but
24 you needn't understand everything. Basically the video output thread
25 manages a heap of pictures and subpictures (5 by default). Every
26 picture has a status (displayed, destroyed, empty...) and eventually
27 a presentation time. The main job of the video output is an infinite
28 loop to : [this is subject to change in the near future]
33 <listitem> <para> Find the next picture to display in the heap.
36 <listitem> <para> Find the current subpicture to display.
39 <listitem> <para> Render the picture (if the video output plug-in
40 doesn't support YUV overlay). Rendering will call an optimized
41 YUV plug-in, which will also do the scaling, add subtitles and
42 an optional picture information field.
45 <listitem> <para> Sleep until the specified date.
48 <listitem> <para> Display the picture (plug-in function). For
49 outputs which display RGB data, it is often accomplished with
50 a buffer switching. <parameter> p_vout->p_buffer </parameter>
51 is an array of two buffers where the YUV transform takes place,
52 and p_vout->i_buffer_index indicates the currently displayed
56 <listitem> <para> Manage events.
63 <sect1> <title> Methods used by video decoders </title>
66 The video output exports a bunch of functions so that decoders can send
67 their decoded data. The most important function is
68 <function>vout_CreatePicture</function> which allocates the picture
69 buffer to the size indicated by the video decoder. It then just needs
70 to feed <type> (void *) </type><parameter> p_picture->p_data </parameter>
71 with the decoded data, and call <function> vout_DisplayPicture </function>
72 and <function> vout_DatePicture </function> upon necessary.
77 <listitem> <para> <type> picture_t * </type> <function>
78 vout_CreatePicture </function>
79 <parameter> ( vout_thread_t *p_vout, int i_type, int i_width,
80 int i_height ) </parameter> :
81 Returns an allocated picture buffer. <parameter> i_type </parameter>
82 will be for instance <constant> YUV_420_PICTURE</constant>, and
83 i_width and i_height are in pixels.
86 <warning> <para> If no picture is available in the heap,
87 <function> vout_CreatePicture </function> will return NULL.
91 <listitem> <para> <function> vout_LinkPicture </function>
92 <parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
93 Increases the refcount of the picture, so that it doesn't get
94 accidently freed while the decoder still needs it. For instance,
95 an I or P picture can still be needed after displaying to decode
96 interleaved B pictures.
99 <listitem> <para> <function> vout_UnlinkPicture </function>
100 <parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
101 Decreases the refcount of the picture. An unlink must be done
102 for every link previously made.
105 <listitem> <para> <function> vout_DatePicture </function>
106 <parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
107 Gives the picture a presentation date. You can start working on
108 a picture before knowing precisely at what time it will be
109 displayed. For instance to date an I or P picture, you must wait
110 until you have decoded all previous B pictures (which are
111 indeed placed after - decoding order != presentation order).
114 <listitem> <para> <function> vout_DisplayPicture </function>
115 <parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
116 Tells the video output that a picture has been completely decoded
117 and is ready to be rendered. It can be called before or after
118 <function> vout_DatePicture</function>.
121 <listitem> <para> <function> vout_DestroyPicture </function>
122 <parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
123 Marks the picture as empty (useful in case of a stream parsing
127 <listitem> <para> <type> subpicture_t * </type> <function>
128 vout_CreateSubPicture </function> <parameter> ( vout_thread_t *p_vout,
129 int i_channel, int i_type ) </parameter> :
130 Returns an allocated subpicture buffer. <parameter> i_channel
131 </parameter> is the ID of the subpicture channel, <parameter> i_type
132 </parameter> is <constant> DVD_SUBPICTURE </constant> or
133 <constant> TEXT_SUBPICTURE</constant>, <parameter> i_size
134 </parameter> is the length in bytes of the packet.
137 <listitem> <para> <function> vout_DisplaySubPicture </function>
138 <parameter> ( vout_thread_t *p_vout, subpicture_t *p_subpic )
140 Tells the video output that a subpicture has been completely
141 decoded. It obsoletes the previous subpicture.
144 <listitem> <para> <function> vout_DestroySubPicture </function>
145 <parameter> ( vout_thread_t *p_vout, subpicture_t *p_subpic )
147 Marks the subpicture as empty.
154 <sect1> <title> How to write a video output plug-in </title>
157 A video output takes care of the system calls to display the pictures and
158 manage the output window. Have a look at <filename>
159 plugins/x11/vout_x11.c</filename>. You must write the following
165 <listitem> <para> <type> int </type> <function> vout_Probe </function>
166 <parameter> ( probedata_t *p_data ) </parameter> :
167 Returns a score between 0 and 999 to indicate whether it can
168 run on the architecture. 999 is the best. <parameter> p_data
169 </parameter> is currently unused.
172 <listitem> <para> <type> int </type> <function> vout_Create </function>
173 <parameter> ( vout_thread_t *p_vout ) </parameter> :
174 Basically, initializes and opens a new window. Returns TRUE if
178 <listitem> <para> <type> int </type> <function> vout_Init </function>
179 <parameter> ( vout_thread_t *p_vout ) </parameter> :
180 Creates optional picture buffers (for instance ximages or
181 xvimages). Returns TRUE if it failed.
184 <listitem> <para> <function> vout_End </function> <parameter>
185 ( vout_thread_t *p_vout ) </parameter> :
186 Frees optional picture buffers.
189 <listitem> <para> <type> int </type> <function> vout_Manage
190 </function> <parameter> ( vout_thread_t *p_vout ) </parameter> :
191 Manages events (including for instance resize events).
194 <listitem> <para> <function> vout_Display </function> <parameter>
195 ( vout_thread_t *p_vout ) </parameter> :
196 Displays a previously rendered buffer.
199 <listitem> <para> <function> vout_SetPalette </function>
200 <parameter> ( vout_thread_t *p_vout, u16 *red, u16 *green,
201 u16 *blue, u16 *transp ) </parameter> :
202 Sets the 8 bpp palette. <parameter> red, green </parameter>
203 and <parameter> blue </parameter> are arrays of 256 <type>
204 unsigned shorts</type>.
211 <sect1> <title> How to write a YUV plug-in </title>
214 Look at the C source <filename> plugins/yuv/transforms_yuv.c</filename>.
215 You need to redefine just the same transformations. Basically, it is a
216 matrix multiply operation. Good luck.