diff --git a/ChangeLog b/ChangeLog index 02717e8ef6..b16dfe3f6f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,19 @@ +2006-03-13 Wim Taymans + + * docs/design/draft-klass.txt: + * docs/design/part-clocks.txt: + * docs/design/part-events.txt: + * docs/design/part-gstbin.txt: + * docs/design/part-gstpipeline.txt: + * docs/design/part-messages.txt: + * docs/design/part-negotiation.txt: + * docs/design/part-overview.txt: + * docs/design/part-preroll.txt: + * docs/design/part-seeking.txt: + * docs/design/part-states.txt: + * docs/design/part-streams.txt: + Documentation updates. + 2006-03-12 Julien MOUTTE * gst/gsttaglist.c: Fix rubbish docs that are encouraging diff --git a/docs/design/draft-klass.txt b/docs/design/draft-klass.txt index 401223a44a..4498f40d2a 100644 --- a/docs/design/draft-klass.txt +++ b/docs/design/draft-klass.txt @@ -31,8 +31,8 @@ Proposal: ['/' PLAYING: - - Select and set a clock. + - Select and a clock. - calculate base time using the stream time. + - set clock and base time on all elements before performing the + state change. - PAUSED -> PLAYING: - calculate the stream time when the pipeline was stopped. - READY -> NULL: - - set the bus to flushing + - set the bus to flushing (when auto-flushing is enabled) Clock selection @@ -44,14 +46,20 @@ pipeline must select a clock. The default clock selection algorithm works as follows: - If the application selected a clock, use that clock. (see below) - - use clock of source elements (*) - - use clock of other element, starting from the sinks going upstream. - (+) - - use GstSystemClock. -(*) currently not implemented. -(+) traversing the graph upstream to find the best clock is not implemented, - currently the first element found that provides a clock is used. + - Use the clock of most upstream element that can provide a clock. This + selection is performed by iterating the element starting from the + sinks going upstream. + + * since this selection procedure happens in the PAUSED->PLAYING + state change, all the sinks are prerolled and we can thus be sure + that each sink is linked to some upstream element. + * in the case of a live pipeline (NO_PREROLL), the sink will not + be prerolled and the selection process will select the clock of + a more upstream element. + + - use GstSystemClock, this only happens when no element provides a + clock. The application can influence this clock selection with two methods: gst_pipeline_use_clock() and gst_pipeline_auto_clock(). @@ -64,6 +72,7 @@ possible. The _auto_clock() method removes the fixed clock and reactivates the auto- matic clock selection algorithm described above. + Seeking ------- @@ -73,7 +82,7 @@ the pipeline performs the following actions: - record the current state of the pipeline. - set the pipeline to paused if a FLUSHING seek is requested - send the seek event to all sinks - - when a FLUSH seek is done, the stream_time is set 0 again. + - when a FLUSH seek was performed successfully, the stream_time is set 0 again. - restore old state of the pipeline. diff --git a/docs/design/part-messages.txt b/docs/design/part-messages.txt index 4fbc37042d..c804be2293 100644 --- a/docs/design/part-messages.txt +++ b/docs/design/part-messages.txt @@ -45,7 +45,10 @@ Message types GST_MESSAGE_BUFFERING: - An element is buffering data and that could potentially take some time. + An element is buffering data and that could potentially take some time. This + message is typically emited by elements that perform some sort of network + buffering. While the pipeline is buffering it should remain in the PAUSED + state. When the buffering is finished, it can resume PLAYING. GST_MESSAGE_STATE_CHANGED: diff --git a/docs/design/part-negotiation.txt b/docs/design/part-negotiation.txt index 270f44fa2d..048e5854bf 100644 --- a/docs/design/part-negotiation.txt +++ b/docs/design/part-negotiation.txt @@ -24,6 +24,8 @@ The basics of negotiation are as follows: new format before processing the buffer data. If the data type on the buffer is not acceptable, the element should refuse the buffer by returning an appropriate return value from the chain function. + The core will automatically call the set_caps function for this purpose + when it is installed on the sink or source pad. - When requesting a buffer from a bufferpool, the prefered type should be passed to the buffer allocation function. After receiving a buffer diff --git a/docs/design/part-overview.txt b/docs/design/part-overview.txt index 593ab5a14f..09fa8fb4f9 100644 --- a/docs/design/part-overview.txt +++ b/docs/design/part-overview.txt @@ -41,7 +41,7 @@ Introduction vorbisdec element decodes the compressed data and sends it to the alsasink element. The alsasink element sends the samples to the audio card for playback. - Downstream and upstream are the term used to describe the direction in the + Downstream and upstream are the terms used to describe the direction in the Pipeline. From source to sink is called "downstream" and "upstream" is from sink to source. @@ -53,7 +53,7 @@ Introduction level functions on the pipeline object such as PLAY/PAUSE/STOP. The application also receives messages and notifications from the pipeline such - as metadata, warning or error messages. + as metadata, warning, error and EOS messages. If the application needs more control over the graph it is possible to directly access the elements and pads in the pipeline. @@ -102,8 +102,8 @@ Elements An element state change to PAUSED will activate the pads of the element. First the source pads are activated, then the sinkpads. When the pads are activated, the - pad activate function is called. Some pads will start a thread or some other - mechanism to start producing or consuming data. + pad activate function is called. Some pads will start a thread (GstTask) or some + other mechanism to start producing or consuming data. The PAUSED state is special as it is used to preroll data in the pipeline. The purpose is to fill all connected elements in the pipeline with data so that the subsequent @@ -125,7 +125,7 @@ Elements - demuxer elements, these elements parse a stream and produce several output streams. - mixer/muxer elements, combine several input streams into one output stream. - Other categories of elements can be constructed. + Other categories of elements can be constructed (see part-klass.txt). Bins @@ -158,8 +158,9 @@ Pipeline A pipeline is a special bin subclass that provides the following features to its children: - - Select and manage a clock - - Provide means for elements to comunicate with the application by the Bus. + - Select and manage a clock. + - Manage stream time based on the selected clock. + - Provide means for elements to comunicate with the application by the GstBus. - Manage the global state of the elements such as Errors and end-of-stream. Normally the application creates one pipeline that will manage all the elements @@ -242,6 +243,8 @@ Dataflow and events the events are used to denote special conditions in the dataflow such as EOS or to inform plugins of special events such as flushing or seeking. + Some events must be serialized with the buffer flow, others don't. + Pipeline construction --------------------- @@ -396,7 +399,7 @@ Pipeline EOS finished. When all sinks have reported EOS, the pipeline forwards the EOS message to the application. - When in EOS, the pipeline remains in the playing state, if is the application + When in EOS, the pipeline remains in the playing state, it is the applications responsability to PAUSE or READY the pipeline. The application can also issue a seek, for example. @@ -428,13 +431,13 @@ Pipeline READY WRONG_STATE return value to the peer element. The sinkpad is deactivated and becomes unusable for sending more data. mp3dec to READY: the pads are deactivated and the state change completes when - mp3dec leaves its _chain() function. + mp3dec leaves its _chain() function. filesrc to READY: the pads are deactivated and the thread is paused. The upstream elements finish their chain() function because the downstream element - returned an error code from the _push() functions. These error codes are eventually - returned to the element that started the streaming thread (filesrc), which pauses - the thread and completes the state change. + returned an error code (WRONG_STATE) from the _push() functions. These error codes + are eventually returned to the element that started the streaming thread (filesrc), + which pauses the thread and completes the state change. This sequence of events ensure that all elements are unblocked and all streaming threads stopped. diff --git a/docs/design/part-preroll.txt b/docs/design/part-preroll.txt index 4062d4b7f8..3f3d458bf0 100644 --- a/docs/design/part-preroll.txt +++ b/docs/design/part-preroll.txt @@ -14,7 +14,8 @@ wait to render the buffers or in the EOS case, wait to post the EOS message. Several things can happen that require the preroll lock to be unlocked. This -include state changes or flush events. +include state changes or flush events. The prerolling is implemented in +sinks (see part-element-sink.txt) Committing the state diff --git a/docs/design/part-seeking.txt b/docs/design/part-seeking.txt index 946673dd0e..9ffcd55932 100644 --- a/docs/design/part-seeking.txt +++ b/docs/design/part-seeking.txt @@ -28,7 +28,11 @@ Segment seeking will not emit an EOS at the end of the range but will 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. +seek events in the pipeline. Since the message is posted as early as +possible in the pipeline, the application has some time to issue a new +seek to make the transition seemless. Typically the allowed delay is +defined by the buffer sizes of the sinks as well as the size of any +queues in the pipeline. The seek can also change the playback speed of the configured segment. A speed of 1.0 is normal speed, 2.0 is double speed. Negative values @@ -60,6 +64,10 @@ seeking without FLUSH This seek type is typically performed after issuing segment seeks to finish the playback of the pipeline. +Performing a non-flushing seek in a PAUSED pipeline blocks until the pipeline +is set to playing again since all data passing is blocked in the prerolled +sinks. + segment seeking with FLUSH -------------------------- diff --git a/docs/design/part-states.txt b/docs/design/part-states.txt index 3a92dcd2a4..611a503620 100644 --- a/docs/design/part-states.txt +++ b/docs/design/part-states.txt @@ -65,15 +65,17 @@ the following state changes are possible: and the base time. It stores this information to continue playback when going back to the PLAYING state. - sinks unblock any clock wait calls. - - sinks return ASYNC from this state change and complete the state change - when they receive a buffer or an EOS event. + - when a sink did not have a pending buffer to play, it returns ASYNC from + this state change and complete the state change when they receive a new buffer + or an EOS event. - any queued EOS messages are removed since they will be reposted when going - back to the PLAYING state. + back to the PLAYING state. The EOS messages are queued in GstBins. - live sources stop generating data and return NO_PREROLL. PAUSED -> READY - sinks unblock any waits in the preroll. - elements unblock any waits on devices + - chain or get_range functions return WRONG_STATE. - the element pads are deactivated so that streaming becomes impossible and all streaming threads are stopped. @@ -125,7 +127,7 @@ The _set_state() function can return 3 possible values: GST_STATE_NO_PREROLL: The state change is completed successfully but the element will not be able to produce data in the PAUSED state. -In the case of an async state change, it is possible to proceed to the next +In the case of an ASYNC state change, it is possible to proceed to the next state before the current state change completed, however, the element will only get to this next state before completing the previous ASYNC state change. After receiving an ASYNC return value, you can use _element_get_state() to poll @@ -204,6 +206,8 @@ ASYNC, the function returns ASYNC as well. If after calling the state function on all children, one of the children returned NO_PREROLL, the function returns NO_PREROLL as well. +If both NO_PREROLL and ASYNC children are present, NO_PREROLL is returned. + The current state of the bin can be retrieved with _get_state(). If the bin is performing an ASYNC state change, it will automatically update its @@ -246,7 +250,8 @@ Bin: A->B: some elements ASYNC - no commit state - listen for commit messages on bus - - for each commit message, poll elements + - for each commit message, poll elements, this happens in another + thread. - if no ASYNC elements, commit state, continue state change to STATE_PENDING @@ -331,7 +336,7 @@ Locking overview (element) - STATE_LOCK is taken in set_state - change state is called and returns ASYNC - ASYNC returned to the caller. - - element takes STATE_LOCK in streaming thread. + - element takes LOCK in streaming thread. - element calls commit_state in streaming thread. - commit state calls change_state to next state change. diff --git a/docs/design/part-streams.txt b/docs/design/part-streams.txt index 19c4f6ef36..71bd3a00d6 100644 --- a/docs/design/part-streams.txt +++ b/docs/design/part-streams.txt @@ -33,15 +33,23 @@ Typical stream +--+ +-++-+ +-+ +---+ 1) NEW_SEGMENT, rate, start/stop, time - - marks valid buffer timestamp range - - marks stream_time of buffers in NEW_SEGMENT - - marks playback rate + - marks valid buffer timestamp range (start, stop) + - marks stream_time of buffers (time) + - marks playback rate (rate) 2) N buffers - displayable buffers are between start/stop of the NEW_SEGMENT + - display_time: (B.timestamp - NS.start) * NS.abs_rate + * used to calculate stream_time and sync_time + - stream_time: display_time + NS.time - - sync_time: display_time + base_time + * current position in stream between 0 and duration + + - sync_time: display_time + NS.accum + base_time + * used to synchronize against the clock. 3) EOS - marks the end of data, nothing is to be expected after EOS + +