From c4abf79f02105ae31ee2cd9427abd35b9e308b5a Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Thu, 3 Nov 2005 14:22:44 +0000 Subject: [PATCH] docs/: Small docs updates. Original commit message from CVS: * docs/design/part-events.txt: * docs/design/part-gstpipeline.txt: * docs/design/part-messages.txt: * docs/design/part-overview.txt: * docs/design/part-seeking.txt: * docs/design/part-states.txt: * docs/design/part-trickmodes.txt: * docs/manual/advanced-position.xml: Small docs updates. * gst/gstobject.h: People think !! is ugly, this looks better. * gst/gstpad.c: (gst_pad_set_blocked_async): Remove !! since it's fixed elsewhere now. --- ChangeLog | 18 ++++++++++++++++++ docs/design/part-events.txt | 5 +++-- docs/design/part-gstpipeline.txt | 2 +- docs/design/part-messages.txt | 9 +++++---- docs/design/part-overview.txt | 8 +++++--- docs/design/part-seeking.txt | 6 +++--- docs/design/part-states.txt | 9 +++++---- docs/design/part-trickmodes.txt | 13 +++++++++++++ docs/manual/advanced-position.xml | 4 +--- gst/gstobject.h | 2 +- gst/gstpad.c | 2 +- 11 files changed, 56 insertions(+), 22 deletions(-) create mode 100644 docs/design/part-trickmodes.txt diff --git a/ChangeLog b/ChangeLog index a7f8f42c0d..0234c0bd3d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,21 @@ +2005-11-03 Wim Taymans + + * docs/design/part-events.txt: + * docs/design/part-gstpipeline.txt: + * docs/design/part-messages.txt: + * docs/design/part-overview.txt: + * docs/design/part-seeking.txt: + * docs/design/part-states.txt: + * docs/design/part-trickmodes.txt: + * docs/manual/advanced-position.xml: + Small docs updates. + + * gst/gstobject.h: + People think !! is ugly, this looks better. + + * gst/gstpad.c: (gst_pad_set_blocked_async): + Remove !! since it's fixed elsewhere now. + 2005-11-03 Tim-Philipp Müller * gst/gstminiobject.h: diff --git a/docs/design/part-events.txt b/docs/design/part-events.txt index ec95728be7..6bf31ec1df 100644 --- a/docs/design/part-events.txt +++ b/docs/design/part-events.txt @@ -132,7 +132,7 @@ of the indicated newsegment range. If a newsegment arrives at an element not preceeded by a flush event, the streamtime of the pipeline will not be reset to 0 so any element that syncs to the clock must use the stop times of the previous newsegment events to -make the buffer timestamps increasing. +make the buffer timestamps increasing (part-segments.txt). TAG --- @@ -176,7 +176,7 @@ at -1 to continue playback to the end of the stream. The seek event also contains the new playback rate of the stream, 1.0 is normal playback, 2.0 double speed and negative values mean backwards playback. -A seek usually flushes the graph to minimize latency after the seek this +A seek usually flushes the graph to minimize latency after the seek. This behaviour is triggered by using the SEEK_FLUSH flag. The seek event is passed along from element to element until it reaches @@ -209,6 +209,7 @@ The general flow of executing the seek with FLUSH is as follows: 4) send a FLUSH_STOP event to all peer elements to allow streaming again. 5) send a NEWSEGMENT event to signal the new buffer timestamp base time. + This can also be done from the streaming thread. 6) start stopped tasks and unlock the STREAM_LOCK, dataflow will continue now from the new position. diff --git a/docs/design/part-gstpipeline.txt b/docs/design/part-gstpipeline.txt index f16b990b77..da48a07c24 100644 --- a/docs/design/part-gstpipeline.txt +++ b/docs/design/part-gstpipeline.txt @@ -1,7 +1,7 @@ GstPipeline ----------- -A GstPipeline is usually a toplevel bin an provides all of its +A GstPipeline is usually a toplevel bin and provides all of its children with a clock. A GstPipeline also provides a toplevel GstBus (see part-gstbus.txt) diff --git a/docs/design/part-messages.txt b/docs/design/part-messages.txt index f3d5d8b77b..4fbc37042d 100644 --- a/docs/design/part-messages.txt +++ b/docs/design/part-messages.txt @@ -18,8 +18,9 @@ Message types GST_MESSAGE_EOS: - The pipeline went to EOS. This means that all the sink elements in the - pipeline posted the EOS message to the bus. + Posted by sink elements. This message is posted to the application when + all the sinks in a pipeline posted an EOS message. When performing a seek, + the EOS state of the pipeline and sinks is undone. GST_MESSAGE_ERROR: @@ -75,8 +76,8 @@ Message types GST_MESSAGE_STREAM_STATUS: - An element posted information about the stream it is handling. This could include - information about the length of the stream. + An element posted information about the stream it is handling. This could include + information about the length of the stream. GST_MESSAGE_APPLICATION: diff --git a/docs/design/part-overview.txt b/docs/design/part-overview.txt index bf82dfd051..593ab5a14f 100644 --- a/docs/design/part-overview.txt +++ b/docs/design/part-overview.txt @@ -397,7 +397,8 @@ Pipeline EOS to the application. When in EOS, the pipeline remains in the playing state, if is the application - responsability to PAUSE or READY the pipeline. + responsability to PAUSE or READY the pipeline. The application can also issue + a seek, for example. Pipeline READY @@ -487,12 +488,13 @@ Pipeline seeking to produce new data. Since the pipeline is still PAUSED, this will preroll the next media sample in the - sinks. + sinks. The application can wait for this preroll to complete by performing a + _get_state() on the pipeline. The last step in the seek operation is then to adjust the stream time of the pipeline to 0 and to set the pipeline back to PLAYING. - The sequence of events in out mp3 playback example. + The sequence of events in our mp3 playback example. | a) seek on pipeline | b) PAUSE pipeline diff --git a/docs/design/part-seeking.txt b/docs/design/part-seeking.txt index d9affcd0c4..946673dd0e 100644 --- a/docs/design/part-seeking.txt +++ b/docs/design/part-seeking.txt @@ -16,16 +16,16 @@ Seeking can be performed in different formats such as time, frames or samples. Seeking can be performed to an absolute position or relative to the -current playback position. +current configured segment. For seeking to work reliably, all plugins in the pipeline need to follow the well-defined rules in this document. Non segment seeking will make the pipeline emit EOS when the configured -playback range has been played. +segment has been played. Segment seeking will not emit an EOS at the end of the range but will -post a SEGMENT_STOP message on the bus. This message is posted by the +post a SEGMENT_DONE message on the bus. This message is posted by the earliest element in the pipeline, typically a demuxer. After receiving the message, the application can reconnect the pipeline or issue other seek events in the pipeline. diff --git a/docs/design/part-states.txt b/docs/design/part-states.txt index 7833397f0a..3a92dcd2a4 100644 --- a/docs/design/part-states.txt +++ b/docs/design/part-states.txt @@ -84,10 +84,7 @@ the following state changes are possible: State variables --------------- -An element has a special lock to manage the state changes. This lock is called -the STATE_LOCK. - -The STATE_LOCK protects 3 element variables: +An element has 4 state variables that are protected with the object LOCK: - STATE - STATE_NEXT @@ -102,6 +99,10 @@ The STATE_RETURN reflects the last return value of a state change. The STATE_NEXT and STATE_PENDING can be VOID_PENDING if the element is in the right state. +An element has a special lock to protect against concurrent invocations of +_set_state(), called the STATE_LOCK. + + Setting state on elements ------------------------- diff --git a/docs/design/part-trickmodes.txt b/docs/design/part-trickmodes.txt new file mode 100644 index 0000000000..69c2e7c98e --- /dev/null +++ b/docs/design/part-trickmodes.txt @@ -0,0 +1,13 @@ +Trickmodes +========== + + +forward playback +---------------- + + + + + +backwards playback +------------------ diff --git a/docs/manual/advanced-position.xml b/docs/manual/advanced-position.xml index 195876033b..f072840e68 100644 --- a/docs/manual/advanced-position.xml +++ b/docs/manual/advanced-position.xml @@ -182,9 +182,7 @@ static void seek_to_time (GstElement *pipeline, gint64 time_nanoseconds) { - GstFormat format = GST_FORMAT_TIME; - - if (!gst_element_seek (pipeline, 1.0, &format, GST_SEEK_FLAG_FLUSH, + if (!gst_element_seek (pipeline, 1.0, GST_FORMAT_TIME, GST_SEEK_FLAG_FLUSH, GST_SEEK_TYPE_SET, time_nanoseconds, GST_SEEK_TYPE_NONE, GST_CLOCK_TIME_NONE)) { g_print ("Seek failed!\n"); diff --git a/gst/gstobject.h b/gst/gstobject.h index bb12839b57..5fd719c8db 100644 --- a/gst/gstobject.h +++ b/gst/gstobject.h @@ -147,7 +147,7 @@ typedef enum * * This macro checks to see if the given flag is set. */ -#define GST_OBJECT_FLAG_IS_SET(obj,flag) !!(GST_OBJECT_FLAGS (obj) & (flag)) +#define GST_OBJECT_FLAG_IS_SET(obj,flag) ((GST_OBJECT_FLAGS (obj) & (flag)) == (flag)) /** * GST_OBJECT_FLAG_SET: * @obj: Object to set flag in. diff --git a/gst/gstpad.c b/gst/gstpad.c index 6c567f2c08..ef3cffdbec 100644 --- a/gst/gstpad.c +++ b/gst/gstpad.c @@ -854,7 +854,7 @@ gst_pad_set_blocked_async (GstPad * pad, gboolean blocked, GST_LOCK (pad); - was_blocked = !!GST_PAD_IS_BLOCKED (pad); + was_blocked = GST_PAD_IS_BLOCKED (pad); if (G_UNLIKELY (was_blocked == blocked)) goto had_right_state;