mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2025-01-24 16:18:16 +00:00
design-docs: add html output using asciidoc
Unify the ad-hoc markup to be asciidoc style in many places. Add a "html" target to Makefile to generate the output.
This commit is contained in:
Stefan Kost
parent
1c50dcd54f
commit
16ce2d4ea4
46 changed files with 1637 additions and 1589 deletions
|
|
@ -47,6 +47,22 @@ EXTRA_DIST = \
|
|||
part-TODO.txt \
|
||||
part-trickmodes.txt
|
||||
|
||||
CLEANFILES = index.html index.txt
|
||||
|
||||
html:
|
||||
if ! test -z `which asciidoc`; then \
|
||||
echo >index.txt "GStreamer design"; \
|
||||
echo >>index.txt "================"; \
|
||||
echo >>index.txt "The Gstreamer developers"; \
|
||||
echo >>index.txt "Version $(PACKAGE_VERSION)"; \
|
||||
echo >>index.txt ""; \
|
||||
( cd $(srcdir) && \
|
||||
cat >>$(abs_builddir)/index.txt $(EXTRA_DIST) ); \
|
||||
asciidoc -o index.html index.txt; \
|
||||
else \
|
||||
echo "need asciidoc to generate html"; \
|
||||
fi;
|
||||
|
||||
upload:
|
||||
@echo nothing to upload
|
||||
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ Some examples of metadata:
|
|||
|
||||
|
||||
Requirements
|
||||
------------
|
||||
~~~~~~~~~~~~
|
||||
|
||||
- It must be fast
|
||||
* allocation, free, low fragmentation
|
||||
|
|
@ -41,7 +41,7 @@ Requirements
|
|||
|
||||
|
||||
GstMiniObject
|
||||
-------------
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
We make GstMiniObject a simple refcounted C structure and also a GLib boxed
|
||||
type. The following fields will be in the structure:
|
||||
|
|
@ -66,7 +66,7 @@ objects.
|
|||
|
||||
|
||||
GstEvent, GstCaps, GstQuery, GstMessage
|
||||
---------------------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Have the new GstMiniObject be the first field in these objects. They will probably
|
||||
also replace the copy and free functions with their own implementations.
|
||||
|
|
@ -77,7 +77,7 @@ the custom functions.
|
|||
|
||||
|
||||
GstBuffer
|
||||
---------
|
||||
~~~~~~~~~
|
||||
|
||||
A GstMiniObject will be the parent instance of the GstBuffer object, which is a
|
||||
regular C structure.
|
||||
|
|
@ -105,7 +105,7 @@ Buffers point to a GstCaps structure that contains the caps of the buffer data.
|
|||
|
||||
|
||||
GstBufferMeta
|
||||
-------------
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
A GstBufferMeta is a structure as follows:
|
||||
|
||||
|
|
@ -208,7 +208,7 @@ GstBufferMetaMemory | | next ---+
|
|||
. .
|
||||
|
||||
API examples
|
||||
------------
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Buffers are created using the normal gst_buffer_new functions. The standard fields
|
||||
are initialized as usual. A memory area that is bigger than the structure size
|
||||
|
|
@ -276,7 +276,7 @@ possible simple API would look like this:
|
|||
|
||||
|
||||
Memory management
|
||||
-----------------
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
* allocation
|
||||
|
||||
|
|
@ -316,7 +316,7 @@ Memory management
|
|||
|
||||
|
||||
Subbuffers
|
||||
----------
|
||||
~~~~~~~~~~
|
||||
|
||||
Subbuffers are a first class feature of the GstBuffer.
|
||||
|
||||
|
|
@ -334,7 +334,7 @@ timing metadata needs to be reset to NONE when the start offset is different.
|
|||
|
||||
|
||||
Serialization
|
||||
-------------
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
When buffer should be sent over the wire or be serialized in GDP, we need a way
|
||||
to perform custom serialization and deserialization on the metadata.
|
||||
|
|
@ -345,7 +345,7 @@ and endianness.
|
|||
|
||||
|
||||
Transformations
|
||||
---------------
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
After certain transformations, the metadata on a buffer might not be relevant
|
||||
anymore.
|
||||
|
|
@ -368,7 +368,7 @@ so on).
|
|||
|
||||
|
||||
Other use cases
|
||||
---------------
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Making the GstBufferMetaMemory (for making the buffer point to the associated
|
||||
memory region) as metadata on a GstBuffer, as opposed to making it an integral
|
||||
|
|
@ -397,7 +397,7 @@ implementations add (or use, in the case of a file reader) the memory metadata.
|
|||
|
||||
|
||||
Relationship with GstCaps
|
||||
-------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The difference between GstCaps, used in negotiation, and the metadata is not
|
||||
clearly defined.
|
||||
|
|
@ -415,7 +415,7 @@ video resolution while the implementation details would be inside the metadata.
|
|||
|
||||
|
||||
Compatibility
|
||||
-------------
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
We need to make sure that elements exchange metadata that they both understand,
|
||||
This is particulary important when the metadata describes the data layout in
|
||||
|
|
@ -436,16 +436,16 @@ that are metadata aware to set a flag on their pads; any buffer passed on that
|
|||
pad will be converted to the old layout when the flag is not set.
|
||||
|
||||
|
||||
Notes:
|
||||
------
|
||||
Notes
|
||||
~~~~~
|
||||
|
||||
Some structures that we need to be able to add to buffers.
|
||||
|
||||
Clean Aperture
|
||||
Arbitrary Matrix Transform
|
||||
Aspect ratio
|
||||
Pan/crop/zoom
|
||||
Video strides
|
||||
* Clean Aperture
|
||||
* Arbitrary Matrix Transform
|
||||
* Aspect ratio
|
||||
* Pan/crop/zoom
|
||||
* Video strides
|
||||
|
||||
Some of these overlap, we need to find a minimal set of metadata structures that
|
||||
allows us to define all use cases.
|
||||
|
|
|
|||
|
|
@ -1,12 +1,8 @@
|
|||
Element Klass definition
|
||||
------------------------
|
||||
|
||||
Status:
|
||||
|
||||
DRAFT.
|
||||
|
||||
|
||||
Purpose:
|
||||
Purpose
|
||||
~~~~~~~
|
||||
|
||||
Applications should be able to retrieve elements from the registry of existing
|
||||
elements based on specific capabilities or features of the element.
|
||||
|
|
@ -20,7 +16,8 @@ Purpose:
|
|||
A list of classes that are used in a installation can be generated using:
|
||||
gst-inspect-0.10 -a | grep -ho Class:.* | cut -c8- | sed "s/\//\\n/g" | sort | uniq
|
||||
|
||||
Proposal:
|
||||
Proposal
|
||||
~~~~~~~~
|
||||
|
||||
The GstElementDetails contains a field named klass that is a pointer to a
|
||||
string describing the element type.
|
||||
|
|
@ -158,7 +155,8 @@ Proposal:
|
|||
autoaudiosink : Sink/Audio/Device
|
||||
alsasink : Sink/Audio/Device
|
||||
|
||||
Use cases:
|
||||
Use cases
|
||||
~~~~~~~~~
|
||||
|
||||
- get a list of all elements implementing a video effect (pitivi):
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ additions.
|
|||
|
||||
|
||||
Supported Metadata standards
|
||||
----------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The paragraphs below list supported native metadata standards sorted by type and
|
||||
then in alphabetical order. Some standards have been extended to support
|
||||
|
|
@ -94,7 +94,7 @@ http://wiki.creativecommons.org/Tracker_CC_Indexing
|
|||
|
||||
|
||||
Current Metadata handling
|
||||
-------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When reading files, demuxers or parsers extract the metadata. It will be sent as
|
||||
a GST_MESSAGE_TAG to the GstBus and GST_EVENT_TAG to downstream elements.
|
||||
|
|
@ -130,10 +130,11 @@ metadata.
|
|||
|
||||
|
||||
Issues
|
||||
------
|
||||
~~~~~~
|
||||
|
||||
Unknown/Unmapped metadata
|
||||
- - - - - - - - - - - - -
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Right now GStreamer can lose metadata when transcoding, remuxing content. This
|
||||
can happend as we don't map all metadata fields to generic ones.
|
||||
|
||||
|
|
@ -159,7 +160,8 @@ We would basically need this for each container format.
|
|||
See also https://bugzilla.gnome.org/show_bug.cgi?id=345352
|
||||
|
||||
Lost metadata
|
||||
- - - - - - -
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
A case slighly different from the previous is that when an application sets a
|
||||
GstTagList on a pipeline. Right elements consuming tags do not report which tags
|
||||
have been consumed. Especially when using elements that make metadata
|
||||
|
|
@ -181,7 +183,8 @@ of elements and their tags. As a convenience we could flatten the list of tags
|
|||
for the top-level element (if the query was sent to a bin) and add that.
|
||||
|
||||
Tags are per Element
|
||||
- - - - - - - - - -
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In many cases we want tags per stream. Even metadata standards like mp4/3gp
|
||||
metadata supports that. Right now GST_MESSAGE_SRC(tags) is the element. We tried
|
||||
changing that to the pad, but that broke applications.
|
||||
|
|
@ -189,7 +192,7 @@ Also we miss the symmetric functionality in GstTagSetter. This interface is
|
|||
usually implemented by elements.
|
||||
|
||||
Open bugs
|
||||
- - - - -
|
||||
^^^^^^^^^
|
||||
|
||||
https://bugzilla.gnome.org/buglist.cgi?query_format=advanced;short_desc=tag;bug_status=UNCONFIRMED;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;bug_status=NEEDINFO;short_desc_type=allwordssubstr;product=GStreamer
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ peeked buffers (a queue element after sink, but that would change pull to push).
|
|||
|
||||
|
||||
Design
|
||||
------
|
||||
~~~~~~
|
||||
|
||||
The plan is that applications can do the following:
|
||||
pipeline = "filesrc ! tagbin"
|
||||
|
|
@ -38,7 +38,8 @@ The plan is that applications can do the following:
|
|||
decodebin
|
||||
|
||||
Interface
|
||||
---------
|
||||
~~~~~~~~~
|
||||
|
||||
* gboolean iface property "tag-reading"
|
||||
Switches the element to tagreading mode. Needed if normal element implement
|
||||
that behaviour. Elements will skip parsing unneeded data, don't build a
|
||||
|
|
@ -47,7 +48,7 @@ Interface
|
|||
Equivalent of EOS.
|
||||
|
||||
Use Cases
|
||||
---------
|
||||
~~~~~~~~~
|
||||
|
||||
* mp3 with id3- and apetags
|
||||
* plug id3demux ! apedemux
|
||||
|
|
@ -57,7 +58,8 @@ Use Cases
|
|||
* plug vorbisdec or special vorbiscomment reader
|
||||
|
||||
Additional Thoughts
|
||||
-------------------
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* would it make sense to have 2-phase tag-reading (property on tagbin and/or
|
||||
tagread elements)
|
||||
* 1st phase: get tag-data that are directly embedded in the data
|
||||
|
|
@ -73,23 +75,25 @@ Additional Thoughts
|
|||
gst_tag_cache_store_tag_data (GstTagCache *self, const gchar *uri, GstTagList *tags);
|
||||
|
||||
Tests
|
||||
-----
|
||||
~~~~~
|
||||
|
||||
* write a generic test for parsers/demuxers to ensure they send tags until they
|
||||
reached PAUSED (elements need to parse file for prerolling anyway):
|
||||
set pipeline to paused, check for tags, set to playing, error out if tags come
|
||||
after paused
|
||||
|
||||
Code Locations
|
||||
--------------
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
* tagreadbin -> gst-plugins-base/gst/tagread
|
||||
* tagreaderiface -> gst-plugins-base/gst-libs/gst/tag
|
||||
|
||||
Reuse
|
||||
-----
|
||||
~~~~~
|
||||
|
||||
ogg : gst-plugins-base/ext/ogg
|
||||
avi : gst-plugins-good/gst/avi
|
||||
mp3 : gst-plugins-good/gst/id3demux
|
||||
wav : gst-plugins-good/gst/wavparse
|
||||
qt : gst-plugins-bad/gst/qtdemux
|
||||
* ogg : gst-plugins-base/ext/ogg
|
||||
* avi : gst-plugins-good/gst/avi
|
||||
* mp3 : gst-plugins-good/gst/id3demux
|
||||
* wav : gst-plugins-good/gst/wavparse
|
||||
* qt : gst-plugins-bad/gst/qtdemux
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ This design decision has implications for the usage of the API and the objects
|
|||
which this document explains.
|
||||
|
||||
MT safety techniques
|
||||
--------------------
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Several design patterns are used to guarantee object consistency in GStreamer.
|
||||
This is an overview of the methods used in various GStreamer subsystems.
|
||||
|
|
@ -140,7 +140,7 @@ Compare and swap
|
|||
|
||||
|
||||
Objects
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
* Locking involved:
|
||||
|
||||
|
|
@ -414,3 +414,4 @@ Objects
|
|||
}
|
||||
}
|
||||
gst_iterator_free (it);
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,8 @@
|
|||
TODO - Future Development
|
||||
-------------------------
|
||||
|
||||
API/ABI
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
- implement return values from events in addition to the gboolean. This should
|
||||
be done by making the event contain a GstStructure with input/output values,
|
||||
|
|
@ -66,7 +69,7 @@ API/ABI
|
|||
|
||||
|
||||
IMPLEMENTATION
|
||||
--------------
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
- implement more QOS, see part-qos.txt.
|
||||
|
||||
|
|
@ -76,7 +79,7 @@ IMPLEMENTATION
|
|||
|
||||
|
||||
DESIGN
|
||||
------
|
||||
~~~~~~
|
||||
|
||||
- unlinking pads in the PAUSED state needs to make sure the stream thread is not
|
||||
executing code. Can this be done with a flush to unlock all downstream chain
|
||||
|
|
|
|||
|
|
@ -1,5 +1,8 @@
|
|||
Pad activation
|
||||
--------------
|
||||
Pad (de)activation
|
||||
------------------
|
||||
|
||||
Activation
|
||||
~~~~~~~~~~
|
||||
|
||||
When changing states, a bin will set the state on all of its children in
|
||||
sink-to-source order. As elements undergo the READY->PAUSED transition,
|
||||
|
|
@ -73,7 +76,7 @@ already in PAUSED with an active sink pad by the time fakesrc starts
|
|||
pushing data.
|
||||
|
||||
Deactivation
|
||||
------------
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Pad deactivation occurs when its parent goes into the READY state or when the
|
||||
pad is deactivated explicitly by the application or element.
|
||||
|
|
@ -82,7 +85,8 @@ activate_push() or activate_pull() with a FALSE argument, depending on the
|
|||
activation mode of the pad.
|
||||
|
||||
Mode switching
|
||||
--------------
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Changing from push to pull modes needs a bit of thought. This is actually
|
||||
possible and implemented but not yet documented here.
|
||||
|
||||
|
|
|
|||
|
|
@ -18,12 +18,13 @@ and will succeed when the following events happen on the pad:
|
|||
|
||||
|
||||
Flushing
|
||||
--------
|
||||
~~~~~~~~
|
||||
|
||||
The flushing event is used to clear any data out of the
|
||||
downstream elements.
|
||||
|
||||
* Generic case
|
||||
Generic case
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Consider the following pipeline:
|
||||
|
||||
|
|
@ -50,7 +51,8 @@ Flushing
|
|||
for the same reason. From then on, the new data after the flushing seek
|
||||
will be queued when the pad block is taken again.
|
||||
|
||||
* Case where the stream is blocking downstream
|
||||
Case where the stream is blocking downstream
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The example above is only valid if the elem1.src pad is really blocking
|
||||
(callback called or sync block returned).
|
||||
|
|
@ -74,10 +76,11 @@ Flushing
|
|||
gives a chance for the elem1.src pad to block.
|
||||
|
||||
|
||||
Use cases:
|
||||
----------
|
||||
Use cases
|
||||
~~~~~~~~~
|
||||
|
||||
* Prerolling a partial pipeline
|
||||
Prerolling a partial pipeline
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.---------. .---------. .----------.
|
||||
| filesrc | | demuxer | .-----. | decoder1 |
|
||||
|
|
@ -109,7 +112,8 @@ Use cases:
|
|||
- connect other elements and unblock the blocked pads.
|
||||
|
||||
|
||||
* dynamically switching an element in a PLAYING pipeline.
|
||||
dynamically switching an element in a PLAYING pipeline
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
.----------. .----------. .----------.
|
||||
|
|
@ -155,7 +159,7 @@ Use cases:
|
|||
|
||||
|
||||
Issues
|
||||
------
|
||||
~~~~~~
|
||||
|
||||
When an EOS event has passed a pad and the pad is set to blocked, the block will
|
||||
never happen because no data is going to flow anymore. One possibility is to
|
||||
|
|
|
|||
|
|
@ -112,7 +112,7 @@ We want to be able to implement the following features:
|
|||
|
||||
|
||||
Messages
|
||||
--------
|
||||
~~~~~~~~
|
||||
|
||||
A GST_MESSAGE_BUFFERING must be posted on the bus when playback temporarily
|
||||
stops to buffer and when buffering finishes. When percentage field in the
|
||||
|
|
@ -137,27 +137,24 @@ are added to the buffering message:
|
|||
|
||||
"avg-in-rate", G_TYPE_INT
|
||||
- gives the average input buffering speed in bytes/second. -1 is unknown.
|
||||
|
||||
This is the average number of bytes per second that is received on the
|
||||
buffering element input (sink) pads. It is a measurement of the network
|
||||
speed in most cases.
|
||||
|
||||
"avg-out-rate", G_TYPE_INT
|
||||
- gives the average consumption speed in bytes/second. -1 is unknown.
|
||||
|
||||
This is the average number of bytes per second that is consumed by the
|
||||
downstream element of the buffering element.
|
||||
|
||||
"buffering-left", G_TYPE_INT64
|
||||
- gives the estimated time that bufferring will take in milliseconds.
|
||||
-1 unknown.
|
||||
|
||||
This is measured based on the avg-in-rate and the filled level of the
|
||||
queue. The application can use this hint to update the GUI about the
|
||||
estimated remaining time that buffering will take.
|
||||
|
||||
Application
|
||||
-----------
|
||||
~~~~~~~~~~~
|
||||
|
||||
While data is buffered, the pipeline should remain in the PAUSED state. It is
|
||||
also possible that more data should be buffered while the pipeline is PLAYING,
|
||||
|
|
@ -180,7 +177,7 @@ time to resume playback to get uninterrupted playback.
|
|||
|
||||
|
||||
Buffering Query
|
||||
---------------
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
In addition to the BUFFERING messages posted by the buffering elements we want
|
||||
to be able to query the same information from the application. We also want to
|
||||
|
|
@ -222,7 +219,7 @@ and newest item (expressed in "format") in the buffer.
|
|||
|
||||
|
||||
Defaults
|
||||
--------
|
||||
~~~~~~~~
|
||||
|
||||
Some defaults for common elements:
|
||||
|
||||
|
|
|
|||
|
|
@ -21,12 +21,13 @@ for the following extra functionality:
|
|||
|
||||
|
||||
Use cases
|
||||
---------
|
||||
~~~~~~~~~
|
||||
|
||||
A typical use case for multimedia pipelines is to append or remove 'headers'
|
||||
from packets of data.
|
||||
|
||||
* Generating RTP packets from h264 video
|
||||
Generating RTP packets from h264 video
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
We receive as input a GstBuffer with an encoded h264 image and we need to
|
||||
create RTP packets containing this h264 data as the payload. We typically need
|
||||
|
|
@ -41,7 +42,7 @@ from packets of data.
|
|||
+-+ +-------+ +-+ +-------+ +-+ +-------+
|
||||
output bufferlist: | | | NALU1 | | | | NALU2 | .... | | | NALUx |
|
||||
+-+ +-------+ +-+ +-------+ +-+ +-------+
|
||||
|
||||
: : : :
|
||||
\-----------/ \-----------/
|
||||
group 1 group 2
|
||||
|
||||
|
|
@ -59,7 +60,7 @@ from packets of data.
|
|||
|
||||
|
||||
API
|
||||
---
|
||||
~~~
|
||||
|
||||
The GstBufferList is an opaque data structure and is operated on using an
|
||||
iterator. It derives from GstMiniObject so that it has basic refcounting and
|
||||
|
|
@ -78,7 +79,7 @@ group.
|
|||
|
||||
|
||||
Metadata
|
||||
--------
|
||||
~~~~~~~~
|
||||
|
||||
Each of the buffers inside the bufferlist can have metadata assiociated with it.
|
||||
|
||||
|
|
@ -92,3 +93,4 @@ first group in the bufferlist. This means that:
|
|||
|
||||
This allows for efficient (re)timestamping and re-typing (caps) of a group of
|
||||
buffers without having to modify each of the buffer's metadata.
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ The time reported by the clock is called the absolute_time.
|
|||
|
||||
|
||||
Clock Selection
|
||||
---------------
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
To synchronize the different elements, the GstPipeline is responsible for
|
||||
selecting and distributing a global GstClock for all the elements in it.
|
||||
|
|
@ -35,7 +35,7 @@ PLAYING and is described in part-states.txt.
|
|||
|
||||
|
||||
Clock features
|
||||
--------------
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
The clock supports periodic and single shot clock notifications both
|
||||
synchronous and asynchronous.
|
||||
|
|
@ -73,7 +73,7 @@ the clock is not PLAYING.
|
|||
|
||||
|
||||
Clock implementations
|
||||
---------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The GStreamer core provides a GstSystemClock based on the system time.
|
||||
Asynchronous callbacks are scheduled from an internal thread.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
Documentation conventions
|
||||
=========================
|
||||
-------------------------
|
||||
|
||||
Due to the potential for exponential growth, several abbreviating conventions will be used throughout this
|
||||
documentation. These conventions have grown primarily from extremely in-depth discussions of the architecure in IRC.
|
||||
|
|
@ -7,21 +7,21 @@ This has verified the safety of these conventions, if used properly. There are
|
|||
context is rigorously observed.
|
||||
|
||||
Object classes
|
||||
--------------
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Since everything starts with Gst, we will generally refer to objects by the shorter name, i.e. Element or Pad. These
|
||||
names will always have their first letter capitalized.
|
||||
|
||||
Function names
|
||||
--------------
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Within the context of a given object, functions defined in that object's header and/or source file will have their
|
||||
object-specific prefix stripped. For instance, gst_element_add_pad() would be referred to as simply _add_pad(). Note
|
||||
that the trailing parentheses should always be present, but sometimes may not be. A prefixing underscore (_) will
|
||||
always tell you it's a function, however, regardless of the presence or absence of the trailing parentheses.
|
||||
|
||||
#defines and enums
|
||||
------------------
|
||||
defines and enums
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Values and macros defined as enums and preprocessor macros will be referred to in all capitals, as per their
|
||||
definition. This includes object flags and element states, as well as general enums. Examples are the states NULL,
|
||||
|
|
@ -31,23 +31,25 @@ element flags should be cross-checked with the header, as there are currently tw
|
|||
_FLAGS_ in the middle.
|
||||
|
||||
Drawing conventions
|
||||
===================
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When drawing pictures the folowing conventions apply:
|
||||
|
||||
objects
|
||||
-------
|
||||
^^^^^^^
|
||||
|
||||
Objects are drawn with a box like:
|
||||
|
||||
Objects are drawn with a box like
|
||||
+------+
|
||||
| |
|
||||
+------+
|
||||
|
||||
|
||||
pointers
|
||||
--------
|
||||
^^^^^^^^
|
||||
|
||||
a pointer to an object.
|
||||
|
||||
+-----+
|
||||
*--->| |
|
||||
+-----+
|
||||
|
|
@ -58,7 +60,7 @@ an invalid pointer, this is a pointer that should not be used.
|
|||
|
||||
|
||||
elements
|
||||
--------
|
||||
^^^^^^^^
|
||||
|
||||
+----------+
|
||||
| name |
|
||||
|
|
@ -66,16 +68,10 @@ elements
|
|||
+----------+
|
||||
|
||||
pad links
|
||||
---------
|
||||
^^^^^^^^^
|
||||
|
||||
-----+ +---
|
||||
| |
|
||||
src--sink
|
||||
-----+ +---
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -11,3 +11,4 @@ following features of gstreamer:
|
|||
- pad blocking (part-block.txt)
|
||||
- playback segments.
|
||||
- streaming vs application threads.
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ Sinks are harder to construct than other element types as they are
|
|||
treated specially by the GStreamer core.
|
||||
|
||||
state changes
|
||||
-------------
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
A sink always returns ASYNC from the state change to PAUSED, this
|
||||
includes a state change from READY->PAUSED and PLAYING->PAUSED. The
|
||||
|
|
@ -29,7 +29,7 @@ and take no part in the preroll procedure.
|
|||
Events other than EOS do not complete the preroll stage.
|
||||
|
||||
sink overview
|
||||
-------------
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
- TODO: PREROLL_LOCK can be removed and we can safely use the STREAM_LOCK.
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ Typical source elements include:
|
|||
|
||||
|
||||
Live sources
|
||||
------------
|
||||
~~~~~~~~~~~~
|
||||
|
||||
A source is said to be a live source when it has the following property:
|
||||
|
||||
|
|
@ -52,7 +52,7 @@ Let's look at some example sources.
|
|||
|
||||
|
||||
Source types
|
||||
------------
|
||||
~~~~~~~~~~~~
|
||||
|
||||
A source element can operate in three ways:
|
||||
|
||||
|
|
@ -90,7 +90,7 @@ source's state change function is called.
|
|||
|
||||
|
||||
Source base classes
|
||||
-------------------
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
GstBaseSrc:
|
||||
|
||||
|
|
@ -119,7 +119,7 @@ GstPushSrc:
|
|||
|
||||
|
||||
Timestamps
|
||||
----------
|
||||
~~~~~~~~~~
|
||||
|
||||
A non-live source should timestamp the buffers it produces starting from 0. If
|
||||
it is not possible to timestamp every buffer (filesrc), the source is allowed to
|
||||
|
|
@ -134,3 +134,4 @@ the pipeline, which is expressed as:
|
|||
With absolute_time the time obtained from the global pipeline with
|
||||
gst_clock_get_time() and base_time being the time of that clock when the
|
||||
pipeline was last set to PLAYING.
|
||||
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ each of the above use cases. We focus mostly on the buffer allocation strategies
|
|||
and caps negotiation.
|
||||
|
||||
Processing
|
||||
----------
|
||||
~~~~~~~~~~
|
||||
|
||||
A transform has 2 main processing functions:
|
||||
|
||||
|
|
@ -94,7 +94,7 @@ When no functions are provided, we can only process in passthrough mode.
|
|||
|
||||
|
||||
Negotiation
|
||||
-----------
|
||||
~~~~~~~~~~~
|
||||
|
||||
Typical (re)negotiation of the transform element in push mode always goes from
|
||||
sink to src, this means triggers the following sequence:
|
||||
|
|
@ -426,7 +426,7 @@ Negotiation
|
|||
|
||||
|
||||
Issues
|
||||
------
|
||||
~~~~~~
|
||||
|
||||
passthrough and in-place transforms (with writable buffers) never need to
|
||||
perform a pad-alloc on the srcpad. This means that if upstream negotiation
|
||||
|
|
@ -454,7 +454,7 @@ Issues
|
|||
|
||||
|
||||
Use cases
|
||||
---------
|
||||
~~~~~~~~~
|
||||
|
||||
videotestsrc ! ximagesink
|
||||
|
||||
|
|
@ -478,7 +478,8 @@ Use cases
|
|||
- resizing the videosink makes videoscale perform the scaling.
|
||||
|
||||
Problematic
|
||||
-----------
|
||||
~~~~~~~~~~~
|
||||
|
||||
filesrc location=~/media/moveyourfeet.mov ! decodebin !
|
||||
ffmpegcolorspace ! videoscale ! ffmpegcolorspace ! ximagesink -v
|
||||
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ Different types of events exist to implement various functionalities.
|
|||
in DVD.
|
||||
|
||||
FLUSH_START/STOP
|
||||
----------------
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
A flush event is sent both downstream and upstream to clear any pending data
|
||||
from the pipeline. This might be needed to make the graph more responsive
|
||||
|
|
@ -65,7 +65,7 @@ base_time (see part-clocks.txt and part-synchronisation.txt).
|
|||
|
||||
|
||||
EOS
|
||||
---
|
||||
~~~
|
||||
|
||||
The EOS event can only be sent on a sinkpad. It is typically emited by the
|
||||
source element when it has finished sending data. This event is mainly sent
|
||||
|
|
@ -107,7 +107,7 @@ A FLUSH_STOP event on an element flushes the EOS state and all pending EOS messa
|
|||
|
||||
|
||||
NEWSEGMENT
|
||||
-------------
|
||||
~~~~~~~~~~
|
||||
|
||||
A newsegment event is sent downstream by an element to indicate that the following
|
||||
group of buffers start and end at the specified positions. The newsegment event
|
||||
|
|
@ -146,7 +146,7 @@ make the buffer timestamps increasing (part-segments.txt).
|
|||
|
||||
|
||||
TAG
|
||||
---
|
||||
~~~
|
||||
|
||||
The tag event is sent downstream when an element has discovered metadata
|
||||
tags in a media file. Encoders can use this event to adjust their tagging
|
||||
|
|
@ -154,15 +154,17 @@ system. A tag is serialized with buffers.
|
|||
|
||||
|
||||
BUFFERSIZE
|
||||
----------
|
||||
~~~~~~~~~~
|
||||
|
||||
NOTE: This event is not yet implemented.
|
||||
|
||||
An element can suggest a buffersize for downstream elements. This is
|
||||
typically done by elements that produce data on multiple source pads
|
||||
such as demuxers. This event is currently not yet defined nor used.
|
||||
such as demuxers.
|
||||
|
||||
|
||||
QOS
|
||||
---
|
||||
~~~
|
||||
|
||||
A QOS, or quality of service message, is generated in an element to report
|
||||
to the upstream elements about the current quality of real-time performance
|
||||
|
|
@ -171,7 +173,7 @@ of framedrops they have. (see part-qos.txt)
|
|||
|
||||
|
||||
SEEK
|
||||
----
|
||||
~~~~
|
||||
|
||||
A seek event is issued by the application to configure the playback range
|
||||
of a stream. It is called form the application thread and travels upstream.
|
||||
|
|
@ -227,7 +229,7 @@ part-seeking.txt.
|
|||
|
||||
|
||||
NAVIGATION
|
||||
----------
|
||||
~~~~~~~~~~~
|
||||
|
||||
A navigation event is generated by a sink element to signal the elements
|
||||
of a navigation event such as a mouse movement or button click.
|
||||
|
|
@ -235,7 +237,7 @@ Navigation events travel upstream.
|
|||
|
||||
|
||||
LATENCY
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
A latency event is used to configure a certain latency in the pipeline. It
|
||||
contains a single GstClockTime with the required latency. The latency value is
|
||||
|
|
@ -246,9 +248,9 @@ timestamps of the buffer in order to delay their presentation.
|
|||
|
||||
|
||||
DRAIN
|
||||
-----
|
||||
~~~~~
|
||||
|
||||
This event is not yet implemented.
|
||||
NOTE: This event is not yet implemented.
|
||||
|
||||
Drain event indicates that upstream is about to perform a real-time event, such
|
||||
as pausing to present an interactive menu or such, and needs to wait for all
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ segments of data in PLAYING.
|
|||
|
||||
|
||||
Use Cases
|
||||
---------
|
||||
~~~~~~~~~
|
||||
|
||||
* frame stepping in video only pipeline in PAUSED
|
||||
|
||||
|
|
@ -92,7 +92,7 @@ Use Cases
|
|||
|
||||
|
||||
events
|
||||
------
|
||||
~~~~~~
|
||||
|
||||
A new GST_EVENT_STEP event is introduced to start the step operation.
|
||||
The step event is created with the following fields in the structure:
|
||||
|
|
@ -166,7 +166,7 @@ events
|
|||
|
||||
|
||||
messages
|
||||
--------
|
||||
~~~~~~~~
|
||||
|
||||
A GST_MESSAGE_STEP_START is created. It contains the following fields.
|
||||
|
||||
|
|
@ -232,7 +232,7 @@ messages
|
|||
|
||||
|
||||
Direction switch
|
||||
----------------
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
When quickly switching between a forwards and a backwards step of, for example,
|
||||
one video frame, we need either:
|
||||
|
|
@ -246,4 +246,3 @@ Direction switch
|
|||
It's unclear how this could work in a generic way. What is a demuxer supposed
|
||||
to do when it received a step event? a flushing seek to what stream position?
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ GstElement. A GstBin provides a GstBus for the children and collates messages
|
|||
from them.
|
||||
|
||||
Add/removing elements
|
||||
---------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The basic functionality of a bin is to add and remove GstElements to/from it.
|
||||
gst_bin_add() and gst_bin_remove() perform these operations respectively.
|
||||
|
|
@ -17,7 +17,7 @@ relations.txt).
|
|||
|
||||
|
||||
Retrieving elements
|
||||
-------------------
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
GstBin provides a number of functions to retrieve one or more children from
|
||||
itself. A few examples of the provided functions:
|
||||
|
|
@ -28,7 +28,7 @@ gst_bin_iterate_elements() returns an iterator to all the children.
|
|||
|
||||
|
||||
element management
|
||||
------------------
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The most important function of the GstBin is to distribute all GstElement
|
||||
operations on itself to all of its children. This includes:
|
||||
|
|
@ -41,7 +41,7 @@ The state change distribution is the most complex and is explained in
|
|||
part-states.txt.
|
||||
|
||||
GstBus
|
||||
------
|
||||
~~~~~~
|
||||
|
||||
The GstBin creates a GstBus for its children and distributes it when child
|
||||
elements are added to the bin. The bin attaches a sync handler to receive
|
||||
|
|
@ -63,7 +63,7 @@ When a bin goes to READY it will clear all cached messages.
|
|||
|
||||
|
||||
EOS
|
||||
---
|
||||
~~~
|
||||
|
||||
The sink elements will post an EOS message on the bus when they reach EOS. The
|
||||
EOS message is only posted to the bus when the sink element is in PLAYING.
|
||||
|
|
@ -77,7 +77,7 @@ to PLAYING again.
|
|||
|
||||
|
||||
SEGMENT_START/DONE
|
||||
------------------
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A bin collects SEGMENT_START messages but does not post them to the application.
|
||||
It counts the number of SEGMENT_START messages and posts a SEGMENT_STOP message
|
||||
|
|
@ -87,7 +87,7 @@ The cached SEGMENT_START/STOP messages are cleared when going to READY.
|
|||
|
||||
|
||||
DURATION
|
||||
--------
|
||||
~~~~~~~~
|
||||
|
||||
When a DURATION query is performed on a bin, it will forward the query to all
|
||||
its sink elements. The bin will calculate the total duration as the MAX of all
|
||||
|
|
@ -103,7 +103,7 @@ posted to the application, which can then fetch the updated DURATION.
|
|||
|
||||
|
||||
Subclassing
|
||||
-----------
|
||||
~~~~~~~~~~~
|
||||
|
||||
Subclasses of GstBin are free to implement their own add/remove implementations.
|
||||
It is a good idea to update the GList of children so that the _iterate() functions
|
||||
|
|
|
|||
|
|
@ -38,3 +38,4 @@ to flushing, ie. the bus will drop all existing and new messages on the bus,
|
|||
This is necessary because bus messages hold references to the bin/pipeline
|
||||
or its elements, so there are circular references that need to be broken if
|
||||
one ever wants to be able to destroy a bin or pipeline properly.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,14 +1,5 @@
|
|||
gstelement
|
||||
name
|
||||
pads
|
||||
state
|
||||
loopfunction
|
||||
threadstate
|
||||
manager
|
||||
ghostpads
|
||||
|
||||
GstElement
|
||||
==========
|
||||
----------
|
||||
|
||||
The Element is the most important object in the entire GStreamer system, as it
|
||||
defines the structure of the pipeline. Elements include sources, filters,
|
||||
|
|
@ -26,7 +17,7 @@ Element. This allows deeply nested pipelines, and the possibility of
|
|||
"black-box" meta-elements.
|
||||
|
||||
Name
|
||||
----
|
||||
~~~~
|
||||
|
||||
All elements are named, and while they should ideally be unique in any given
|
||||
pipeline, they do not have to be. The only guaranteed unique name for an
|
||||
|
|
@ -39,7 +30,7 @@ or name of an element is changed.
|
|||
|
||||
|
||||
Pads
|
||||
----
|
||||
~~~~
|
||||
|
||||
GstPads are the property of a given GstElement. They provide the connection
|
||||
capability, with allowing arbitrary structure in the graph. For any Element
|
||||
|
|
@ -67,10 +58,12 @@ pad = gst_element_get_pad(element,"padname"):
|
|||
|
||||
|
||||
Ghost Pads
|
||||
----------
|
||||
~~~~~~~~~~
|
||||
|
||||
More info in part-gstghostpad.txt.
|
||||
|
||||
State
|
||||
-----
|
||||
~~~~~
|
||||
|
||||
An element has a state. More info in part-states.txt.
|
||||
|
||||
|
|
|
|||
|
|
@ -346,12 +346,11 @@ Ghostpads
|
|||
|
||||
|
||||
Activation
|
||||
==========
|
||||
~~~~~~~~~~
|
||||
|
||||
Sometimes ghost pads should proxy activation functions. This thingie
|
||||
attempts to explain how it should work in the different cases.
|
||||
|
||||
|
||||
+---+ +----+ +----+ +----+
|
||||
| A +-----+ B | | C |-------+ D |
|
||||
+---+ +---=+ +=---+ +----+
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
GstObject
|
||||
=========
|
||||
---------
|
||||
|
||||
The base class for the entire GStreamer hierarchy is the GstObject.
|
||||
|
||||
Parentage
|
||||
---------
|
||||
~~~~~~~~~
|
||||
|
||||
A pointer is available to store the current parent of the object. This is one
|
||||
of the two fundamental requirements for a hierarchical system such as GStreamer
|
||||
|
|
@ -20,7 +20,8 @@ allows for new additions later.
|
|||
|
||||
|
||||
Naming
|
||||
------
|
||||
~~~~~~
|
||||
|
||||
- names of objects cannot be changed when they are parented
|
||||
- names of objects should be unique across parent
|
||||
- set_name() can fail because of this
|
||||
|
|
@ -36,7 +37,7 @@ Naming
|
|||
|
||||
|
||||
Locking
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
The GstObject contains the necessary primitives to lock the object in a
|
||||
thread-safe manner. This will be used to provide general thread-safety as
|
||||
|
|
@ -62,7 +63,7 @@ GstObject.
|
|||
|
||||
|
||||
Locking order
|
||||
-------------
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
In parent-child situations the lock of the parent must always be taken first
|
||||
before taking the lock of the child. It is NOT allowed to hold the child
|
||||
|
|
@ -76,7 +77,7 @@ parent-child relation (eg. pads), an explictic locking order has to be defined.
|
|||
|
||||
|
||||
Path Generation
|
||||
---------------
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Due to the base nature of the GstObject, it becomes the only reasonable place
|
||||
to put this particular function (_get_path_string). It will generate a string
|
||||
|
|
@ -84,7 +85,7 @@ describing the parent hierarchy of a given GstObject.
|
|||
|
||||
|
||||
Flags
|
||||
-----
|
||||
~~~~~
|
||||
|
||||
Each object in the GStreamer object hierarchy can have flags associated with it,
|
||||
which are used to describe a state or a feature of the object.
|
||||
|
|
@ -92,7 +93,7 @@ GstObject has flags to mark its lifecycle: FLOATING and DISPOSING.
|
|||
|
||||
|
||||
Class signals
|
||||
-------------
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
It is possible to know when a new object is loaded by connecting to the
|
||||
GstObjectClass signal. This feature is not very much used and might be removed
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ The pipeline will calculate a global latency for the elements in the pipeline.
|
|||
(See also part-latency.txt).
|
||||
|
||||
State changes
|
||||
-------------
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
In addition to the normal state change procedure of its parent class
|
||||
GstBin, the pipeline performs the following actions during a state change:
|
||||
|
|
@ -43,7 +43,7 @@ The running_time is set to 0 after a flushing seek.
|
|||
|
||||
|
||||
Clock selection
|
||||
---------------
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Since all of the children of a GstPipeline must use the same clock, the
|
||||
pipeline must select a clock. This clock selection happens when the pipeline
|
||||
|
|
@ -80,7 +80,7 @@ matic clock selection algorithm described above.
|
|||
|
||||
|
||||
GstBus
|
||||
------
|
||||
~~~~~~
|
||||
|
||||
A GstPipeline provides a GstBus to the application. The bus can be retrieved
|
||||
with gst_pipeline_get_bus() and can then be used to retrieve messages posted by
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ application needs (required minimal latency).
|
|||
|
||||
|
||||
Pipelines without latency compensation
|
||||
--------------------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
We show some examples to demonstrate the problem of latency in typical
|
||||
capture pipelines.
|
||||
|
|
@ -196,7 +196,7 @@ capture pipelines.
|
|||
|
||||
|
||||
State Changes revised
|
||||
---------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
As a first step in a generic solution we propose to modify the state changes so
|
||||
that no sink is set to PLAYING before it is prerolled.
|
||||
|
|
@ -229,7 +229,7 @@ implications:
|
|||
|
||||
|
||||
Latency compensation
|
||||
--------------------
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
As an extension to the revised state changes we can perform latency calculation
|
||||
and compensation before we proceed to the PLAYING state.
|
||||
|
|
@ -277,7 +277,7 @@ the same for all sinks, all sinks will render data relatively synchronised.
|
|||
|
||||
|
||||
Flushing a playing pipeline
|
||||
---------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Using the new state change mechanism we can implement resynchronisation after an
|
||||
uncontrolled FLUSH in (part of) a pipeline. Indeed, when a flush is performed on
|
||||
|
|
@ -306,7 +306,7 @@ to perform additional latency calculations and adjustments before doing this.
|
|||
|
||||
|
||||
Dynamically adjusting latency
|
||||
-----------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
An element that want to change the latency in the pipeline can do this by
|
||||
posting a LATENCY message on the bus. This message instructs the pipeline to:
|
||||
|
|
|
|||
|
|
@ -28,14 +28,14 @@ a blocking wait.
|
|||
|
||||
|
||||
Scheduling
|
||||
----------
|
||||
~~~~~~~~~~
|
||||
|
||||
Live sources will not produce data in the paused state. They block in the
|
||||
getrange function or in the loop function until they go to PLAYING.
|
||||
|
||||
|
||||
Latency
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
The live source timestamps its data with the time of the clock at the
|
||||
time the data was captured. Normally it will take some time to capture
|
||||
|
|
@ -49,7 +49,7 @@ See part-latency.txt.
|
|||
|
||||
|
||||
Timestamps
|
||||
----------
|
||||
~~~~~~~~~~
|
||||
|
||||
Live sources always timestamp their buffers with the running_time of the
|
||||
pipeline. This is needed to be able to match the timestamps of different live
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ application using the GstBus (See also part-gstbus.txt and part-gstpipeline.txt)
|
|||
|
||||
|
||||
Message types
|
||||
-------------
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
GST_MESSAGE_EOS:
|
||||
|
||||
|
|
@ -133,3 +133,4 @@ Message types
|
|||
Posted by elements when they want to change the state of the pipeline they
|
||||
are in. A typical use case would be an audio sink that requests the pipeline
|
||||
to pause in order to play a higher priority stream.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
What to do when a plugin is missing
|
||||
===================================
|
||||
-----------------------------------
|
||||
|
||||
The mechanism and API described in this document requires GStreamer core and
|
||||
gst-plugins-base versions >= 0.10.12. Further information on some aspects of
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ themselves to different mechanisms to achieve this goal. As it is more
|
|||
common we describe push mode negotiation first.
|
||||
|
||||
Push-mode negotiation
|
||||
---------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Push-mode negotiation happens when elements want to push buffers and
|
||||
need to decide on the format. This is called downstream negotiation
|
||||
|
|
@ -168,10 +168,10 @@ videotestsrc ! queue ! xvimagesink
|
|||
|
||||
|
||||
Pull-mode negotiation
|
||||
---------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Rationale
|
||||
.........
|
||||
^^^^^^^^^
|
||||
|
||||
A pipeline in pull mode has different negotiation needs than one
|
||||
activated in push mode. Push mode is optimized for two use cases:
|
||||
|
|
@ -237,7 +237,7 @@ but before the sink has spawned the pulling thread.
|
|||
|
||||
|
||||
Mechanism
|
||||
.........
|
||||
^^^^^^^^^
|
||||
|
||||
The sink determines that the upstream elements support pull based scheduling by
|
||||
calling gst_pad_check_pull_range().
|
||||
|
|
@ -276,3 +276,4 @@ GST_FLOW_NOT_NEGOTIATED. Because of the low-latency requirements,
|
|||
changing caps in an activate pull-mode pipeline is not supported, as it
|
||||
might require e.g. the sound card to reconfigure its hardware buffers,
|
||||
and start capsnego again.
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ Overview
|
|||
|
||||
|
||||
Introduction
|
||||
------------
|
||||
~~~~~~~~~~~~
|
||||
|
||||
GStreamer is a set of libraries and plugins that can be used to implement various
|
||||
multimedia applications ranging from desktop players, audio/video recorders,
|
||||
|
|
@ -64,7 +64,7 @@ Introduction
|
|||
|
||||
|
||||
Design overview
|
||||
---------------
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
GStreamer design goals include:
|
||||
|
||||
|
|
@ -82,7 +82,7 @@ Design overview
|
|||
|
||||
|
||||
Elements
|
||||
--------
|
||||
~~~~~~~~
|
||||
|
||||
The smallest building blocks in a pipeline are elements. An element provides a
|
||||
number of pads which can be source or sinkpads. Sourcepads provide data and
|
||||
|
|
@ -133,7 +133,7 @@ Elements
|
|||
|
||||
|
||||
Bins
|
||||
----
|
||||
~~~~
|
||||
|
||||
A bin is an element subclass and acts as a container for other elements so that multiple
|
||||
elements can be combined into one element.
|
||||
|
|
@ -157,7 +157,7 @@ Bins
|
|||
|
||||
|
||||
Pipeline
|
||||
--------
|
||||
~~~~~~~~
|
||||
|
||||
A pipeline is a special bin subclass that provides the following features to its
|
||||
children:
|
||||
|
|
@ -175,7 +175,7 @@ Pipeline
|
|||
|
||||
|
||||
Dataflow and buffers
|
||||
--------------------
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
GStreamer supports two possible types of dataflow, the push and pull model. In the
|
||||
push model, an upstream element sends data to a downstream element by calling a
|
||||
|
|
@ -231,7 +231,7 @@ Dataflow and buffers
|
|||
|
||||
|
||||
Caps
|
||||
----
|
||||
~~~~
|
||||
|
||||
A media type (Caps) is described using a generic list of key/value pairs. The key is
|
||||
a string and the value can be a single/list/range of int/float/string.
|
||||
|
|
@ -244,7 +244,7 @@ Caps
|
|||
|
||||
|
||||
Dataflow and events
|
||||
-------------------
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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.
|
||||
|
|
@ -263,7 +263,7 @@ Dataflow and events
|
|||
|
||||
|
||||
Pipeline construction
|
||||
---------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The application starts by creating a Pipeline element using gst_pipeline_new ().
|
||||
Elements are added to and removed from the pipeline with gst_bin_add() and
|
||||
|
|
@ -293,7 +293,7 @@ Pipeline construction
|
|||
|
||||
|
||||
Pipeline clock
|
||||
--------------
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
One of the important functions of the pipeline is to select a global clock
|
||||
for all the elements in the pipeline.
|
||||
|
|
@ -319,7 +319,7 @@ Pipeline clock
|
|||
|
||||
|
||||
Pipeline states
|
||||
---------------
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
When all the pads are linked and signals have been connected, the pipeline can
|
||||
be put in the PAUSED state to start dataflow.
|
||||
|
|
@ -377,7 +377,7 @@ Pipeline states
|
|||
|
||||
|
||||
Pipeline status
|
||||
---------------
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The pipeline informs the application of any special events that occur in the
|
||||
pipeline with the bus. The bus is an object that the pipeline provides and that
|
||||
|
|
@ -401,7 +401,7 @@ Pipeline status
|
|||
|
||||
|
||||
Pipeline EOS
|
||||
------------
|
||||
~~~~~~~~~~~~
|
||||
|
||||
When the source filter encounters the end of the stream, it sends an EOS event to
|
||||
the peer element. This event will then travel downstream to all of the connected
|
||||
|
|
@ -423,7 +423,7 @@ Pipeline EOS
|
|||
|
||||
|
||||
Pipeline READY
|
||||
--------------
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
When a running pipeline is set from the PLAYING to READY state, the following
|
||||
actions occur in the pipeline:
|
||||
|
|
@ -462,7 +462,7 @@ Pipeline READY
|
|||
|
||||
|
||||
Pipeline seeking
|
||||
----------------
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Seeking in the pipeline requires a very specific order of operations to make
|
||||
sure that the elements remain synchronized and that the seek is performed with
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ sinks (see part-element-sink.txt)
|
|||
|
||||
|
||||
Committing the state
|
||||
--------------------
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When going to PAUSED and PLAYING a buffer should be queued in the pad. We also
|
||||
make this requirement for going to PLAYING since a flush event in the PAUSED
|
||||
|
|
@ -39,7 +39,7 @@ blocking wait.
|
|||
|
||||
|
||||
Unlocking the preroll
|
||||
---------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The following conditions unlock the preroll:
|
||||
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ srcpads implementing a getrange function will be the exception.
|
|||
|
||||
|
||||
state changes
|
||||
-------------
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
The GstBin sets the state of all the sink elements. These are the elements
|
||||
without source pads.
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ made:
|
|||
|
||||
|
||||
Sources of quality problems
|
||||
---------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- High CPU load
|
||||
- Network problems
|
||||
|
|
@ -26,7 +26,7 @@ Sources of quality problems
|
|||
|
||||
|
||||
QoS event
|
||||
---------
|
||||
~~~~~~~~~
|
||||
|
||||
The QoS event is generated by an element that synchronizes against the clock. It
|
||||
travels upstream and contains the following fields:
|
||||
|
|
@ -51,7 +51,7 @@ operations.
|
|||
|
||||
|
||||
QoS message
|
||||
-----------
|
||||
~~~~~~~~~~~
|
||||
|
||||
A QOS message is posted on the bus whenever an element decides to:
|
||||
|
||||
|
|
@ -122,7 +122,7 @@ relevant elements or baseclasses.
|
|||
|
||||
|
||||
Collecting statistics
|
||||
---------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A buffer with timestamp B1 arrives in the sink at time T1. The buffer
|
||||
timestamp is then synchronized against the clock which yields a jitter J1
|
||||
|
|
@ -179,7 +179,7 @@ An element that is not receiving enough data is said to be starved.
|
|||
|
||||
|
||||
Element measurements
|
||||
--------------------
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In addition to the measurements of the datarate of the upstream element, a
|
||||
typical element must also measure its own performance. Global pipeline
|
||||
|
|
@ -389,3 +389,4 @@ Live sources will automatically drop data when it takes too long to process the
|
|||
that the element pushes out.
|
||||
|
||||
Live sources should post a QoS message when data is dropped.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,16 @@
|
|||
DRAFT Query
|
||||
-----------
|
||||
Query
|
||||
-----
|
||||
|
||||
NOTE: this is implemented as proposed
|
||||
|
||||
Purpose
|
||||
~~~~~~~
|
||||
|
||||
Queries are used to get information about the stream.
|
||||
A query is started on a specific pad and travels up or downstream.
|
||||
|
||||
Types of queries
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
- get length of stream
|
||||
- get position in stream
|
||||
|
|
@ -17,6 +21,7 @@ Types of queries
|
|||
- query internal links.
|
||||
|
||||
Current implementation
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The current implementation of query requires pads to implement the
|
||||
following functions:
|
||||
|
|
@ -36,12 +41,14 @@ Current implementation
|
|||
|
||||
|
||||
Requirements
|
||||
~~~~~~~~~~~~
|
||||
|
||||
- multiple return values, grouped together when they make sense.
|
||||
- one pad function to perform the query
|
||||
- extensible queries.
|
||||
|
||||
Proposition
|
||||
~~~~~~~~~~~
|
||||
|
||||
- define GstQuery extending GstMiniObject and containing a GstStructure (see GstMessage)
|
||||
- define standard query types (see proposed types)
|
||||
|
|
@ -54,6 +61,7 @@ Proposition
|
|||
query is not supported.
|
||||
|
||||
Proposed types
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
- GST_QUERY_SEEKING:
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,8 @@ This document describes the relations between objects that exist in GStreamer.
|
|||
It will also describe the way of handling the relation wrt locking and
|
||||
refcounting.
|
||||
|
||||
1) parent-child relation
|
||||
parent-child relation
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
+---------+ +-------+
|
||||
| parent | | child |
|
||||
|
|
@ -136,7 +137,7 @@ refcounting.
|
|||
disposed. To avoid the parent dispose problem, when obtaining the
|
||||
parent pointer, if should be reffed before releasing the child LOCK.
|
||||
|
||||
I) getting a reference to the parent.
|
||||
1) getting a reference to the parent.
|
||||
|
||||
- a referece is held to the child, so it cannot be disposed.
|
||||
|
||||
|
|
@ -148,7 +149,7 @@ refcounting.
|
|||
|
||||
_unref (parent);
|
||||
|
||||
II) getting a reference to a child
|
||||
2) getting a reference to a child
|
||||
|
||||
- a reference to a child can be obtained by reffing it before
|
||||
adding it to the parent or by querying the parent.
|
||||
|
|
@ -208,7 +209,8 @@ refcounting.
|
|||
_ref() the child first.
|
||||
|
||||
|
||||
2) single-reffed relation
|
||||
single-reffed relation
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
+---------+ +---------+
|
||||
*--->| object1 | *--->| object2 |
|
||||
|
|
@ -337,7 +339,8 @@ refcounting.
|
|||
+---------+ +---------+
|
||||
|
||||
|
||||
3) unreffed relation
|
||||
unreffed relation
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
+---------+ +---------+
|
||||
*--->| object1 | *--->| object2 |
|
||||
|
|
@ -461,7 +464,8 @@ refcounting.
|
|||
UNLOCK (object1);
|
||||
|
||||
|
||||
4) double-reffed relation
|
||||
double-reffed relation
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
+---------+ +---------+
|
||||
*--->| object1 | *--->| object2 |
|
||||
|
|
@ -485,7 +489,3 @@ refcounting.
|
|||
|
||||
- lifecycle
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ The scheduling in GStreamer is based on pads actively pushing (producing) data o
|
|||
pad pulling in data (consuming) from other pads.
|
||||
|
||||
Pushing
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
A pad can produce data and push it to the next pad. A pad that behaves this way
|
||||
exposes a loop function that will be called repeadedly until it returns false.
|
||||
|
|
@ -20,7 +20,7 @@ This method of producing data is called the streaming mode since the producer
|
|||
produces a constant stream of data.
|
||||
|
||||
Pulling
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
Pads that operate in pulling mode can only pull data from a pad that exposes the
|
||||
pull_range function. In this case, the sink pad exposes a loop function that will be
|
||||
|
|
@ -31,7 +31,7 @@ push function to push the result to the peer sinkpad.
|
|||
|
||||
|
||||
Deciding the scheduling mode
|
||||
----------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When tha pad is activated, the _activate() function is called. The pad can then
|
||||
choose to activate itself in push or pull mode depending on upstream
|
||||
|
|
@ -41,22 +41,22 @@ The GStreamer core will by default activate pads in push mode when there is no
|
|||
activate function for the pad.
|
||||
|
||||
The chain function
|
||||
------------------
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The chain function will be called when a upstream element perform a _push() on the pad.
|
||||
The upstream element can be another chain based element or a pushing source.
|
||||
|
||||
The getrange function
|
||||
---------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The getrange function is called when a peer pad perform a _pull_range() on the pad. This
|
||||
downstream pad can be a pulling element or another _pull_range() based element.
|
||||
|
||||
Plug-in techniques
|
||||
------------------
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Multi-sink elements
|
||||
-------------------
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Elements with multiple sinks can either expose a loop function on each of the pads to
|
||||
actively pull_range data or they can expose a chain function on each pad.
|
||||
|
|
@ -108,7 +108,8 @@ Multi-sink elements
|
|||
|
||||
|
||||
Cases
|
||||
-----
|
||||
~~~~~
|
||||
|
||||
Inside the braces below the pads is stated what function the
|
||||
pad support:
|
||||
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ more important than accurately producing all frames.
|
|||
|
||||
|
||||
Seeking in push based elements
|
||||
------------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
|
||||
|
|
@ -66,19 +66,21 @@ Seeking in push based elements
|
|||
|
||||
|
||||
Generating seeking events
|
||||
-------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A seek event is created with gst_event_new_seek ().
|
||||
|
||||
|
||||
|
||||
Seeking variants
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
The different kinds of seeking methods and their internal workings are
|
||||
described below.
|
||||
|
||||
|
||||
FLUSH seeking
|
||||
-------------
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
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
|
||||
|
|
@ -86,7 +88,7 @@ played after the seek calls returns.
|
|||
|
||||
|
||||
seeking without FLUSH
|
||||
---------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This seek type is typically performed after issuing segment seeks to finish
|
||||
the playback of the pipeline.
|
||||
|
|
@ -97,13 +99,13 @@ sinks.
|
|||
|
||||
|
||||
segment seeking with FLUSH
|
||||
--------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This seek is typically performed when starting seamless looping.
|
||||
|
||||
|
||||
segment seeking without FLUSH
|
||||
-----------------------------
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This seek is typically performed when continuing seamless looping.
|
||||
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ outside of the segment and that might therefore be discarded or clipped.
|
|||
|
||||
|
||||
Use case: FLUSHING seek
|
||||
-----------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
ex.
|
||||
|
||||
|
|
@ -95,13 +95,13 @@ Use case: FLUSHING seek
|
|||
|
||||
|
||||
Use case: live stream
|
||||
---------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
|
||||
|
||||
Use case: segment looping
|
||||
-------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Consider the case of a wav file with raw audio.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,8 @@ DRAFT Sparse Streams
|
|||
--------------------
|
||||
|
||||
Introduction
|
||||
------------
|
||||
~~~~~~~~~~~~
|
||||
|
||||
In 0.8, there was some support for Sparse Streams through the use of
|
||||
FILLER events. These were used to mark gaps between buffers so that downstream
|
||||
elements could know not to expect any more data for that gap.
|
||||
|
|
@ -11,7 +12,8 @@ In 0.10, segment information conveyed through NEWSEGMENT events can be used
|
|||
for the same purpose.
|
||||
|
||||
Use cases
|
||||
---------
|
||||
~~~~~~~~~
|
||||
|
||||
1) Sub-title streams
|
||||
Sub-title information from muxed formats such as Matroska or MPEG consist of
|
||||
irregular buffers spaced far apart compared to the other streams
|
||||
|
|
@ -37,7 +39,8 @@ Use cases
|
|||
application that uses noise-gating (to save bandwith).
|
||||
|
||||
Details
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
1) Sub-title streams
|
||||
The main requirement here is to avoid stalling the pipeline between sub-title
|
||||
packets, and is effectively updating the minimum-timestamp for that stream.
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ collection has many potential pitfalls as far as the pointers go. Therefore,
|
|||
some standards must be adhered to as far as who owns what.
|
||||
|
||||
Strings
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
Arguments passed into a function are owned by the caller, and the function
|
||||
will make a copy of the string for its own internal use. The string should
|
||||
|
|
@ -21,7 +21,7 @@ original and should be freed after usage by the caller.
|
|||
|
||||
|
||||
Objects
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
Objects passed into a function are owned by the caller, any additional
|
||||
reference held to the object after leaving the function should increase the
|
||||
|
|
@ -40,7 +40,7 @@ called should _free() or _unref() the object after usage.
|
|||
|
||||
|
||||
Iterators
|
||||
---------
|
||||
~~~~~~~~~
|
||||
|
||||
When retrieving multiple objects from an object an iterator should be used.
|
||||
The iterator allows you to access the objects one after another while making
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
States
|
||||
======
|
||||
------
|
||||
|
||||
Both elements and pads can be in different states. The states of the pads are
|
||||
linked to the state of the element so the design of the states is mainly
|
||||
|
|
@ -10,7 +10,7 @@ is initially instantiated, it is in the NULL state.
|
|||
|
||||
|
||||
State definitions
|
||||
-----------------
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
- NULL: This is the initial state of an element.
|
||||
- READY: The element should be prepared to go to PAUSED.
|
||||
|
|
@ -24,7 +24,7 @@ a downwards state change.
|
|||
|
||||
|
||||
State transitions
|
||||
-----------------
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
the following state changes are possible:
|
||||
|
||||
|
|
@ -89,7 +89,7 @@ the following state changes are possible:
|
|||
|
||||
|
||||
State variables
|
||||
---------------
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
An element has 4 state variables that are protected with the object LOCK:
|
||||
|
||||
|
|
@ -111,7 +111,7 @@ _set_state(), called the STATE_LOCK.
|
|||
|
||||
|
||||
Setting state on elements
|
||||
-------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The state of an element can be changed with _element_set_state(). When chaning
|
||||
the state of an element all intermediate states will also be set on the element
|
||||
|
|
@ -147,7 +147,7 @@ is immediatly returned to the caller.
|
|||
|
||||
|
||||
Getting state of elements
|
||||
-------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The _get_state() function takes 3 arguments, two pointers that will hold the
|
||||
current and pending state and one GstClockTime that holds a timeout value. The
|
||||
|
|
@ -184,7 +184,7 @@ function returns a GstElementStateReturn.
|
|||
|
||||
|
||||
States in GstBin
|
||||
----------------
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
A GstBin manages the state of its children. It does this by propagating the state
|
||||
changes performed on it to all of its children. The _set_state() function on a
|
||||
|
|
@ -221,15 +221,15 @@ current state fields when it receives state messages from the children.
|
|||
|
||||
|
||||
Implementing states in elements
|
||||
-------------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
READY
|
||||
-----
|
||||
^^^^^
|
||||
|
||||
|
||||
|
||||
upward state change
|
||||
-------------------
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Upward state changes always return ASYNC either if the STATE_PENDING is
|
||||
reached or not.
|
||||
|
|
@ -262,7 +262,7 @@ Bin:
|
|||
to STATE_PENDING
|
||||
|
||||
downward state change
|
||||
----------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Downward state changes only return ASYNC if the final state is ASYNC.
|
||||
This is to make sure that it's not needed to wait for an element to
|
||||
|
|
@ -296,7 +296,7 @@ Bin:
|
|||
|
||||
|
||||
Locking overview (element)
|
||||
--------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* Element commiting SUCCESS
|
||||
|
||||
|
|
@ -376,8 +376,8 @@ Locking overview (element)
|
|||
| ...
|
||||
STREAM_UNLOCK
|
||||
|
||||
*********************************************
|
||||
*********************************************
|
||||
Remarks
|
||||
~~~~~~~
|
||||
|
||||
set_state cannot be called from multiple threads at the same time. The STATE_LOCK
|
||||
prevents this.
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ We allow for the following scenarios:
|
|||
|
||||
|
||||
Use cases
|
||||
---------
|
||||
~~~~~~~~~
|
||||
|
||||
* boost the priority of the udp receiver streaming thread
|
||||
|
||||
|
|
@ -56,7 +56,7 @@ Use cases
|
|||
|
||||
|
||||
Messages
|
||||
--------
|
||||
~~~~~~~~
|
||||
|
||||
The existing STREAM_STATUS message will be further defined and implemented in
|
||||
(selected) elements. The following fields will be contained in the message:
|
||||
|
|
@ -101,7 +101,7 @@ Messages
|
|||
|
||||
|
||||
Events
|
||||
------
|
||||
~~~~~~
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ Streams
|
|||
|
||||
|
||||
Stream objects
|
||||
--------------
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
The following objects are to be expected in the streaming thread:
|
||||
|
||||
|
|
@ -21,7 +21,7 @@ and live sources.
|
|||
|
||||
|
||||
Typical stream
|
||||
--------------
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
A typical stream starts with a newsegment event that marks the
|
||||
buffer timestamp range. After that buffers are send one after the
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ Synchronisation in a GstPipeline is achieved using the following 3 components:
|
|||
|
||||
|
||||
A GstClock
|
||||
----------
|
||||
~~~~~~~~~~
|
||||
|
||||
This object provides a counter that represents the current time in nanoseconds.
|
||||
This value is called the absolute_time.
|
||||
|
|
@ -33,7 +33,7 @@ A GstClock always counts time upwards and does not necessarily start at 0.
|
|||
|
||||
|
||||
Running time
|
||||
------------
|
||||
~~~~~~~~~~~~
|
||||
|
||||
After a pipeline selected a clock it will maintain the running_time based on the
|
||||
selected clock. This running_time represents the total time spent in the PLAYING
|
||||
|
|
@ -66,7 +66,7 @@ This value is monotonically increasing at the rate of the clock.
|
|||
|
||||
|
||||
Timestamps
|
||||
----------
|
||||
~~~~~~~~~~
|
||||
|
||||
The GstBuffer timestamps and the preceeding NEW_SEGMENT event (See
|
||||
part-streams.txt) define a transformation of the buffer timestamps to
|
||||
|
|
@ -112,7 +112,7 @@ NS.stop and NS.accum == 0).
|
|||
|
||||
|
||||
Synchronisation
|
||||
---------------
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
As we have seen, we can get a running_time:
|
||||
|
||||
|
|
@ -161,7 +161,7 @@ synchronized buffers have the same timestamps.
|
|||
|
||||
|
||||
Stream time
|
||||
-----------
|
||||
~~~~~~~~~~~
|
||||
|
||||
The stream time is also known as the position in the stream and is a value
|
||||
between 0 and the total duration of the media file.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
Trickmodes
|
||||
==========
|
||||
----------
|
||||
|
||||
GStreamer provides API for performing various trickmode playback. This includes:
|
||||
|
||||
|
|
@ -18,7 +18,7 @@ Seeking can both be done in a playback pipeline and a transcoding pipeline.
|
|||
|
||||
|
||||
General seeking overview
|
||||
------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Consider a typical playback pipeline:
|
||||
|
||||
|
|
@ -35,7 +35,8 @@ position 0 and stopping at the total duration of the file.
|
|||
|
||||
When performing a seek, the following steps have to be taken by the application:
|
||||
|
||||
1) Create a seek event:
|
||||
Create a seek event
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The seek event contains:
|
||||
|
||||
|
|
@ -57,7 +58,10 @@ When performing a seek, the following steps have to be taken by the application:
|
|||
See also gst_event_new_seek().
|
||||
|
||||
|
||||
2) Send the seek event to the pipeline with gst_element_send_event()
|
||||
Send the seek event
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Send the new seek event to the pipeline with gst_element_send_event().
|
||||
|
||||
By default the pipeline will send the event to all sink elements.
|
||||
By default an element will forward the event upstream on all sinkpads.
|
||||
|
|
@ -84,7 +88,7 @@ When performing a seek, the following steps have to be taken by the application:
|
|||
|
||||
|
||||
Server side trickmode
|
||||
---------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The source element operates in push mode. It can reopen a server connection requesting
|
||||
a new byte or time position and a new playback speed. The capabilities can be queried
|
||||
|
|
@ -131,7 +135,7 @@ playback speed or direction.
|
|||
|
||||
|
||||
client side forward trickmodes
|
||||
------------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The seek happens as stated above. a NEW_SEGMENT event is sent downstream with a rate
|
||||
different from 1.0. Plugins receiving the NEW_SEGMENT can decide to perform the
|
||||
|
|
@ -154,7 +158,7 @@ case, the demuxer would scale the timestamps and would set an applied rate of S.
|
|||
|
||||
|
||||
client side backwards trickmode
|
||||
-------------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For backwards playback the following rules apply:
|
||||
|
||||
|
|
@ -202,7 +206,8 @@ For plugins the following rules apply:
|
|||
In SKIP mode, the same algorithm as for forward SKIP mode can be used.
|
||||
|
||||
|
||||
Notes:
|
||||
Notes
|
||||
~~~~~
|
||||
|
||||
- The clock/running_time keeps running forward.
|
||||
- backwards playback potentially uses a lot of memory as frames and undecoded
|
||||
|
|
|
|||
Loading…
Reference in a new issue