basesink: Document the interaction between unlock() and wait_preroll()

This was totally non-obvious, the kind of big problem is that subclasses must
be able to unblock their streaming thread and continue exactly where they left off
on unpause!

https://bugzilla.gnome.org/show_bug.cgi?id=773912

diff --git a/libs/gst/base/gstbasesink.c b/libs/gst/base/gstbasesink.c
index aef33fd..b4c8752 100644 (file)
--- a/libs/gst/base/gstbasesink.c
+++ b/libs/gst/base/gstbasesink.c
@@ -2239,6 +2239,13 @@ no_clock:
  * against the clock it must unblock when going from PLAYING to the PAUSED state
  * and call this method before continuing to render the remaining data.
  *
+ * If the #GstBaseSinkClass.render() method can block on something else than
+ * the clock, it must also be ready to unblock immediately on
+ * the #GstBaseSinkClass.unlock() method and cause the
+ * #GstBaseSinkClass.render() method to immediately call this function.
+ * In this case, the subclass must be prepared to continue rendering where it
+ * left off if this function returns %GST_FLOW_OK.
+ *
  * This function will block until a state change to PLAYING happens (in which
  * case this function returns %GST_FLOW_OK) or the processing must be stopped due
  * to a state change to READY or a FLUSH event (in which case this function

diff --git a/libs/gst/base/gstbasesink.h b/libs/gst/base/gstbasesink.h
index faf3534..802bd69 100644 (file)
--- a/libs/gst/base/gstbasesink.h
+++ b/libs/gst/base/gstbasesink.h
@@ -122,9 +122,12 @@ struct _GstBaseSink {
  * @start: Start processing. Ideal for opening resources in the subclass
  * @stop: Stop processing. Subclasses should use this to close resources.
  * @unlock: Unlock any pending access to the resource. Subclasses should
- *     unblock any blocked function ASAP
+ *     unblock any blocked function ASAP and call gst_base_sink_wait_preroll()
  * @unlock_stop: Clear the previous unlock request. Subclasses should clear
- *     any state they set during unlock(), such as clearing command queues.
+ *     any state they set during #GstBaseSinkClass.unlock(), and be ready to
+ *     continue where they left off after gst_base_sink_wait_preroll(),
+ *     gst_base_sink_wait() or gst_wait_sink_wait_clock() return or
+ *     #GstBaseSinkClass.render() is called again.
  * @query: perform a #GstQuery on the element.
  * @event: Override this to handle events arriving on the sink pad
  * @wait_event: Override this to implement custom logic to wait for the event