mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-18 15:51:11 +00:00
310 lines
13 KiB
XML
310 lines
13 KiB
XML
<chapter id="chapter-other-base" xreflabel="Pre-made base classes">
|
|
<title>Pre-made base classes</title>
|
|
<para>
|
|
So far, we've been looking at low-level concepts of creating any type of
|
|
&GStreamer; element. Now, let's assume that all you want is to create an
|
|
simple audiosink that works exactly the same as, say,
|
|
<quote>esdsink</quote>, or a filter that simply normalizes audio volume.
|
|
Such elements are very general in concept and since they do nothing
|
|
special, they should be easier to code than to provide your own scheduler
|
|
activation functions and doing complex caps negotiation. For this purpose,
|
|
&GStreamer; provides base classes that simplify some types of elements.
|
|
Those base classes will be discussed in this chapter.
|
|
</para>
|
|
|
|
<sect1 id="section-base-sink" xreflabel="Writing a sink">
|
|
<title>Writing a sink</title>
|
|
<para>
|
|
Sinks are special elements in &GStreamer;. This is because sink elements
|
|
have to take care of <emphasis>preroll</emphasis>, which is the process
|
|
that takes care that elements going into the
|
|
<classname>GST_STATE_PAUSED</classname> state will have buffers ready
|
|
after the state change. The result of this is that such elements can
|
|
start processing data immediately after going into the
|
|
<classname>GST_STATE_PLAYING</classname> state, without requiring to
|
|
take some time to initialize outputs or set up decoders; all that is done
|
|
already before the state-change to <classname>GST_STATE_PAUSED</classname>
|
|
successfully completes.
|
|
</para>
|
|
<para>
|
|
Preroll, however, is a complex process that would require the same
|
|
code in many elements. Therefore, sink elements can derive from the
|
|
<classname>GstBaseSink</classname> base-class, which does preroll and
|
|
a few other utility functions automatically. The derived class only
|
|
needs to implement a bunch of virtual functions and will work
|
|
automatically.
|
|
</para>
|
|
<para>
|
|
The base class implement much of the synchronization logic that a
|
|
sink has to perform.
|
|
</para>
|
|
<para>
|
|
The <classname>GstBaseSink</classname> base-class specifies some
|
|
limitations on elements, though:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
It requires that the sink only has one sinkpad. Sink elements that
|
|
need more than one sinkpad, must make a manager element with
|
|
multiple GstBaseSink elements inside.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Sink elements can derive from <classname>GstBaseSink</classname> using
|
|
the usual <classname>GObject</classname> convenience macro
|
|
<function>G_DEFINE_TYPE ()</function>:
|
|
</para>
|
|
<programlisting>
|
|
G_DEFINE_TYPE (GstMySink, gst_my_sink, GST_TYPE_BASE_SINK);
|
|
|
|
[..]
|
|
|
|
static void
|
|
gst_my_sink_class_init (GstMySinkClass * klass)
|
|
{
|
|
klass->set_caps = [..];
|
|
klass->render = [..];
|
|
[..]
|
|
}
|
|
</programlisting>
|
|
<para>
|
|
The advantages of deriving from <classname>GstBaseSink</classname> are
|
|
numerous:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Derived implementations barely need to be aware of preroll, and do
|
|
not need to know anything about the technical implementation
|
|
requirements of preroll. The base-class does all the hard work.
|
|
</para>
|
|
<para>
|
|
Less code to write in the derived class, shared code (and thus
|
|
shared bugfixes).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
There are also specialized base classes for audio and video, let's look
|
|
at those a bit.
|
|
</para>
|
|
|
|
<sect2 id="section-base-audiosink" xreflabel="Writing an audio sink">
|
|
<title>Writing an audio sink</title>
|
|
<para>
|
|
Essentially, audio sink implementations are just a special case of a
|
|
general sink. An audio sink has the added complexity that it needs to
|
|
schedule playback of samples. It must match the clock selected in the
|
|
pipeline against the clock of the audio device and calculate and
|
|
compensate for drift and jitter.
|
|
</para>
|
|
<para>
|
|
There are two audio base classes that you can choose to
|
|
derive from, depending on your needs:
|
|
<classname>GstAudioBasesink</classname> and
|
|
<classname>GstAudioSink</classname>. The audiobasesink provides full
|
|
control over how synchronization and scheduling is handled, by using
|
|
a ringbuffer that the derived class controls and provides. The
|
|
audiosink base-class is a derived class of the audiobasesink,
|
|
implementing a standard ringbuffer implementing default
|
|
synchronization and providing a standard audio-sample clock. Derived
|
|
classes of this base class merely need to provide a <function>_open
|
|
()</function>, <function>_close ()</function> and a <function>_write
|
|
()</function> function implementation, and some optional functions.
|
|
This should suffice for many sound-server output elements and even
|
|
most interfaces. More demanding audio systems, such as Jack, would
|
|
want to implement the <classname>GstAudioBaseSink</classname>
|
|
base-class.
|
|
</para>
|
|
<para>
|
|
The <classname>GstBaseAusioSink</classname> has little to no
|
|
limitations and should fit virtually every implementation, but is
|
|
hard to implement. The <classname>GstAudioSink</classname>, on the
|
|
other hand, only fits those systems with a simple <function>open
|
|
()</function> / <function>close ()</function> / <function>write
|
|
()</function> API (which practically means pretty much all of them),
|
|
but has the advantage that it is a lot easier to implement. The
|
|
benefits of this second base class are large:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Automatic synchronization, without any code in the derived class.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Also automatically provides a clock, so that other sinks (e.g. in
|
|
case of audio/video playback) are synchronized.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Features can be added to all audiosinks by making a change in the
|
|
base class, which makes maintenance easy.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Derived classes require only three small functions, plus some
|
|
<classname>GObject</classname> boilerplate code.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
In addition to implementing the audio base-class virtual functions,
|
|
derived classes can (should) also implement the
|
|
<classname>GstBaseSink</classname> <function>set_caps ()</function> and
|
|
<function>get_caps ()</function> virtual functions for negotiation.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="section-base-videosink" xreflabel="Writing a general sink">
|
|
<title>Writing a video sink</title>
|
|
<para>
|
|
Writing a videosink can be done using the
|
|
<classname>GstVideoSink</classname> base-class, which derives from
|
|
<classname>GstBaseSink</classname> internally. Currently, it does
|
|
nothing yet but add another compile dependency, so derived classes
|
|
will need to implement all base-sink virtual functions. When they do
|
|
this correctly, this will have some positive effects on the end user
|
|
experience with the videosink:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Because of preroll (and the <function>preroll ()</function> virtual
|
|
function), it is possible to display a video frame already when
|
|
going into the <classname>GST_STATE_PAUSED</classname> state.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
By adding new features to <classname>GstVideoSink</classname>, it
|
|
will be possible to add extensions to videosinks that affect all of
|
|
them, but only need to be coded once, which is a huge maintenance
|
|
benefit.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="section-base-src" xreflabel="Writing a source">
|
|
<title>Writing a source</title>
|
|
<para>
|
|
In the previous part, particularly <xref
|
|
linkend="section-scheduling-randomxs"/>, we have learned that some types
|
|
of elements can provide random access. This applies most definitely to
|
|
source elements reading from a randomly seekable location, such as file
|
|
sources. However, other source elements may be better described as a
|
|
live source element, such as a camera source, an audio card source and
|
|
such; those are not seekable and do not provide byte-exact access. For
|
|
all such use cases, &GStreamer; provides two base classes:
|
|
<classname>GstBaseSrc</classname> for the basic source functionality, and
|
|
<classname>GstPushSrc</classname>, which is a non-byte exact source
|
|
base-class. The pushsource base class itself derives from basesource as
|
|
well, and thus all statements about the basesource apply to the
|
|
pushsource, too.
|
|
</para>
|
|
<para>
|
|
The basesrc class does several things automatically for derived classes,
|
|
so they no longer have to worry about it:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Fixes to <classname>GstBaseSrc</classname> apply to all derived
|
|
classes automatically.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Automatic pad activation handling, and task-wrapping in case we get
|
|
assigned to start a task ourselves.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
The <classname>GstBaseSrc</classname> may not be suitable for all cases,
|
|
though; it has limitations:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
There is one and only one sourcepad. Source elements requiring
|
|
multiple sourcepads must implement a manager bin and use multiple
|
|
source elements internally or make a manager element that uses
|
|
a source element and a demuxer inside.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
It is possible to use special memory, such as X server memory pointers
|
|
or <function>mmap ()</function>'ed memory areas, as data pointers in
|
|
buffers returned from the <function>create()</function> virtual function.
|
|
</para>
|
|
|
|
<sect2 id="section-base-audiosrc" xreflabel="Writing an audio source">
|
|
<title>Writing an audio source</title>
|
|
<para>
|
|
An audio source is nothing more but a special case of a pushsource.
|
|
Audio sources would be anything that reads audio, such as a source
|
|
reading from a soundserver, a kernel interface (such as ALSA) or a
|
|
test sound / signal generator. &GStreamer; provides two base classes,
|
|
similar to the two audiosinks described in <xref
|
|
linkend="section-base-audiosink"/>; one is ringbuffer-based, and
|
|
requires the derived class to take care of its own scheduling,
|
|
synchronization and such. The other is based on this
|
|
<classname>GstAudioBaseSrc</classname> and is called
|
|
<classname>GstAudioSrc</classname>, and provides a simple
|
|
<function>open ()</function>, <function>close ()</function> and
|
|
<function>read ()</function> interface, which is rather simple to
|
|
implement and will suffice for most soundserver sources and audio
|
|
interfaces (e.g. ALSA or OSS) out there.
|
|
</para>
|
|
<para>
|
|
The <classname>GstAudioSrc</classname> base-class has several benefits
|
|
for derived classes, on top of the benefits of the
|
|
<classname>GstPushSrc</classname> base-class that it is based on:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Does syncronization and provides a clock.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
New features can be added to it and will apply to all derived
|
|
classes automatically.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="section-base-transform"
|
|
xreflabel="Writing a transformation element">
|
|
<title>Writing a transformation element</title>
|
|
<para>
|
|
A third base-class that &GStreamer; provides is the
|
|
<classname>GstBaseTransform</classname>. This is a base class for
|
|
elements with one sourcepad and one sinkpad which act as a filter
|
|
of some sort, such as volume changing, audio resampling, audio format
|
|
conversion, and so on and so on. There is quite a lot of bookkeeping
|
|
that such elements need to do in order for things such as buffer
|
|
allocation forwarding, passthrough, in-place processing and such to all
|
|
work correctly. This base class does all that for you, so that you just
|
|
need to do the actual processing.
|
|
</para>
|
|
<para>
|
|
Since the <classname>GstBaseTransform</classname> is based on the 1-to-1
|
|
model for filters, it may not apply well to elements such as decoders,
|
|
which may have to parse properties from the stream. Also, it will not
|
|
work for elements requiring more than one sourcepad or sinkpad.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|