<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Interfaces</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="GStreamer Plugin Writer's Guide"
HREF="index.html"><LINK
REL="UP"
TITLE="Advanced Filter Concepts"
HREF="part-advanced.html"><LINK
REL="PREVIOUS"
TITLE="MIDI"
HREF="chapter-advanced-midi.html"><LINK
REL="NEXT"
TITLE="Mixer Interface"
HREF="section-iface-mixer.html"></HEAD
><BODY
CLASS="chapter"
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</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="chapter-advanced-midi.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="section-iface-mixer.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="chapter"
><H1
><A
NAME="chapter-advanced-interfaces"
></A
>Chapter 18. Interfaces</H1
><P
> Previously, in the chapter <A
HREF="chapter-building-args.html"
>Adding Arguments</A
>, 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.
</P
><P
> 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 <CODE
CLASS="classname"
>GParamSpec</CODE
> 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.
</P
><P
> 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.
</P
><P
> 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
<CODE
CLASS="classname"
>GTypeInterface</CODE
> 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
<CODE
CLASS="classname"
>GTypeInterface</CODE
> (which is static itself, too) which
allows us to query for interface availability based on runtime properties.
This extension is called <CODE
CLASS="classname"
>GstImplementsInterface</CODE
>.
</P
><P
> One important note: interfaces do <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>not</I
></SPAN
> replace
properties. Rather, interfaces should be built <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>next to</I
></SPAN
>
properties. There are two important reasons for this. Firstly, properties
can be saved in XML files. Secondly, properties can be specified on the
commandline (<TT
CLASS="filename"
>gst-launch</TT
>).
</P
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="section-iface-general"
>18.1. How to Implement Interfaces</A
></H1
><P
> Implementing interfaces is intiated in the <CODE
CLASS="function"
>_get_type ()</CODE
>
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 <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>some</I
></SPAN
>
interfaces have is <CODE
CLASS="classname"
>GstImplementsInterface</CODE
>. Per
interface, we will indicate clearly when it depends on this extension.
If it does, you need to register support for <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>that</I
></SPAN
>
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 <CODE
CLASS="classname"
>GstImplementsInterface</CODE
>, see the next section
about the mixer interface: <A
HREF="section-iface-mixer.html"
>Mixer Interface</A
>.
</P
><PRE
CLASS="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 */
}
</PRE
></DIV
></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="chapter-advanced-midi.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-mixer.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>MIDI</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="part-advanced.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Mixer Interface</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
