video: Update/add docs

6 files changed, 127 insertions, 29 deletions

diff --git a/gst-libs/gst/video/gstbasevideocodec.c b/gst-libs/gst/video/gstbasevideocodec.c
index 9bdee5936..cae94ab11 100644
--- a/gst-libs/gst/video/gstbasevideocodec.c
+++ b/gst-libs/gst/video/gstbasevideocodec.c
@@ -21,6 +21,12 @@
 #include "config.h"
 #endif
 
+/**
+ * SECTION:gstbasevideocodec
+ * @short_description: Base class for video codecs
+ * @see_also: #GstBaseVideoDecoder , #GstBaseVideoEncoder
+ */
+
 /* FIXME 0.11: suppress warnings for deprecated API such as GStaticRecMutex
  * with newer GLib versions (>= 2.31.0) */
 #define GLIB_DISABLE_DEPRECATION_WARNINGS
@@ -189,6 +195,14 @@ gst_base_video_codec_change_state (GstElement * element,
   return ret;
 }
 
+/**
+ * gst_base_video_codec_new_frame:
+ * @base_video_codec: a #GstBaseVideoCodec
+ *
+ * Create a new blank #GstVideoFrame.
+ * 
+ * Returns: (transfer full): a new #GstVideoFrame
+ */
 GstVideoFrame *
 gst_base_video_codec_new_frame (GstBaseVideoCodec * base_video_codec)
 {
@@ -231,6 +245,14 @@ _gst_video_frame_free (GstVideoFrame * frame)
   g_slice_free (GstVideoFrame, frame);
 }
 
+/**
+ * gst_video_frame_ref:
+ * @frame: a #GstVideoFrame
+ *
+ * Increases the refcount of the given frame by one.
+ *
+ * Returns: @buf
+ */
 GstVideoFrame *
 gst_video_frame_ref (GstVideoFrame * frame)
 {
@@ -241,6 +263,13 @@ gst_video_frame_ref (GstVideoFrame * frame)
   return frame;
 }
 
