+++ /dev/null
-<chapter> <title> The video output layer </title>
-
- <sect1> <title> Data structures and main loop </title>
-
- <para>
-Important data structures are defined in <filename> include/video.h
-</filename> and <filename> include/video_output.h</filename>. The main
-data structure is <type> picture_t</type>, which describes everything a
-video decoder thread needs. Please refer to this file for more
-information. Typically, <parameter> p_data </parameter> will be a
-pointer to YUV planar picture.
- </para>
-
- <para>
-Note also the <type> subpicture_t </type> structure. In fact the VLC SPU
-decoder only parses the SPU header, and converts the SPU graphical data
-to an internal format which can be rendered much faster. So a part of
-the "real" SPU decoder lies in
-<filename> src/video_output/video_spu.c</filename>.
- </para>
-
- <para>
-The <type> vout_thread_t </type> structure is much more complex, but
-you needn't understand everything. Basically the video output thread
-manages a heap of pictures and subpictures (5 by default). Every
-picture has a status (displayed, destroyed, empty...) and eventually
-a presentation time. The main job of the video output is an infinite
-loop to : [this is subject to change in the near future]
- </para>
-
- <orderedlist>
-
- <listitem> <para> Find the next picture to display in the heap.
- </para> </listitem>
-
- <listitem> <para> Find the current subpicture to display.
- </para> </listitem>
-
- <listitem> <para> Render the picture (if the video output plug-in
- doesn't support YUV overlay). Rendering will call an optimized
- YUV plug-in, which will also do the scaling, add subtitles and
- an optional picture information field.
- </para> </listitem>
-
- <listitem> <para> Sleep until the specified date.
- </para> </listitem>
-
- <listitem> <para> Display the picture (plug-in function). For
- outputs which display RGB data, it is often accomplished with
- a buffer switching. <parameter> p_vout->p_buffer </parameter>
- is an array of two buffers where the YUV transform takes place,
- and p_vout->i_buffer_index indicates the currently displayed
- buffer.
- </para> </listitem>
-
- <listitem> <para> Manage events.
- </para> </listitem>
-
- </orderedlist>
-
- </sect1>
-
- <sect1> <title> Methods used by video decoders </title>
-
- <para>
-The video output exports a bunch of functions so that decoders can send
-their decoded data. The most important function is
-<function>vout_CreatePicture</function> which allocates the picture
-buffer to the size indicated by the video decoder. It then just needs
-to feed <type> (void *) </type><parameter> p_picture->p_data </parameter>
-with the decoded data, and call <function> vout_DisplayPicture </function>
-and <function> vout_DatePicture </function> upon necessary.
- </para>
-
- <itemizedlist>
-
- <listitem> <para> <type> picture_t * </type> <function>
- vout_CreatePicture </function>
- <parameter> ( vout_thread_t *p_vout, int i_type, int i_width,
- int i_height ) </parameter> :
- Returns an allocated picture buffer. <parameter> i_type </parameter>
- will be for instance <constant> YUV_420_PICTURE</constant>, and
- i_width and i_height are in pixels.
- </para>
-
- <warning> <para> If no picture is available in the heap,
- <function> vout_CreatePicture </function> will return NULL.
- </para> </warning>
- </listitem>
-
- <listitem> <para> <function> vout_LinkPicture </function>
- <parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
- Increases the refcount of the picture, so that it doesn't get
- accidently freed while the decoder still needs it. For instance,
- an I or P picture can still be needed after displaying to decode
- interleaved B pictures.
- </para> </listitem>
-
- <listitem> <para> <function> vout_UnlinkPicture </function>
- <parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
- Decreases the refcount of the picture. An unlink must be done
- for every link previously made.
- </para> </listitem>
-
- <listitem> <para> <function> vout_DatePicture </function>
- <parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
- Gives the picture a presentation date. You can start working on
- a picture before knowing precisely at what time it will be
- displayed. For instance to date an I or P picture, you must wait
- until you have decoded all previous B pictures (which are
- indeed placed after - decoding order != presentation order).
- </para> </listitem>
-
- <listitem> <para> <function> vout_DisplayPicture </function>
- <parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
- Tells the video output that a picture has been completely decoded
- and is ready to be rendered. It can be called before or after
- <function> vout_DatePicture</function>.
- </para> </listitem>
-
- <listitem> <para> <function> vout_DestroyPicture </function>
- <parameter> ( vout_thread_t *p_vout, picture_t *p_pic ) </parameter> :
- Marks the picture as empty (useful in case of a stream parsing
- error).
- </para> </listitem>
-
- <listitem> <para> <type> subpicture_t * </type> <function>
- vout_CreateSubPicture </function> <parameter> ( vout_thread_t *p_vout,
- int i_channel, int i_type ) </parameter> :
- Returns an allocated subpicture buffer. <parameter> i_channel
- </parameter> is the ID of the subpicture channel, <parameter> i_type
- </parameter> is <constant> DVD_SUBPICTURE </constant> or
- <constant> TEXT_SUBPICTURE</constant>, <parameter> i_size
- </parameter> is the length in bytes of the packet.
- </para> </listitem>
-
- <listitem> <para> <function> vout_DisplaySubPicture </function>
- <parameter> ( vout_thread_t *p_vout, subpicture_t *p_subpic )
- </parameter> :
- Tells the video output that a subpicture has been completely
- decoded. It obsoletes the previous subpicture.
- </para> </listitem>
-
- <listitem> <para> <function> vout_DestroySubPicture </function>
- <parameter> ( vout_thread_t *p_vout, subpicture_t *p_subpic )
- </parameter> :
- Marks the subpicture as empty.
- </para> </listitem>
-
- </itemizedlist>
-
- </sect1>
-
- <sect1> <title> How to write a video output plug-in </title>
-
- <para>
-A video output takes care of the system calls to display the pictures and
-manage the output window. Have a look at <filename>
-plugins/x11/vout_x11.c</filename>. You must write the following
-functions :
- </para>
-
- <orderedlist>
-
- <listitem> <para> <type> int </type> <function> vout_Probe </function>
- <parameter> ( probedata_t *p_data ) </parameter> :
- Returns a score between 0 and 999 to indicate whether it can
- run on the architecture. 999 is the best. <parameter> p_data
- </parameter> is currently unused.
- </para> </listitem>
-
- <listitem> <para> <type> int </type> <function> vout_Create </function>
- <parameter> ( vout_thread_t *p_vout ) </parameter> :
- Basically, initializes and opens a new window. Returns TRUE if
- it failed.
- </para> </listitem>
-
- <listitem> <para> <type> int </type> <function> vout_Init </function>
- <parameter> ( vout_thread_t *p_vout ) </parameter> :
- Creates optional picture buffers (for instance ximages or
- xvimages). Returns TRUE if it failed.
- </para> </listitem>
-
- <listitem> <para> <function> vout_End </function> <parameter>
- ( vout_thread_t *p_vout ) </parameter> :
- Frees optional picture buffers.
- </para> </listitem>
-
- <listitem> <para> <type> int </type> <function> vout_Manage
- </function> <parameter> ( vout_thread_t *p_vout ) </parameter> :
- Manages events (including for instance resize events).
- </para> </listitem>
-
- <listitem> <para> <function> vout_Display </function> <parameter>
- ( vout_thread_t *p_vout ) </parameter> :
- Displays a previously rendered buffer.
- </para> </listitem>
-
- <listitem> <para> <function> vout_SetPalette </function>
- <parameter> ( vout_thread_t *p_vout, u16 *red, u16 *green,
- u16 *blue, u16 *transp ) </parameter> :
- Sets the 8 bpp palette. <parameter> red, green </parameter>
- and <parameter> blue </parameter> are arrays of 256 <type>
- unsigned shorts</type>.
- </para> </listitem>
-
- </orderedlist>
-
- </sect1>
-
- <sect1> <title> How to write a YUV plug-in </title>
-
- <para>
-Look at the C source <filename> plugins/yuv/transforms_yuv.c</filename>.
-You need to redefine just the same transformations. Basically, it is a
-matrix multiply operation. Good luck.
- </para>
-
- </sect1>
-
-</chapter>
projects / vlc / blobdiff