gst/gstelement.*: New function for setting element time taking into account a hardware buffering delay.

Original commit message from CVS:
* gst/gstelement.h:
* gst/gstelement.c (gst_element_set_time_delay): New function for
setting element time taking into account a hardware buffering
delay.
(gst_element_set_time): Now just an invocation of
gst_element_set_time_delay.
* gst/gstclock.h:
* gst/gstclock.c (gst_clock_get_event_time_delay): New function
allowing to set event times in the future.
(gst_clock_get_event_time): Now just an invocation of
gst_clock_get_event_time_delay.

ChangeLog

@@ -1,3 +1,17 @@
+2004-03-28  Martin Soto  <martinsoto@users.sourceforge.net>
+
+	* gst/gstelement.h: 
+	* gst/gstelement.c (gst_element_set_time_delay): New function for
+	setting element time taking into account a hardware buffering
+	delay.
+	(gst_element_set_time): Now just an invocation of
+	gst_element_set_time_delay.
+	* gst/gstclock.h: 
+	* gst/gstclock.c (gst_clock_get_event_time_delay): New function
+	allowing to set event times in the future.
+	(gst_clock_get_event_time): Now just an invocation of
+	gst_clock_get_event_time_delay.
+
 2004-03-28  Benjamin Otte  <otte@gnome.org>
 
 	* gst/gstbin.c: (gst_bin_set_element_sched),

gst/gstclock.c

@@ -634,6 +634,28 @@ gst_clock_get_time (GstClock * clock)
  */
 GstClockTime
 gst_clock_get_event_time (GstClock * clock)
+{
+  return gst_clock_get_event_time_delay (clock, 0);
+}
+
+/**
+ * gst_clock_get_event_time_delay:
+ * @clock: clock to query
+ * @delay: time before the event actually occurs
+ *
+ * Gets the "event time" of a given clock. An event on the clock happens
+ * whenever this function is called. This ensures that multiple events that
+ * happen shortly after each other are treated as if they happened at the same
+ * time. GStreamer uses to keep state changes of multiple elements in sync.
+ *
+ * When calling this function, the specified delay will be added to the current
+ * time to produce the event time. This can be used for events that are
+ * scheduled to happen at some point in the future.
+ *
+ * Returns: the time of the event
+ */
+GstClockTime
+gst_clock_get_event_time_delay (GstClock * clock, GstClockTime delay)
 {
   GstClockTime time;
 
@@ -641,13 +663,14 @@ gst_clock_get_event_time (GstClock * clock)
 
   time = gst_clock_get_time (clock);
 
-  if (clock->last_event + clock->max_event_diff >= time) {
+  if (ABS (GST_CLOCK_DIFF (clock->last_event, time + delay)) <
+      clock->max_event_diff) {
     GST_LOG_OBJECT (clock, "reporting last event time %" G_GUINT64_FORMAT,
         clock->last_event);
   } else {
+    clock->last_event = time + delay;
     GST_LOG_OBJECT (clock, "reporting new event time %" G_GUINT64_FORMAT,
         clock->last_event);
-    clock->last_event = time;
   }
 
   return clock->last_event;

gst/gstclock.h

@@ -176,6 +176,7 @@ gboolean		gst_clock_handle_discont	(GstClock *clock, guint64 time);
 
 GstClockTime		gst_clock_get_time		(GstClock *clock);
 GstClockTime		gst_clock_get_event_time	(GstClock *clock);
+GstClockTime		gst_clock_get_event_time_delay	(GstClock *clock, GstClockTime delay);
 
 
 GstClockID		gst_clock_get_next_id		(GstClock *clock);

gst/gstelement.c

@@ -882,6 +882,29 @@ gst_element_wait (GstElement * element, GstClockTime timestamp)
  */
 void
 gst_element_set_time (GstElement * element, GstClockTime time)
+{
+  gst_element_set_time_delay (element, time, 0);
+}
+
+/**
+ * gst_element_set_time_delay:
+ * @element: element to set time on
+ * @time: time to set
+ * @delay: a delay to discount from the given time
+ *
+ * Sets the current time of the element to time - delay. This function can be
+ * used when handling discont events in elements writing to an external buffer,
+ * i. e., an audio sink that writes to a sound card that buffers the sound
+ * before playing it. The delay should be the current buffering delay.
+ *
+ * You can only call this function on an element with a clock in
+ * #GST_STATE_PAUSED or #GST_STATE_PLAYING. You might want to have a look at
+ * gst_element_adjust_time(), if you want to adjust by a difference as that is
+ * more accurate.
+ */
+void
+gst_element_set_time_delay (GstElement * element, GstClockTime time,
+    GstClockTime delay)
 {
   GstClockTime event_time;
 
@@ -891,10 +914,10 @@ gst_element_set_time (GstElement * element, GstClockTime time)
 
   switch (element->current_state) {
     case GST_STATE_PAUSED:
-      element->base_time = time;
+      element->base_time = time - delay;
       break;
     case GST_STATE_PLAYING:
-      event_time = gst_clock_get_event_time (element->clock);
+      event_time = gst_clock_get_event_time_delay (element->clock, delay);
       GST_CAT_LOG_OBJECT (GST_CAT_CLOCK, element,
           "clock time %llu: setting element time to %llu", event_time, time);
       element->base_time = event_time - time;

gst/gstelement.h

@@ -293,6 +293,8 @@ GstClockReturn		gst_element_clock_wait 		(GstElement *element,
 GstClockTime		gst_element_get_time		(GstElement *element);
 gboolean		gst_element_wait		(GstElement *element, GstClockTime timestamp);
 void			gst_element_set_time		(GstElement *element, GstClockTime time);
+void			gst_element_set_time_delay	(GstElement *element, GstClockTime time, GstClockTime delay);
+
 void			gst_element_adjust_time		(GstElement *element, GstClockTimeDiff diff);
  
 /* indexs */