+/**
+ * gst_video_frame_unref:
+ * @frame: a #GstVideoFrame
+ *
+ * Decreases the refcount of the frame. If the refcount reaches 0, the frame
+ * will be freed.
+ */
 void
 gst_video_frame_unref (GstVideoFrame * frame)
 {
diff --git a/gst-libs/gst/video/gstbasevideocodec.h b/gst-libs/gst/video/gstbasevideocodec.h
index 7a76f9d12..de5d3fe72 100644
--- a/gst-libs/gst/video/gstbasevideocodec.h
+++ b/gst-libs/gst/video/gstbasevideocodec.h
@@ -76,10 +76,27 @@ G_BEGIN_DECLS
 /**
  * GST_BASE_VIDEO_CODEC_FLOW_NEED_DATA:
  *
+ * Returned while parsing to indicate more data is needed.
  */
 #define GST_BASE_VIDEO_CODEC_FLOW_NEED_DATA GST_FLOW_CUSTOM_SUCCESS
 
+/**
+ * GST_BASE_VIDEO_CODEC_STREAM_LOCK:
+ * @codec: video codec instance
+ *
+ * Obtain a lock to protect the codec function from concurrent access.
+ *
+ * Since: 0.10.22
+ */
 #define GST_BASE_VIDEO_CODEC_STREAM_LOCK(codec) g_static_rec_mutex_lock (&GST_BASE_VIDEO_CODEC (codec)->stream_lock)
+/**
+ * GST_BASE_VIDEO_CODEC_STREAM_UNLOCK:
+ * @codec: video codec instance
+ *
+ * Release the lock that protects the codec function from concurrent access.
+ *
+ * Since: 0.10.22
+ */
 #define GST_BASE_VIDEO_CODEC_STREAM_UNLOCK(codec) g_static_rec_mutex_unlock (&GST_BASE_VIDEO_CODEC (codec)->stream_lock)
 
 typedef struct _GstVideoState GstVideoState;
@@ -87,6 +104,10 @@ typedef struct _GstVideoFrame GstVideoFrame;
 typedef struct _GstBaseVideoCodec GstBaseVideoCodec;
 typedef struct _GstBaseVideoCodecClass GstBaseVideoCodecClass;
 
+/**
+ * GstVideoState:
+ * @caps: The caps 
+ */
 struct _GstVideoState
 {
   GstCaps *caps;
@@ -147,38 +168,51 @@ struct _GstVideoFrame
   GList *events;
 };
 
+/**
+ * GstBaseVideoCodec:
+ *
+ * The opaque #GstBaseVideoCodec data structure.
+ */
 struct _GstBaseVideoCodec
 {
-  GstElement element;
-
   /*< private >*/
-  GstPad *sinkpad;
-  GstPad *srcpad;
+  GstElement      element;
+
+  /*< protected >*/
+  GstPad         *sinkpad;
+  GstPad         *srcpad;
 
   /* protects all data processing, i.e. is locked
    * in the chain function, finish_frame and when
    * processing serialized events */
   GStaticRecMutex stream_lock;
 
-  guint64 system_frame_number;
+  guint64         system_frame_number;
 
-  GList *frames;  /* Protected with OBJECT_LOCK */
-  GstVideoState state;
-  GstSegment segment;
+  GList          *frames;  /* Protected with OBJECT_LOCK */
+  GstVideoState   state;
+  GstSegment      segment;
 
-  gdouble proportion;
-  GstClockTime earliest_time;
-  gboolean discont;
+  /* QoS properties */
+  gdouble         proportion;
+  GstClockTime    earliest_time;
+  gboolean        discont;
 
-  gint64 bytes;
-  gint64 time;
+  gint64          bytes;
+  gint64          time;
 
   /* FIXME before moving to base */
-  void *padding[GST_PADDING_LARGE];
+  void           *padding[GST_PADDING_LARGE];
 };
 
+/**
+ * GstBaseVideoCodecClass:
+ *
+ * The opaque #GstBaseVideoCodecClass data structure.
+ */
 struct _GstBaseVideoCodecClass
 {
+  /*< private >*/
   GstElementClass element_class;
 
   /* FIXME before moving to base */
diff --git a/gst-libs/gst/video/gstbasevideodecoder.c b/gst-libs/gst/video/gstbasevideodecoder.c
index dab7ae898..dc4549820 100644
--- a/gst-libs/gst/video/gstbasevideodecoder.c
+++ b/gst-libs/gst/video/gstbasevideodecoder.c
@@ -1690,7 +1690,7 @@ done:
 }
 
 /**
- * gst_base_video_decoder_finish_frame:
+ * gst_base_video_decoder_add_to_frame:
  * @base_video_decoder: a #GstBaseVideoDecoder
  * @n_bytes: an encoded #GstVideoFrame
  *
@@ -1886,11 +1886,15 @@ exit:
  * gst_base_video_decoder_get_state:
  * @base_video_decoder: a #GstBaseVideoDecoder
  *
+ * Get the current #GstVideoState
+ *
  * Returns: #GstVideoState describing format of video data.
  */
 GstVideoState *
 gst_base_video_decoder_get_state (GstBaseVideoDecoder * base_video_decoder)
 {
+  /* FIXME : Move to base codec class */
+
   return &GST_BASE_VIDEO_CODEC (base_video_decoder)->state;
 }
 
@@ -1939,6 +1943,8 @@ gst_base_video_decoder_set_sync_point (GstBaseVideoDecoder * base_video_decoder)
  * gst_base_video_decoder_get_oldest_frame:
  * @base_video_decoder: a #GstBaseVideoDecoder
  *
+ * Get the oldest pending unfinished #GstVideoFrame
+ *
  * Returns: oldest pending unfinished #GstVideoFrame.
  */
 GstVideoFrame *
@@ -1947,6 +1953,8 @@ gst_base_video_decoder_get_oldest_frame (GstBaseVideoDecoder *
 {
   GList *g;
 
+  /* FIXME : Move to base codec class */
+
   GST_BASE_VIDEO_CODEC_STREAM_LOCK (base_video_decoder);
   g = g_list_first (GST_BASE_VIDEO_CODEC (base_video_decoder)->frames);
   GST_BASE_VIDEO_CODEC_STREAM_UNLOCK (base_video_decoder);
@@ -1961,6 +1969,8 @@ gst_base_video_decoder_get_oldest_frame (GstBaseVideoDecoder *
  * @base_video_decoder: a #GstBaseVideoDecoder
  * @frame_number: system_frame_number of a frame
  *
+ * Get a pending unfinished #GstVideoFrame
+ * 
  * Returns: pending unfinished #GstVideoFrame identified by @frame_number.
  */
 GstVideoFrame *
@@ -1991,6 +2001,7 @@ gst_base_video_decoder_get_frame (GstBaseVideoDecoder * base_video_decoder,
  *
  * Sets src pad caps according to currently configured #GstVideoState.
  *
+ * Returns: #TRUE if the caps were accepted downstream, else #FALSE.
  */
 gboolean
 gst_base_video_decoder_set_src_caps (GstBaseVideoDecoder * base_video_decoder)
@@ -2042,11 +2053,11 @@ gst_base_video_decoder_set_src_caps (GstBaseVideoDecoder * base_video_decoder)
  * gst_base_video_decoder_alloc_src_buffer:
  * @base_video_decoder: a #GstBaseVideoDecoder
  *
- * Helper function that uses gst_pad_alloc_buffer_and_set_caps
+ * Helper function that uses @gst_pad_alloc_buffer_and_set_caps()
  * to allocate a buffer to hold a video frame for @base_video_decoder's
  * current #GstVideoState.
  *
- * Returns: allocated buffer
+ * Returns: (transfer full): allocated buffer
  */
 GstBuffer *
 gst_base_video_decoder_alloc_src_buffer (GstBaseVideoDecoder *
@@ -2075,6 +2086,7 @@ gst_base_video_decoder_alloc_src_buffer (GstBaseVideoDecoder *
   }
 
   GST_BASE_VIDEO_CODEC_STREAM_UNLOCK (base_video_decoder);
+
   return buffer;
 }
 
@@ -2083,7 +2095,7 @@ gst_base_video_decoder_alloc_src_buffer (GstBaseVideoDecoder *
  * @base_video_decoder: a #GstBaseVideoDecoder
  * @frame: a #GstVideoFrame
  *
- * Helper function that uses gst_pad_alloc_buffer_and_set_caps
+ * Helper function that uses @gst_pad_alloc_buffer_and_set_caps()
  * to allocate a buffer to hold a video frame for @base_video_decoder's
  * current #GstVideoState.  Subclass should already have configured video state
  * and set src pad caps.
@@ -2158,8 +2170,10 @@ gst_base_video_decoder_get_max_decode_time (GstBaseVideoDecoder *
 }
 
 /**
- * gst_base_video_decoder_get_oldest_frame:
+ * gst_base_video_decoder_class_set_capture_pattern:
  * @base_video_decoder_class: a #GstBaseVideoDecoderClass
+ * @mask: The mask used for scanning
+ * @pattern: The pattern used for matching
  *
  * Sets the mask and pattern that will be scanned for to obtain parse sync.
  * Note that a non-zero @mask implies that @scan_for_sync will be ignored.
diff --git a/gst-libs/gst/video/gstbasevideodecoder.h b/gst-libs/gst/video/gstbasevideodecoder.h
index a3b81fe44..21d757a5e 100644
--- a/gst-libs/gst/video/gstbasevideodecoder.h
+++ b/gst-libs/gst/video/gstbasevideodecoder.h
@@ -95,7 +95,7 @@ GstFlowReturn _gst_base_video_decoder_error (GstBaseVideoDecoder *dec, gint weig
  *          enclosed in parentheses)
  * @ret:    variable to receive return value
  *
- * Utility function that audio decoder elements can use in case they encountered
+ * Utility function that video decoder elements can use in case they encountered
  * a data processing error that may be fatal for the current "data unit" but
  * need not prevent subsequent decoding.  Such errors are counted and if there
  * are too many, as configured in the context's max_errors, the pipeline will
@@ -104,7 +104,7 @@ GstFlowReturn _gst_base_video_decoder_error (GstBaseVideoDecoder *dec, gint weig
  * is logged. In either case, @ret is set to the proper value to
  * return to upstream/caller (indicating either GST_FLOW_ERROR or GST_FLOW_OK).
  */
-#define GST_BASE_AUDIO_DECODER_ERROR(el, w, domain, code, text, debug, ret) \
+#define GST_BASE_VIDEO_DECODER_ERROR(el, w, domain, code, text, debug, ret) \
 G_STMT_START {                                                              \
   gchar *__txt = _gst_element_error_printf text;                            \
   gchar *__dbg = _gst_element_error_printf debug;                           \
@@ -122,6 +122,7 @@ G_STMT_START {                                                              \
  */
 struct _GstBaseVideoDecoder
 {
+  /*< private >*/
   GstBaseVideoCodec base_video_codec;
 
   /*< protected >*/
@@ -220,8 +221,10 @@ struct _GstBaseVideoDecoder
  */
 struct _GstBaseVideoDecoderClass
 {
+  /*< private >*/
   GstBaseVideoCodecClass base_video_codec_class;
 
+  /*< public >*/
   gboolean      (*start)          (GstBaseVideoDecoder *coder);
 
   gboolean      (*stop)           (GstBaseVideoDecoder *coder);
@@ -248,12 +251,12 @@ struct _GstBaseVideoDecoderClass
   void         *padding[GST_PADDING_LARGE];
 };
 
-void             gst_base_video_decoder_class_set_capture_pattern (GstBaseVideoDecoderClass *klass,
+void             gst_base_video_decoder_class_set_capture_pattern (GstBaseVideoDecoderClass *base_video_decoder_class,
                                     guint32 mask, guint32 pattern);
 
-GstVideoFrame   *gst_base_video_decoder_get_frame (GstBaseVideoDecoder *coder,
+GstVideoFrame   *gst_base_video_decoder_get_frame (GstBaseVideoDecoder *base_video_decoder,
                                     int frame_number);
-GstVideoFrame   *gst_base_video_decoder_get_oldest_frame (GstBaseVideoDecoder *coder);
+GstVideoFrame   *gst_base_video_decoder_get_oldest_frame (GstBaseVideoDecoder *base_video_decoder);
 
 void             gst_base_video_decoder_add_to_frame (GstBaseVideoDecoder *base_video_decoder,
                                     int n_bytes);
diff --git a/gst-libs/gst/video/gstbasevideoencoder.c b/gst-libs/gst/video/gstbasevideoencoder.c
index d643e7279..50ed82ad9 100644
--- a/gst-libs/gst/video/gstbasevideoencoder.c
+++ b/gst-libs/gst/video/gstbasevideoencoder.c
@@ -264,6 +264,13 @@ gst_base_video_encoder_init (GstBaseVideoEncoder * base_video_encoder,
   base_video_encoder->sink_clipping = TRUE;
 }
 
+/**
+ * gst_base_video_encoder_set_headers:
+ * @base_video_encoder: a #GstBaseVideoEncoder
+ * @headers: (transfer full): the #GstBuffer containing the codec header
+ *
+ * Set the codec headers to be sent downstream whenever requested.
+ */
 void
 gst_base_video_encoder_set_headers (GstBaseVideoEncoder * base_video_encoder,
     GstBuffer * headers)
@@ -1131,11 +1138,15 @@ done:
  * gst_base_video_encoder_get_state:
  * @base_video_encoder: a #GstBaseVideoEncoder
  *
+ * Get the current #GstVideoState
+ *
  * Returns: #GstVideoState describing format of video data.
  */
 const GstVideoState *
 gst_base_video_encoder_get_state (GstBaseVideoEncoder * base_video_encoder)
 {
+  /* FIXME : Move to base codec class */
+
   return &GST_BASE_VIDEO_CODEC (base_video_encoder)->state;
 }
 
@@ -1166,7 +1177,7 @@ gst_base_video_encoder_set_latency (GstBaseVideoEncoder * base_video_encoder,
 /**
  * gst_base_video_encoder_set_latency_fields:
  * @base_video_encoder: a #GstBaseVideoEncoder
- * @fields: latency in fields
+ * @n_fields: latency in fields
  *
  * Informs baseclass of encoding latency in terms of fields (both min
  * and max latency).
@@ -1193,6 +1204,8 @@ gst_base_video_encoder_set_latency_fields (GstBaseVideoEncoder *
  * gst_base_video_encoder_get_oldest_frame:
  * @base_video_encoder: a #GstBaseVideoEncoder
  *
+ * Get the oldest unfinished pending #GstVideoFrame
+ *
  * Returns: oldest unfinished pending #GstVideoFrame
  */
 GstVideoFrame *
@@ -1201,6 +1214,8 @@ gst_base_video_encoder_get_oldest_frame (GstBaseVideoEncoder *
 {
   GList *g;
 
+  /* FIXME : Move to base codec class */
+
   GST_BASE_VIDEO_CODEC_STREAM_LOCK (base_video_encoder);
   g = g_list_first (GST_BASE_VIDEO_CODEC (base_video_encoder)->frames);
   GST_BASE_VIDEO_CODEC_STREAM_UNLOCK (base_video_encoder);
diff --git a/gst-libs/gst/video/gstbasevideoencoder.h b/gst-libs/gst/video/gstbasevideoencoder.h
index 6e2aa7095..4fad71b6c 100644
--- a/gst-libs/gst/video/gstbasevideoencoder.h
+++ b/gst-libs/gst/video/gstbasevideoencoder.h
@@ -70,12 +70,12 @@ typedef struct _GstBaseVideoEncoderClass GstBaseVideoEncoderClass;
 
 /**
  * GstBaseVideoEncoder:
- * @element: the parent element.
  *
  * The opaque #GstBaseVideoEncoder data structure.
  */
 struct _GstBaseVideoEncoder
 {
+  /*< private >*/
   GstBaseVideoCodec base_video_codec;
 
   /*< protected >*/
@@ -115,6 +115,8 @@ struct _GstBaseVideoEncoder
  *                  GstVideoState fields have already been
  *                  set according to provided caps.
  * @handle_frame:   Provides input frame to subclass.
+ * @reset:          Optional.
+ *                  Allows subclass (codec) to perform post-seek semantics reset.
  * @finish:         Optional.
  *                  Called to request subclass to dispatch any pending remaining
  *                  data (e.g. at EOS).
@@ -133,6 +135,7 @@ struct _GstBaseVideoEncoder
  */
 struct _GstBaseVideoEncoderClass
 {
+  /*< private >*/
   GstBaseVideoCodecClass              base_video_codec_class;
 
   /*< public >*/
@@ -164,9 +167,9 @@ struct _GstBaseVideoEncoderClass
 
 GType                  gst_base_video_encoder_get_type (void);
 
-const GstVideoState*   gst_base_video_encoder_get_state (GstBaseVideoEncoder *coder);
+const GstVideoState*   gst_base_video_encoder_get_state (GstBaseVideoEncoder *base_video_encoder);
 
-GstVideoFrame*         gst_base_video_encoder_get_oldest_frame (GstBaseVideoEncoder *coder);
+GstVideoFrame*         gst_base_video_encoder_get_oldest_frame (GstBaseVideoEncoder *base_video_encoder);
 GstFlowReturn          gst_base_video_encoder_finish_frame (GstBaseVideoEncoder *base_video_encoder,
                                                             GstVideoFrame *frame);
 
@@ -175,7 +178,7 @@ void                   gst_base_video_encoder_set_latency (GstBaseVideoEncoder *
 void                   gst_base_video_encoder_set_latency_fields (GstBaseVideoEncoder *base_video_encoder,
                                                                   int n_fields);
 void                   gst_base_video_encoder_set_headers (GstBaseVideoEncoder *base_video_encoder,
-                                                                  GstBuffer *headers);
+							   GstBuffer *headers);
 G_END_DECLS
 
 #endif