mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-06-27 02:10:41 +00:00
Code Issues 1 Projects Releases Wiki Activity

gst/gstbin.c: Update documentation.

Browse source 
Original commit message from CVS:
* gst/gstbin.c:
Update documentation.
* gst/gstelement.c: (gst_element_class_init),
(gst_element_release_request_pad), (gst_element_set_clock),
(gst_element_get_index), (gst_element_add_pad),
(gst_element_remove_pad), (gst_element_get_random_pad),
(gst_element_send_event), (gst_element_get_query_types),
(gst_element_query), (gst_element_post_message),
(gst_element_message_full), (gst_element_continue_state),
(gst_element_lost_state), (gst_element_save_thyself),
(gst_element_restore_thyself):
Documentation updates.
Rename last bit of the new-pad -> pad-added signal rename.
Fix the case where an element query would only work if the source
pad was linked.
Avoid some useless type checking in message handling.
* gst/gstevent.c:
* gst/gstevent.h:
* gst/gstutils.c:
Documentation updates.
This commit is contained in:
Wim Taymans 2006-09-15 08:32:57 +00:00
parent 4754b38d74
commit 84fc21c3c1
6 changed files with 188 additions and 90 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
ChangeLog
View file

@ -1,3 +1,28 @@
2006-09-06 Wim Taymans <wim@fluendo.com>
* gst/gstbin.c:
Update documentation.
* gst/gstelement.c: (gst_element_class_init),
(gst_element_release_request_pad), (gst_element_set_clock),
(gst_element_get_index), (gst_element_add_pad),
(gst_element_remove_pad), (gst_element_get_random_pad),
(gst_element_send_event), (gst_element_get_query_types),
(gst_element_query), (gst_element_post_message),
(gst_element_message_full), (gst_element_continue_state),
(gst_element_lost_state), (gst_element_save_thyself),
(gst_element_restore_thyself):
Documentation updates.
Rename last bit of the new-pad -> pad-added signal rename.
Fix the case where an element query would only work if the source
pad was linked.
Avoid some useless type checking in message handling.
* gst/gstevent.c:
* gst/gstevent.h:
* gst/gstutils.c:
Documentation updates.
2006-09-14 Thomas Vander Stichele <thomas at apestaart dot org>
* plugins/elements/gstfdsrc.c: (gst_fd_src_update_fd):

14
gst/gstbin.c
View file

