mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-01-09 08:55:33 +00:00
Code Issues 1 Projects Releases Wiki Activity

manual: fix up the manual

Browse source 
MIME-type -> media types
Fix up the manual in various places with the 1.0 way of doing things
such as probes, static elements, scheduling, ...
Add porting from 0.10 to 1.0 chapter.
Add probe example to build.
Remove some docs for remove components such as GstMixer and
GstPropertyProbe, XML...
This commit is contained in:
Wim Taymans 2012-09-25 14:40:20 +02:00
parent 36be78bb00
commit 7c24fc7450
17 changed files with 316 additions and 251 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
docs/manual/advanced-autoplugging.xml
View file

@ -20,32 +20,32 @@
without needing any adaptations to its autopluggers. without needing any adaptations to its autopluggers.
</para> </para>
<para> <para>
We will first introduce the concept of MIME types as a dynamic and We will first introduce the concept of Media types as a dynamic and
extendible way of identifying media streams. After that, we will introduce extendible way of identifying media streams. After that, we will introduce
the concept of typefinding to find the type of a media stream. Lastly, the concept of typefinding to find the type of a media stream. Lastly,
we will explain how autoplugging and the &GStreamer; registry can be we will explain how autoplugging and the &GStreamer; registry can be
used to setup a pipeline that will convert media from one mimetype to used to setup a pipeline that will convert media from one mediatype to
another, for example for media decoding. another, for example for media decoding.
</para> </para>
<sect1 id="section-mime"> <sect1 id="section-media">
<title>MIME-types as a way to identify streams</title> <title>Media types as a way to identify streams</title>
<para> <para>
We have previously introduced the concept of capabilities as a way We have previously introduced the concept of capabilities as a way
for elements (or, rather, pads) to agree on a media type when for elements (or, rather, pads) to agree on a media type when
streaming data from one element to the next (see <xref streaming data from one element to the next (see <xref
linkend="section-caps"/>). We have explained that a capability is linkend="section-caps"/>). We have explained that a capability is
a combination of a mimetype and a set of properties. For most a combination of a media type and a set of properties. For most
container formats (those are the files that you will find on your container formats (those are the files that you will find on your
hard disk; Ogg, for example, is a container format), no properties hard disk; Ogg, for example, is a container format), no properties
are needed to describe the stream. Only a MIME-type is needed. A are needed to describe the stream. Only a media type is needed. A
full list of MIME-types and accompanying properties can be found full list of media types and accompanying properties can be found
in <ulink type="http" in <ulink type="http"
url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/section-types-definitions.html">the url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/section-types-definitions.html">the
Plugin Writer's Guide</ulink>. Plugin Writer's Guide</ulink>.
</para> </para>
<para> <para>
An element must associate a MIME-type to its source and sink pads An element must associate a media type to its source and sink pads
when it is loaded into the system. &GStreamer; knows about the when it is loaded into the system. &GStreamer; knows about the
different elements and what type of data they expect and emit through different elements and what type of data they expect and emit through
the &GStreamer; registry. This allows for very dynamic and extensible the &GStreamer; registry. This allows for very dynamic and extensible
@ -54,14 +54,14 @@
<para> <para>
In <xref linkend="chapter-helloworld"/>, we've learned to build a In <xref linkend="chapter-helloworld"/>, we've learned to build a
music player for Ogg/Vorbis files. Let's look at the MIME-types music player for Ogg/Vorbis files. Let's look at the media types
associated with each pad in this pipeline. <xref associated with each pad in this pipeline. <xref
linkend="section-mime-img"/> shows what MIME-type belongs to each linkend="section-mime-img"/> shows what media type belongs to each
pad in this pipeline. pad in this pipeline.
</para> </para>
<figure float="1" id="section-mime-img"> <figure float="1" id="section-mime-img">
<title>The Hello world pipeline with MIME types</title> <title>The Hello world pipeline with media types</title>
<mediaobject> <mediaobject>
<imageobject> <imageobject>
<imagedata scale="75" fileref="images/mime-world.&image;" format="&IMAGE;"/> <imagedata scale="75" fileref="images/mime-world.&image;" format="&IMAGE;"/>
@ -98,11 +98,11 @@
<para> <para>
Plugins in &GStreamer; can, as mentioned before, implement typefinder Plugins in &GStreamer; can, as mentioned before, implement typefinder
functionality. A plugin implementing this functionality will submit functionality. A plugin implementing this functionality will submit
a mimetype, optionally a set of file extensions commonly used for this a media type, optionally a set of file extensions commonly used for this
media type, and a typefind function. Once this typefind function inside media type, and a typefind function. Once this typefind function inside
the plugin is called, the plugin will see if the data in this media the plugin is called, the plugin will see if the data in this media
stream matches a specific pattern that marks the media type identified stream matches a specific pattern that marks the media type identified
by that mimetype. If it does, it will notify the typefind element of by that media type. If it does, it will notify the typefind element of
this fact, telling which mediatype was recognized and how certain we this fact, telling which mediatype was recognized and how certain we
are that this stream is indeed that mediatype. Once this run has been are that this stream is indeed that mediatype. Once this run has been
completed for all plugins implementing a typefind functionality, the completed for all plugins implementing a typefind functionality, the
@ -257,7 +257,7 @@ GstElement *pipeline;
the registry that can decode this streamtype. For this, we will get the registry that can decode this streamtype. For this, we will get
all element factories (which we've seen before in <xref all element factories (which we've seen before in <xref
linkend="section-elements-create"/>) and find the ones with the linkend="section-elements-create"/>) and find the ones with the
given MIME-type and capabilities on their sinkpad. Note that we will given media type and capabilities on their sinkpad. Note that we will
only use parsers, demuxers and decoders. We will not use factories for only use parsers, demuxers and decoders. We will not use factories for
any other element types, or we might get into a loop of encoders and any other element types, or we might get into a loop of encoders and
decoders. For this, we will want to build a list of <quote>allowed</quote> decoders. For this, we will want to build a list of <quote>allowed</quote>
@ -416,7 +416,7 @@ try_to_plug (GstPad *pad,
GstCaps *caps) GstCaps *caps)
{ {
GstObject *parent = GST_OBJECT (GST_OBJECT_PARENT (pad)); GstObject *parent = GST_OBJECT (GST_OBJECT_PARENT (pad));
const gchar *mime; const gchar *media;
const GList *item; const GList *item;
GstCaps *res, *audiocaps; GstCaps *res, *audiocaps;
@ -428,10 +428,10 @@ try_to_plug (GstPad *pad,
} }
/* as said above, we only try to plug audio... Omit video */ /* as said above, we only try to plug audio... Omit video */
mime = gst_structure_get_name (gst_caps_get_structure (caps, 0)); media = gst_structure_get_name (gst_caps_get_structure (caps, 0));
if (g_strrstr (mime, "video")) { if (g_strrstr (media, "video")) {
g_print ("Omitting link for pad %s:%s because mimetype %s is non-audio\n", g_print ("Omitting link for pad %s:%s because media type %s is non-audio\n",
GST_OBJECT_NAME (parent), GST_OBJECT_NAME (pad), mime); GST_OBJECT_NAME (parent), GST_OBJECT_NAME (pad), media);
return; return;
} }
@ -489,7 +489,7 @@ try_to_plug (GstPad *pad,
/* if we get here, no item was found */ /* if we get here, no item was found */
g_print ("No compatible pad found to decode %s on %s:%s\n", g_print ("No compatible pad found to decode %s on %s:%s\n",
mime, GST_OBJECT_NAME (parent), GST_OBJECT_NAME (pad)); media, GST_OBJECT_NAME (parent), GST_OBJECT_NAME (pad));
} }
static void static void

