<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Mixer Interface</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79;charset=UTF-8"><LINK
REL="HOME"
TITLE="GStreamer Plugin Writer's Guide (0.10.36)"
HREF="index.html"><LINK
REL="UP"
TITLE="Interfaces"
HREF="chapter-advanced-interfaces.html"><LINK
REL="PREVIOUS"
TITLE="URI interface"
HREF="section-iface-uri.html"><LINK
REL="NEXT"
TITLE="Tuner Interface"
HREF="section-iface-tuner.html"></HEAD
><BODY
CLASS="sect1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
><SPAN
CLASS="application"
>GStreamer</SPAN
> Plugin Writer's Guide (0.10.36)</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="section-iface-uri.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 16. Interfaces</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="section-iface-tuner.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="section-iface-mixer"
>16.3. Mixer Interface</A
></H1
><P
> 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 <SPAN
CLASS="QUOTE"
>"volume"</SPAN
>
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.
</P
><P
> The mixer interface requires the <A
HREF="../../gstreamer/html/GstImplementsInterface.html"
TARGET="_top"
><CODE
CLASS="classname"
> GstImplementsInterface</CODE
></A
>
interface to be implemented by the element. The example below will
feature both, so it serves as an example for the <A
HREF="../../gstreamer/html/GstImplementsInterface.html"
TARGET="_top"
><CODE
CLASS="classname"
> GstImplementsInterface</CODE
></A
>, too. In this
interface, it is required to set a function pointer for the <CODE
CLASS="function"
> supported ()</CODE
> 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
<CODE
CLASS="function"
>list_tracks ()</CODE
>. All other function pointers in the
mixer interface are optional, although it is strongly recommended to set
function pointers for at least the <CODE
CLASS="function"
>get_volume ()</CODE
> and
<CODE
CLASS="function"
>set_volume ()</CODE
> functions. The API reference for this
interface documents the goal of each function, so we will limit ourselves
to the implementation here.
</P
><P
> The following example shows a mixer implementation for a software N-to-1
element. It does not show the actual process of stream mixing, that is
far too complicated for this guide.
</P
><PRE
CLASS="programlisting"
> #include <gst/mixer/mixer.h>
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;
}
</PRE
><P
> The mixer interface is very audio-centric. However, with the software
flag set, the mixer can be used to mix any kind of stream in a N-to-1
element to join (not aggregate!) streams together into one output stream.
Conceptually, that's called mixing too. You can always use the element
factory's <SPAN
CLASS="QUOTE"
>"category"</SPAN
> to indicate type of your element. In
a software element that mixes random streams, you would not be required
to implement the <CODE
CLASS="function"
>_get_volume ()</CODE
> or
<CODE
CLASS="function"
>_set_volume ()</CODE
> functions. Rather, you would only
implement the <CODE
CLASS="function"
>_set_record ()</CODE
> to enable or disable
tracks in the output stream. to make sure that a mixer-implementing
element is of a certain type, check the element factory's category.
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="section-iface-uri.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="section-iface-tuner.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>URI interface</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="chapter-advanced-interfaces.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Tuner Interface</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
