| <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> |