From bd2ece0c4814ca610fd212f5c11409d79bee6301 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Tim-Philipp=20M=C3=BCller?= Date: Tue, 20 Aug 2013 17:06:49 +0100 Subject: [PATCH] docs: flesh out gst_element_query_{duration,position} docs a bit --- gst/gstutils.c | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/gst/gstutils.c b/gst/gstutils.c index 09cd786..33f518c 100644 --- a/gst/gstutils.c +++ b/gst/gstutils.c @@ -2136,8 +2136,15 @@ gst_element_unlink (GstElement * src, GstElement * dest) * @cur: (out) (allow-none): a location in which to store the current * position, or NULL. * - * Queries an element for the stream position. If one repeatedly calls this - * function one can also create and reuse it in gst_element_query(). + * Queries an element (usually top-level pipeline or playbin element) for the + * stream position in nanoseconds. This will be a value between 0 and the + * stream duration (if the stream duration is known). This query will usually + * only work once the pipeline is prerolled (i.e. reached PAUSED or PLAYING + * state). The application will receive an ASYNC_DONE message on the pipeline + * bus when that is the case. + * + * If one repeatedly calls this function one can also create a query and reuse + * it in gst_element_query(). * * Returns: TRUE if the query could be performed. */ @@ -2168,7 +2175,14 @@ gst_element_query_position (GstElement * element, GstFormat format, * @format: the #GstFormat requested * @duration: (out) (allow-none): A location in which to store the total duration, or NULL. * - * Queries an element for the total stream duration. + * Queries an element (usually top-level pipeline or playbin element) for the + * total stream duration in nanoseconds. This query will only work once the + * pipeline is prerolled (i.e. reached PAUSED or PLAYING state). The application + * will receive an ASYNC_DONE message on the pipeline bus when that is the case. + * + * If the duration changes for some reason, you will get a DURATION_CHANGED + * message on the pipeline bus, in which case you should re-query the duration + * using this function. * * Returns: TRUE if the query could be performed. */ -- 2.7.4