mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-19 16:21:17 +00:00
46d2c100f8
Original commit message from CVS: * docs/design/part-TODO.txt: * docs/design/part-activation.txt: * docs/design/part-block.txt: * docs/design/part-buffering.txt: * docs/design/part-clocks.txt: * docs/design/part-element-source.txt: * docs/design/part-events.txt: * docs/design/part-gstbin.txt: * docs/design/part-gstbus.txt: * docs/design/part-gstpipeline.txt: * docs/design/part-live-source.txt: * docs/design/part-messages.txt: * docs/design/part-overview.txt: * docs/design/part-qos.txt: * docs/design/part-query.txt: * docs/design/part-states.txt: * docs/design/part-trickmodes.txt: Some doc updates. Start renaming from stream_time to running_time where it was used wrongly.
119 lines
4.5 KiB
Text
119 lines
4.5 KiB
Text
Source elements
|
|
---------------
|
|
|
|
A source element is an element that provides data to the pipeline. It
|
|
does typically not have any sink (input) pads.
|
|
|
|
Typical source elements include:
|
|
|
|
- file readers
|
|
- network elements (live or not)
|
|
- capture elements (video/audio/...)
|
|
- generators (signals/video/audio/...)
|
|
|
|
|
|
Live sources
|
|
------------
|
|
|
|
A source is said to be a live source when it has the following property:
|
|
|
|
* temporarily stopping reading from the source causes data to be lost.
|
|
|
|
In general when this property holds, the source also produces data at a fixed
|
|
rate. Most sources have a limit to the rate at which they can deliver data, which
|
|
might be faster or slower than the consumption rate. this property however does
|
|
not make them a live source.
|
|
|
|
Let's look at some example sources.
|
|
|
|
- file readers: you can PAUSE without losing data. There is however a limit to
|
|
how fast you can read from this source. This limit is usually much higher
|
|
than the consumption rate. In some cases it might be slower (an NFS share,
|
|
for example) in which case you might need to use some buffering
|
|
(see part-buffering.txt).
|
|
|
|
- http network element: you can PAUSE without data loss. Depending on the
|
|
available network bandwidth, consumption rate might be higher than production
|
|
rate in which case buffering should be used (see part-buffering.txt).
|
|
|
|
- audio source: pausing the audio capture will lead to lost data. this source
|
|
is therefore definatly live. In addition, an audio source will produce data
|
|
at a fixed rate (the samplerate). Also depending on the buffersize, this
|
|
source will introduce a latency (see part-latency.txt).
|
|
|
|
- udp network source: Pausing the receiving part will lead to lost data. This
|
|
source is therefore a live source. Also in a typical case the udp packets
|
|
will be received at a certain rate, which might be difficult to guess because
|
|
of network jitter. This source does not necessarily introduce latency on its
|
|
own.
|
|
|
|
- dvb source: PAUSING this element will lead to data loss, it's a live source
|
|
similar to a UDP source.
|
|
|
|
|
|
Source types
|
|
------------
|
|
|
|
A source element can operate in three ways:
|
|
|
|
- it is fully seekable, this means that random access can be performed
|
|
on it in an efficient way. (a file reader,...). This also typically
|
|
means that the source is not live.
|
|
|
|
- data can be obtained from it with a variable size. This means that
|
|
the source can give N bytes of data. An example is an audio source.
|
|
A video source always provides the same amount of data (one video
|
|
frame). Note that this is not a fully seekable source.
|
|
|
|
- it is a live source, see above.
|
|
|
|
When writing a source, one has to look at how the source can operate to
|
|
decide on the scheduling methods to implement on the source.
|
|
|
|
- fully seekable sources implement a getrange function on the source pad.
|
|
|
|
- sources that can give N bytes but cannot do seeking also implement a
|
|
getrange function but state that they cannot do random access.
|
|
|
|
- sources that are purely live sources implement a task to push out
|
|
data.
|
|
|
|
Any source that has a getrange function must also implement a push based
|
|
scheduling mode. In this mode the source starts a task that gets N bytes
|
|
and pushes them out. Whenever possible, the peer element will select the
|
|
getrange based scheduling method of the source, though.
|
|
|
|
A source with a getrange function must activate itself in the pad activate
|
|
function. This is needed because the downstream peer element will decide
|
|
and activate the source element in its state change function before the
|
|
source's state change function is called.
|
|
|
|
|
|
Source base classes
|
|
-------------------
|
|
|
|
GstBaseSrc:
|
|
|
|
This base class provides an implementation of a random access source and
|
|
is very well suited for file reader like sources.
|
|
|
|
|
|
GstPushSrc:
|
|
|
|
Base class for block-based sources. This class is mostly useful for
|
|
elements that cannot do random access, or at least very slowly. The
|
|
source usually prefers to push out a fixed size buffer.
|
|
|
|
Classes extending this base class will usually be scheduled in a push
|
|
based mode. It the peer accepts to operate without offsets and withing
|
|
the limits of the allowed block size, this class can operate in getrange
|
|
based mode automatically.
|
|
|
|
The subclass should extend the methods from the baseclass in
|
|
addition to the create method. If the source is seekable, it
|
|
needs to override GstBaseSrc::event() in addition to
|
|
GstBaseSrc::is_seekable() in order to retrieve the seek offset,
|
|
which is the offset of the next buffer to be requested.
|
|
|
|
Flushing, scheduling and sync is all handled by this base class.
|
|
|