mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-28 03:00:35 +00:00
316 lines
14 KiB
XML
316 lines
14 KiB
XML
<chapter id="chapter-porting">
|
|
<title>Porting 0.8 applications to 0.10</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.8 to &GStreamer;-0.10, 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;-0.10 in less than a day.
|
|
</para>
|
|
|
|
<sect1 id="section-porting-objects">
|
|
<title>List of changes</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Most functions returning an object or an object property have
|
|
been changed to return its own reference rather than a constant
|
|
reference of the one owned by the object itself. The reason for
|
|
this change is primarily thread safety. This means, effectively,
|
|
that return values of functions such as
|
|
<function>gst_element_get_pad ()</function>,
|
|
<function>gst_pad_get_name ()</function> and many more like these
|
|
have to be free'ed or unreferenced after use. Check the API
|
|
references of each function to know for sure whether return
|
|
values should be free'ed or not. It is important that all objects
|
|
derived from GstObject are ref'ed/unref'ed using gst_object_ref()
|
|
and gst_object_unref() respectively (instead of g_object_ref/unref).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Applications should no longer use signal handlers to be notified
|
|
of errors, end-of-stream and other similar pipeline events.
|
|
Instead, they should use the <classname>GstBus</classname>, which
|
|
has been discussed in <xref linkend="chapter-bus"/>. The bus will
|
|
take care that the messages will be delivered in the context of a
|
|
main loop, which is almost certainly the application's main thread.
|
|
The big advantage of this is that applications no longer need to
|
|
be thread-aware; they don't need to use <function>g_idle_add
|
|
()</function> in the signal handler and do the actual real work
|
|
in the idle-callback. &GStreamer; now does all that internally.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Related to this, <function>gst_bin_iterate ()</function> has been
|
|
removed. Pipelines will iterate in their own thread, and applications
|
|
can simply run a <classname>GMainLoop</classname> (or call the
|
|
mainloop of their UI toolkit, such as <function>gtk_main
|
|
()</function>).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
State changes can be delayed (ASYNC). Due to the new fully threaded
|
|
nature of GStreamer-0.10, state changes are not always immediate,
|
|
in particular changes including the transition from READY to PAUSED
|
|
state. This means two things in the context of porting applications:
|
|
first of all, it is no longer always possible to do
|
|
<function>gst_element_set_state ()</function> and check for a return
|
|
value of GST_STATE_CHANGE_SUCCESS, as the state change might be
|
|
delayed (ASYNC) and the result will not be known until later. You
|
|
should still check for GST_STATE_CHANGE_FAILURE right away, it is
|
|
just no longer possible to assume that everything that is not SUCCESS
|
|
means failure. Secondly, state changes might not be immediate, so
|
|
your code needs to take that into account. You can wait for a state
|
|
change to complete if you use GST_CLOCK_TIME_NONE as timeout interval
|
|
with <function>gst_element_get_state ()</function>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
In 0.8, events and queries had to manually be sent to sinks in
|
|
pipelines (unless you were using playbin). This is no longer
|
|
the case in 0.10. In 0.10, queries and events can be sent to
|
|
toplevel pipelines, and the pipeline will do the dispatching
|
|
internally for you. This means less bookkeeping in your
|
|
application. For a short code example, see <xref
|
|
linkend="chapter-queryevents"/>. Related, seeking is now
|
|
threadsafe, and your video output will show the new video
|
|
position's frame while seeking, providing a better user
|
|
experience.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <classname>GstThread</classname> object has been removed.
|
|
Applications can now simply put elements in a pipeline with
|
|
optionally some <quote>queue</quote> elements in between for
|
|
buffering, and &GStreamer; will take care of creating threads
|
|
internally. It is still possible to have parts of a pipeline
|
|
run in different threads than others, by using the
|
|
<quote>queue</quote> element. See <xref linkend="chapter-threads"/>
|
|
for details.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Filtered caps -> capsfilter element (the pipeline syntax for
|
|
gst-launch has not changed though).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
libgstgconf-0.10.la does not exist. Use the
|
|
<quote>gconfvideosink</quote> and <quote>gconfaudiosink</quote>
|
|
elements instead, which will do live-updates and require no library
|
|
linking.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The <quote>new-pad</quote> and <quote>state-change</quote> signals on
|
|
<classname>GstElement</classname> were renamed to
|
|
<quote>pad-added</quote> and <quote>state-changed</quote>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<function>gst_init_get_popt_table ()</function> has been removed
|
|
in favour of the new GOption command line option API that was
|
|
added to GLib 2.6. <function>gst_init_get_option_group ()</function>
|
|
is the new GOption-based equivalent to
|
|
<function>gst_init_get_ptop_table ()</function>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
</chapter>
|
|
<chapter id="chapter-porting-1.0">
|
|
<title>Porting 0.10 applications to 1.0</title>
|
|
|
|
<para>This section outlines some of the changes necessary to port
|
|
applications from &GStreamer;-0.10 to &GStreamer;-1.0. For a
|
|
comprehensive and up-to-date list, see the separate <ulink
|
|
type="http"
|
|
url="http://cgit.freedesktop.org/gstreamer/gstreamer/plain/docs/random/porting-to-1.0.txt">
|
|
Porting to 1.0</ulink> document.
|
|
</para>
|
|
<para>
|
|
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
|
|
GST_DISABLE_DEPRECATED defined (such as by adding
|
|
-DGST_DISABLE_DEPRECATED to the compiler flags) 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 on playbin
|
|
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. There is no replacement
|
|
for it in GStreamer 1.0.x and 1.2.x, but since version 1.4 there is
|
|
a more featureful replacement for device discovery and feature
|
|
querying provided by GstDeviceMonitor, GstDevice, and friends. See
|
|
the <ulink type="http"
|
|
url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-device-probing.html">
|
|
"GStreamer Device Discovery and Device Probing" documentation</ulink>.
|
|
</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>
|