From f7c57675597ed1250457f5b804fd517a9f34c801 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Thu, 21 May 2009 17:32:00 +0200 Subject: [PATCH] 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. --- gst/gstclock.c | 8 ++++---- gst/gstelement.c | 4 ++-- gst/gstelement.h | 2 +- gst/gstevent.c | 5 +++-- gst/gstpipeline.c | 41 ++++++++++++++++++++++++----------------- 5 files changed, 34 insertions(+), 26 deletions(-) diff --git a/gst/gstclock.c b/gst/gstclock.c index 70b94c2aab..5ba1687428 100644 --- 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 2d657948ea..9a56465e6f 100644 --- 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 543a3cae7b..65f281df4b 100644 --- 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 9f10d2be42..bf5a544016 100644 --- 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 07754f8207..2075a8b742 100644 --- 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