mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2025-01-09 17:05:52 +00:00
design docs: fix a few typos and a thinko
This commit is contained in:
parent
8163e51bad
commit
4b88f6048a
13 changed files with 26 additions and 26 deletions
|
@ -38,7 +38,7 @@ is called or the sync block returned) no data is flowing in elem2.sink.
|
||||||
In this situation, the streaming thread is blocked on a GCond and is
|
In this situation, the streaming thread is blocked on a GCond and is
|
||||||
waiting to be unblocked.
|
waiting to be unblocked.
|
||||||
|
|
||||||
When sending a flushing seek upstream on elem1.src, the FLUSH_START and
|
When sending a flushing seek upstream on elem1.src, the FLUSH_START event
|
||||||
will temporary unblock the streaming thread and make all pad functions that
|
will temporary unblock the streaming thread and make all pad functions that
|
||||||
triggers a block (_push/_alloc_buffer/_push_event/_pull_range) return
|
triggers a block (_push/_alloc_buffer/_push_event/_pull_range) return
|
||||||
GST_FLOW_WRONG_STATE. This will then eventually pause the streaming thread
|
GST_FLOW_WRONG_STATE. This will then eventually pause the streaming thread
|
||||||
|
|
|
@ -14,7 +14,7 @@ organized in a list) to be treated as a multiple groups of GstBuffers. This allo
|
||||||
for the following extra functionality:
|
for the following extra functionality:
|
||||||
|
|
||||||
- A logical GstBuffer (called a group) can consist of disjoint memory each with
|
- A logical GstBuffer (called a group) can consist of disjoint memory each with
|
||||||
their own copy/free and metadata. Logicallty the group should be treated as
|
their own copy/free and metadata. Logically the group should be treated as
|
||||||
one single GstBuffer.
|
one single GstBuffer.
|
||||||
- Multiple groups can be put into one bufferlist. This allows for a single
|
- Multiple groups can be put into one bufferlist. This allows for a single
|
||||||
method call to pass multiple (logical) buffers downstream.
|
method call to pass multiple (logical) buffers downstream.
|
||||||
|
|
|
@ -5,7 +5,7 @@ The GstClock returns a monotonically increasing time with the method
|
||||||
_get_time(). Its accuracy and base time depends on the specific clock
|
_get_time(). Its accuracy and base time depends on the specific clock
|
||||||
implementation but time is always expessed in nanoseconds. Since the
|
implementation but time is always expessed in nanoseconds. Since the
|
||||||
baseline of the clock is undefined, the clock time returned is not
|
baseline of the clock is undefined, the clock time returned is not
|
||||||
meaningfull in itself, what matters are the deltas between two clock
|
meaningful in itself, what matters are the deltas between two clock
|
||||||
times.
|
times.
|
||||||
The time reported by the clock is called the absolute_time.
|
The time reported by the clock is called the absolute_time.
|
||||||
|
|
||||||
|
|
|
@ -3,7 +3,7 @@ Sink elements
|
||||||
|
|
||||||
Sink elements consume data. They normally have no source pads.
|
Sink elements consume data. They normally have no source pads.
|
||||||
|
|
||||||
typical sink elements include:
|
Typical sink elements include:
|
||||||
|
|
||||||
- audio/video renderers
|
- audio/video renderers
|
||||||
- network sinks
|
- network sinks
|
||||||
|
|
|
@ -53,7 +53,7 @@ The task of the application is to construct a pipeline as above using existing
|
||||||
elements. This is further explained in the pipeline building topic.
|
elements. This is further explained in the pipeline building topic.
|
||||||
|
|
||||||
The application does not have to manage any of the complexities of the
|
The application does not have to manage any of the complexities of the
|
||||||
actual dataflow/decoding/conversions/synchronsiation etc. but only calls high
|
actual dataflow/decoding/conversions/synchronisation etc. but only calls high
|
||||||
level functions on the pipeline object such as PLAY/PAUSE/STOP.
|
level functions on the pipeline object such as PLAY/PAUSE/STOP.
|
||||||
|
|
||||||
The application also receives messages and notifications from the pipeline such
|
The application also receives messages and notifications from the pipeline such
|
||||||
|
@ -249,7 +249,7 @@ Dataflow and events
|
||||||
Parallel to the dataflow is a flow of events. Unlike the buffers, events can pass
|
Parallel to the dataflow is a flow of events. Unlike the buffers, events can pass
|
||||||
both upstream and downstream. Some events only travel upstream others only downstream.
|
both upstream and downstream. Some events only travel upstream others only downstream.
|
||||||
|
|
||||||
the events are used to denote special conditions in the dataflow such as EOS or
|
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.
|
to inform plugins of special events such as flushing or seeking.
|
||||||
|
|
||||||
Some events must be serialized with the buffer flow, others don't. Serialized
|
Some events must be serialized with the buffer flow, others don't. Serialized
|
||||||
|
@ -491,7 +491,7 @@ element performs the following steps.
|
||||||
5) send NEWSEGMENT event to inform all elements of the new position and to complete
|
5) send NEWSEGMENT event to inform all elements of the new position and to complete
|
||||||
the seek.
|
the seek.
|
||||||
|
|
||||||
In step 1) all dowstream elements have to return from any blocking operations
|
In step 1) all downstream elements have to return from any blocking operations
|
||||||
and have to refuse any further buffers or events different from a FLUSH done.
|
and have to refuse any further buffers or events different from a FLUSH done.
|
||||||
|
|
||||||
The first step ensures that the streaming thread eventually unblocks and that
|
The first step ensures that the streaming thread eventually unblocks and that
|
||||||
|
|
|
@ -6,7 +6,7 @@ has been queued on the input pad or pads. This process is called prerolling
|
||||||
and is needed to fill the pipeline with buffers so that the transition to
|
and is needed to fill the pipeline with buffers so that the transition to
|
||||||
PLAYING goes as fast as possible with no visual delay for the user.
|
PLAYING goes as fast as possible with no visual delay for the user.
|
||||||
|
|
||||||
Preroll is also crucial in maintaining correct audio and video synchronsation
|
Preroll is also crucial in maintaining correct audio and video synchronisation
|
||||||
and ensuring that no buffers are dropped in the sinks.
|
and ensuring that no buffers are dropped in the sinks.
|
||||||
|
|
||||||
After receiving a buffer (or EOS) on a pad the chain/event function should
|
After receiving a buffer (or EOS) on a pad the chain/event function should
|
||||||
|
|
|
@ -8,7 +8,7 @@ driving force in the pipeline as it initiates data transport.
|
||||||
|
|
||||||
It is also possible for an element to pull data from an upstream element.
|
It is also possible for an element to pull data from an upstream element.
|
||||||
The downstream element does this by calling gst_pad_pull_range() on one
|
The downstream element does this by calling gst_pad_pull_range() on one
|
||||||
of its sinkpads. In this mode, the upstream element is the driving force
|
of its sinkpads. In this mode, the downstream element is the driving force
|
||||||
in the pipeline as it initiates data transfer.
|
in the pipeline as it initiates data transfer.
|
||||||
|
|
||||||
It is important that the elements are in the correct state to handle a
|
It is important that the elements are in the correct state to handle a
|
||||||
|
|
|
@ -33,7 +33,7 @@ push function to push the result to the peer sinkpad.
|
||||||
Deciding the scheduling mode
|
Deciding the scheduling mode
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
When tha pad is activated, the _activate() function is called. The pad can then
|
When a pad is activated, the _activate() function is called. The pad can then
|
||||||
choose to activate itself in push or pull mode depending on upstream
|
choose to activate itself in push or pull mode depending on upstream
|
||||||
capabilities.
|
capabilities.
|
||||||
|
|
||||||
|
@ -43,13 +43,13 @@ activate function for the pad.
|
||||||
The chain function
|
The chain function
|
||||||
~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The chain function will be called when a upstream element perform a _push() on the pad.
|
The chain function will be called when a upstream element performs a _push() on the pad.
|
||||||
The upstream element can be another chain based element or a pushing source.
|
The upstream element can be another chain based element or a pushing source.
|
||||||
|
|
||||||
The getrange function
|
The getrange function
|
||||||
~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The getrange function is called when a peer pad perform a _pull_range() on the pad. This
|
The getrange function is called when a peer pad performs a _pull_range() on the pad. This
|
||||||
downstream pad can be a pulling element or another _pull_range() based element.
|
downstream pad can be a pulling element or another _pull_range() based element.
|
||||||
|
|
||||||
Plug-in techniques
|
Plug-in techniques
|
||||||
|
|
|
@ -11,15 +11,15 @@ pipeline. Sending the seek event to a bin will by default forward
|
||||||
the event to all sinks in the bin.
|
the event to all sinks in the bin.
|
||||||
|
|
||||||
When performing a seek, the start and stop values of the segment can be
|
When performing a seek, the start and stop values of the segment can be
|
||||||
specified as absoulte positions or relative to the currently configured
|
specified as absolute positions or relative to the currently configured
|
||||||
playback segment. Note that it is not possible to seek relative to the current
|
playback segment. Note that it is not possible to seek relative to the current
|
||||||
playback position. To seek relative to the current playback position, one must
|
playback position. To seek relative to the current playback position, one must
|
||||||
query the position first and then perform an absolute seek to the desired
|
query the position first and then perform an absolute seek to the desired
|
||||||
position.
|
position.
|
||||||
|
|
||||||
Feedback of the seek operation can be immediatly using the GST_SEEK_FLAG_FLUSH
|
Feedback of the seek operation can be immediately using the GST_SEEK_FLAG_FLUSH
|
||||||
flag. With this flag, all pending data in the pipeline is discarded and playback
|
flag. With this flag, all pending data in the pipeline is discarded and playback
|
||||||
starts from the new position immediatly.
|
starts from the new position immediately.
|
||||||
|
|
||||||
When the FLUSH flag is not set, the seek will be queued and executed as
|
When the FLUSH flag is not set, the seek will be queued and executed as
|
||||||
soon as possible, which might be after all queues are emptied.
|
soon as possible, which might be after all queues are emptied.
|
||||||
|
@ -47,7 +47,7 @@ application has some time to issue a new seek to make the transition seamless.
|
||||||
Typically the allowed delay is defined by the buffer sizes of the sinks as well
|
Typically the allowed delay is defined by the buffer sizes of the sinks as well
|
||||||
as the size of any queues in the pipeline.
|
as the size of any queues in the pipeline.
|
||||||
|
|
||||||
The seek can also change the playback speed of the configured segment.
|
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
|
A speed of 1.0 is normal speed, 2.0 is double speed. Negative values
|
||||||
mean backward playback.
|
mean backward playback.
|
||||||
|
|
||||||
|
@ -83,8 +83,8 @@ FLUSH seeking
|
||||||
^^^^^^^^^^^^^
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
This is the most common way of performing a seek in a playback application.
|
This is the most common way of performing a seek in a playback application.
|
||||||
The application issues a seek on the pipeline and the new media is immediatly
|
The application issues a seek on the pipeline and the new media is immediately
|
||||||
played after the seek calls returns.
|
played after the seek call returns.
|
||||||
|
|
||||||
|
|
||||||
seeking without FLUSH
|
seeking without FLUSH
|
||||||
|
|
|
@ -80,7 +80,7 @@ Use case: FLUSHING seek
|
||||||
synchronisation and position reporting.
|
synchronisation and position reporting.
|
||||||
|
|
||||||
Since after a flushing seek the stream_time is reset to 0, the new buffer
|
Since after a flushing seek the stream_time is reset to 0, the new buffer
|
||||||
will be rendered immediatly after the seek and the current_position will be
|
will be rendered immediately after the seek and the current_position will be
|
||||||
the stream_time of the seek that was performed.
|
the stream_time of the seek that was performed.
|
||||||
|
|
||||||
The stop time is important when the video format contains B frames. The
|
The stop time is important when the video format contains B frames. The
|
||||||
|
|
|
@ -48,7 +48,7 @@ the following state changes are possible:
|
||||||
PAUSED -> PLAYING
|
PAUSED -> PLAYING
|
||||||
- Most elements ignore this state change.
|
- Most elements ignore this state change.
|
||||||
- The pipeline selects a clock and distributes this to all the children
|
- The pipeline selects a clock and distributes this to all the children
|
||||||
before setting them to PLAYING. This means that it is only alowed to
|
before setting them to PLAYING. This means that it is only allowed to
|
||||||
synchronize on the clock in the PLAYING state.
|
synchronize on the clock in the PLAYING state.
|
||||||
- The pipeline uses the clock and the running_time to calculate the base_time.
|
- The pipeline uses the clock and the running_time to calculate the base_time.
|
||||||
The base_time is distributed to all children when performing the state
|
The base_time is distributed to all children when performing the state
|
||||||
|
@ -113,7 +113,7 @@ _set_state(), called the STATE_LOCK.
|
||||||
Setting state on elements
|
Setting state on elements
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The state of an element can be changed with _element_set_state(). When chaning
|
The state of an element can be changed with _element_set_state(). When changing
|
||||||
the state of an element all intermediate states will also be set on the element
|
the state of an element all intermediate states will also be set on the element
|
||||||
until the final desired state is set.
|
until the final desired state is set.
|
||||||
|
|
||||||
|
@ -125,7 +125,7 @@ The _set_state() function can return 3 possible values:
|
||||||
GST_STATE_SUCCESS: The state change is completed successfully.
|
GST_STATE_SUCCESS: The state change is completed successfully.
|
||||||
|
|
||||||
GST_STATE_ASYNC: The state change will complete later on. This can happen
|
GST_STATE_ASYNC: The state change will complete later on. This can happen
|
||||||
When the element needs a long time to perform the state
|
when the element needs a long time to perform the state
|
||||||
change or for sinks that need to receive the first buffer
|
change or for sinks that need to receive the first buffer
|
||||||
before they can complete the state change (preroll).
|
before they can complete the state change (preroll).
|
||||||
|
|
||||||
|
@ -143,7 +143,7 @@ When setting the state of an element, the STATE_PENDING is set to the required
|
||||||
state. Then the state change function of the element is called and the result of
|
state. Then the state change function of the element is called and the result of
|
||||||
that function is used to update the STATE and STATE_RETURN fields, STATE_NEXT,
|
that function is used to update the STATE and STATE_RETURN fields, STATE_NEXT,
|
||||||
STATE_PENDING and STATE_RETURN fields. If the function returned ASYNC, this result
|
STATE_PENDING and STATE_RETURN fields. If the function returned ASYNC, this result
|
||||||
is immediatly returned to the caller.
|
is immediately returned to the caller.
|
||||||
|
|
||||||
|
|
||||||
Getting state of elements
|
Getting state of elements
|
||||||
|
|
|
@ -24,9 +24,9 @@ Typical stream
|
||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
A typical stream starts with a newsegment event that marks the
|
A typical stream starts with a newsegment event that marks the
|
||||||
buffer timestamp range. After that buffers are send one after the
|
buffer timestamp range. After that buffers are sent one after the
|
||||||
other. After the last buffer an EOS marks the end of the stream. No
|
other. After the last buffer an EOS marks the end of the stream. No
|
||||||
more buffer are to be processed after the EOS event.
|
more buffers are to be processed after the EOS event.
|
||||||
|
|
||||||
+--+ +-++-+ +-+ +---+
|
+--+ +-++-+ +-+ +---+
|
||||||
|NS| |B||B| ... |B| |EOS|
|
|NS| |B||B| ... |B| |EOS|
|
||||||
|
|
|
@ -55,7 +55,7 @@ to PAUSED and restores this time based on the current absolute_time when going
|
||||||
back to PLAYING. This allows for both clocks that progress when in the PAUSED
|
back to PLAYING. This allows for both clocks that progress when in the PAUSED
|
||||||
state (systemclock) and clocks that don't (audioclock).
|
state (systemclock) and clocks that don't (audioclock).
|
||||||
|
|
||||||
The clock and pipeline now provides a running_time to all elements that want to
|
The clock and pipeline now provide a running_time to all elements that want to
|
||||||
perform synchronisation. Indeed, the running time can be observed in each
|
perform synchronisation. Indeed, the running time can be observed in each
|
||||||
element (during the PLAYING state) as:
|
element (during the PLAYING state) as:
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue