mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-26 02:00:33 +00:00
7c24fc7450
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...
305 lines
13 KiB
XML
305 lines
13 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 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>
|