event: add QoS event type

Add a parameter to the QoS event to specify the QoS event type.
Update docs and add unit test.

See #638891

6 files changed, 131 insertions, 9 deletions

diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt
index 5c731dc96a..139504861b 100644
--- a/docs/gst/gstreamer-sections.txt
+++ b/docs/gst/gstreamer-sections.txt
@@ -793,14 +793,17 @@ gst_event_parse_new_segment_full
 gst_event_new_tag
 gst_event_parse_tag
 
 gst_event_new_buffer_size
 gst_event_parse_buffer_size
 
+GstQOSType
 gst_event_new_qos
+gst_event_new_qos_full
 gst_event_parse_qos
+gst_event_parse_qos_full
 
 GstSeekType
 GstSeekFlags
 gst_event_new_seek
 gst_event_parse_seek
 
@@ -823,20 +826,22 @@ GST_IS_EVENT_CLASS
 GST_EVENT_CLASS
 GST_EVENT_GET_CLASS
 GST_TYPE_EVENT
 GST_TYPE_EVENT_TYPE
 GST_TYPE_SEEK_TYPE
 GST_TYPE_SEEK_FLAGS
+GST_TYPE_QOS_TYPE
 GST_TYPE_EVENT_TYPE_FLAGS
 <SUBSECTION Private>
 GST_EVENT_TYPE_SHIFT
 FLAG
 gst_event_get_type
 gst_event_type_get_type
 gst_seek_type_get_type
 gst_seek_flags_get_type
+gst_qos_type_get_type
 gst_event_type_flags_get_type
 </SECTION>
 
 
 <SECTION>
 <FILE>gstfilter</FILE>