101
docs/manual/advanced-dataaccess.xml
View file

@ -17,18 +17,11 @@
<title>Data probing</title> <title>Data probing</title>
<para> <para>
Probing is best envisioned as a pad listener. Technically, a probe is Probing is best envisioned as a pad listener. Technically, a probe is
nothing more than a signal callback that can be attached to a pad. nothing more than a callback that can be attached to a pad.
Those signals are by default not fired at all (since that may have a You can attach a probe using <function>gst_pad_add_probe ()</function>.
negative impact on performance), but can be enabled by attaching a Similarly, one can use the
probe using <function>gst_pad_add_buffer_probe ()</function>, <function>gst_pad_remove_probe ()</function>
<function>gst_pad_add_event_probe ()</function>, or to remove the callback again.
<function>gst_pad_add_data_probe ()</function>.
Those functions attach the signal handler and
enable the actual signal emission. Similarly, one can use the
<function>gst_pad_remove_buffer_probe ()</function>,
<function>gst_pad_remove_event_probe ()</function>, or
<function>gst_pad_remove_data_probe ()</function>
to remove the signal handlers again.
</para> </para>
<para> <para>
Probes run in pipeline threading context, so callbacks should try to Probes run in pipeline threading context, so callbacks should try to
@ -50,18 +43,21 @@
<programlisting><!-- example-begin probe.c --> <programlisting><!-- example-begin probe.c -->
#include &lt;gst/gst.h&gt; #include &lt;gst/gst.h&gt;
static gboolean static GstPadProbeReturn
cb_have_data (GstPad *pad, cb_have_data (GstPad *pad,
GstBuffer *buffer, GstPadProbeInfo *info,
gpointer u_data) gpointer user_data)
{ {
gint x, y; gint x, y;
GstMapInfo info; GstMapInfo map;
guint16 *ptr, t; guint16 *ptr, t;
GstBuffer *buffer;
gst_buffer_map (buffer, &amp;info, GST_MAP_WRITE);
ptr = info.data; buffer = GST_PAD_PROBE_INFO_BUFFER (info);
gst_buffer_map (buffer, &amp;map, GST_MAP_WRITE);
ptr = (guint16 *) map.data;
/* invert data */ /* invert data */
for (y = 0; y &lt; 288; y++) { for (y = 0; y &lt; 288; y++) {
for (x = 0; x &lt; 384 / 2; x++) { for (x = 0; x &lt; 384 / 2; x++) {
@ -71,7 +67,7 @@ cb_have_data (GstPad *pad,
} }
ptr += 384; ptr += 384;
} }
gst_buffer_unmap (buffer, &amp;info); gst_buffer_unmap (buffer, &amp;map);
return TRUE; return TRUE;
} }
@ -120,8 +116,9 @@ main (gint argc,
g_object_set (G_OBJECT (filter), "caps", filtercaps, NULL); g_object_set (G_OBJECT (filter), "caps", filtercaps, NULL);
gst_caps_unref (filtercaps); gst_caps_unref (filtercaps);
pad = gst_element_get_pad (src, "src"); pad = gst_element_get_static_pad (src, "src");
gst_pad_add_buffer_probe (pad, G_CALLBACK (cb_have_data), NULL); gst_pad_add_probe (pad, GST_PAD_PROBE_TYPE_BUFFER,
(GstPadProbeCallback) cb_have_data, NULL, NULL);
gst_object_unref (pad); gst_object_unref (pad);
/* run */ /* run */
@ -150,17 +147,14 @@ main (gint argc,
<para> <para>
The above example is not really correct though. Strictly speaking, a The above example is not really correct though. Strictly speaking, a
pad probe callback is only allowed to modify the buffer content if the pad probe callback is only allowed to modify the buffer content if the
buffer is writable, and it is only allowed to modify buffer metadata like buffer is writable. Whether this is the case or not depends a lot on
timestamps, caps, etc. if the buffer metadata is writable. Whether this the pipeline and the elements involved. Often enough, this is the case,
is the case or not depends a lot on the pipeline and the elements but sometimes it is not, and if it is not then unexpected modification
involved. Often enough, this is the case, but sometimes it is not, of the data or metadata can introduce bugs that are very hard to debug
and if it is not then unexpected modification of the data or metadata and track down. You can check if a buffer is writable with
can introduce bugs that are very hard to debug and track down. You can <function>gst_buffer_is_writable ()</function>. Since you
check if a buffer and its metadata are writable with can pass back a different buffer than the one passed in, it is a good
<function>gst_buffer_is_writable ()</function> and idea to make the buffer writable in the callback function.
<function>gst_buffer_is_metadata_writable ()</function>. Since you
can't pass back a different buffer than the one passed in, there is no
point of making a buffer writable in the callback function.
</para> </para>
<para> <para>
Pad probes are suited best for looking at data as it passes through Pad probes are suited best for looking at data as it passes through
@ -364,11 +358,12 @@ main (gint argc,
contains an initialization function (usually called contains an initialization function (usually called
<function>plugin_init</function>) that will be called right after that. <function>plugin_init</function>) that will be called right after that.
It's purpose is to register the elements provided by the plugin with It's purpose is to register the elements provided by the plugin with
the &GStreamer; framework. If you want to embed elements directly in the &GStreamer; framework.
If you want to embed elements directly in
your application, the only thing you need to do is to replace your application, the only thing you need to do is to replace
<function>GST_PLUGIN_DEFINE ()</function> with <function>GST_PLUGIN_DEFINE ()</function> with a call to
<function>GST_PLUGIN_DEFINE_STATIC ()</function>. This will cause the <function>gst_plugin_register_static ()</function>. As soon as you
elements to be registered when your application loads, and the elements call <function>gst_plugin_register_static ()</function>, the elements
will from then on be available like any other element, without them will from then on be available like any other element, without them
having to be dynamically loadable libraries. In the example below, you having to be dynamically loadable libraries. In the example below, you
would be able to call <function>gst_element_factory_make would be able to call <function>gst_element_factory_make
@ -390,17 +385,25 @@ register_elements (GstPlugin *plugin)
GST_RANK_NONE, MY_PLUGIN_TYPE); GST_RANK_NONE, MY_PLUGIN_TYPE);
} }
GST_PLUGIN_DEFINE_STATIC ( static
GST_VERSION_MAJOR, my_code_init (void)
GST_VERSION_MINOR, {
"my-private-plugins", ...
"Private elements of my application",
register_elements, gst_plugin_register_static (
VERSION, GST_VERSION_MAJOR,
"LGPL", GST_VERSION_MINOR,
"my-application", "my-private-plugins",
"http://www.my-application.net/" "Private elements of my application",
) register_elements,
VERSION,
"LGPL",
"my-application-source",
"my-application",
"http://www.my-application.net/")
...
}
</programlisting> </programlisting>
</sect1> </sect1>
</chapter> </chapter>