@ -2082,6 +2082,9 @@ bin_bus_handler (GstBus * bus, GstMessage * message, GstBin * bin)
}
/* handle child messages:
*
* This method is called synchronously when a child posts a message on
* the internal bus.
*
* GST_MESSAGE_EOS: This message is only posted by sinks
* in the PLAYING state. If all sinks posted the EOS message, post
@ -2089,7 +2092,8 @@ bin_bus_handler (GstBus * bus, GstMessage * message, GstBin * bin)
*
* GST_MESSAGE_STATE_DIRTY: if we are the toplevel bin we do a state
* recalc. If we are not toplevel (we have a parent) we just post
* the message upwards.
* the message upwards. This makes sure only the toplevel bin will
* run over all its children to check if a state change happened.
*
* GST_MESSAGE_SEGMENT_START: just collect, never forward upwards. If an
* element posts segment_start twice, only the last message is kept.
@ -2102,13 +2106,15 @@ bin_bus_handler (GstBus * bus, GstMessage * message, GstBin * bin)
* Whenever someone performs a duration query on the bin, we store the
* result so we can answer it quicker the next time. Any element that
* changes its duration marks our cached values invalid.
* This message is also posted upwards.
* This message is also posted upwards. This is currently disabled
* because too many elements don't post DURATION messages when the
* duration changes.
*
* GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it
* can no longer provide a clock. The default bin behaviour is to
* check if the lost clock was the one provided by the bin. If so and
* we are currently in the PLAYING state, we forward the message to
* our parent.
* our parent.
* This message is also generated when we remove a clock provider from
* a bin. If this message is received by the application, it should
* PAUSE the pipeline and set it back to PLAYING to force a new clock
@ -2119,7 +2125,7 @@ bin_bus_handler (GstBus * bus, GstMessage * message, GstBin * bin)
* provider to the bin. The default behaviour of the bin is to mark the
* currently selected clock as dirty, which will perform a clock
* recalculation the next time we are asked to provide a clock.
* This message is never sent tot the application but is forwarded to
* This message is never sent to the application but is forwarded to
* the parent.
*
* OTHER: post upwards.

163
gst/gstelement.c
View file

@ -93,7 +93,7 @@
/* Element signals and args */
enum
{
NEW_PAD,
PAD_ADDED,
PAD_REMOVED,
NO_MORE_PADS,
/* add more above */
@ -180,7 +180,7 @@ gst_element_class_init (GstElementClass * klass)
*
* a new #GstPad has been added to the element.
*/
gst_element_signals[NEW_PAD] =
gst_element_signals[PAD_ADDED] =
g_signal_new ("pad-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GstElementClass, pad_added), NULL, NULL,
gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
@ -303,6 +303,8 @@ gst_element_release_request_pad (GstElement * element, GstPad * pad)
oclass = GST_ELEMENT_GET_CLASS (element);
/* if the element implements a custom release function we call that, else we
* simply remove the pad from the element */
if (oclass->release_pad)
(oclass->release_pad) (element, pad);
else
@ -315,7 +317,7 @@ gst_element_release_request_pad (GstElement * element, GstPad * pad)
*
* Query if the element requires a clock.
*
* Returns: TRUE if the element requires a clock
* Returns: %TRUE if the element requires a clock
*
* MT safe.
*/
@ -337,8 +339,11 @@ gst_element_requires_clock (GstElement * element)
*
* Query if the element provides a clock. A #GstClock provided by an
* element can be used as the global #GstClock for the pipeline.
* An element that can provide a clock is only required to do so in the PAUSED
* state, this means when it is fully negotiated and has allocated the resources
* to operate the clock.
*
* Returns: TRUE if the element provides a clock
* Returns: %TRUE if the element provides a clock
*
* MT safe.
*/
@ -358,10 +363,12 @@ gst_element_provides_clock (GstElement * element)
* gst_element_provide_clock:
* @element: a #GstElement to query
*
* Get the clock provided by the given element.
* Get the clock provided by the given element.
* <note>An element is only required to provide a clock in the PAUSED
* state. Some elements can provide a clock in other states.</note>
*
* Returns: the GstClock provided by the element or NULL
* if no clock could be provided. Unref after usage.
* if no clock could be provided. Unref after usage.
*
* MT safe.
*/
@ -390,7 +397,9 @@ gst_element_provide_clock (GstElement * element)
* refcount on the clock. Any previously set clock on the object
* is unreffed.
*
* Returns: TRUE if the element accepted the clock.
* Returns: %TRUE if the element accepted the clock. An element can refuse a
* clock when it, for example, is not able to slave its internal clock to the
* @clock or when it requires a specific clock to operate.
*
* MT safe.
*/
@ -411,6 +420,7 @@ gst_element_set_clock (GstElement * element, GstClock * clock)
res = oclass->set_clock (element, clock);
if (res) {
/* only update the clock pointer if the element accepted the clock */
GST_OBJECT_LOCK (element);
clock_p = &element->clock;
gst_object_replace ((GstObject **) clock_p, (GstObject *) clock);
@ -423,7 +433,8 @@ gst_element_set_clock (GstElement * element, GstClock * clock)
* gst_element_get_clock:
* @element: a #GstElement to get the clock of.
*
* Gets the currently configured clock of the element.
* Gets the currently configured clock of the element. This is the clock as was
* last set with gst_element_set_clock().
*
* Returns: the #GstClock of the element. unref after usage.
*
@ -555,15 +566,16 @@ GstIndex *
gst_element_get_index (GstElement * element)
{
GstElementClass *oclass;
GstIndex *result = NULL;
g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
oclass = GST_ELEMENT_GET_CLASS (element);
if (oclass->get_index)
return oclass->get_index (element);
result = oclass->get_index (element);
return NULL;
return result;
}
#endif
@ -577,11 +589,13 @@ gst_element_get_index (GstElement * element)
*
* Pads are not automatically activated so elements should perform the needed
* steps to activate the pad in case this pad is added in the PAUSED or PLAYING
* state.
* state. See gst_pad_set_active() for more information about activating pads.
*
* The pad and the element should be unlocked when calling this function.
*
* Returns: TRUE if the pad could be added. This function can fail when
* This function will emit the #GstElement::pad-added signal on the element.
*
* Returns: %TRUE if the pad could be added. This function can fail when
* a pad with the same name already existed or the pad already had another
* parent.
*
@ -632,8 +646,8 @@ gst_element_add_pad (GstElement * element, GstPad * pad)
element->pads_cookie++;
GST_OBJECT_UNLOCK (element);
/* emit the NEW_PAD signal */
g_signal_emit (G_OBJECT (element), gst_element_signals[NEW_PAD], 0, pad);
/* emit the PAD_ADDED signal */
g_signal_emit (element, gst_element_signals[PAD_ADDED], 0, pad);
return TRUE;
@ -673,15 +687,23 @@ no_direction:
* @pad: the #GstPad to remove from the element.
*
* Removes @pad from @element. @pad will be destroyed if it has not been
* referenced elsewhere.
* referenced elsewhere using gst_object_unparent().
*
* This function is used by plugin developers and should not be used
* by applications. Pads that were dynamically requested from elements
* with gst_element_get_request_pad() should be released with the
* gst_element_release_request_pad() function instead.
*
* Returns: TRUE if the pad could be removed. Can return FALSE if the
* pad is not belonging to the provided element.
* Pads are not automatically deactivated so elements should perform the needed
* steps to deactivate the pad in case this pad is removed in the PAUSED or PLAYING
* state. See gst_pad_set_active() for more information about deactivating pads.
*
* The pad and the element should be unlocked when calling this function.
*
* This function will emit the #GstElement::pad-removed signal on the element.
*
* Returns: %TRUE if the pad could be removed. Can return %FALSE if the
* pad does not belong to the provided element.
*
* MT safe.
*/
@ -735,12 +757,14 @@ gst_element_remove_pad (GstElement * element, GstPad * pad)
element->pads_cookie++;
GST_OBJECT_UNLOCK (element);
g_signal_emit (G_OBJECT (element), gst_element_signals[PAD_REMOVED], 0, pad);
/* emit the PAD_REMOVED signal before unparenting and losing the last ref. */
g_signal_emit (element, gst_element_signals[PAD_REMOVED], 0, pad);
gst_object_unparent (GST_OBJECT (pad));
gst_object_unparent (GST_OBJECT_CAST (pad));
return TRUE;
/* ERRORS */
not_our_pad:
{
/* FIXME, locking order? */
@ -763,6 +787,8 @@ not_our_pad:
* pad templates use this in combination with autopluggers to figure out that
* the element is done initializing its pads.
*
* This function emits the #GstElement::no-more-pads signal.
*
* MT safe.
*/
void
@ -854,7 +880,7 @@ gst_element_request_pad (GstElement * element, GstPadTemplate * templ,
* request pads. The pad should be released with
* gst_element_release_request_pad().
*
* Returns: requested #GstPad if found, otherwise NULL. Unref after usage.
* Returns: requested #GstPad if found, otherwise NULL. Release after usage.
*/
GstPad *
gst_element_get_request_pad (GstElement * element, const gchar * name)
@ -930,7 +956,12 @@ gst_element_get_request_pad (GstElement * element, const gchar * name)
* Retrieves a pad from @element by name. Tries gst_element_get_static_pad()
* first, then gst_element_get_request_pad().
*
* Returns: the #GstPad if found, otherwise %NULL. Unref after usage.
* <note>Usage of this function is not recommended as it is unclear if the reference
* to the result pad should be released with gst_object_unref() in case of a static pad
* or gst_element_release_request_pad() in case of a request pad.</note>
*
* Returns: the #GstPad if found, otherwise %NULL. Unref or Release after usage,
* depending on the type of the pad.
*/
GstPad *
gst_element_get_pad (GstElement * element, const gchar * name)
@ -1128,8 +1159,12 @@ gst_element_class_get_pad_template (GstElementClass * element_class,
return NULL;
}
/* get a random pad on element of the given direction.
* The pad is random in a sense that it is the first pad that is (optionaly) linked.
*/
static GstPad *
gst_element_get_random_pad (GstElement * element, GstPadDirection dir)
gst_element_get_random_pad (GstElement * element, gboolean need_linked,
GstPadDirection dir)
{
GstPad *result = NULL;
GList *pads;
@ -1149,21 +1184,27 @@ gst_element_get_random_pad (GstElement * element, GstPadDirection dir)
goto wrong_direction;
}
for (; pads; pads = g_list_next (pads)) {
GstPad *pad = GST_PAD (pads->data);
GstPad *pad = GST_PAD_CAST (pads->data);
GST_OBJECT_LOCK (pad);
GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "checking pad %s:%s",
GST_DEBUG_PAD_NAME (pad));
if (GST_PAD_IS_LINKED (pad)) {
if (need_linked && !GST_PAD_IS_LINKED (pad)) {
/* if we require a linked pad, and it is not linked, continue the
* search */
GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is not linked",
GST_DEBUG_PAD_NAME (pad));
GST_OBJECT_UNLOCK (pad);
continue;
} else {
/* found a pad, stop search */
GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
GST_DEBUG_PAD_NAME (pad));
GST_OBJECT_UNLOCK (pad);
result = pad;
break;
} else {
GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is not linked",
GST_DEBUG_PAD_NAME (pad));
}
GST_OBJECT_UNLOCK (pad);
}
if (result)
gst_object_ref (result);
@ -1185,13 +1226,14 @@ wrong_direction:
* @element: a #GstElement to send the event to.
* @event: the #GstEvent to send to the element.
*
* Sends an event to an element. If the element doesn't
* implement an event handler, the event will be forwarded
* to a random sink pad. This function takes owership of the
* provided event so you should gst_event_ref() it if you want to reuse
* the event after this call.
* Sends an event to an element. If the element doesn't implement an
* event handler, the event will be pushed on a random linked sink pad for
* upstream events or a random linked source pad for downstream events.
*
* Returns: TRUE if the event was handled.
* This function takes owership of the provided event so you should
* gst_event_ref() it if you want to reuse the event after this call.
*
* Returns: %TRUE if the event was handled.
*
* MT safe.
*/
@ -1212,8 +1254,8 @@ gst_element_send_event (GstElement * element, GstEvent * event)
result = oclass->send_event (element, event);
} else {
GstPad *pad = GST_EVENT_IS_DOWNSTREAM (event) ?
gst_element_get_random_pad (element, GST_PAD_SRC) :
gst_element_get_random_pad (element, GST_PAD_SINK);
gst_element_get_random_pad (element, TRUE, GST_PAD_SRC) :
gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
if (pad) {
GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
@ -1243,7 +1285,9 @@ gst_element_send_event (GstElement * element, GstEvent * event)
* @stop_type: The type and flags for the new stop position
* @stop: The value of the new stop position
*
* Sends a seek event to an element.
* Sends a seek event to an element. See gst_event_new_seek() for the details of
* the parameters. The seek event is sent to the element using
* gst_element_send_event().
*
* Returns: %TRUE if the event was handled.
*
@ -1272,7 +1316,7 @@ gst_element_seek (GstElement * element, gdouble rate, GstFormat format,
*
* Get an array of query types from the element.
* If the element doesn't implement a query types function,
* the query will be forwarded to a random sink pad.
* the query will be forwarded to the peer of a random linked sink pad.
*
* Returns: An array of #GstQueryType elements that should not
* be freed or modified.
@ -1292,7 +1336,7 @@ gst_element_get_query_types (GstElement * element)
if (oclass->get_query_types) {
result = oclass->get_query_types (element);
} else {
GstPad *pad = gst_element_get_random_pad (element, GST_PAD_SINK);
GstPad *pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
if (pad) {
GstPad *peer = gst_pad_get_peer (pad);
@ -1313,11 +1357,11 @@ gst_element_get_query_types (GstElement * element)
* @element: a #GstElement to perform the query on.
* @query: the #GstQuery.
*
* Performs a query on the given element. If the format is set
* to #GST_FORMAT_DEFAULT and this function returns TRUE, the
* format pointer will hold the default format.
* For element that don't implement a query handler, this function
* forwards the query to a random usable sinkpad of this element.
* Performs a query on the given element.
*
* For elements that don't implement a query handler, this function
* forwards the query to a random srcpad or to the peer of a
* random linked sinkpad of this element.
*
* Returns: TRUE if the query could be performed.
*
@ -1339,14 +1383,14 @@ gst_element_query (GstElement * element, GstQuery * query)
GST_ELEMENT_NAME (element));
result = oclass->query (element, query);
} else {
GstPad *pad = gst_element_get_random_pad (element, GST_PAD_SRC);
GstPad *pad = gst_element_get_random_pad (element, FALSE, GST_PAD_SRC);
if (pad) {
result = gst_pad_query (pad, query);
gst_object_unref (pad);
} else {
pad = gst_element_get_random_pad (element, GST_PAD_SINK);
pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
if (pad) {
GstPad *peer = gst_pad_get_peer (pad);
@ -1371,7 +1415,8 @@ gst_element_query (GstElement * element, GstQuery * query)
* message; if you want to access the message after this call, you should add an
* additional reference before calling.
*
* Returns: TRUE if the message was successfully posted.
* Returns: %TRUE if the message was successfully posted. The function returns
* %FALSE if the element did not have a bus.
*
* MT safe.
*/
@ -1393,11 +1438,14 @@ gst_element_post_message (GstElement * element, GstMessage * message)
gst_object_ref (bus);
GST_OBJECT_UNLOCK (element);
/* we release the element lock when posting the message so that any
* (synchronous) message handlers can operate on the element */
result = gst_bus_post (bus, message);
gst_object_unref (bus);
return result;
/* ERRORS */
no_bus:
{
GST_DEBUG ("not posting message %p: no bus", message);
@ -1484,7 +1532,7 @@ void gst_element_message_full
has_debug = FALSE;
}
name = gst_object_get_path_string (GST_OBJECT (element));
name = gst_object_get_path_string (GST_OBJECT_CAST (element));
if (has_debug)
sent_debug = g_strdup_printf ("%s(%d): %s (): %s:\n%s",
file, line, function, name, debug);
@ -1500,9 +1548,10 @@ void gst_element_message_full
gerror = g_error_new_literal (domain, code, sent_text);
if (type == GST_MESSAGE_ERROR) {
message = gst_message_new_error (GST_OBJECT (element), gerror, sent_debug);
message =
gst_message_new_error (GST_OBJECT_CAST (element), gerror, sent_debug);
} else if (type == GST_MESSAGE_WARNING) {
message = gst_message_new_warning (GST_OBJECT (element), gerror,
message = gst_message_new_warning (GST_OBJECT_CAST (element), gerror,
sent_debug);
} else {
g_assert_not_reached ();
@ -1918,7 +1967,7 @@ gst_element_continue_state (GstElement * element, GstStateChangeReturn ret)
gst_element_state_get_name (old_next),
gst_element_state_get_name (pending));
message = gst_message_new_state_changed (GST_OBJECT (element),
message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
old_state, old_next, pending);
gst_element_post_message (element, message);
@ -1952,7 +2001,7 @@ complete:
* We do signal the cond though as a _get_state() might be blocking
* on it. */
if (old_state != old_next || old_ret == GST_STATE_CHANGE_ASYNC) {
message = gst_message_new_state_changed (GST_OBJECT (element),
message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
old_state, old_next, GST_STATE_VOID_PENDING);
gst_element_post_message (element, message);
}
@ -2004,12 +2053,12 @@ gst_element_lost_state (GstElement * element)
GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
GST_OBJECT_UNLOCK (element);
message = gst_message_new_state_changed (GST_OBJECT (element),
message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
current_state, current_state, current_state);
gst_element_post_message (element, message);
/* and mark us dirty */
message = gst_message_new_state_dirty (GST_OBJECT (element));
message = gst_message_new_state_dirty (GST_OBJECT_CAST (element));
gst_element_post_message (element, message);
return;
@ -2604,13 +2653,13 @@ gst_element_save_thyself (GstObject * object, xmlNodePtr parent)
pads = GST_ELEMENT_PADS (element);
while (pads) {
GstPad *pad = GST_PAD (pads->data);
GstPad *pad = GST_PAD_CAST (pads->data);
/* figure out if it's a direct pad or a ghostpad */
if (GST_ELEMENT (GST_OBJECT_PARENT (pad)) == element) {
xmlNodePtr padtag = xmlNewChild (parent, NULL, (xmlChar *) "pad", NULL);
gst_object_save_thyself (GST_OBJECT (pad), padtag);
gst_object_save_thyself (GST_OBJECT_CAST (pad), padtag);
}
pads = g_list_next (pads);
}
@ -2656,7 +2705,7 @@ gst_element_restore_thyself (GstObject * object, xmlNodePtr self)
children = self->xmlChildrenNode;
while (children) {
if (!strcmp ((char *) children->name, "pad")) {
gst_pad_load_and_link (children, GST_OBJECT (element));
gst_pad_load_and_link (children, GST_OBJECT_CAST (element));
}
children = children->next;
}

43
gst/gstevent.c
View file

@ -72,7 +72,7 @@
* </programlisting>
* </example>
*
* Last reviewed on 2006-08-11 (0.10.10)
* Last reviewed on 2006-09-6 (0.10.10)
*/
@ -352,7 +352,12 @@ gst_event_get_structure (GstEvent * event)
*
* Allocate a new flush start event. The flush start event can be send
* upstream and downstream and travels out-of-bounds with the dataflow.
* It marks pads as being in a WRONG_STATE to process more data.
*
* It marks pads as being flushing and will make them return
* #GST_FLOW_WRONG_STATE when used for data flow with gst_pad_push(),
* gst_pad_chain(), gst_pad_alloc_buffer(), gst_pad_get_range() and
* gst_pad_pull_range(). Any event (except a #GST_EVENT_FLUSH_STOP) received
* on a flushing pad will return %FALSE immediatly.
*
* Elements unlock and blocking functions and exit their streaming functions
* as fast as possible.
@ -395,11 +400,11 @@ gst_event_new_flush_stop (void)
*
* Create a new EOS event. The eos event can only travel downstream
* synchronized with the buffer flow. Elements that receive the EOS
* event on a pad can return UNEXPECTED as a GstFlowReturn when data
* after the EOS event arrives.
* event on a pad can return #GST_FLOW_UNEXPECTED as a #GstFlowReturn
* when data after the EOS event arrives.
*
* The EOS event will travel down to the sink elements in the pipeline
* which will then post the GST_MESSAGE_EOS on the bus after they have
* which will then post the #GST_MESSAGE_EOS on the bus after they have
* finished playing any buffered data.
*
* When all sinks have posted an EOS message, the EOS message is
@ -635,7 +640,7 @@ gst_event_parse_tag (GstEvent * event, GstTagList ** taglist)
* Create a new buffersize event. The event is sent downstream and notifies
* elements that they should provide a buffer of the specified dimensions.
*
* When the async flag is set, a thread boundary is prefered.
* When the @async flag is set, a thread boundary is prefered.
*
* Returns: a new #GstEvent
*/
@ -788,24 +793,30 @@ gst_event_parse_qos (GstEvent * event, gdouble * proportion,
* Allocate a new seek event with the given parameters.
*
* The seek event configures playback of the pipeline from
* @cur to @stop at the speed given in @rate, also called a segment.
* @cur to @stop at the speed given in @rate, also called a playback segment.
* The @cur and @stop values are expressed in format @format.
*
* A @rate of 1.0 means normal playback rate, 2.0 means double speed.
* Negatives values means backwards playback. A value of 0.0 for the
* rate is not allowed.
* rate is not allowed and should be accomplished instead by PAUSING the
* pipeline.
*
* A pipeline has a default playback segment configured with a current
* position of 0, a stop position of the total duration of the stream(s) and
* a rate of 1.0. The currently configured playback segment can be queried
* with #GST_QUERY_SEGMENT.
*
* @cur_type and @stop_type specify how to adjust the current and stop
* time, relative or absolute to the last configured positions. A type
* time, relative or absolute to the last configured playback segment. A type
* of #GST_SEEK_TYPE_NONE means that the position should not be updated.
* The currently configured playback segment can be queried with
* #GST_QUERY_SEGMENT.
*
* Note that updating the @cur position will actually move the current
* playback pointer to that new position. It is not possible to seek
* relative to the current playing position, to do this, pause the pipeline,
* get the current position and perform a GST_SEEK_TYPE_SET to the desired
* position.
* Updating the @cur position will actually move the current playback position
* to that new position.
*
* It is not possible to seek relative to the current playback position, to do
* this, PAUSE the pipeline, query the current playback position with
* #GST_QUERY_POSITION and update the playback segment current position with a
* #GST_SEEK_TYPE_SET to the desired position.
*
* Returns: A new seek event.
*/

16
gst/gstevent.h
View file

@ -230,10 +230,10 @@ typedef struct _GstEventClass GstEventClass;
* @GST_SEEK_TYPE_SET: absolute position is requested
* @GST_SEEK_TYPE_END: relative position to duration is requested
*
* The different types of seek events. When constructing a seek event, a format,
* a seek method and optional flags are to be provided. The seek event is then
* inserted into the graph with gst_pad_send_event() or
* gst_element_send_event().
* The different types of seek events. When constructing a seek event with
* gst_event_new_seek(), a format, a seek method and optional flags are to
* be provided. The seek event is then inserted into the graph with
* gst_pad_send_event() or gst_element_send_event().
*/
typedef enum {
/* one of these */
@ -264,10 +264,10 @@ typedef enum {
*
* When performing a segment seek: after the playback of the segment completes,
* no EOS will be emmited by the element that performed the seek, but a
* SEGMENT_DONE message will be posted on the bus by the element. When this
* message is posted, it is possible to send a new seek event to continue
* playback. With this seek method it is possible to perform seemless looping
* or simple linear editing.
* #GST_MESSAGE_SEGMENT_DONE message will be posted on the bus by the element.
* When this message is posted, it is possible to send a new seek event to
* continue playback. With this seek method it is possible to perform seemless
* looping or simple linear editing.
*/
typedef enum {
GST_SEEK_FLAG_NONE = 0,

17
gst/gstutils.c
View file

@ -1934,13 +1934,20 @@ gst_element_query_convert (GstElement * element, GstFormat src_format,
* Simple API to perform a seek on the given element, meaning it just seeks
* to the given position relative to the start of the stream. For more complex
* operations like segment seeks (e.g. for looping) or changing the playback
* rate or seeking relative to the current position or seeking relative to
* the end of the stream you should use gst_element_seek ().
* rate or seeking relative to the last configured playback segment you should
* use gst_element_seek().
*
* Note that seeking is usually only possible in PAUSED or PLAYING state.
* In a completely prerolled PAUSED or PLAYING pipeline, seeking is always
* guaranteed to return %TRUE on a seekable media type or %FALSE when the media
* type is certainly not seekable (such as a live stream).
*
* Returns: TRUE if the seek operation succeeded (the seek
* might not always be executed instantly though)
* Some elements allow for seeking in the READY state, in this
* case they will store the seek event and execute it when they are put to
* PAUSED. If the element supports seek in READY, it will always return %TRUE when
* it receives the event in the READY state.
*
* Returns: %TRUE if the seek operation succeeded (the seek might not always be
* executed instantly though)
*
* Since: 0.10.7
*/