Commit a1c32761 authored by Thiago Santos's avatar Thiago Santos
Browse files

videodecoder: documentation cleanup

Remove some whitespace and break lines longer than 80 columns
parent 30e9c26b
...@@ -25,12 +25,13 @@ ...@@ -25,12 +25,13 @@
/** /**
* SECTION:gstvideodecoder * SECTION:gstvideodecoder
* @short_description: Base class for video decoders * @short_description: Base class for video decoders
* @see_also: * @see_also:
* *
* This base class is for video decoders turning encoded data into raw video * This base class is for video decoders turning encoded data into raw video
* frames. * frames.
* *
* The GstVideoDecoder base class and derived subclasses should cooperate as follows: * The GstVideoDecoder base class and derived subclasses should cooperate as
* follows:
* <orderedlist> * <orderedlist>
* <listitem> * <listitem>
* <itemizedlist><title>Configuration</title> * <itemizedlist><title>Configuration</title>
...@@ -46,7 +47,8 @@ ...@@ -46,7 +47,8 @@
* parameters require reconfiguration. * parameters require reconfiguration.
* </para></listitem> * </para></listitem>
* <listitem><para> * <listitem><para>
* Incoming data buffers are processed as needed, described in Data Processing below. * Incoming data buffers are processed as needed, described in Data
* Processing below.
* </para></listitem> * </para></listitem>
* <listitem><para> * <listitem><para>
* GstVideoDecoder calls @stop at end of all processing. * GstVideoDecoder calls @stop at end of all processing.
...@@ -62,15 +64,17 @@ ...@@ -62,15 +64,17 @@
* corresponding to and referred to as 'frames'. * corresponding to and referred to as 'frames'.
* </para></listitem> * </para></listitem>
* <listitem><para> * <listitem><para>
* Each input frame is provided in turn to the subclass' @handle_frame callback. * Each input frame is provided in turn to the subclass' @handle_frame
* callback.
* The ownership of the frame is given to the @handle_frame callback. * The ownership of the frame is given to the @handle_frame callback.
* </para></listitem> * </para></listitem>
* <listitem><para> * <listitem><para>
* If codec processing results in decoded data, the subclass should call * If codec processing results in decoded data, the subclass should call
* @gst_video_decoder_finish_frame to have decoded data pushed. * @gst_video_decoder_finish_frame to have decoded data pushed.
* downstream. Otherwise, the subclass must call @gst_video_decoder_drop_frame, to * downstream. Otherwise, the subclass must call
* allow the base class to do timestamp and offset tracking, and possibly to * @gst_video_decoder_drop_frame, to allow the base class to do timestamp
* requeue the frame for a later attempt in the case of reverse playback. * and offset tracking, and possibly to requeue the frame for a later
* attempt in the case of reverse playback.
* </para></listitem> * </para></listitem>
* </itemizedlist> * </itemizedlist>
* </listitem> * </listitem>
...@@ -87,20 +91,21 @@ ...@@ -87,20 +91,21 @@
* <listitem> * <listitem>
* <itemizedlist><title>Seeking/Flushing</title> * <itemizedlist><title>Seeking/Flushing</title>
* <listitem><para> * <listitem><para>
* When the pipeline is seeked or otherwise flushed, the subclass is informed via a call * When the pipeline is seeked or otherwise flushed, the subclass is
* to its @reset callback, with the hard parameter set to true. This indicates the * informed via a call to its @reset callback, with the hard parameter
* subclass should drop any internal data queues and timestamps and prepare for a fresh * set to true. This indicates the subclass should drop any internal data
* set of buffers to arrive for parsing and decoding. * queues and timestamps and prepare for a fresh set of buffers to arrive
* for parsing and decoding.
* </para></listitem> * </para></listitem>
* </itemizedlist> * </itemizedlist>
* </listitem> * </listitem>
* <listitem> * <listitem>
* <itemizedlist><title>End Of Stream</title> * <itemizedlist><title>End Of Stream</title>
* <listitem><para> * <listitem><para>
* At end-of-stream, the subclass @parse function may be called some final times with the * At end-of-stream, the subclass @parse function may be called some final
* at_eos parameter set to true, indicating that the element should not expect any more data * times with the at_eos parameter set to true, indicating that the element
* to be arriving, and it should parse and remaining frames and call * should not expect any more data to be arriving, and it should parse and
* gst_video_decoder_have_frame() if possible. * remaining frames and call gst_video_decoder_have_frame() if possible.
* </para></listitem> * </para></listitem>
* </itemizedlist> * </itemizedlist>
* </listitem> * </listitem>
...@@ -125,26 +130,30 @@ ...@@ -125,26 +130,30 @@
* should rather be left to upstream demuxer, parser or alike. This simple * should rather be left to upstream demuxer, parser or alike. This simple
* approach caters for seeking and duration reporting using estimated input * approach caters for seeking and duration reporting using estimated input
* bitrates. To enable it, a subclass should call * bitrates. To enable it, a subclass should call
* @gst_video_decoder_set_estimate_rate to enable handling of incoming byte-streams. * @gst_video_decoder_set_estimate_rate to enable handling of incoming
* byte-streams.
* *
* The base class provides some support for reverse playback, in particular * The base class provides some support for reverse playback, in particular
* in case incoming data is not packetized or upstream does not provide * in case incoming data is not packetized or upstream does not provide
* fragments on keyframe boundaries. However, the subclass should then be prepared * fragments on keyframe boundaries. However, the subclass should then be
* for the parsing and frame processing stage to occur separately (in normal * prepared for the parsing and frame processing stage to occur separately
* forward processing, the latter immediately follows the former), * (in normal forward processing, the latter immediately follows the former),
* The subclass also needs to ensure the parsing stage properly marks keyframes, * The subclass also needs to ensure the parsing stage properly marks
* unless it knows the upstream elements will do so properly for incoming data. * keyframes, unless it knows the upstream elements will do so properly for
* incoming data.
* *
* The bare minimum that a functional subclass needs to implement is: * The bare minimum that a functional subclass needs to implement is:
* <itemizedlist> * <itemizedlist>
* <listitem><para>Provide pad templates</para></listitem> * <listitem><para>Provide pad templates</para></listitem>
* <listitem><para> * <listitem><para>
* Inform the base class of output caps via @gst_video_decoder_set_output_state * Inform the base class of output caps via
* @gst_video_decoder_set_output_state
* </para></listitem> * </para></listitem>
* <listitem><para> * <listitem><para>
* Parse input data, if it is not considered packetized from upstream * Parse input data, if it is not considered packetized from upstream
* Data will be provided to @parse which should invoke @gst_video_decoder_add_to_frame and * Data will be provided to @parse which should invoke
* @gst_video_decoder_have_frame to separate the data belonging to each video frame. * @gst_video_decoder_add_to_frame and @gst_video_decoder_have_frame to
* separate the data belonging to each video frame.
* </para></listitem> * </para></listitem>
* <listitem><para> * <listitem><para>
* Accept data in @handle_frame and provide decoded results to * Accept data in @handle_frame and provide decoded results to
...@@ -177,16 +186,17 @@ ...@@ -177,16 +186,17 @@
* on whether forward or reverse playback is requested. * on whether forward or reverse playback is requested.
* *
* Forward playback: * Forward playback:
* * Incoming buffer -> @parse() -> add_to_frame()/have_frame() -> handle_frame() -> * * Incoming buffer -> @parse() -> add_to_frame()/have_frame() ->
* push downstream * handle_frame() -> push downstream
* *
* Reverse playback is more complicated, since it involves gathering incoming data regions * Reverse playback is more complicated, since it involves gathering incoming
* as we loop backwards through the upstream data. The processing concept (using incoming * data regions as we loop backwards through the upstream data. The processing
* buffers as containing one frame each to simplify things) is: * concept (using incoming buffers as containing one frame each to simplify
* things) is:
* *
* Upstream data we want to play: * Upstream data we want to play:
* Buffer encoded order: 1 2 3 4 5 6 7 8 9 EOS * Buffer encoded order: 1 2 3 4 5 6 7 8 9 EOS
* Keyframe flag: K K * Keyframe flag: K K
* Groupings: AAAAAAA BBBBBBB CCCCCCC * Groupings: AAAAAAA BBBBBBB CCCCCCC
* *
* Input: * Input:
...@@ -210,19 +220,20 @@ ...@@ -210,19 +220,20 @@
* this: * this:
* *
* while (gather) * while (gather)
* take head of queue and prepend to parse queue (this reverses the sequence, * take head of queue and prepend to parse queue (this reverses the
* so parse queue is 7 -> 8 -> 9) * sequence, so parse queue is 7 -> 8 -> 9)
* *
* Next, we process the parse queue, which now contains all un-parsed packets (including * Next, we process the parse queue, which now contains all un-parsed packets
* any leftover ones from the previous decode section) * (including any leftover ones from the previous decode section)
* *
* for each buffer now in the parse queue: * for each buffer now in the parse queue:
* Call the subclass parse function, prepending each resulting frame to * Call the subclass parse function, prepending each resulting frame to
* the parse_gather queue. Buffers which precede the first one that * the parse_gather queue. Buffers which precede the first one that
* produces a parsed frame are retained in the parse queue for re-processing on * produces a parsed frame are retained in the parse queue for
* the next cycle of parsing. * re-processing on the next cycle of parsing.
* *
* The parse_gather queue now contains frame objects ready for decoding, in reverse order. * The parse_gather queue now contains frame objects ready for decoding,
* in reverse order.
* parse_gather: 9 -> 8 -> 7 * parse_gather: 9 -> 8 -> 7
* *
* while (parse_gather) * while (parse_gather)
...@@ -233,8 +244,8 @@ ...@@ -233,8 +244,8 @@
* Processing the decode queue results in frames with attached output buffers * Processing the decode queue results in frames with attached output buffers
* stored in the 'output_queue' ready for outputting in reverse order. * stored in the 'output_queue' ready for outputting in reverse order.
* *
* After we flushed the gather queue and parsed it, we add 4 to the (now empty) gather queue. * After we flushed the gather queue and parsed it, we add 4 to the (now empty)
* We get the following situation: * gather queue. We get the following situation:
* *
* gather queue: 4 * gather queue: 4
* decode queue: 7 8 9 * decode queue: 7 8 9
...@@ -262,7 +273,7 @@ ...@@ -262,7 +273,7 @@
* output queue: * output queue:
* *
* gather queue: 4 * gather queue: 4
* decode queue: * decode queue:
* output queue: 9 8 7 6 5 * output queue: 9 8 7 6 5
* *
* Now output all the frames in the output queue, picking a frame from the * Now output all the frames in the output queue, picking a frame from the
...@@ -287,7 +298,7 @@ ...@@ -287,7 +298,7 @@
* Decoded output: * Decoded output:
* *
* gather queue: 1 * gather queue: 1
* decode queue: * decode queue:
* output queue: 4 3 2 * output queue: 4 3 2
* *
* Leftover buffer 1 cannot be decoded and must be discarded. * Leftover buffer 1 cannot be decoded and must be discarded.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment