docs: update docs for stream_time->running_time

Change some instances where we wrongly refer to stream time where it should have
been running time.

diff --git a/gst/gstclock.c b/gst/gstclock.c
index 70b94c2..5ba1687 100644 (file)
--- a/gst/gstclock.c
+++ b/gst/gstclock.c
@@ -28,7 +28,7 @@
  *
  * GStreamer uses a global clock to synchronize the plugins in a pipeline.
  * Different clock implementations are possible by implementing this abstract
- * base class.
+ * base class or, more conveniently, by subclassing #GstSystemClock.
  *
  * The #GstClock returns a monotonically increasing time with the method
  * gst_clock_get_time(). Its accuracy and base time depend on the specific
@@ -37,7 +37,7 @@
  * meaningful in itself, what matters are the deltas between two clock times.
  * The time returned by a clock is called the absolute time.
  *
- * The pipeline uses the clock to calculate the stream time. Usually all
+ * The pipeline uses the clock to calculate the running time. Usually all
  * renderers synchronize to the global clock using the buffer timestamps, the
  * newsegment events and the element's base time, see #GstPipeline.
  *
@@ -77,7 +77,7 @@
  * state changes and if the entry would be unreffed automatically, the handle 
  * might become invalid without any notification.
  *
- * These clock operations do not operate on the stream time, so the callbacks
+ * These clock operations do not operate on the running time, so the callbacks
  * will also occur when not in PLAYING state as if the clock just keeps on
  * running. Some clocks however do not progress when the element that provided
  * the clock is not PLAYING.
@@ -99,7 +99,7 @@
  * number of samples to use when calibrating and #GstClock:window-threshold
  * defines the minimum number of samples before the calibration is performed.
  *
- * Last reviewed on 2006-08-11 (0.10.10)
+ * Last reviewed on 2009-05-21 (0.10.24)
  */
 
 

diff --git a/gst/gstelement.c b/gst/gstelement.c
index 2d65794..9a56465 100644 (file)
--- a/gst/gstelement.c
+++ b/gst/gstelement.c
@@ -73,7 +73,7 @@
  * toplevel #GstPipeline so the clock functions are only to be used in very
  * specific situations.
  *
- * Last reviewed on 2006-03-12 (0.10.5)
+ * Last reviewed on 2009-05-21 (0.10.24)
  */
 
 #include "gst_private.h"
@@ -510,7 +510,7 @@ gst_element_set_base_time (GstElement * element, GstClockTime time)
  * Returns the base time of the element. The base time is the
  * absolute time of the clock when this element was last put to
  * PLAYING. Subtracting the base time from the clock time gives
- * the stream time of the element.
+ * the running time of the element.
  *
  * Returns: the base time of the element.
  *

diff --git a/gst/gstelement.h b/gst/gstelement.h
index 543a3ca..65f281d 100644 (file)
--- a/gst/gstelement.h
+++ b/gst/gstelement.h
@@ -394,7 +394,7 @@ G_STMT_START {                                                              \
  * element by the toplevel #GstPipeline.
  * @base_time: the time of the clock right before the element is set to
  * PLAYING. Subtracting @base_time from the current clock time in the PLAYING
- * state will yield the stream time.
+ * state will yield the running_time against the clock.
  * @numpads: number of pads of the element, includes both source and sink pads.
  * @pads: list of pads
  * @numsrcpads: number of source pads of the element.

diff --git a/gst/gstevent.c b/gst/gstevent.c
index 9f10d2b..bf5a544 100644 (file)
--- a/gst/gstevent.c
+++ b/gst/gstevent.c
@@ -542,7 +542,8 @@ gst_event_parse_new_segment (GstEvent * event, gboolean * update,
  * The newsegment event marks the range of buffers to be processed. All
  * data not within the segment range is not to be processed. This can be
  * used intelligently by plugins to apply more efficient methods of skipping
- * unneeded data.
+ * unneeded data. The valid range is expressed with the @start and @stop
+ * values.
  *
  * The position value of the segment is used in conjunction with the start
  * value to convert the buffer timestamps into the stream time. This is 
@@ -1043,7 +1044,7 @@ gst_event_new_navigation (GstStructure * structure)
  *
  * Create a new latency event. The event is sent upstream from the sinks and
  * notifies elements that they should add an additional @latency to the
- * timestamps before synchronising against the clock.
+ * running time before synchronising against the clock.
  *
  * The latency is mostly used in live sinks and is always expressed in
  * the time format.

diff --git a/gst/gstpipeline.c b/gst/gstpipeline.c
index 07754f8..2075a8b 100644 (file)
--- a/gst/gstpipeline.c
+++ b/gst/gstpipeline.c
@@ -62,23 +62,23 @@
  * gst_pipeline_auto_clock() the default clock selection algorithm can be
  * restored.
  *
- * A #GstPipeline maintains a stream time for the elements. The stream
+ * A #GstPipeline maintains a running time for the elements. The running
  * time is defined as the difference between the current clock time and
  * the base time. When the pipeline goes to READY or a flushing seek is
- * performed on it, the stream time is reset to 0. When the pipeline is
+ * performed on it, the running time is reset to 0. When the pipeline is
  * set from PLAYING to PAUSED, the current clock time is sampled and used to
  * configure the base time for the elements when the pipeline is set
- * to PLAYING again. The effect is that the stream time (as the difference
+ * to PLAYING again. The effect is that the running time (as the difference
  * between the clock time and the base time) will count how much time was spent
  * in the PLAYING state. This default behaviour can be changed with the
  * gst_pipeline_set_new_stream_time() method.
  *
  * When sending a flushing seek event to a GstPipeline (see
  * gst_element_seek()), it will make sure that the pipeline is properly
- * PAUSED and resumed as well as set the new stream time to 0 when the
+ * PAUSED and resumed as well as set the new running time to 0 when the
  * seek succeeded.
  *
- * Last reviewed on 2006-03-12 (0.10.5)
+ * Last reviewed on 2009-05-21 (0.10.24)
  */
 
 #include "gst_private.h"
@@ -292,9 +292,9 @@ gst_pipeline_get_property (GObject * object, guint prop_id,
   }
 }
 
-/* set the stream time to 0 */
+/* set the running time to 0 */
 static void
-reset_stream_time (GstPipeline * pipeline)
+reset_running_time (GstPipeline * pipeline)
 {
   GST_OBJECT_LOCK (pipeline);
   if (pipeline->stream_time != GST_CLOCK_TIME_NONE) {
@@ -364,7 +364,7 @@ gst_pipeline_change_state (GstElement * element, GstStateChange transition)
       delay = pipeline->delay;
       GST_OBJECT_UNLOCK (element);
 
-      /* stream time changed, either with a PAUSED or a flush, we need to check
+      /* running time changed, either with a PAUSED or a flush, we need to check
        * if there is a new clock & update the base time */
       if (update_stream_time) {
         GST_DEBUG_OBJECT (pipeline, "Need to update stream_time");
@@ -444,7 +444,7 @@ gst_pipeline_change_state (GstElement * element, GstStateChange transition)
       break;
     case GST_STATE_CHANGE_READY_TO_PAUSED:
     {
-      reset_stream_time (pipeline);
+      reset_running_time (pipeline);
       break;
     }
     case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
@@ -462,7 +462,7 @@ gst_pipeline_change_state (GstElement * element, GstStateChange transition)
         gst_object_unref (clock);
 
         GST_OBJECT_LOCK (element);
-        /* store the current stream time */
+        /* store the current running time */
         if (pipeline->stream_time != GST_CLOCK_TIME_NONE) {
           pipeline->stream_time = now - element->base_time;
           /* we went to PAUSED, when going to PLAYING select clock and new
@@ -540,10 +540,10 @@ gst_pipeline_handle_message (GstBin * bin, GstMessage * message)
 
       gst_message_parse_async_start (message, &new_base_time);
 
-      /* reset our stream time if we need to distribute a new base_time to the
+      /* reset our running time if we need to distribute a new base_time to the
        * children. */
       if (new_base_time)
-        reset_stream_time (pipeline);
+        reset_running_time (pipeline);
 
       break;
     }
@@ -572,9 +572,13 @@ gst_pipeline_get_bus (GstPipeline * pipeline)
 /**
  * gst_pipeline_set_new_stream_time:
  * @pipeline: a #GstPipeline
- * @time: the new stream time to set
+ * @time: the new running time to set
  *
- * Set the new stream time of @pipeline to @time. The stream time is used to
+ * Note, the name of this function is wrong, it should be
+ * gst_pipeline_set_new_running_time(), this function does not change the stream
+ * time of the pipeline elements but the running time.
+ *
+ * Set the new running time of @pipeline to @time. The running time is used to
  * set the base time on the elements (see gst_element_set_base_time())
  * in the PAUSED->PLAYING state transition.
  *
@@ -607,10 +611,13 @@ gst_pipeline_set_new_stream_time (GstPipeline * pipeline, GstClockTime time)
  * gst_pipeline_get_last_stream_time:
  * @pipeline: a #GstPipeline
  *
- * Gets the last stream time of @pipeline. If the pipeline is PLAYING,
- * the returned time is the stream time used to configure the element's
+ * Note, the name of this function is wrong, it should be
+ * gst_pipeline_get_last_running_time().
+ *
+ * Gets the last running time of @pipeline. If the pipeline is PLAYING,
+ * the returned time is the running time used to configure the element's
  * base time in the PAUSED->PLAYING state. If the pipeline is PAUSED, the
- * returned time is the stream time when the pipeline was paused.
+ * returned time is the running time when the pipeline was paused.
  *
  * This function returns #GST_CLOCK_TIME_NONE if the pipeline was
  * configured to not handle the management of the element's base time