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-dataaccess.xml: * docs/manual/appendix-checklist.xml: * docs/manual/appendix-programs.xml: * docs/manual/basics-pads.xml: * docs/manual/highlevel-components.xml: * docs/manual/manual.xml: Update for 0.10: s/0.9/0.10/; s/audioscale/audiorsample/; add converters in front of pipelines; remove curly brackets for threads stuff, they no longer exist; use GST_TYPE_FRACTION for framerates; update some pieces of code to 0.10, but there's plenty more to do. * docs/manual/appendix-porting.xml: Expand on asynchroneous state changes; s/0.9/0.10/; mention disappearance of gst_init_get_popt_table() (fixes #322916).
130 lines
6.2 KiB
XML
130 lines
6.2 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>
|