diff --git a/gst/gst.c b/gst/gst.c
index 3bde138aa8..50de2c0efc 100644
--- a/gst/gst.c
+++ b/gst/gst.c
@@ -702,12 +702,13 @@ init_post (GOptionContext * context, GOptionGroup * group, gpointer data,
   g_type_class_ref (gst_resource_error_get_type ());
   g_type_class_ref (gst_stream_error_get_type ());
   g_type_class_ref (gst_event_type_flags_get_type ());
   g_type_class_ref (gst_event_type_get_type ());
   g_type_class_ref (gst_seek_type_get_type ());
   g_type_class_ref (gst_seek_flags_get_type ());
+  g_type_class_ref (gst_qos_type_get_type ());
   g_type_class_ref (gst_format_get_type ());
   g_type_class_ref (gst_index_certainty_get_type ());
   g_type_class_ref (gst_index_entry_type_get_type ());
   g_type_class_ref (gst_index_lookup_method_get_type ());
   g_type_class_ref (gst_assoc_flags_get_type ());
   g_type_class_ref (gst_index_resolver_method_get_type ());
@@ -1068,12 +1069,13 @@ gst_deinit (void)
   g_type_class_unref (g_type_class_peek (gst_structure_change_type_get_type
           ()));
   g_type_class_unref (g_type_class_peek (gst_event_type_flags_get_type ()));
   g_type_class_unref (g_type_class_peek (gst_event_type_get_type ()));
   g_type_class_unref (g_type_class_peek (gst_seek_type_get_type ()));
   g_type_class_unref (g_type_class_peek (gst_seek_flags_get_type ()));
+  g_type_class_unref (g_type_class_peek (gst_qos_type_get_type ()));
   g_type_class_unref (g_type_class_peek (gst_format_get_type ()));
   g_type_class_unref (g_type_class_peek (gst_index_certainty_get_type ()));
   g_type_class_unref (g_type_class_peek (gst_index_entry_type_get_type ()));
   g_type_class_unref (g_type_class_peek (gst_index_lookup_method_get_type ()));
   g_type_class_unref (g_type_class_peek (gst_assoc_flags_get_type ()));
   g_type_class_unref (g_type_class_peek (gst_index_resolver_method_get_type
diff --git a/gst/gstevent.c b/gst/gstevent.c
index c407fedb17..07414c7fa4 100644
--- a/gst/gstevent.c
+++ b/gst/gstevent.c
@@ -796,17 +796,53 @@ gst_event_parse_buffer_size (GstEvent * event, GstFormat * format,
 /**
  * gst_event_new_qos:
  * @proportion: the proportion of the qos message
  * @diff: The time difference of the last Clock sync
  * @timestamp: The timestamp of the buffer
  *
+ * Allocate a new qos event with the given values. This function calls
+ * gst_event_new_qos_full() with the type set to #GST_QOS_TYPE_OVERFLOW
+ * when diff is negative (buffers are in time) and #GST_QOS_TYPE_UNDERFLOW
+ * when @diff is positive (buffers are late).
+ *
+ * Returns: (transfer full): a new QOS event.
+ */
+GstEvent *
+gst_event_new_qos (gdouble proportion, GstClockTimeDiff diff,
+    GstClockTime timestamp)
+{
+  GstQOSType type;
+
+  if (diff <= 0)
+    type = GST_QOS_TYPE_OVERFLOW;
+  else
+    type = GST_QOS_TYPE_UNDERFLOW;
+
+  return gst_event_new_qos_full (type, proportion, diff, timestamp);
+}
+
+/**
+ * gst_event_new_qos_full:
+ * @type: the QoS type
+ * @proportion: the proportion of the qos message
+ * @diff: The time difference of the last Clock sync
+ * @timestamp: The timestamp of the buffer
+ *
  * Allocate a new qos event with the given values.
  * The QOS event is generated in an element that wants an upstream
  * element to either reduce or increase its rate because of
- * high/low CPU load or other resource usage such as network performance.
- * Typically sinks generate these events for each buffer they receive.
+ * high/low CPU load or other resource usage such as network performance or
+ * throttling. Typically sinks generate these events for each buffer
+ * they receive.
+ *
+ * @type indicates the reason for the QoS event. #GST_QOS_TYPE_OVERFLOW is
+ * used when a buffer arrived in time or when the sink cannot keep up with
+ * the upstream datarate. #GST_QOS_TYPE_UNDERFLOW is when the sink is not
+ * receiving buffers fast enough and thus has to drop late buffers. 
+ * #GST_QOS_TYPE_THROTTLE is used when the datarate is artificially limited
+ * by the application, for example to reduce power consumption.
  *
  * @proportion indicates the real-time performance of the streaming in the
  * element that generated the QoS event (usually the sink). The value is
  * generally computed based on more long term statistics about the streams
  * timestamps compared to the clock.
  * A value < 1.0 indicates that the upstream element is producing data faster
@@ -815,13 +851,14 @@ gst_event_parse_buffer_size (GstEvent * event, GstFormat * format,
  * proportion value can safely be used to lower or increase the quality of
  * the element.
  *
  * @diff is the difference against the clock in running time of the last
  * buffer that caused the element to generate the QOS event. A negative value
  * means that the buffer with @timestamp arrived in time. A positive value
- * indicates how late the buffer with @timestamp was.
+ * indicates how late the buffer with @timestamp was. When throttling is
+ * enabled, @diff will be set to the requested throttling interval.
  *
  * @timestamp is the timestamp of the last buffer that cause the element
  * to generate the QOS event. It is expressed in running time and thus an ever
  * increasing value.
  *
  * The upstream element can use the @diff and @timestamp values to decide
@@ -831,29 +868,32 @@ gst_event_parse_buffer_size (GstEvent * event, GstFormat * format,
  * result smaller than 0 is not allowed.
  *
  * The application can use general event probes to intercept the QoS
  * event and implement custom application specific QoS handling.
  *
  * Returns: (transfer full): a new QOS event.
+ *
+ * Since: 0.10.33
  */
 GstEvent *
-gst_event_new_qos (gdouble proportion, GstClockTimeDiff diff,
-    GstClockTime timestamp)
+gst_event_new_qos_full (GstQOSType type, gdouble proportion,
+    GstClockTimeDiff diff, GstClockTime timestamp)
 {
   GstEvent *event;
   GstStructure *structure;
 
   /* diff must be positive or timestamp + diff must be positive */
   g_return_val_if_fail (diff >= 0 || -diff <= timestamp, NULL);
 
   GST_CAT_INFO (GST_CAT_EVENT,
-      "creating qos proportion %lf, diff %" G_GINT64_FORMAT
-      ", timestamp %" GST_TIME_FORMAT, proportion,
+      "creating qos type %d, proportion %lf, diff %" G_GINT64_FORMAT
+      ", timestamp %" GST_TIME_FORMAT, type, proportion,
       diff, GST_TIME_ARGS (timestamp));
 
   structure = gst_structure_id_new (GST_QUARK (EVENT_QOS),
+      GST_QUARK (TYPE), GST_TYPE_QOS_TYPE, type,
       GST_QUARK (PROPORTION), G_TYPE_DOUBLE, proportion,
       GST_QUARK (DIFF), G_TYPE_INT64, diff,
       GST_QUARK (TIMESTAMP), G_TYPE_UINT64, timestamp, NULL);
   event = gst_event_new_custom (GST_EVENT_QOS, structure);
 
   return event;
@@ -870,18 +910,42 @@ gst_event_new_qos (gdouble proportion, GstClockTimeDiff diff,
  * gst_event_new_qos() for more information about the different QoS values.
  */
 void
 gst_event_parse_qos (GstEvent * event, gdouble * proportion,
     GstClockTimeDiff * diff, GstClockTime * timestamp)
 {
+  gst_event_parse_qos_full (event, NULL, proportion, diff, timestamp);
+}
+
+/**
+ * gst_event_parse_qos_full:
+ * @event: The event to query
+ * @type: (out): A pointer to store the QoS type in
+ * @proportion: (out): A pointer to store the proportion in
+ * @diff: (out): A pointer to store the diff in
+ * @timestamp: (out): A pointer to store the timestamp in
+ *
+ * Get the type, proportion, diff and timestamp in the qos event. See
+ * gst_event_new_qos_full() for more information about the different QoS values.
+ *
+ * Since: 0.10.33
+ */
+void
+gst_event_parse_qos_full (GstEvent * event, GstQOSType * type,
+    gdouble * proportion, GstClockTimeDiff * diff, GstClockTime * timestamp)
+{
   const GstStructure *structure;
 
   g_return_if_fail (GST_IS_EVENT (event));
   g_return_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_QOS);
 
   structure = event->structure;
+  if (type)
+    *type =
+        g_value_get_enum (gst_structure_id_get_value (structure,
+            GST_QUARK (TYPE)));
   if (proportion)
     *proportion =
         g_value_get_double (gst_structure_id_get_value (structure,
             GST_QUARK (PROPORTION)));
   if (diff)
     *diff =
diff --git a/gst/gstevent.h b/gst/gstevent.h
index 9568514866..34983b679b 100644
--- a/gst/gstevent.h
+++ b/gst/gstevent.h
@@ -91,14 +91,14 @@ typedef enum {
  * @GST_EVENT_BUFFERSIZE: Notification of buffering requirements. Currently not
  *                 used yet.
  * @GST_EVENT_SINK_MESSAGE: An event that sinks turn into a message. Used to
  *                          send messages that should be emitted in sync with
  *                          rendering.
  * @GST_EVENT_QOS: A quality message. Used to indicate to upstream elements
- *                 that the downstream elements are being starved of or
- *                 flooded with data.
+ *                 that the downstream elements should adjust their processing
+ *                 rate.
  * @GST_EVENT_SEEK: A request for a new playback position and rate.
  * @GST_EVENT_NAVIGATION: Navigation events are usually used for communicating
  *                        user requests, such as mouse or keyboard movements,
  *                        to upstream elements.
  * @GST_EVENT_LATENCY: Notification of new latency adjustment. Sinks will use
  *                     the latency information to adjust their synchronisation.
@@ -306,12 +306,35 @@ typedef enum {
   GST_SEEK_FLAG_KEY_UNIT        = (1 << 2),
   GST_SEEK_FLAG_SEGMENT         = (1 << 3),
   GST_SEEK_FLAG_SKIP            = (1 << 4)
 } GstSeekFlags;
 
 /**
+ * GstQOSType:
+ * @GST_QOS_TYPE_OVERFLOW: The QoS event type that is produced when downstream
+ *    elements are producing data too quickly and the element can't keep up
+ *    processing the data. Upstream should reduce their processing rate. This
+ *    type is also used when buffers arrive early or in time.
+ * @GST_QOS_TYPE_UNDERFLOW: The QoS event type that is produced when downstream
+ *    elements are producing data too slowly and need to speed up their processing
+ *    rate. 
+ * @GST_QOS_TYPE_THROTTLE: The QoS event type that is produced when the
+ *    application enabled throttling to limit the datarate.
+ *
+ * The different types of QoS events that can be given to the 
+ * gst_event_new_qos_full() method. 
+ *
+ * Since: 0.10.33
+ */
+typedef enum {
+  GST_QOS_TYPE_OVERFLOW        = 0,
+  GST_QOS_TYPE_UNDERFLOW       = 1,
+  GST_QOS_TYPE_THROTTLE        = 2
+} GstQOSType;
+
+/**
  * GstEvent:
  * @mini_object: the parent structure
  * @type: the #GstEventType of the event
  * @timestamp: the timestamp of the event
  * @src: the src of the event
  * @structure: the #GstStructure containing the event info.
@@ -458,14 +481,19 @@ GstEvent *      gst_event_new_buffer_size       (GstFormat format, gint64 minsiz
 void            gst_event_parse_buffer_size     (GstEvent *event, GstFormat *format, gint64 *minsize,
                                                  gint64 *maxsize, gboolean *async);
 
 /* QOS events */
 GstEvent*       gst_event_new_qos               (gdouble proportion, GstClockTimeDiff diff,
                                                  GstClockTime timestamp);
+GstEvent*       gst_event_new_qos_full          (GstQOSType type, gdouble proportion,
+                                                 GstClockTimeDiff diff, GstClockTime timestamp);
 void            gst_event_parse_qos             (GstEvent *event, gdouble *proportion, GstClockTimeDiff *diff,
                                                  GstClockTime *timestamp);
+void            gst_event_parse_qos_full        (GstEvent *event, GstQOSType *type,
+                                                 gdouble *proportion, GstClockTimeDiff *diff,
+                                                 GstClockTime *timestamp);
 /* seek event */
 GstEvent*       gst_event_new_seek              (gdouble rate, GstFormat format, GstSeekFlags flags,
                                                  GstSeekType start_type, gint64 start,
                                                  GstSeekType stop_type, gint64 stop);
 void            gst_event_parse_seek            (GstEvent *event, gdouble *rate, GstFormat *format,
                                                  GstSeekFlags *flags,
diff --git a/tests/check/gst/gstevent.c b/tests/check/gst/gstevent.c
index 5a2ec2325c..8c0829aab4 100644
--- a/tests/check/gst/gstevent.c
+++ b/tests/check/gst/gstevent.c
@@ -135,12 +135,13 @@ GST_START_TEST (create_events)
     fail_unless (taglist == tl2);
     gst_event_unref (event);
   }
 
   /* QOS */
   {
+    GstQOSType t1 = GST_QOS_TYPE_THROTTLE, t2;
     gdouble p1 = 1.0, p2;
     GstClockTimeDiff ctd1 = G_GINT64_CONSTANT (10), ctd2;
     GstClockTime ct1 = G_GUINT64_CONSTANT (20), ct2;
 
     event = gst_event_new_qos (p1, ctd1, ct1);
     fail_if (event == NULL);
@@ -150,12 +151,31 @@ GST_START_TEST (create_events)
     fail_if (GST_EVENT_IS_SERIALIZED (event));
 
     gst_event_parse_qos (event, &p2, &ctd2, &ct2);
     fail_unless (p1 == p2);
     fail_unless (ctd1 == ctd2);
     fail_unless (ct1 == ct2);
+    gst_event_parse_qos_full (event, &t2, &p2, &ctd2, &ct2);
+    fail_unless (t2 == GST_QOS_TYPE_UNDERFLOW);
+    fail_unless (p1 == p2);
+    fail_unless (ctd1 == ctd2);
+    fail_unless (ct1 == ct2);
+    gst_event_unref (event);
+
+    ctd1 = G_GINT64_CONSTANT (-10);
+    event = gst_event_new_qos (p1, ctd1, ct1);
+    gst_event_parse_qos_full (event, &t2, &p2, &ctd2, &ct2);
+    fail_unless (t2 == GST_QOS_TYPE_OVERFLOW);
+    gst_event_unref (event);
+
+    event = gst_event_new_qos_full (t1, p1, ctd1, ct1);
+    gst_event_parse_qos_full (event, &t2, &p2, &ctd2, &ct2);
+    fail_unless (t2 == GST_QOS_TYPE_THROTTLE);
+    fail_unless (p1 == p2);
+    fail_unless (ctd1 == ctd2);
+    fail_unless (ct1 == ct2);
     gst_event_unref (event);
   }
 
   /* SEEK */
   {
     gdouble rate;
diff --git a/win32/common/libgstreamer.def b/win32/common/libgstreamer.def
index eef40ded4e..dd505908bf 100644
--- a/win32/common/libgstreamer.def
+++ b/win32/common/libgstreamer.def
@@ -389,21 +389,23 @@ EXPORTS
 	gst_event_new_flush_stop
 	gst_event_new_latency
 	gst_event_new_navigation
 	gst_event_new_new_segment
 	gst_event_new_new_segment_full
 	gst_event_new_qos
+	gst_event_new_qos_full
 	gst_event_new_seek
 	gst_event_new_sink_message
 	gst_event_new_step
 	gst_event_new_tag
 	gst_event_parse_buffer_size
 	gst_event_parse_latency
 	gst_event_parse_new_segment
 	gst_event_parse_new_segment_full
 	gst_event_parse_qos
+	gst_event_parse_qos_full
 	gst_event_parse_seek
 	gst_event_parse_sink_message
 	gst_event_parse_step
 	gst_event_parse_tag
 	gst_event_set_seqnum
 	gst_event_type_flags_get_type
@@ -809,12 +811,13 @@ EXPORTS
 	gst_preset_rename_preset
 	gst_preset_save_preset
 	gst_preset_set_meta
 	gst_print_element_args
 	gst_print_pad_caps
 	gst_proxy_pad_get_type
+	gst_qos_type_get_type
 	gst_query_add_buffering_range
 	gst_query_get_n_buffering_ranges
 	gst_query_get_structure
 	gst_query_get_type
 	gst_query_new_application
 	gst_query_new_buffering