basesink: add property to configure a throttle-time

Add a property to configure the throttle time on a sink. The
property is not yet used.

See #638891

4 files changed, 80 insertions, 0 deletions

diff --git a/docs/libs/gstreamer-libs-sections.txt b/docs/libs/gstreamer-libs-sections.txt
index 25cbcd3ccc..3678413215 100644
--- a/docs/libs/gstreamer-libs-sections.txt
+++ b/docs/libs/gstreamer-libs-sections.txt
@@ -282,12 +282,14 @@ gst_base_sink_set_render_delay
 gst_base_sink_get_render_delay
 gst_base_sink_set_last_buffer_enabled
 gst_base_sink_is_last_buffer_enabled
 gst_base_sink_get_last_buffer
 gst_base_sink_set_blocksize
 gst_base_sink_get_blocksize
+gst_base_sink_get_throttle_time
+gst_base_sink_set_throttle_time
 
 GST_BASE_SINK_PAD
 
 <SUBSECTION Standard>
 GST_BASE_SINK
 GST_BASE_SINK_CAST
diff --git a/libs/gst/base/gstbasesink.c b/libs/gst/base/gstbasesink.c
index cffd33b9cd..b4c5e7366e 100644
--- a/libs/gst/base/gstbasesink.c
+++ b/libs/gst/base/gstbasesink.c
@@ -256,12 +256,15 @@ struct _GstBaseSinkPrivate
   /* we have a pending and a current step operation */
   GstStepInfo current_step;
   GstStepInfo pending_step;
 
   /* Cached GstClockID */
   GstClockID cached_clock_id;
+
+  /* for throttling */
+  GstClockTime throttle_time;
 };
 
 #define DO_RUNNING_AVG(avg,val,size) (((val) + ((size)-1) * (avg)) / (size))
 
 /* generic running average, this has a neutral window size */
 #define UPDATE_RUNNING_AVG(avg,val)   DO_RUNNING_AVG(avg,val,8)
@@ -296,12 +299,13 @@ enum
 #define DEFAULT_QOS                 FALSE
 #define DEFAULT_ASYNC               TRUE
 #define DEFAULT_TS_OFFSET           0
 #define DEFAULT_BLOCKSIZE           4096
 #define DEFAULT_RENDER_DELAY        0
 #define DEFAULT_ENABLE_LAST_BUFFER  TRUE
+#define DEFAULT_THROTTLE_TIME       0
 
 enum
 {
   PROP_0,
   PROP_PREROLL_QUEUE_LEN,
   PROP_SYNC,
@@ -310,12 +314,13 @@ enum
   PROP_ASYNC,
   PROP_TS_OFFSET,
   PROP_ENABLE_LAST_BUFFER,
   PROP_LAST_BUFFER,
   PROP_BLOCKSIZE,
   PROP_RENDER_DELAY,
+  PROP_THROTTLE_TIME,
   PROP_LAST
 };
 
 static GstElementClass *parent_class = NULL;
 
 static void gst_base_sink_class_init (GstBaseSinkClass * klass);
