mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-29 23:32:33 +00:00
fad4a520cd
Original commit message from CVS: 2004-01-28 Ronald Bultje <rbultje@ronald.bitfreak.net> * docs/pwg/advanced_interfaces.xml: Docs for mixer interface. Also a check for website uploading.
311 lines
11 KiB
XML
311 lines
11 KiB
XML
<chapter id="cha-advanced-interfaces">
|
|
<title>Interfaces</title>
|
|
<para>
|
|
Previously, in the chapter <xref linkend="cha-building-args"/>, we have
|
|
introduced the concept of GObject properties of controlling an element's
|
|
behaviour. This is a very powerful, but has two big disadvantage: firstly,
|
|
it is too generic, and secondly, it isn't dynamic.
|
|
</para>
|
|
<para>
|
|
The first disadvantage has to do with customizability of the end-user
|
|
interface that will be built to control the element. Some properties are
|
|
more important than others. Some integer properties are better shown in a
|
|
spin-button widget, whereas others would be better represented by a slider
|
|
widget. Such things are not possible because the UI has no actual meaning
|
|
in the application. A UI widget that stands for a bitrate property is the
|
|
same as an UI widget that stands for the size of a video, as long as both
|
|
are of the same <classname>GParamSpec</classname> type. Another problem,
|
|
related to the one about parameter important, is that things like parameter
|
|
grouping, function grouping or anything to make parameters coherent, is not
|
|
really possible.
|
|
</para>
|
|
<para>
|
|
The second argument against parameters are that they are not dynamic. In
|
|
many cases, the allowed values for a property are not fixed, but depend
|
|
on things that can only be detected at run-time. The names of inputs for
|
|
a TV card in a video4linux source element, for example, can only be
|
|
retrieved from the kernel driver when we've opened the device; this only
|
|
happens when the element goes into the READY state. This means that we
|
|
cannot create an enum property type to show this to the user.
|
|
</para>
|
|
<para>
|
|
The solution to those problems is to create very specialized types of
|
|
controls for certain often-used controls. We use the concept of interfaces
|
|
to achieve this. The basis of this all is the glib
|
|
<classname>GTypeInterface</classname> type. For each case where we think
|
|
it's useful, we've created interfaces which can be implemented by elements
|
|
at their own will. We've also created a small extension to
|
|
<classname>GTypeInterface</classname> (which is static itself, too) which
|
|
allows us to query for interface availability based on runtime properties.
|
|
This extension is called <classname>GstImplementsInterface</classname>.
|
|
</para>
|
|
|
|
<sect1 id="sect1-iface-general" xreflabel="How to Implement Interfaces">
|
|
<title>How to Implement Interfaces</title>
|
|
<para>
|
|
Implementing interfaces is intiated 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
|
|
will be notified of doing that wrongly when using the element: it will
|
|
quit with failed assertions, which will explain what went wrong. In the
|
|
case of GStreamer, the only dependency that <emphasis>some</emphasis>
|
|
interfaces have is <classname>GstImplementsInterface</classname>. Per
|
|
interface, we will indicate clearly when it depends on this extension.
|
|
If it does, you need to register support for <emphasis>that</emphasis>
|
|
interface before registering support for the interface that you're
|
|
wanting to support. The example below explains how to add support for a
|
|
simple interface with no further dependencies. For a small explanation
|
|
on <classname>GstImplementsInterface</classname>, see the next section
|
|
about the mixer interface: <xref linkend="sect1-iface-mixer"/>.
|
|
</para>
|
|
<programlisting>
|
|
static void gst_my_filter_some_interface_init (GstSomeInterface *iface);
|
|
|
|
GType
|
|
gst_my_filter_get_type (void)
|
|
{
|
|
static GType my_filter_type = 0;
|
|
|
|
if (!my_filter_type) {
|
|
static const GTypeInfo my_filter_info = {
|
|
sizeof (GstMyFilterClass),
|
|
(GBaseInitFunc) gst_my_filter_base_init,
|
|
NULL,
|
|
(GClassInitFunc) gst_my_filter_class_init,
|
|
NULL,
|
|
NULL,
|
|
sizeof (GstMyFilter),
|
|
0,
|
|
(GInstanceInitFunc) gst_my_filter_init
|
|
};
|
|
static const GInterfaceInfo some_interface_info = {
|
|
(GInterfaceInitFunc) gst_my_filter_some_interface_init,
|
|
NULL,
|
|
NULL
|
|
};
|
|
|
|
my_filter_type =
|
|
g_type_register_static (GST_TYPE_MY_FILTER,
|
|
"GstMyFilter",
|
|
&my_filter_info, 0);
|
|
g_type_add_interface_static (my_filter_type,
|
|
GST_TYPE_SOME_INTERFACE,
|
|
&some_interface_info);
|
|
}
|
|
|
|
return my_filter_type;
|
|
}
|
|
|
|
static void
|
|
gst_my_filter_some_interface_init (GstSomeInterface *iface)
|
|
{
|
|
/* here, you would set virtual function pointers in the interface */
|
|
}
|
|
</programlisting>
|
|
</sect1>
|
|
|
|
<sect1 id="sect1-iface-mixer" xreflabel="Mixer Interface">
|
|
<title>Mixer Interface</title>
|
|
<para>
|
|
The goal of the mixer interface is to provide a simple yet powerful API
|
|
to applications for audio hardware mixer/volume control. Most soundcards
|
|
have hardware mixers, where volume can be changed, they can be muted,
|
|
inputs can be modified to mix their content into what will be read from
|
|
the device by applications (in our case: audio source plugins). The
|
|
mixer interface is the way to control those. The mixer interface can
|
|
also be used for volume control in software (e.g. the <quote>volume</quote>
|
|
element). The end goal of this interface is to allow development of
|
|
hardware volume control applications and for the control of audio volume
|
|
and input/output settings.
|
|
</para>
|
|
<para>
|
|
The mixer interface requires the <classname>GstImplementsInterface</classname>
|
|
interface to be implemented by the element. The example below will
|
|
feature both, so it serves as an example for the
|
|
<classname>GstImplementsInterface</classname>, too. In the
|
|
<classname>GstImplementsInterface</classname>, it is required to set a
|
|
function pointer for the <function>supported ()</function> function. If
|
|
you don't, this function will always return FALSE (default
|
|
implementation) and the mixer interface implementation will not work. For
|
|
the mixer interface, the only required function is
|
|
<function>list_tracks ()</function>. All other function pointers in the
|
|
mixer interface are optional, although it is strongly recommended to set
|
|
function pointers for at least the <function>get_volume ()</function> and
|
|
<function>set_volume ()</function> functions. The API reference for this
|
|
interface documents the goal of each function, so we will limit ourselves
|
|
to the implementation here.
|
|
</para>
|
|
<programlisting>
|
|
typedef struct _GstMyFilter {
|
|
[..]
|
|
gint volume;
|
|
GList *tracks;
|
|
} GstMyFilter;
|
|
|
|
static void gst_my_filter_implements_interface_init (GstImplementsInterfaceClass *iface);
|
|
static void gst_my_filter_mixer_interface_init (GstMixerClass *iface);
|
|
|
|
GType
|
|
gst_my_filter_get_type (void)
|
|
{
|
|
[..]
|
|
static const GInterfaceInfo implements_interface_info = {
|
|
(GInterfaceInitFunc) gst_my_filter_implements_interface_init,
|
|
NULL,
|
|
NULL
|
|
};
|
|
static const GInterfaceInfo mixer_interface_info = {
|
|
(GInterfaceInitFunc) gst_my_filter_mixer_interface_init,
|
|
NULL,
|
|
NULL
|
|
};
|
|
[..]
|
|
g_type_add_interface_static (my_filter_type,
|
|
GST_TYPE_IMPLEMENTS_INTERFACE,
|
|
&implements_interface_info);
|
|
g_type_add_interface_static (my_filter_type,
|
|
GST_TYPE_MIXER,
|
|
&mixer_interface_info);
|
|
[..]
|
|
}
|
|
|
|
static void
|
|
gst_my_filter_init (GstMyFilter *filter)
|
|
{
|
|
GstMixerTrack *track = NULL;
|
|
[..]
|
|
filter->volume = 100;
|
|
filter->tracks = NULL;
|
|
track = g_object_new (GST_TYPE_MIXER_TRACK, NULL);
|
|
track->label = g_strdup ("MyTrack");
|
|
track->num_channels = 1;
|
|
track->min_volume = 0;
|
|
track->max_volume = 100;
|
|
track->flags = GST_MIXER_TRACK_SOFTWARE;
|
|
filter->tracks = g_list_append (filter->tracks, track);
|
|
}
|
|
|
|
static gboolean
|
|
gst_my_filter_interface_supported (GstImplementsInterface *iface,
|
|
GType iface_type)
|
|
{
|
|
g_return_val_if_fail (iface_type == GST_TYPE_MIXER, FALSE);
|
|
|
|
/* for the sake of this example, we'll always support it. However, normally,
|
|
* you would check whether the device you've opened supports mixers. */
|
|
return TRUE;
|
|
}
|
|
|
|
static void
|
|
gst_my_filter_implements_interface_init (GstImplementsInterfaceClass *iface)
|
|
{
|
|
iface->supported = gst_my_filter_interface_supported;
|
|
}
|
|
|
|
/*
|
|
* This function returns the list of support tracks (inputs, outputs)
|
|
* on this element instance. Elements usually build this list during
|
|
* _init () or when going from NULL to READY.
|
|
*/
|
|
|
|
static const GList *
|
|
gst_my_filter_mixer_list_tracks (GstMixer *mixer)
|
|
{
|
|
GstMyFilter *filter = GST_MY_FILTER (mixer);
|
|
|
|
return filter->tracks;
|
|
}
|
|
|
|
/*
|
|
* Set volume. volumes is an array of size track->num_channels, and
|
|
* each value in the array gives the wanted volume for one channel
|
|
* on the track.
|
|
*/
|
|
|
|
static void
|
|
gst_my_filter_mixer_set_volume (GstMixer *mixer,
|
|
GstMixerTrack *track,
|
|
gint *volumes)
|
|
{
|
|
GstMyFilter *filter = GST_MY_FILTER (mixer);
|
|
|
|
filter->volume = volumes[0];
|
|
|
|
g_print ("Volume set to %d\n", filter->volume);
|
|
}
|
|
|
|
static void
|
|
gst_my_filter_mixer_get_volume (GstMixer *mixer,
|
|
GstMixerTrack *track,
|
|
gint *volumes)
|
|
{
|
|
GstMyFilter *filter = GST_MY_FILTER (mixer);
|
|
|
|
volumes[0] = filter->volume;
|
|
}
|
|
|
|
static void
|
|
gst_my_filter_mixer_interface_init (GstMixerClass *iface)
|
|
{
|
|
/* the mixer interface requires a definition of the mixer type:
|
|
* hardware or software? */
|
|
GST_MIXER_TYPE (iface) = GST_MIXER_SOFTWARE;
|
|
|
|
/* virtual function pointers */
|
|
iface->list_tracks = gst_my_filter_mixer_list_tracks;
|
|
iface->set_volume = gst_my_filter_mixer_set_volume;
|
|
iface->get_volume = gst_my_filter_mixer_get_volume;
|
|
}
|
|
</programlisting>
|
|
</sect1>
|
|
|
|
<sect1 id="sect1-iface-tuner" xreflabel="Tuner Interface">
|
|
<title>Tuner Interface</title>
|
|
<para>
|
|
WRITEME
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="sect1-iface-colorbalance" xreflabel="Color Balance Interface">
|
|
<title>Color Balance Interface</title>
|
|
<para>
|
|
WRITEME
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="sect1-iface-propprobe" xreflabel="Property Probe Interface">
|
|
<title>Property Probe Interface</title>
|
|
<para>
|
|
WRITEME
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="sect1-iface-profile" xreflabel="Profile Interface">
|
|
<title>Profile Interface</title>
|
|
<para>
|
|
WRITEME
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="sect1-iface-xoverlay" xreflabel="X Overlay Interface">
|
|
<title>X Overlay Interface</title>
|
|
<para>
|
|
WRITEME
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="sect1-iface-navigation" xreflabel="Navigation Interface">
|
|
<title>Navigation Interface</title>
|
|
<para>
|
|
WRITEME
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="sect1-iface-tagging" xreflabel="Tagging Interface">
|
|
<title>Tagging Interface</title>
|
|
<para>
|
|
WRITEME
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|