docs/pwg/advanced-interfaces.xml: Added tuner interface docs.

Original commit message from CVS:
2004-01-30  Ronald Bultje  <rbultje@ronald.bitfreak.net>

* docs/pwg/advanced-interfaces.xml:
Added tuner interface docs.
This commit is contained in:
Ronald S. Bultje 2004-01-30 12:00:16 +00:00
parent 0fc84c1471
commit 0de6f6fb67
2 changed files with 158 additions and 1 deletions

View file

@ -1,3 +1,8 @@
2004-01-30 Ronald Bultje <rbultje@ronald.bitfreak.net>
* docs/pwg/advanced-interfaces.xml:
Added tuner interface docs.
2004-01-30 Benjamin Otte <in7y118@public.uni-hamburg.de> 2004-01-30 Benjamin Otte <in7y118@public.uni-hamburg.de>
* docs/random/mimetypes: * docs/random/mimetypes:

View file

@ -143,6 +143,11 @@ gst_my_filter_some_interface_init (GstSomeInterface *iface)
interface documents the goal of each function, so we will limit ourselves interface documents the goal of each function, so we will limit ourselves
to the implementation here. to the implementation here.
</para> </para>
<para>
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.
</para>
<programlisting> <programlisting>
#include &lt;gst/mixer/mixer.h&gt; #include &lt;gst/mixer/mixer.h&gt;
@ -267,12 +272,159 @@ gst_my_filter_mixer_interface_init (GstMixerClass *iface)
iface->get_volume = gst_my_filter_mixer_get_volume; iface->get_volume = gst_my_filter_mixer_get_volume;
} }
</programlisting> </programlisting>
<para>
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 <quote>category</quote> to indicate type of your element. In
a software element that mixes random streams, you would not be required
to implement the <function>_get_volume ()</function> or
<function>_set_volume ()</function> functions. Rather, you would only
implement the <function>_set_record ()</function> 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.
</para>
</sect1> </sect1>
<sect1 id="section-iface-tuner" xreflabel="Tuner Interface"> <sect1 id="section-iface-tuner" xreflabel="Tuner Interface">
<title>Tuner Interface</title> <title>Tuner Interface</title>
<para> <para>
WRITEME As opposed to the mixer interface, that's used to join together N streams
into one output stream by mixing all streams together, the tuner
interface is used in N-to-1 elements too, but instead of mixing the input
streams, it will select one stream and push the data of that stream to
the output stream. It will discard the data of all other streams. There
is a flag that indicates whether this is a software-tuner (in which case
it is a pure software implementation, with N sink pads and 1 source pad)
or a hardware-tuner, in which case it only has one source pad, and the
whole stream selection process is done in hardware. The software case can
be used in elements such as <emphasis>switch</emphasis>. The hardware
case can be used in elements with channel selection, such as video source
elements (v4lsrc, v4l2src, etc.). If you need a specific element type,
use the element factory's <quote>category</quote> to make sure that the
element is of the type that you need. Note that the interface itself is
highly analog-video-centric.
</para>
<para>
This interface requires the <classname>GstImplemensInterface</classname>
interface to work correctly.
</para>
<para>
The following example shows how to implement the tuner interface in an
element. It does not show the actual process of stream selection, that
is irrelevant for this section.
</para>
<programlisting>
#include &lt;gst/tuner/tuner.h&gt;
typedef struct _GstMyFilter {
[..]
gint active_input;
GList *channels;
} GstMyFilter;
static void gst_my_filter_implements_interface_init (GstImplementsInterfaceClass *iface);
static void gst_my_filter_tuner_interface_init (GstTunerClass *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 tuner_interface_info = {
(GInterfaceInitFunc) gst_my_filter_tuner_interface_init,
NULL,
NULL
};
[..]
g_type_add_interface_static (my_filter_type,
GST_TYPE_IMPLEMENTS_INTERFACE,
&amp;implements_interface_info);
g_type_add_interface_static (my_filter_type,
GST_TYPE_TUNER,
&amp;tunerr_interface_info);
[..]
}
static void
gst_my_filter_init (GstMyFilter *filter)
{
GstTunerChannel *channel = NULL;
[..]
filter->active_input = 0;
filter->channels = NULL;
channel = g_object_new (GST_TYPE_TUNER_CHANNEL, NULL);
channel->label = g_strdup ("MyChannel");
channel->flags = GST_TUNER_CHANNEL_INPUT;
filter->channels = g_list_append (filter->channels, channel);
}
static gboolean
gst_my_filter_interface_supported (GstImplementsInterface *iface,
GType iface_type)
{
g_return_val_if_fail (iface_type == GST_TYPE_TUNER, FALSE);
/* for the sake of this example, we'll always support it. However, normally,
* you would check whether the device you've opened supports tuning. */
return TRUE;
}
static void
gst_my_filter_implements_interface_init (GstImplementsInterfaceClass *iface)
{
iface->supported = gst_my_filter_interface_supported;
}
static const GList *
gst_my_filter_tuner_list_channels (GstTuner *tuner)
{
GstMyFilter *filter = GST_MY_FILTER (tuner);
return filter->channels;
}
static GstTunerChannel *
gst_my_filter_tuner_get_channel (GstTuner *tuner)
{
GstMyFilter *filter = GST_MY_FILTER (tuner);
return g_list_nth_data (filter->channels,
filter->active_input);
}
static void
gst_my_filter_tuner_set_channel (GstTuner *tuner,
GstTunerChannel *channel)
{
GstMyFilter *filter = GST_MY_FILTER (tuner);
filter->active_input = g_list_index (filter->channels, channel);
g_assert (filter->active_input >= 0);
}
static void
gst_my_filter_tuner_interface_init (GstTunerClass *iface)
{
iface->list_channels = gst_my_filter_tuner_list_channels;
iface->get_channel = gst_my_filter_tuner_get_channel;
iface->set_channel = gst_my_filter_tuner_set_channel;
}
</programlisting>
<para>
As said, the tuner interface is very analog video-centric. It features
functions for selecting an input or output, and on inputs, it features
selection of a tuning frequency if the channel supports frequency-tuning
on that input. Likewise, it allows signal-strength-acquiring if the input
supports that. Frequency tuning can be used for radio or cable-TV tuning.
Signal-strength is an indication of the signal and can be used for
visual feedback to the user or for autodetection. Next to that, it also
features norm selection, which is only useful for analog video elements.
</para> </para>
</sect1> </sect1>