mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-07-04 13:45:52 +00:00
Arun Raghavan
Tim-Philipp Müller
parent
5998e902a3
commit
8d1c45f513
|
|
@ -33,7 +33,7 @@
|
|||
<para>
|
||||
As clocks return an absolute measure of time, they are not usually used
|
||||
directly. Instead, a reference to a clock is stored in any element that needs
|
||||
it, and it is used internaly by GStreamer to calculate the element time.
|
||||
it, and it is used internally by GStreamer to calculate the element time.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
|
|
@ -59,7 +59,7 @@
|
|||
element will be regarded as the source element for this discussion.
|
||||
</para>
|
||||
</footnote>
|
||||
First, the source element sends a discontinous event. This event carries information
|
||||
First, the source element sends a discontinuous event. This event carries information
|
||||
about the current relative time of the next sample. This relative time is
|
||||
arbitrary, but it must be consistent with the timestamp that will be
|
||||
placed in buffers. It is expected to be the relative time to the start
|
||||
|
|
@ -71,7 +71,7 @@
|
|||
<para>
|
||||
Then the source element sends media samples in buffers. This element places a
|
||||
timestamp in each buffer saying when the sample should be played. When the
|
||||
buffer reachs the sink pad of the last element, this element compares the
|
||||
buffer reaches the sink pad of the last element, this element compares the
|
||||
current element time with the timestamp of the buffer. If the timestamp is
|
||||
higher or equal it plays the buffer, otherwise it waits until the time to
|
||||
place the buffer arrives with <function>gst_element_wait()</function>.
|
||||
|
|
@ -81,7 +81,7 @@
|
|||
<para>
|
||||
If the stream is seeked, the next samples sent will have a timestamp that
|
||||
is not adjusted with the element time. Therefore, the source element must
|
||||
send a discontinous event.
|
||||
send a discontinuous event.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="section-clock-obligations-of-each-element" xreflabel="Obligations
|
||||
|
|
@ -101,14 +101,14 @@
|
|||
Source elements (or parsers of formats that provide notion of time, such
|
||||
as MPEG, as explained above) must place a timestamp in each buffer that
|
||||
they deliver. The origin of the time used is arbitrary, but it must
|
||||
match the time delivered in the discontinous event (see below).
|
||||
match the time delivered in the discontinuous event (see below).
|
||||
However, it is expected that the origin is the origin of the media
|
||||
stream.
|
||||
</para>
|
||||
<para>
|
||||
In order to initialize the element time of the rest of the pipeline, a
|
||||
source element must send a discontinous event before starting to play.
|
||||
In addition, after seeking, a discontinious event must be sent, because
|
||||
source element must send a discontinuous event before starting to play.
|
||||
In addition, after seeking, a discontinuous event must be sent, because
|
||||
the timestamp of the next element does not match the element time of the
|
||||
rest of the pipeline.
|
||||
</para>
|
||||
|
|
|
|||
|
|
@ -6,8 +6,8 @@
|
|||
<para>
|
||||
Sometimes object properties are not powerful enough to control the
|
||||
parameters that affect the behaviour of your element.
|
||||
When this is the case you can mark these parameters as beeing Controllable.
|
||||
Aware appliations can use the controller subsystem to dynamically adjust
|
||||
When this is the case you can mark these parameters as being Controllable.
|
||||
Aware applications can use the controller subsystem to dynamically adjust
|
||||
the property values over time.
|
||||
</para>
|
||||
|
||||
|
|
@ -77,7 +77,7 @@
|
|||
<sect2 id="chapter-dparam-loop-video">
|
||||
<title>The Data Processing Loop for Video Elements</title>
|
||||
<para>
|
||||
For video processing elements it is the best to synchonise for every frame.
|
||||
For video processing elements it is the best to synchronise for every frame.
|
||||
That means one would add the <function>gst_object_sync_values()</function>
|
||||
call described in the previous section to the data processing function of
|
||||
the element.
|
||||
|
|
@ -93,7 +93,7 @@
|
|||
standard audio it will be 44100 samples.
|
||||
It is rarely useful to synchronise controllable parameters that often.
|
||||
The easiest solution is also to have just one synchronisation call per
|
||||
buffer processing. This makes the control-rate dependend on the buffer
|
||||
buffer processing. This makes the control-rate depend on the buffer
|
||||
size.
|
||||
</para>
|
||||
<para>
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@
|
|||
<sect1 id="section-iface-general" xreflabel="How to Implement Interfaces">
|
||||
<title>How to Implement Interfaces</title>
|
||||
<para>
|
||||
Implementing interfaces is intiated in the <function>_get_type ()</function>
|
||||
Implementing interfaces is initiated in the <function>_get_type ()</function>
|
||||
of your element. You can register one or more interfaces after having
|
||||
registered the type itself. Some interfaces have dependencies on other
|
||||
interfaces or can only be registered by certain types of elements. You
|
||||
|
|
@ -325,7 +325,7 @@ gst_my_filter_mixer_interface_init (GstMixerClass *iface)
|
|||
<para>
|
||||
This interface requires the <ulink type="http"
|
||||
url="../../gstreamer/html/GstImplementsInterface.html"><classname>
|
||||
GstImplemensInterface</classname></ulink>
|
||||
GstImplementsInterface</classname></ulink>
|
||||
interface to work correctly.
|
||||
</para>
|
||||
<para>
|
||||
|
|
@ -365,7 +365,7 @@ gst_my_filter_get_type (void)
|
|||
&implements_interface_info);
|
||||
g_type_add_interface_static (my_filter_type,
|
||||
GST_TYPE_TUNER,
|
||||
&tunerr_interface_info);
|
||||
&tuner_interface_info);
|
||||
[..]
|
||||
}
|
||||
|
||||
|
|
@ -477,7 +477,7 @@ gst_my_filter_tuner_interface_init (GstTunerClass *iface)
|
|||
the property to create a <classname>GValueArray</classname>, and one to
|
||||
retrieve the current <classname>GValueArray</classname>. Those two are
|
||||
separated because probing might take a long time (several seconds). Also,
|
||||
this simpliies interface implementation in elements. For the application,
|
||||
this simplifies interface implementation in elements. For the application,
|
||||
there are functions that wrap those two. For more information on this,
|
||||
have a look at the API reference for the
|
||||
<!-- FIXME: add link, but this is in ./gst-plugins/gst-libs/gst/propertyprobe/propertyprobe.c-->
|
||||
|
|
@ -624,7 +624,7 @@ gst_my_filter_probe_interface_init (GstPropertyProbeInterface *iface)
|
|||
An X Overlay is basically a video output in a XFree86 drawable. Elements
|
||||
implementing this interface will draw video in a X11 window. Through this
|
||||
interface, applications will be proposed 2 different modes to work with
|
||||
a plugin implemeting it. The first mode is a passive mode where the plugin
|
||||
a plugin implementing it. The first mode is a passive mode where the plugin
|
||||
owns, creates and destroys the X11 window. The second mode is an active
|
||||
mode where the application handles the X11 window creation and then tell
|
||||
the plugin where it should output video. Let's get a bit deeper in those
|
||||
|
|
@ -635,7 +635,7 @@ gst_my_filter_probe_interface_init (GstPropertyProbeInterface *iface)
|
|||
window at one stage or another. Passive mode simply means that no window
|
||||
has been given to the plugin before that stage, so the plugin created the
|
||||
window by itself. In that case the plugin is responsible of destroying
|
||||
that window when it's not needed anymore and it has to tell the
|
||||
that window when it's not needed any more and it has to tell the
|
||||
applications that a window has been created so that the application can
|
||||
use it. This is done using the <classname>have_xwindow_id</classname>
|
||||
signal that can be emitted from the plugin with the
|
||||
|
|
|
|||
|
|
@ -19,13 +19,13 @@
|
|||
<para>
|
||||
Let's take the case of a file source, linked to a demuxer, linked to a
|
||||
decoder, linked to a converter with a caps filter and finally an audio
|
||||
output. When dataflow originally starts, the demuxer will parse the
|
||||
output. When data flow originally starts, the demuxer will parse the
|
||||
file header (e.g. the Ogg headers), and notice that there is, for
|
||||
example, a Vorbis stream in this Ogg file. Noticing that, it will
|
||||
create an output pad for the Vorbis elementary stream and set a
|
||||
Vorbis-caps on it. Lastly, it adds the pad. As of this point, the pad
|
||||
is ready to be used to stream data, and so the Ogg demuxer is now done.
|
||||
This pad is <emphasis>not</emphasis> re-negotiatable, since the type of
|
||||
This pad is <emphasis>not</emphasis> re-negotiable, since the type of
|
||||
the data stream is embedded within the data.
|
||||
</para>
|
||||
<para>
|
||||
|
|
@ -58,13 +58,13 @@
|
|||
<para>
|
||||
In order for caps negotiation on non-fixed links to work correctly,
|
||||
pads can optionally implement a function that tells peer elements what
|
||||
formats it supports and/or preferes. When upstream renegotiation is
|
||||
formats it supports and/or prefers. When upstream renegotiation is
|
||||
triggered, this becomes important.
|
||||
</para>
|
||||
<para>
|
||||
Downstream elements are notified of a newly set caps only when data
|
||||
is actually passing their pad. This is because caps is attached to
|
||||
buffers during dataflow. So when the vorbis decoder sets a caps on
|
||||
buffers during data flow. So when the vorbis decoder sets a caps on
|
||||
its source pad (to configure the output format), the converter will
|
||||
not yet be notified. Instead, the converter will only be notified
|
||||
when the decoder pushes a buffer over its source pad to the converter.
|
||||
|
|
@ -112,7 +112,7 @@
|
|||
</programlisting>
|
||||
<para>
|
||||
Elements that could implement fixed caps (on their source pads) are,
|
||||
in general, all elements that are not renegotiatable. Examples include:
|
||||
in general, all elements that are not renegotiable. Examples include:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
|
|
@ -125,14 +125,14 @@
|
|||
<para>
|
||||
Pretty much all demuxers, since the contained elementary data
|
||||
streams are defined in the file headers, and thus not
|
||||
renegotiatable.
|
||||
renegotiable.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Some decoders, where the format is embedded in the datastream
|
||||
Some decoders, where the format is embedded in the data stream
|
||||
and not part of the peercaps <emphasis>and</emphasis> where the
|
||||
decoder itself is not reconfigureable, too.
|
||||
decoder itself is not reconfigurable, too.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
|
@ -316,7 +316,7 @@ gst_my_filter_chain (GstPad *pad,
|
|||
does not contain the information required to know the output format
|
||||
yet; rather, the data headers need to be parsed, too. In many cases,
|
||||
fixed-caps will be enough, but in some cases, particularly in cases
|
||||
where such decoders are renegotiatable, it is also possible to use
|
||||
where such decoders are renegotiable, it is also possible to use
|
||||
full caps negotiation.
|
||||
</para>
|
||||
<para>
|
||||
|
|
@ -370,7 +370,7 @@ gst_my_filter_chain (GstPad *pad,
|
|||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Elements that are renegotiatable should implement a
|
||||
Elements that are renegotiable should implement a
|
||||
<quote>setcaps</quote>-function on their sourcepad as well.
|
||||
</para>
|
||||
</listitem>
|
||||
|
|
|
|||
|
|
@ -190,7 +190,7 @@ gst_my_filter_loopfunc (GstElement *element)
|
|||
<para>
|
||||
Note that we use a lot of checks everywhere to make sure that the content
|
||||
in the file is valid. This has two purposes: first, the file could be
|
||||
erronous, in which case we prevent a crash. The second and most important
|
||||
erroneous, in which case we prevent a crash. The second and most important
|
||||
reason is that - in extreme cases - the file could be used maliciously to
|
||||
cause undefined behaviour in the plugin, which might lead to security
|
||||
issues. <emphasis>Always</emphasis> assume that the file could be used to
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@
|
|||
function will have random data access (through
|
||||
<function>gst_pad_get_range ()</function>) over all sinkpads, and
|
||||
can push data over the sourcepads, which effectively means that
|
||||
this element controls dataflow in the pipeline. Prerequisites for
|
||||
this element controls data flow in the pipeline. Prerequisites for
|
||||
this mode are that all downstream elements can act in chain-based
|
||||
mode, and that all upstream elements allow random access (see below).
|
||||
Source elements can be told to act in this mode if their sourcepads
|
||||
|
|
@ -83,7 +83,7 @@
|
|||
start a task on their own. Rather, it means that they are pull
|
||||
slave for the downstream element, and have to provide random data
|
||||
access to it from their <function>_get_range ()</function>-function.
|
||||
Requiremenents are that the a <function>_get_range
|
||||
Requirements are that the a <function>_get_range
|
||||
()</function>-function was set on this pad using the function
|
||||
<function>gst_pad_set_getrange_function ()</function>. Also, if
|
||||
the element has any sinkpads, all those pads (and thereby their
|
||||
|
|
@ -105,7 +105,7 @@
|
|||
<para>
|
||||
Sinkpads assigned to operate in pull-based mode, while none of its
|
||||
sourcepads operate in pull-based mode (or it has no sourcepads), can
|
||||
start a task that will drive the pipeline dataflow. Within this
|
||||
start a task that will drive the pipeline data flow. Within this
|
||||
function, those elements have random access over all of their sinkpads,
|
||||
and push data over their sourcepads. This can come in useful for
|
||||
several different kinds of elements:
|
||||
|
|
@ -123,7 +123,7 @@
|
|||
<listitem>
|
||||
<para>
|
||||
Certain kind of audio outputs, which require control over their
|
||||
input dataflow, such as the Jack sound server.
|
||||
input data flow, such as the Jack sound server.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@
|
|||
Examples are <quote>codec</quote> or <quote>bitrate</quote>. Note that some
|
||||
container formats (like ID3) store various streaminfo tags as metadata in
|
||||
the file container, which means that they can be changed so that they don't
|
||||
match the content in the file anymore. Still, they are called metadata
|
||||
match the content in the file any more. Still, they are called metadata
|
||||
because <emphasis>technically</emphasis>, they can be changed without
|
||||
re-encoding the whole stream, even though that makes them invalid. Files
|
||||
with such metadata tags will have the same tag twice: once as metadata,
|
||||
|
|
|
|||
|
|
@ -89,7 +89,7 @@
|
|||
In order for a random data file to be recognized and played back as
|
||||
such, we need a way of recognizing their type out of the blue. For this
|
||||
purpose, <quote>typefinding</quote> was introduced. Typefinding is the
|
||||
process of detecting the type of a datastream. Typefinding consists of
|
||||
process of detecting the type of a data stream. Typefinding consists of
|
||||
two separate parts: first, there's an unlimited number of functions
|
||||
that we call <emphasis>typefind functions</emphasis>, which are each
|
||||
able to recognize one or more types from an input stream. Then,
|
||||
|
|
@ -486,7 +486,7 @@ plugin_init (GstPlugin *plugin)
|
|||
<row>
|
||||
<entry morerows="3">audio/mpeg</entry>
|
||||
<entry morerows="3">
|
||||
Audio data compressed using the MPEG audio encoding scehem.
|
||||
Audio data compressed using the MPEG audio encoding scheme.
|
||||
</entry>
|
||||
<entry>mpegversion</entry>
|
||||
<entry>integer</entry>
|
||||
|
|
@ -1060,7 +1060,7 @@ plugin_init (GstPlugin *plugin)
|
|||
<entry>integer</entry>
|
||||
<entry>1 to 64</entry>
|
||||
<entry>
|
||||
Bitdepth of the used palette. This means that the palette
|
||||
Bit depth of the used palette. This means that the palette
|
||||
that belongs to this format defines 2^depth colors.
|
||||
</entry>
|
||||
</row>
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@
|
|||
Most functions returning an object or an object property have
|
||||
been changed to return its own reference rather than a constant
|
||||
reference of the one owned by the object itself. The reason for
|
||||
this change is primarily threadsafety. This means effectively
|
||||
this change is primarily thread-safety. This means effectively
|
||||
that return values of functions such as
|
||||
<function>gst_element_get_pad ()</function>,
|
||||
<function>gst_pad_get_name ()</function>,
|
||||
|
|
@ -123,7 +123,7 @@
|
|||
<symbol>GST_STATE_PLAYING</symbol> have changed for elements that
|
||||
are not sink elements. Non-sink elements need to be able to accept
|
||||
and process data already in the <symbol>GST_STATE_PAUSED</symbol>
|
||||
state now (ie. when prerolling the pipeline). More details can be
|
||||
state now (i.e. when prerolling the pipeline). More details can be
|
||||
found in <xref linkend="chapter-statemanage-states"/>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
|
|
|||
|
|
@ -199,7 +199,7 @@ GST_BOILERPLATE (GstMyFilter, gst_my_filter, GstElement, GST_TYPE_ELEMENT);
|
|||
</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
A long, english, name for the element.
|
||||
A long, English, name for the element.
|
||||
</para></listitem><listitem><para>
|
||||
The type of the element, see the docs/design/draft-klass.txt document
|
||||
in the GStreamer core source tree for details and examples.
|
||||
|
|
|
|||
|
|
@ -44,7 +44,7 @@ gst_my_filter_change_state (GstElement * element, GstStateChange transition)
|
|||
<para>
|
||||
Obviously, the above doesn't do much useful. Instead of printing that the
|
||||
data is in, you would normally process the data there. Remember, however,
|
||||
that buffers are not always writable. In more advanced elements (the ones
|
||||
that buffers are not always writeable. In more advanced elements (the ones
|
||||
that do event processing), you may want to additionally specify an event
|
||||
handling function, which will be called when stream-events are sent (such
|
||||
as end-of-stream, discontinuities, tags, etc.).
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@
|
|||
you have to set a <function>_setcaps ()</function> function pointer and
|
||||
optionally a <function>_getcaps ()</function> function pointer. Also, you
|
||||
have to set a <function>_chain ()</function> function pointer.
|
||||
Alternatively, pads can also operate in looping mode, which mans that they
|
||||
Alternatively, pads can also operate in looping mode, which means that they
|
||||
can pull data themselves. More on this topic later. After that, you have
|
||||
to register the pad with the element. This happens like this:
|
||||
</para>
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@ gst_my_filter_get_property (GObject *object,
|
|||
<para>
|
||||
The above is a very simple example of how arguments are used. Graphical
|
||||
applications - for example GStreamer Editor - will use these properties
|
||||
and will display a user-controlleable widget with which these properties
|
||||
and will display a user-controllable widget with which these properties
|
||||
can be changed. This means that - for the property to be as user-friendly
|
||||
as possible - you should be as exact as possible in the definition of the
|
||||
property. Not only in defining ranges in between which valid properties
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@
|
|||
calling <function>gst_init ()</function>. You can alternatively call
|
||||
<function>gst_init_with_popt_tables ()</function>, which will return
|
||||
a pointer to popt tables. You can then use libpopt to handle the
|
||||
given argument table, and this will finish the &GStreamer; intialization.
|
||||
given argument table, and this will finish the &GStreamer; initialization.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
|
@ -97,7 +97,7 @@ bus_call (GstBus *bus,
|
|||
g_error_free (err);
|
||||
|
||||
if (debug) {
|
||||
g_print ("Debug deails: %s\n", debug);
|
||||
g_print ("Debug details: %s\n", debug);
|
||||
g_free (debug);
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@
|
|||
contain so that data flows smoothly. Another type of bin, called
|
||||
<emphasis>autoplugger</emphasis> elements, automatically add other
|
||||
elements to the bin and links them together so that they act as a
|
||||
filter between two arbitary stream types.
|
||||
filter between two arbitrary stream types.
|
||||
</para>
|
||||
<para>
|
||||
The plugin mechanism is used everywhere in &GStreamer;, even if only the
|
||||
|
|
@ -165,7 +165,7 @@
|
|||
<para>
|
||||
Events
|
||||
contain information on the state of the stream flowing between the two
|
||||
linked pads. Events will only be sent if the element explicitely supports
|
||||
linked pads. Events will only be sent if the element explicitly supports
|
||||
them, else the core will (try to) handle the events automatically. Events
|
||||
are used to indicate, for example, a clock discontinuity, the end of a
|
||||
media stream or that the cache should be flushed.
|
||||
|
|
@ -215,7 +215,7 @@
|
|||
buffers created by filesrc act exactly like generic buffers, except
|
||||
that they are read-only. The buffer freeing code automatically
|
||||
determines the correct method of freeing the underlying memory.
|
||||
Downstream elements that recieve these kinds of buffers do not
|
||||
Downstream elements that receive these kinds of buffers do not
|
||||
need to do anything special to handle or unreference it.
|
||||
</para>
|
||||
<para>
|
||||
|
|
|
|||
Loading…
Reference in a new issue