videodecoder: documentation cleanup

Remove some whitespace and break lines longer than 80 columns

gst-libs/gst/video/gstvideodecoder.c

@@ -25,12 +25,13 @@
 /**
  * SECTION:gstvideodecoder
  * @short_description: Base class for video decoders
- * @see_also: 
+ * @see_also:
  *
  * This base class is for video decoders turning encoded data into raw video
  * frames.
  *
- * The GstVideoDecoder base class and derived subclasses should cooperate as follows:
+ * The GstVideoDecoder base class and derived subclasses should cooperate as
+ * follows:
  * <orderedlist>
  * <listitem>
  *   <itemizedlist><title>Configuration</title>
@@ -46,7 +47,8 @@
  *     parameters require reconfiguration.
  *   </para></listitem>
  *   <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>
  *   <listitem><para>
  *     GstVideoDecoder calls @stop at end of all processing.
@@ -62,15 +64,17 @@
  *       corresponding to and referred to as 'frames'.
  *     </para></listitem>
  *     <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.
  *     </para></listitem>
  *     <listitem><para>
  *       If codec processing results in decoded data, the subclass should call
  *       @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>
  *   </itemizedlist>
  * </listitem>
@@ -87,20 +91,21 @@
  *   <listitem>
  *     <itemizedlist><title>Seeking/Flushing</title>
  *     <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>
  *     </itemizedlist>
  *   </listitem>
  *   <listitem>
  *     <itemizedlist><title>End Of Stream</title>
  *     <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>
  *     </itemizedlist>
  *   </listitem>
@@ -125,26 +130,30 @@
  * should rather be left to upstream demuxer, parser or alike.  This simple
  * approach caters for seeking and duration reporting using estimated input
  * 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
  * 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:
  * <itemizedlist>
  *   <listitem><para>Provide pad templates</para></listitem>
  *   <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>
  *   <listitem><para>
  *      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>
  *   <listitem><para>
  *      Accept data in @handle_frame and provide decoded results to
@@ -177,16 +186,17 @@
  * on whether forward or reverse playback is requested.
  *
  * 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:
  *  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
  *
  * Input:
@@ -210,19 +220,20 @@
  * this:
  *
  *   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:
  *     Call the subclass parse function, prepending each resulting frame to
  *     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
  *
  *   while (parse_gather)
@@ -233,8 +244,8 @@
  *  Processing the decode queue results in frames with attached output buffers
  *  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
  *  decode queue:    7  8  9
@@ -262,7 +273,7 @@
  *   output queue:
  *
  *    gather queue:    4
- *    decode queue:    
+ *    decode queue:
  *    output queue:    9  8  7  6  5
  *
  *   Now output all the frames in the output queue, picking a frame from the
@@ -287,7 +298,7 @@
  *  Decoded output:
  *
  *    gather queue:    1
- *    decode queue:    
+ *    decode queue:
  *    output queue:    4  3  2
  *
  *  Leftover buffer 1 cannot be decoded and must be discarded.