110
docs/manual/advanced-interfaces.xml
View file

@ -48,78 +48,6 @@
</para> </para>
</sect1> </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>
<para>
You should not use this interface for volume control in a playback
application. Either use a <classname>volume</classname> element or use
<classname>playbin</classname>'s <quote>volume</quote> property, or use
the <classname>audiosink</classname>'s <quote>volume</quote> property (if it has one).
</para>
<note>
<para>
In order for the <ulink type="http"
url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-libs/html/gst-plugins-base-libs-gstmixer.html"><classname>GstMixer</classname></ulink>
interface to be
usable, the element implementing it needs to be in the right state,
so that the underlying mixer device is open. This usually means the
element needs to be at least in <classname>GST_STATE_READY</classname>
before you can use this interface. You will get confusing warnings
if the element is not in the right state when the interface is used.
</para>
</note>
</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 then 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>
<note>
<para>
In order for the <ulink type="http"
url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-libs/html/gst-plugins-base-libs-gsttuner.html"><classname>GstTuner</classname></ulink>
interface to be
usable, the element implementing it needs to be in the right state,
so that the underlying device is open. This usually means the
element needs to be at least in <classname>GST_STATE_READY</classname>
before you can use this interface. You will get confusing warnings
if the element is not in the right state when the interface is used.
</para>
</note>
</sect1>
<sect1 id="section-interfaces-colorbalance"> <sect1 id="section-interfaces-colorbalance">
<title>The Color Balance interface</title> <title>The Color Balance interface</title>
@ -132,45 +60,23 @@
</para> </para>
<para> <para>
The colorbalance interface is implemented by several plugins, including The colorbalance interface is implemented by several plugins, including
xvimagesink and the Video4linux and Video4linux2 elements. xvimagesink and the Video4linux2 elements.
</para> </para>
</sect1> </sect1>
<sect1 id="section-interfaces-proprobe"> <sect1 id="section-interfaces-videooverlay">
<title>The Property Probe interface</title> <title>The Video Overlay interface</title>
<para> <para>
The property probe is a way to autodetect allowed values for a The Video Overlay interface was created to solve the problem of embedding
<classname>GObject</classname> property. It's primary use 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.
</para>
<note>
<para>
Given the overlap between HAL and the practical implementations of this
interface, this might in time be deprecated in favour of HAL.
</para>
</note>
<para>
This interface is currently implemented by many elements, including
the ALSA, OSS, XVideo, 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 video streams in an application window. The application provides an
X-window to the element implementing this interface to draw on, and window handle to the element implementing this interface to draw on, and
the element will then use this X-window to draw on rather than creating the element will then use this window handle to draw on rather than creating
a new toplevel window. This is useful to embed video in video players. a new toplevel window. This is useful to embed video in video players.
</para> </para>
<para> <para>
This interface is implemented by, amongst others, the Video4linux and This interface is implemented by, amongst others, the Video4linux2
Video4linux2 elements and by ximagesink, xvimagesink and sdlvideosink. elements and by ximagesink, xvimagesink and sdlvideosink.
</para> </para>
</sect1> </sect1>
</chapter> </chapter>

