video-info: improve GST_CAPS_FEATURE_FORMAT_INTERLACED documentation

Copied the description from gst-doc written by Tim.

Fix #606

diff --git a/gst-libs/gst/video/video-info.h b/gst-libs/gst/video/video-info.h
index e6a175e..62c2356 100644 (file)
--- a/gst-libs/gst/video/video-info.h
+++ b/gst-libs/gst/video/video-info.h
@@ -33,8 +33,19 @@ typedef struct _GstVideoInfo GstVideoInfo;
 /**
  * GST_CAPS_FEATURE_FORMAT_INTERLACED:
  *
- * Name of the caps feature indicating that the stream is interlaced. Currently
- * it is only used for video.
+ * Name of the caps feature indicating that the stream is interlaced.
+ *
+ * Currently it is only used for video with 'interlace-mode=alternate'
+ * to ensure backwards compatibility for this new mode.
+ * In this mode each buffer carries a single field of interlaced video.
+ * @GST_VIDEO_BUFFER_FLAG_TOP_FIELD and @GST_VIDEO_BUFFER_FLAG_BOTTOM_FIELD
+ * indicate whether the buffer carries a top or bottom field. The order of
+ * buffers/fields in the stream and the timestamps on the buffers indicate the
+ * temporal order of the fields.
+ * Top and bottom fields are expected to alternate in this mode.
+ * The frame rate in the caps still signals the frame rate, so the notional field
+ * rate will be twice the frame rate from the caps
+ * (see @GST_VIDEO_INFO_FIELD_RATE_N).
  *
  * Since: 1.16.
  */