Fixes #609286.
<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>
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
<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>.
<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
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>
<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>
<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.
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>
<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
<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>
&implements_interface_info);
g_type_add_interface_static (my_filter_type,
GST_TYPE_TUNER,
- &tunerr_interface_info);
+ &tuner_interface_info);
[..]
}
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-->
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
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
<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>
<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.
</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>
<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>
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>
</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>
<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
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
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
<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:
<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>
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,
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,
<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>
<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>
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>,
<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>
</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.
<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.).
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>
<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
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>
g_error_free (err);
if (debug) {
- g_print ("Debug deails: %s\n", debug);
+ g_print ("Debug details: %s\n", debug);
g_free (debug);
}
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
<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.
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>
projects / platform / upstream / gstreamer.git / commitdiff