18
docs/manual/advanced-threads.xml
View file

@ -80,16 +80,14 @@
<title>Scheduling in &GStreamer;</title> <title>Scheduling in &GStreamer;</title>
<para> <para>
Scheduling of pipelines in &GStreamer; is done by using a thread for Each element in the &GStreamer; pipeline decides how it is going to
each <quote>group</quote>, where a group is a set of elements separated be scheduled. Elements can choose to be scheduled push-based or
by <quote>queue</quote> elements. Within such a group, scheduling is pull-based.
either push-based or pull-based, depending on which mode is supported If elements support random access to data, such as file sources,
by the particular element. If elements support random access to data, then elements downstream in the pipeline can ask to schedule the random
such as file sources, then elements downstream in the pipeline become access elements in pull-based mode. Data is pulled from upstream
the entry point of this group (i.e. the element controlling the and pushed downstream. If pull-mode is not supported, the element can
scheduling of other elements). The entry point pulls data from upstream decide to operate in push-mode.
and pushes data downstream, thereby calling data handling functions on
either type of element.
</para> </para>
<para> <para>
In practice, most elements in &GStreamer;, such as decoders, encoders, In practice, most elements in &GStreamer;, such as decoders, encoders,

10
docs/manual/appendix-checklist.xml
View file

@ -74,7 +74,7 @@
For example, <option>--gst-debug=oggdemux:5</option> would turn For example, <option>--gst-debug=oggdemux:5</option> would turn
on debugging for the Ogg demuxer element. You can use wildcards as on debugging for the Ogg demuxer element. You can use wildcards as
well. A debugging level of 0 will turn off all debugging, and a level well. A debugging level of 0 will turn off all debugging, and a level
of 5 will turn on all debugging. Intermediate values only turn on of 9 will turn on all debugging. Intermediate values only turn on
some debugging (based on message severity; 2, for example, will only some debugging (based on message severity; 2, for example, will only
display errors and warnings). Here's a list of all available options: display errors and warnings). Here's a list of all available options:
</para> </para>
@ -187,13 +187,5 @@
</para> </para>
</sect2> </sect2>
<sect2 id="section-applications-gst-editor">
<title>GstEditor</title>
<para>
GstEditor is a set of widgets to display a graphical representation of a
pipeline.
</para>
</sect2>
</sect1> </sect1>
</chapter> </chapter>

9
docs/manual/appendix-integration.xml
View file

@ -23,16 +23,15 @@
<para> <para>
For audio input and output, &GStreamer; provides input and For audio input and output, &GStreamer; provides input and
output elements for several audio subsystems. Amongst others, output elements for several audio subsystems. Amongst others,
&GStreamer; includes elements for ALSA (alsasrc, alsamixer, &GStreamer; includes elements for ALSA (alsasrc,
alsasink), OSS (osssrc, ossmixer, osssink) and Sun audio alsasink), OSS (osssrc, osssink) Pulesaudio (pulsesrc, pulsesink)
(sunaudiosrc, sunaudiomixer, sunaudiosink). and Sun audio (sunaudiosrc, sunaudiomixer, sunaudiosink).
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
For video input, &GStreamer; contains source elements for For video input, &GStreamer; contains source elements for
Video4linux (v4lsrc, v4lmjpegsrc, v4lelement and v4lmjpegisnk) Video4linux2 (v4l2src, v4l2element, v4l2sink).
and Video4linux2 (v4l2src, v4l2element).
</para> </para>
</listitem> </listitem>
<listitem> <listitem>

175
docs/manual/appendix-porting.xml
View file

@ -128,3 +128,178 @@
</itemizedlist> </itemizedlist>
</sect1> </sect1>
</chapter> </chapter>
<chapter id="chapter-porting-1.0">
<title>Porting 0.10 applications to 1.0</title>
<para>
This section of the appendix will discuss shortly what changes to
applications will be needed to quickly and conveniently port most
applications from &GStreamer;-0.10 to &GStreamer;-1.0, with references
to the relevant sections in this Application Development Manual
where needed. With this list, it should be possible to port simple
applications to &GStreamer;-1.0 in less than a day.
</para>
<sect1 id="section-porting-objects-1.0">
<title>List of changes</title>
<itemizedlist>
<listitem>
<para>
All deprecated methods were removed. Recompile against 0.10 with
DISABLE_DEPRECATED and fix issues before attempting to port to 1.0.
</para>
</listitem>
<listitem>
<para>
"playbin2" has been renamed to "playbin", with similar API
</para>
</listitem>
<listitem>
<para>
"decodebin2" has been renamed to "decodebin", with similar API. Note
that there is no longer a "new-decoded-pad" signal, just use GstElement's
"pad-added" signal instead (but don't forget to remove the 'gboolean last'
argument from your old signal callback functino signature).
</para>
</listitem>
<listitem>
<para>
the names of some "formatted" pad templates has been changed from e.g.
"src%d" to "src%u" or "src_%u" or similar, since we don't want to see
negative numbers in pad names. This mostly affects applications that
create request pads from elements.
</para>
</listitem>
<listitem>
<para>
some elements that used to have a single dynamic source pad have a
source pad now. Example: wavparse, id3demux, iceydemux, apedemux.
(This does not affect applications using decodebin or playbin).
</para>
</listitem>
<listitem>
<para>
playbin now proxies the GstVideoOverlay (former GstXOverlay) interface,
so most applications can just remove the sync bus handler where they
would set the window ID, and instead just set the window ID on playbin
from the application thread before starting playback.
</para>
<para>
playbin also proxies the GstColorBalance and GstNavigation interfaces,
so applications that use this don't need to go fishing for elements
that may implement those any more, but can just use them unconditionally.
</para>
</listitem>
<listitem>
<para>
multifdsink, tcpclientsink, tcpclientsrc, tcpserversrc the protocol property
is removed, use gdppay and gdpdepay.
</para>
</listitem>
<listitem>
<para>
XML serialization was removed.
</para>
</listitem>
<listitem>
<para>
Probes and pad blocking was merged into new pad probes.
</para>
</listitem>
<listitem>
<para>
Position, duration and convert functions no longer use an inout parameter
for the destination format.
</para>
</listitem>
<listitem>
<para>
Video and audio caps were simplified. audio/x-raw-int and audio/x-raw-float
are now all under the audio/x-raw media type. Similarly, video/x-raw-rgb
and video/x-raw-yuv are now video/x-raw.
</para>
</listitem>
<listitem>
<para>
ffmpegcolorspace was removed and replaced with videoconvert.
</para>
</listitem>
<listitem>
<para>
GstMixerInterface / GstTunerInterface were removed without replacement.
</para>
</listitem>
<listitem>
<para>
The GstXOverlay interface was renamed to GstVideoOverlay, and now part
of the video library in gst-plugins-base, as the interfaces library
no longer exists.
</para>
<para>
The name of the GstXOverlay "prepare-xwindow-id" message has changed
to "prepare-window-handle" (and GstXOverlay has been renamed to
GstVideoOverlay). Code that checks for the string directly should be
changed to use gst_is_video_overlay_prepare_window_handle_message(message)
instead.
</para>
</listitem>
<listitem>
<para>
The GstPropertyProbe interface was removed. the is no replacement yet,
but a more featureful replacement for device discovery and feature
querying is planned, see https://bugzilla.gnome.org/show_bug.cgi?id=678402
</para>
</listitem>
<listitem>
<para>
gst_uri_handler_get_uri() and the get_uri vfunc now return a copy of
the URI string
</para>
<para>
gst_uri_handler_set_uri() and the set_uri vfunc now take an additional
GError argument so the handler can notify the caller why it didn't
accept a particular URI.
</para>
<para>
gst_uri_handler_set_uri() now checks if the protocol of the URI passed
is one of the protocols advertised by the uri handler, so set_uri vfunc
implementations no longer need to check that as well.
</para>
</listitem>
<listitem>
<para>
GstTagList is now an opaque mini object instead of being typedefed to a
GstStructure. While it was previously okay (and in some cases required because of
missing taglist API) to cast a GstTagList to a GstStructure or use
gst_structure_* API on taglists, you can no longer do that. Doing so will
cause crashes.
</para>
<para>
Also, tag lists are refcounted now, and can therefore not be freely
modified any longer. Make sure to call gst_tag_list_make_writable (taglist)
before adding, removing or changing tags in the taglist.
</para>
<para>
GST_TAG_IMAGE, GST_TAG_PREVIEW_IMAGE, GST_TAG_ATTACHMENT: many tags that
used to be of type GstBuffer are now of type GstSample (which is basically
a struct containing a buffer alongside caps and some other info).
</para>
</listitem>
<listitem>
<para>
GstController has now been merged into GstObject. It does not exists as an
individual object anymore. In addition core contains a GstControlSource base
class and the GstControlBinding. The actual control sources are in the controller
library as before. The 2nd big change is that control sources generate
a sequence of gdouble values and those are mapped to the property type and
value range by GstControlBindings.
</para>
<para>
The whole gst_controller_* API is gone and now available in simplified form
under gst_object_*. ControlSources are now attached via GstControlBinding
to properties. There are no GValue arguments used anymore when programming
control sources.
</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>

21
docs/manual/basics-bins.xml
View file

@ -19,11 +19,8 @@
</para> </para>
<para> <para>
The bin will also manage the elements contained in it. It will The bin will also manage the elements contained in it. It will
figure out how the data will flow in the bin and generate an perform state changes on the elements as well as collect and
optimal plan for that data flow. Plan generation is one of the forward bus messages.
most complicated procedures in &GStreamer;. You will learn more
about this process, called scheduling, in <xref
linkend="section-threads-scheduling"/>.
</para> </para>
<figure float="1" id="section-bin-img"> <figure float="1" id="section-bin-img">
@ -42,10 +39,10 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
A pipeline: a generic container that allows scheduling of the A pipeline: a generic container that manages the synchronization
containing elements. The toplevel bin has to be a pipeline, and bus messages of the contained elements. The toplevel bin has
every application thus needs at least one of these. Pipelines will to be a pipeline, every application thus needs at least one of
automatically run themselves in a background thread when started. these.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -139,17 +136,17 @@ main (int argc,
</programlisting> </programlisting>
<para> <para>
(This is a silly example of course, there already exists a much more (This is a silly example of course, there already exists a much more
powerful and versatile custom bin like this: the playbin2 element.) powerful and versatile custom bin like this: the playbin element.)
</para> </para>
<para> <para>
Custom bins can be created with a plugin or an XML description. You Custom bins can be created with a plugin or from the application. You
will find more information about creating custom bin in the <ulink will find more information about creating custom bin in the <ulink
type="http" type="http"
url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
Writers Guide</ulink>. Writers Guide</ulink>.
</para> </para>
<para> <para>
Examples of such custom bins are the playbin2 and uridecodebin elements from<ulink Examples of such custom bins are the playbin and uridecodebin elements from<ulink
type="http" type="http"
url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/index.html"> url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/index.html">
gst-plugins-base</ulink>. gst-plugins-base</ulink>.

4
docs/manual/basics-bus.xml
View file

@ -97,6 +97,7 @@ main (gint argc,
{ {
GstElement *pipeline; GstElement *pipeline;
GstBus *bus; GstBus *bus;
guint bus_watch_id;
/* init */ /* init */
gst_init (&amp;argc, &amp;argv); gst_init (&amp;argc, &amp;argv);
@ -109,7 +110,7 @@ main (gint argc,
* GLib main loop is attached to below * GLib main loop is attached to below
*/ */
bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline)); bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
gst_bus_add_watch (bus, my_bus_callback, NULL); bus_watch_id = gst_bus_add_watch (bus, my_bus_callback, NULL);
gst_object_unref (bus); gst_object_unref (bus);
<!-- example-end bus.c a --> <!-- example-end bus.c a -->
[..]<!-- example-begin bus.c b --> [..]<!-- example-begin bus.c b -->
@ -127,6 +128,7 @@ main (gint argc,
/* clean up */ /* clean up */
gst_element_set_state (pipeline, GST_STATE_NULL); gst_element_set_state (pipeline, GST_STATE_NULL);
gst_object_unref (pipeline); gst_object_unref (pipeline);
g_source_remove (bus_watch_id);
g_main_loop_unref (loop); g_main_loop_unref (loop);
return 0; return 0;

8
docs/manual/basics-data.xml
View file

@ -24,12 +24,8 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
A pointer to a piece of memory. Pointers to memory objects. Memory objects encapsulate a region
</para> in the memory.
</listitem>
<listitem>
<para>
The size of the memory.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>

9
docs/manual/basics-elements.xml
View file

@ -289,7 +289,7 @@ main (int argc,
The Glib Object system</ulink>. The Glib Object system</ulink>.
</para> </para>
<para> <para>
A <ulink type="http" url="&URLAPI;GstElementFactory.html"> A <ulink type="http" url="&URLAPI;GstElement.html">
<classname>GstElement</classname></ulink> also provides various <classname>GstElement</classname></ulink> also provides various
<classname>GObject</classname> signals that can be used as a flexible <classname>GObject</classname> signals that can be used as a flexible
callback mechanism. Here, too, you can use <command>gst-inspect</command> callback mechanism. Here, too, you can use <command>gst-inspect</command>
@ -303,17 +303,14 @@ main (int argc,
<title>More about element factories</title> <title>More about element factories</title>
<para> <para>
In the previous section, we briefly introduced the <ulink type="http" In the previous section, we briefly introduced the <ulink type="http"
url="&URLAPI;GstElement.html"><classname>GstElementFactory</classname></ulink> url="&URLAPI;GstElementFactory.html"><classname>GstElementFactory</classname></ulink>
object already as a way to create instances of an element. Element object already as a way to create instances of an element. Element
factories, however, are much more than just that. Element factories factories, however, are much more than just that. Element factories
are the basic types retrieved from the &GStreamer; registry, they are the basic types retrieved from the &GStreamer; registry, they
describe all plugins and elements that &GStreamer; can create. This describe all plugins and elements that &GStreamer; can create. This
means that element factories are useful for automated element means that element factories are useful for automated element
instancing, such as what autopluggers do, and for creating lists instancing, such as what autopluggers do, and for creating lists
of available elements, such as what pipeline editing applications of available elements.
(e.g. <ulink type="http"
url="http://gstreamer.freedesktop.org/modules/gst-editor.html">&GStreamer;
Editor</ulink>) do.
</para> </para>
<sect2 id="section-elements-factories-details"> <sect2 id="section-elements-factories-details">

9
docs/manual/basics-helloworld.xml
View file

@ -44,8 +44,8 @@
</para> </para>
<para> <para>
The last thing left to do is to add all elements into a container The last thing left to do is to add all elements into a container
element, a <classname>GstPipeline</classname>, and iterate this element, a <classname>GstPipeline</classname>, and wait until
pipeline until we've played the whole song. We've previously we've played the whole song. We've previously
learned how to add elements to a container bin in <xref learned how to add elements to a container bin in <xref
linkend="chapter-bins"/>, and we've learned about element states linkend="chapter-bins"/>, and we've learned about element states
in <xref linkend="section-elements-states"/>. We will also attach in <xref linkend="section-elements-states"/>. We will also attach
@ -125,6 +125,7 @@ main (int argc,
GstElement *pipeline, *source, *demuxer, *decoder, *conv, *sink; GstElement *pipeline, *source, *demuxer, *decoder, *conv, *sink;
GstBus *bus; GstBus *bus;
guint bus_watch_id;
/* Initialisation */ /* Initialisation */
gst_init (&amp;argc, &amp;argv); gst_init (&amp;argc, &amp;argv);
@ -159,7 +160,7 @@ main (int argc,
/* we add a message handler */ /* we add a message handler */
bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline)); bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
gst_bus_add_watch (bus, bus_call, loop); bus_watch_id = gst_bus_add_watch (bus, bus_call, loop);
gst_object_unref (bus); gst_object_unref (bus);
/* we add all elements into the pipeline */ /* we add all elements into the pipeline */
@ -197,6 +198,8 @@ main (int argc,
g_print ("Deleting pipeline\n"); g_print ("Deleting pipeline\n");
gst_object_unref (GST_OBJECT (pipeline)); gst_object_unref (GST_OBJECT (pipeline));
g_source_remove (bus_watch_id);
g_main_loop_unref (loop);
return 0; return 0;
} }

17
docs/manual/highlevel-components.xml
View file

@ -172,12 +172,9 @@ main (gint argc,
</itemizedlist> </itemizedlist>
<para> <para>
For convenience, it is possible to test <quote>playbin</quote> on For convenience, it is possible to test <quote>playbin</quote> on
the commandline, using the command <quote>gst-launch-0.10 playbin the commandline, using the command <quote>gst-launch-1.0 playbin
uri=file:///path/to/file</quote>. uri=file:///path/to/file</quote>.
</para> </para>
<para>
New applications should use playbin2 instead of the old playbin.
</para>
</sect1> </sect1>
<sect1 id="section-components-decodebin"> <sect1 id="section-components-decodebin">
@ -189,7 +186,7 @@ main (gint argc,
input from a source that is linked to its sinkpad and will try to input from a source that is linked to its sinkpad and will try to
detect the media type contained in the stream, and set up decoder detect the media type contained in the stream, and set up decoder
routines for each of those. It will automatically select decoders. routines for each of those. It will automatically select decoders.
For each decoded stream, it will emit the <quote>new-decoded-pad</quote> For each decoded stream, it will emit the <quote>pad-added</quote>
signal, to let the client know about the newly found decoded stream. signal, to let the client know about the newly found decoded stream.
For unknown streams (which might be the whole stream), it will emit For unknown streams (which might be the whole stream), it will emit
the <quote>unknown-type</quote> signal. The application is then the <quote>unknown-type</quote> signal. The application is then
@ -238,7 +235,6 @@ GstElement *pipeline, *audio;
static void static void
cb_newpad (GstElement *decodebin, cb_newpad (GstElement *decodebin,
GstPad *pad, GstPad *pad,
gboolean last,
gpointer data) gpointer data)
{ {
GstCaps *caps; GstCaps *caps;
@ -297,7 +293,7 @@ main (gint argc,
src = gst_element_factory_make ("filesrc", "source"); src = gst_element_factory_make ("filesrc", "source");
g_object_set (G_OBJECT (src), "location", argv[1], NULL); g_object_set (G_OBJECT (src), "location", argv[1], NULL);
dec = gst_element_factory_make ("decodebin", "decoder"); dec = gst_element_factory_make ("decodebin", "decoder");
g_signal_connect (dec, "new-decoded-pad", G_CALLBACK (cb_newpad), NULL); g_signal_connect (dec, "pad-added", G_CALLBACK (cb_newpad), NULL);
gst_bin_add_many (GST_BIN (pipeline), src, dec, NULL); gst_bin_add_many (GST_BIN (pipeline), src, dec, NULL);
gst_element_link (src, dec); gst_element_link (src, dec);
@ -367,14 +363,11 @@ main (gint argc,
</itemizedlist> </itemizedlist>
<para> <para>
Decodebin can be easily tested on the commandline, e.g. by using the Decodebin can be easily tested on the commandline, e.g. by using the
command <command>gst-launch-0.10 filesrc location=file.ogg ! decodebin command <command>gst-launch-1.0 filesrc location=file.ogg ! decodebin
! audioconvert ! audioresample ! autoaudiosink</command>. ! audioconvert ! audioresample ! autoaudiosink</command>.
</para> </para>
<para> <para>
New applications should use decodebin2 instead of the old decodebin. The uridecodebin element is very similar to decodebin, only that it
</para>
<para>
The uridecodebin element is very similar to decodebin2, only that it
automatically plugs a source plugin based on the protocol of the URI automatically plugs a source plugin based on the protocol of the URI
given. given.
</para> </para>

19
docs/manual/intro-basics.xml
View file

@ -59,10 +59,10 @@
through one or more <emphasis>sink pads</emphasis>. Source and sink through one or more <emphasis>sink pads</emphasis>. Source and sink
elements have only source and sink pads, respectively. Data usually elements have only source and sink pads, respectively. Data usually
means buffers (described by the <ulink type="http" means buffers (described by the <ulink type="http"
url="&URLAPI;gstreamer-GstBuffer.html"><classname>GstBuffer url="&URLAPI;gstreamer-GstBuffer.html">
</classname></ulink> object) and events (described by the <ulink <classname>GstBuffer</classname></ulink> object) and events (described
type="http" url="&URLAPI;gstreamer-GstEvent.html"><classname> by the <ulink type="http" url="&URLAPI;gstreamer-GstEvent.html">
GstEvent</classname></ulink> object). <classname>GstEvent</classname></ulink> object).
</para> </para>
</sect1> </sect1>
@ -71,8 +71,7 @@
<para> <para>
A <emphasis>bin</emphasis> is a container for a collection of elements. A <emphasis>bin</emphasis> is a container for a collection of elements.
A <emphasis>pipeline</emphasis> is a special subtype of a bin that allows execution of all Since bins are subclasses of elements
of its contained child elements. Since bins are subclasses of elements
themselves, you can mostly control a bin as if it were an element, themselves, you can mostly control a bin as if it were an element,
thereby abstracting away a lot of complexity for your application. You thereby abstracting away a lot of complexity for your application. You
can, for example change state on all elements in a bin by changing the can, for example change state on all elements in a bin by changing the
@ -80,9 +79,11 @@
contained children (such as error messages, tag messages or EOS messages). contained children (such as error messages, tag messages or EOS messages).
</para> </para>
<para> <para>
A <emphasis>pipeline</emphasis> is a top-level bin. As you set it to PAUSED or PLAYING state, A <emphasis>pipeline</emphasis> is a top-level bin. It provides a bus for
data flow will start and media processing will take place. Once started, the application and manages the synchronization for its children.
pipelines will run in a separate thread until you stop them or the end As you set it to PAUSED or PLAYING state, data flow will start and media
processing will take place. Once started, pipelines will run in a
separate thread until you stop them or the end
of the data stream is reached. of the data stream is reached.
</para> </para>

8
docs/manual/manual.xml
View file

@ -47,7 +47,6 @@
<!ENTITY DATAACCESS SYSTEM "advanced-dataaccess.xml"> <!ENTITY DATAACCESS SYSTEM "advanced-dataaccess.xml">
<!-- Part 4: Higher-level interfaces --> <!-- Part 4: Higher-level interfaces -->
<!ENTITY XML SYSTEM "highlevel-xml.xml">
<!ENTITY COMPONENTS SYSTEM "highlevel-components.xml"> <!ENTITY COMPONENTS SYSTEM "highlevel-components.xml">
<!-- Appendices --> <!-- Appendices -->
@ -191,8 +190,8 @@
much control (and as much code), but will prefer to use a standard much control (and as much code), but will prefer to use a standard
playback interface that does most of the difficult internals for playback interface that does most of the difficult internals for
them. In this chapter, we will introduce you into the concept of them. In this chapter, we will introduce you into the concept of
autopluggers, playback managing elements, XML-based pipelines and autopluggers, playback managing elements and other such things.
other such things. Those higher-level interfaces are intended to Those higher-level interfaces are intended to
simplify &GStreamer;-based application programming. They do, however, simplify &GStreamer;-based application programming. They do, however,
also reduce the flexibility. It is up to the application developer also reduce the flexibility. It is up to the application developer
to choose which interface he will want to use. to choose which interface he will want to use.
@ -200,7 +199,6 @@
</partintro> </partintro>
&COMPONENTS; &COMPONENTS;
&XML;
</part> </part>
@ -221,7 +219,7 @@
</para> </para>
<para> <para>
In addition, we also provide a porting guide which will explain In addition, we also provide a porting guide which will explain
easily how to port &GStreamer;-0.8 applications to &GStreamer;-0.10. easily how to port &GStreamer;-0.10 applications to &GStreamer;-1.0.
</para> </para>
</partintro> </partintro>

4
docs/random/porting-to-1.0.txt
View file

@ -207,8 +207,8 @@ GStreamer 0.10 to 1.0 porting guide
The GST_MINI_OBJECT_READONLY flag was removed as it used to mark the The GST_MINI_OBJECT_READONLY flag was removed as it used to mark the
memory in buffers as READONLY. Marking memory READONLY can now be done memory in buffers as READONLY. Marking memory READONLY can now be done
with the GstMemory API. Writability of miniobjects is now only done by using with the GstMemory API. Writability of miniobjects is now either done
the refcount. by using the refcount or by using exclusive locking.
* GstBuffer * GstBuffer
A GstBuffer is now a simple boxed type this means that subclassing is not A GstBuffer is now a simple boxed type this means that subclassing is not

5
tests/examples/manual/Makefile.am
View file

@ -35,6 +35,7 @@ EXAMPLES = \
init \ init \
query \ query \
typefind \ typefind \
probe \
fakesrc \ fakesrc \
playbin \ playbin \
decodebin decodebin
@ -48,6 +49,7 @@ BUILT_SOURCES = \
init.c \ init.c \
query.c \ query.c \
typefind.c dynamic.c \ typefind.c dynamic.c \
probe.c \
fakesrc.c \ fakesrc.c \
playbin.c decodebin.c playbin.c decodebin.c
@ -81,6 +83,9 @@ query.c: $(top_srcdir)/docs/manual/advanced-position.xml
typefind.c dynamic.c: $(top_srcdir)/docs/manual/advanced-autoplugging.xml typefind.c dynamic.c: $(top_srcdir)/docs/manual/advanced-autoplugging.xml
$(PERL_PATH) $(srcdir)/extract.pl $@ $< $(PERL_PATH) $(srcdir)/extract.pl $@ $<
probe.c: $(top_srcdir)/docs/manual/advanced-dataaccess.xml
$(PERL_PATH) $(srcdir)/extract.pl $@ $<
fakesrc.c: $(top_srcdir)/docs/manual/advanced-dataaccess.xml fakesrc.c: $(top_srcdir)/docs/manual/advanced-dataaccess.xml
$(PERL_PATH) $(srcdir)/extract.pl $@ $< $(PERL_PATH) $(srcdir)/extract.pl $@ $<