@@ -521,12 +526,25 @@ gst_base_sink_class_init (GstBaseSinkClass * klass)
    * Since: 0.10.22
    */
   g_object_class_install_property (gobject_class, PROP_RENDER_DELAY,
       g_param_spec_uint64 ("render-delay", "Render Delay",
           "Additional render delay of the sink in nanoseconds", 0, G_MAXUINT64,
           DEFAULT_RENDER_DELAY, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+  /**
+   * GstBaseSink:throttle-time
+   *
+   * The time to insert between buffers. This property can be used to control
+   * the maximum amount of buffers per second to render. Setting this property
+   * to a value bigger than 0 will make the sink create THROTTLE QoS events.
+   *
+   * Since: 0.10.33
+   */
+  g_object_class_install_property (gobject_class, PROP_THROTTLE_TIME,
+      g_param_spec_uint64 ("throttle-time", "Throttle time",
+          "The time to keep between rendered buffers (unused)", 0, G_MAXUINT64,
+          DEFAULT_THROTTLE_TIME, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
   gstelement_class->change_state =
       GST_DEBUG_FUNCPTR (gst_base_sink_change_state);
   gstelement_class->send_event = GST_DEBUG_FUNCPTR (gst_base_sink_send_event);
   gstelement_class->query = GST_DEBUG_FUNCPTR (gst_base_sink_query);
   gstelement_class->get_query_types =
@@ -686,12 +704,13 @@ gst_base_sink_init (GstBaseSink * basesink, gpointer g_class)
   priv->async_enabled = DEFAULT_ASYNC;
   priv->ts_offset = DEFAULT_TS_OFFSET;
   priv->render_delay = DEFAULT_RENDER_DELAY;
   priv->blocksize = DEFAULT_BLOCKSIZE;
   priv->cached_clock_id = NULL;
   g_atomic_int_set (&priv->enable_last_buffer, DEFAULT_ENABLE_LAST_BUFFER);
+  priv->throttle_time = DEFAULT_THROTTLE_TIME;
 
   GST_OBJECT_FLAG_SET (basesink, GST_ELEMENT_IS_SINK);
 }
 
 static void
 gst_base_sink_finalize (GObject * object)
@@ -1280,12 +1299,59 @@ gst_base_sink_get_blocksize (GstBaseSink * sink)
   res = sink->priv->blocksize;
   GST_OBJECT_UNLOCK (sink);
 
   return res;
 }
 
+/**
+ * gst_base_sink_set_throttle_time:
+ * @sink: a #GstBaseSink
+ * @throttle: the throttle time in nanoseconds
+ *
+ * Set the time that will be inserted between rendered buffers. This
+ * can be used to control the maximum buffers per second that the sink
+ * will render. 
+ *
+ * Since: 0.10.33
+ */
+void
+gst_base_sink_set_throttle_time (GstBaseSink * sink, guint64 throttle)
+{
+  g_return_if_fail (GST_IS_BASE_SINK (sink));
+
+  GST_OBJECT_LOCK (sink);
+  sink->priv->throttle_time = throttle;
+  GST_LOG_OBJECT (sink, "set throttle_time to %" G_GUINT64_FORMAT, throttle);
+  GST_OBJECT_UNLOCK (sink);
+}
+
+/**
+ * gst_base_sink_get_throttle_time:
+ * @sink: a #GstBaseSink
+ *
+ * Get the time that will be inserted between frames to control the 
+ * maximum buffers per second.
+ *
+ * Returns: the number of nanoseconds @sink will put between frames.
+ *
+ * Since: 0.10.33
+ */
+guint64
+gst_base_sink_get_throttle_time (GstBaseSink * sink)
+{
+  guint64 res;
+
+  g_return_val_if_fail (GST_IS_BASE_SINK (sink), 0);
+
+  GST_OBJECT_LOCK (sink);
+  res = sink->priv->throttle_time;
+  GST_OBJECT_UNLOCK (sink);
+
+  return res;
+}
+
 static void
 gst_base_sink_set_property (GObject * object, guint prop_id,
     const GValue * value, GParamSpec * pspec)
 {
   GstBaseSink *sink = GST_BASE_SINK (object);
 
@@ -1317,12 +1383,15 @@ gst_base_sink_set_property (GObject * object, guint prop_id,
     case PROP_RENDER_DELAY:
       gst_base_sink_set_render_delay (sink, g_value_get_uint64 (value));
       break;
     case PROP_ENABLE_LAST_BUFFER:
       gst_base_sink_set_last_buffer_enabled (sink, g_value_get_boolean (value));
       break;
+    case PROP_THROTTLE_TIME:
+      gst_base_sink_set_throttle_time (sink, g_value_get_uint64 (value));
+      break;
     default:
       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
       break;
   }
 }
 
@@ -1360,12 +1429,15 @@ gst_base_sink_get_property (GObject * object, guint prop_id, GValue * value,
     case PROP_BLOCKSIZE:
       g_value_set_uint (value, gst_base_sink_get_blocksize (sink));
       break;
     case PROP_RENDER_DELAY:
       g_value_set_uint64 (value, gst_base_sink_get_render_delay (sink));
       break;
+    case PROP_THROTTLE_TIME:
+      g_value_set_uint64 (value, gst_base_sink_get_throttle_time (sink));
+      break;
     default:
       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
       break;
   }
 }
 
diff --git a/libs/gst/base/gstbasesink.h b/libs/gst/base/gstbasesink.h
index e91cb2cfe7..a4215b8de4 100644
--- a/libs/gst/base/gstbasesink.h
+++ b/libs/gst/base/gstbasesink.h
@@ -230,12 +230,16 @@ void            gst_base_sink_set_render_delay  (GstBaseSink *sink, GstClockTime
 GstClockTime    gst_base_sink_get_render_delay  (GstBaseSink *sink);
 
 /* blocksize */
 void            gst_base_sink_set_blocksize     (GstBaseSink *sink, guint blocksize);
 guint           gst_base_sink_get_blocksize     (GstBaseSink *sink);
 
+/* throttle-time */
+void            gst_base_sink_set_throttle_time (GstBaseSink *sink, guint64 throttle);
+guint64         gst_base_sink_get_throttle_time (GstBaseSink *sink);
+
 GstClockReturn  gst_base_sink_wait_clock        (GstBaseSink *sink, GstClockTime time,
                                                  GstClockTimeDiff * jitter);
 GstFlowReturn   gst_base_sink_wait_eos          (GstBaseSink *sink, GstClockTime time,
                                                  GstClockTimeDiff *jitter);
 
 G_END_DECLS
diff --git a/win32/common/libgstbase.def b/win32/common/libgstbase.def
index 6676afe569..cccb58b2c5 100644
--- a/win32/common/libgstbase.def
+++ b/win32/common/libgstbase.def
@@ -18,12 +18,13 @@ EXPORTS
 	gst_base_sink_get_blocksize
 	gst_base_sink_get_last_buffer
 	gst_base_sink_get_latency
 	gst_base_sink_get_max_lateness
 	gst_base_sink_get_render_delay
 	gst_base_sink_get_sync
+	gst_base_sink_get_throttle_time
 	gst_base_sink_get_ts_offset
 	gst_base_sink_get_type
 	gst_base_sink_is_async_enabled
 	gst_base_sink_is_last_buffer_enabled
 	gst_base_sink_is_qos_enabled
 	gst_base_sink_query_latency
@@ -31,12 +32,13 @@ EXPORTS
 	gst_base_sink_set_blocksize
 	gst_base_sink_set_last_buffer_enabled
 	gst_base_sink_set_max_lateness
 	gst_base_sink_set_qos_enabled
 	gst_base_sink_set_render_delay
 	gst_base_sink_set_sync
+	gst_base_sink_set_throttle_time
 	gst_base_sink_set_ts_offset
 	gst_base_sink_wait_clock
 	gst_base_sink_wait_eos
 	gst_base_sink_wait_preroll
 	gst_base_src_get_blocksize
 	gst_base_src_get_do_timestamp