git.sesse.net Git - vlc/blob - doc/developer/video_output.xml

   1 <chapter> <title> The video output layer </title>
   2
   3   <sect1> <title> Data structures and main loop </title>
   4
   5     <para>
   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.
  12     </para>
  13
  14     <para>
  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>.
  20     </para>
  21
  22     <para>
  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]
  29     </para>
  30
  31     <orderedlist>
  32
  33       <listitem> <para> Find the next picture to display in the heap.
  34       </para> </listitem>
  35
  36       <listitem> <para> Find the current subpicture to display.
  37       </para> </listitem>
  38
  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.
  43       </para> </listitem>
  44
  45       <listitem> <para> Sleep until the specified date.
  46       </para> </listitem>
  47
  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-&gt;p_buffer </parameter>
  51       is an array of two buffers where the YUV transform takes place,
  52       and p_vout-&gt;i_buffer_index indicates the currently displayed
  53       buffer.
  54       </para> </listitem>
  55
  56       <listitem> <para> Manage events.
  57       </para> </listitem>
  58
  59     </orderedlist>
  60
  61   </sect1>
  62
  63   <sect1> <title> Methods used by video decoders </title>
  64
  65     <para>
  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-&gt;p_data </parameter>
  71 with the decoded data, and call <function> vout_DisplayPicture </function>
  72 and <function> vout_DatePicture </function> upon necessary.
  73     </para>
  74
  75     <itemizedlist>
  76
  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.
  84       </para>
  85
  86       <warning> <para> If no picture is available in the heap,
  87       <function> vout_CreatePicture </function> will return NULL.
  88       </para> </warning>
  89       </listitem>
  90
  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.
  97       </para> </listitem>
  98
  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.
 103       </para> </listitem>
 104
 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).
 112       </para> </listitem>
 113
 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>.
 119       </para> </listitem>
 120
 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
 124       error).
 125       </para> </listitem>
 126
 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.
 135       </para> </listitem>
 136
 137       <listitem> <para> <function> vout_DisplaySubPicture </function>
 138       <parameter> ( vout_thread_t *p_vout, subpicture_t *p_subpic )
 139       </parameter> :
 140       Tells the video output that a subpicture has been completely
 141       decoded. It obsoletes the previous subpicture.
 142       </para> </listitem>
 143
 144       <listitem> <para> <function> vout_DestroySubPicture </function>
 145       <parameter> ( vout_thread_t *p_vout, subpicture_t *p_subpic )
 146       </parameter> :
 147       Marks the subpicture as empty.
 148       </para> </listitem>
 149
 150     </itemizedlist>
 151
 152   </sect1>
 153
 154   <sect1> <title> How to write a video output plug-in </title>
 155
 156     <para>
 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
 160 functions :
 161     </para>
 162
 163     <orderedlist>
 164
 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.
 170       </para> </listitem>
 171
 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
 175       it failed.
 176       </para> </listitem>
 177
 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.
 182       </para> </listitem>
 183
 184       <listitem> <para> <function> vout_End </function> <parameter>
 185       ( vout_thread_t *p_vout ) </parameter> :
 186       Frees optional picture buffers.
 187       </para> </listitem>
 188
 189       <listitem> <para> <function> vout_Destroy </function> <parameter>
 190       ( vout_thread_t *p_vout ) </parameter> :
 191       Unmaps the window and frees all allocated resources.
 192       </para> </listitem>
 193
 194       <listitem> <para> <type> int </type> <function> vout_Manage
 195       </function> <parameter> ( vout_thread_t *p_vout ) </parameter> :
 196       Manages events (including for instance resize events).
 197       </para> </listitem>
 198
 199       <listitem> <para> <function> vout_Display </function> <parameter>
 200       ( vout_thread_t *p_vout ) </parameter> :
 201       Displays a previously rendered buffer.
 202       </para> </listitem>
 203
 204       <listitem> <para> <function> vout_SetPalette </function>
 205       <parameter> ( vout_thread_t *p_vout, u16 *red, u16 *green,
 206       u16 *blue, u16 *transp ) </parameter> :
 207       Sets the 8 bpp palette. <parameter> red, green </parameter>
 208       and <parameter> blue </parameter> are arrays of 256 <type>
 209       unsigned shorts</type>.
 210       </para> </listitem>
 211
 212     </orderedlist>
 213
 214   </sect1>
 215
 216   <sect1> <title> How to write a YUV plug-in </title>
 217
 218     <para>
 219 Look at the C source <filename> plugins/yuv/transforms_yuv.c</filename>.
 220 You need to redefine just the same transformations. Basically, it is a
 221 matrix multiply operation. Good luck.
 222     </para>
 223
 224   </sect1>
 225
 226 </chapter>