mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-08 13:18:52 +00:00
Original commit message from CVS: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-porting.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-bus.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-pads.xml: * docs/manual/highlevel-components.xml: * docs/manual/manual.xml: * docs/manual/thread.fig: Update (until threads/scheduling) Application Development Manual; remove GstThread, add GstBus, add simple porting checklist, add documentation for tag writing, clocks, make all examples until this part compile and run. * examples/manual/Makefile.am: Update from changes to Application Development Manual; add bus example, remove thread example.
137 lines
5.7 KiB
XML
137 lines
5.7 KiB
XML
<chapter id="chapter-interfaces">
|
|
<title>Interfaces</title>
|
|
|
|
<para>
|
|
In <xref linkend="section-elements-properties"/>, you have learned how
|
|
to use <classname>GObject</classname> properties as a simple way to do
|
|
interaction between applications and elements. This method suffices for
|
|
the simple'n'straight settings, but fails for anything more complicated
|
|
than a getter and setter. For the more complicated use cases, &GStreamer;
|
|
uses interfaces based on the Glib <classname>GInterface</classname> type.
|
|
</para>
|
|
|
|
<para>
|
|
Most of the interfaces handled here will not contain any example code.
|
|
See the API references for details. Here, we will just describe the
|
|
scope and purpose of each interface.
|
|
</para>
|
|
|
|
<sect1 id="section-interfaces-uri">
|
|
<title>The URI interface</title>
|
|
|
|
<para>
|
|
In all examples so far, we have only supported local files through the
|
|
<quote>filesrc</quote> element. &GStreamer;, obviously, supports many
|
|
more location sources. However, we don't want applications to need to
|
|
know any particular element implementation details, such as element
|
|
names for particular network source types and so on. Therefore, there
|
|
is a URI interface, which can be used to get the source element that
|
|
supports a particular URI type. There is no strict rule for URI naming,
|
|
but in general we follow naming conventions that others use, too. For
|
|
example, assuming you have the correct plugins installed, &GStreamer;
|
|
supports <quote>file:///<path>/<file></quote>,
|
|
<quote>http://<host>/<path>/<file></quote>,
|
|
<quote>mms://<host>/<path>/<file></quote>, and so on.
|
|
</para>
|
|
<para>
|
|
In order to get the source or sink element supporting a particular URI,
|
|
use <function>gst_element_make_from_uri ()</function>, with the URI
|
|
type being either <classname>GST_URI_SRC</classname> for a source
|
|
element, or <classname>GST_URI_SINK</classname> for a sink element.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="section-interfaces-mixer">
|
|
<title>The Mixer interface</title>
|
|
|
|
<para>
|
|
The mixer interface provides a uniform way to control the volume on a
|
|
hardware (or software) mixer. The interface is primarily intended to
|
|
be implemented by elements for audio inputs and outputs that talk
|
|
directly to the hardware (e.g. OSS or ALSA plugins).
|
|
</para>
|
|
<para>
|
|
Using this interface, it is possible to control a list of tracks
|
|
(such as Line-in, Microphone, etc.) from a mixer element. They can
|
|
be muted, their volume can be changed and, for input tracks, their
|
|
record flag can be set as well.
|
|
</para>
|
|
<para>
|
|
Example plugins implementing this interface include the OSS elements
|
|
(osssrc, osssink, ossmixer) and the ALSA plugins (alsasrc, alsasink
|
|
and alsamixer).
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="section-interfaces-tuner">
|
|
<title>The Tuner interface</title>
|
|
|
|
<para>
|
|
The tuner interface is a uniform way to control inputs and outputs
|
|
on a multi-input selection device. This is primarily used for input
|
|
selection on elements for TV- and capture-cards.
|
|
</para>
|
|
<para>
|
|
Using this interface, it is possible to select one track from a list
|
|
of tracks supported by that tuner-element. The tuner will than select
|
|
that track for media-processing internally. This can, for example, be
|
|
used to switch inputs on a TV-card (e.g. from Composite to S-video).
|
|
</para>
|
|
<para>
|
|
This interface is currently only implemented by the Video4linux and
|
|
Video4linux2 elements.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="section-interfaces-colorbalance">
|
|
<title>The Color Balance interface</title>
|
|
|
|
<para>
|
|
The colorbalance interface is a way to control video-related properties
|
|
on an element, such as brightness, contrast and so on. It's sole
|
|
reason for existance is that, as far as its authors know, there's no
|
|
way to dynamically register properties using
|
|
<classname>GObject</classname>.
|
|
</para>
|
|
<para>
|
|
The colorbalance interface is implemented by several plugins, including
|
|
xvimagesink and the Video4linux and Video4linux2 elements.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="section-interfaces-proprobe">
|
|
<title>The Property Probe interface</title>
|
|
|
|
<para>
|
|
The property probe is a way to autodetect allowed values for a
|
|
<classname>GObject</classname> property. It's primary use (and
|
|
the only thing that we currently use it for) is to autodetect
|
|
devices in several elements. For example, the OSS elements use
|
|
this interface to detect all OSS devices on a system. Applications
|
|
can then <quote>probe</quote> this property and get a list of
|
|
detected devices. Given the overlap between HAL and the practical
|
|
implementations of this interface, this might in time be deprecated
|
|
in favour of HAL.
|
|
</para>
|
|
<para>
|
|
This interface is currently implemented by many elements, including
|
|
the ALSA, OSS, Video4linux and Video4linux2 elements.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="section-interfaces-xoverlay">
|
|
<title>The X Overlay interface</title>
|
|
|
|
<para>
|
|
The X Overlay interface was created to solve the problem of embedding
|
|
video streams in an application window. The application provides an
|
|
X-window to the element implementing this interface to draw on, and
|
|
the element will then use this X-window to draw on rather than creating
|
|
a new toplevel window. This is useful to embed video in video players.
|
|
</para>
|
|
<para>
|
|
This interface is implemented by, amongst others, the Video4linux and
|
|
Video4linux2 elements and by ximagesink, xvimagesink and sdlvideosink.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|