docs/manual/appendix-porting.xml

   1 <chapter id="chapter-porting">
   2   <title>Porting 0.8 applications to 0.10</title>
   3   <para>
   4     This section of the appendix will discuss shortly what changes to
   5     applications will be needed to quickly and conveniently port most
   6     applications from &GStreamer;-0.8 to &GStreamer;-0.10, with references
   7     to the relevant sections in this Application Development Manual
   8     where needed. With this list, it should be possible to port simple
   9     applications to &GStreamer;-0.10 in less than a day.
  10   </para>
  11
  12   <sect1 id="section-porting-objects">
  13     <title>List of changes</title>
  14     <itemizedlist>
  15       <listitem>
  16         <para>
  17           Most functions returning an object or an object property have
  18           been changed to return its own reference rather than a constant
  19           reference of the one owned by the object itself. The reason for
  20           this change is primarily thread safety. This means, effectively,
  21           that return values of functions such as
  22           <function>gst_element_get_pad ()</function>,
  23           <function>gst_pad_get_name ()</function> and many more like these
  24           have to be free'ed or unreferenced after use. Check the API
  25           references of each function to know for sure whether return
  26           values should be free'ed or not. It is important that all objects
  27           derived from GstObject are ref'ed/unref'ed using gst_object_ref()
  28           and gst_object_unref() respectively (instead of g_object_ref/unref).
  29         </para>
  30       </listitem>
  31       <listitem>
  32         <para>
  33           Applications should no longer use signal handlers to be notified
  34           of errors, end-of-stream and other similar pipeline events.
  35           Instead, they should use the <classname>GstBus</classname>, which
  36           has been discussed in <xref linkend="chapter-bus"/>. The bus will
  37           take care that the messages will be delivered in the context of a
  38           main loop, which is almost certainly the application's main thread.
  39           The big advantage of this is that applications no longer need to
  40           be thread-aware; they don't need to use <function>g_idle_add
  41           ()</function> in the signal handler and do the actual real work
  42           in the idle-callback. &GStreamer; now does all that internally.
  43         </para>
  44       </listitem>
  45       <listitem>
  46         <para>
  47           Related to this, <function>gst_bin_iterate ()</function> has been
  48           removed. Pipelines will iterate in their own thread, and applications
  49           can simply run a <classname>GMainLoop</classname> (or call the
  50           mainloop of their UI toolkit, such as <function>gtk_main
  51           ()</function>).
  52         </para>
  53       </listitem>
  54       <listitem>
  55         <para>
  56           State changes can be delayed (ASYNC). Due to the new fully threaded
  57           nature of GStreamer-0.10, state changes are not always immediate,
  58           in particular changes including the transition from READY to PAUSED
  59           state. This means two things in the context of porting applications:
  60           first of all, it is no longer always possible to do
  61           <function>gst_element_set_state ()</function> and check for a return
  62           value of GST_STATE_CHANGE_SUCCESS, as the state change might be
  63           delayed (ASYNC) and the result will not be known until later. You
  64           should still check for GST_STATE_CHANGE_FAILURE right away, it is
  65           just no longer possible to assume that everything that is not SUCCESS
  66           means failure. Secondly, state changes might not be immediate, so
  67           your code needs to take that into account. You can wait for a state
  68           change to complete if you use GST_CLOCK_TIME_NONE as timeout interval
  69           with <function>gst_element_get_state ()</function>.
  70         </para>
  71       </listitem>
  72       <listitem>
  73         <para>
  74           In 0.8, events and queries had to manually be sent to sinks in
  75           pipelines (unless you were using playbin). This is no longer
  76           the case in 0.10. In 0.10, queries and events can be sent to
  77           toplevel pipelines, and the pipeline will do the dispatching
  78           internally for you. This means less bookkeeping in your
  79           application. For a short code example, see <xref
  80           linkend="chapter-queryevents"/>. Related, seeking is now
  81           threadsafe, and your video output will show the new video
  82           position's frame while seeking, providing a better user
  83           experience.
  84         </para>
  85       </listitem>
  86       <listitem>
  87         <para>
  88           The <classname>GstThread</classname> object has been removed.
  89           Applications can now simply put elements in a pipeline with
  90           optionally some <quote>queue</quote> elements in between for
  91           buffering, and &GStreamer; will take care of creating threads
  92           internally. It is still possible to have parts of a pipeline
  93           run in different threads than others, by using the
  94           <quote>queue</quote> element. See <xref linkend="chapter-threads"/>
  95           for details.
  96         </para>
  97       </listitem>
  98       <listitem>
  99         <para>
 100           Filtered caps -> capsfilter element (the pipeline syntax for
 101           gst-launch has not changed though).
 102         </para>
 103       </listitem>
 104       <listitem>
 105         <para>
 106           libgstgconf-0.10.la does not exist. Use the
 107           <quote>gconfvideosink</quote> and <quote>gconfaudiosink</quote>
 108           elements instead, which will do live-updates and require no library
 109           linking.
 110         </para>
 111       </listitem>
 112       <listitem>
 113         <para>
 114           The <quote>new-pad</quote> and <quote>state-change</quote> signals on
 115           <classname>GstElement</classname> were renamed to
 116           <quote>pad-added</quote> and <quote>state-changed</quote>.
 117         </para>
 118       </listitem>
 119       <listitem>
 120         <para>
 121           <function>gst_init_get_popt_table ()</function> has been removed
 122           in favour of the new GOption command line option API that was
 123           added to GLib 2.6. <function>gst_init_get_option_group ()</function>
 124           is the new GOption-based equivalent to
 125           <function>gst_init_get_ptop_table ()</function>.
 126         </para>
 127       </listitem>
 128     </itemizedlist>
 129   </sect1>
 130 </chapter>
 131 <chapter id="chapter-porting-1.0">
 132   <title>Porting 0.10 applications to 1.0</title>
 133   <para>
 134     This section of the appendix will discuss shortly what changes to
 135     applications will be needed to quickly and conveniently port most
 136     applications from &GStreamer;-0.10 to &GStreamer;-1.0, with references
 137     to the relevant sections in this Application Development Manual
 138     where needed. With this list, it should be possible to port simple
 139     applications to &GStreamer;-1.0 in less than a day.
 140   </para>
 141
 142   <sect1 id="section-porting-objects-1.0">
 143     <title>List of changes</title>
 144     <itemizedlist>
 145       <listitem>
 146         <para>
 147           All deprecated methods were removed. Recompile against 0.10 with
 148           DISABLE_DEPRECATED and fix issues before attempting to port to 1.0.
 149         </para>
 150       </listitem>
 151       <listitem>
 152         <para>
 153           "playbin2" has been renamed to "playbin", with similar API
 154         </para>
 155       </listitem>
 156       <listitem>
 157         <para>
 158           "decodebin2" has been renamed to "decodebin", with similar API. Note
 159           that there is no longer a "new-decoded-pad" signal, just use GstElement's
 160           "pad-added" signal instead (but don't forget to remove the 'gboolean last'
 161           argument from your old signal callback functino signature).
 162         </para>
 163       </listitem>
 164       <listitem>
 165         <para>
 166           the names of some "formatted" pad templates has been changed from e.g.
 167           "src%d" to "src%u" or "src_%u" or similar, since we don't want to see
 168           negative numbers in pad names. This mostly affects applications that
 169           create request pads from elements.
 170         </para>
 171       </listitem>
 172       <listitem>
 173         <para>
 174           some elements that used to have a single dynamic source pad have a
 175           source pad now. Example: wavparse, id3demux, iceydemux, apedemux.
 176           (This does not affect applications using decodebin or playbin).
 177         </para>
 178       </listitem>
 179       <listitem>
 180         <para>
 181           playbin now proxies the GstVideoOverlay (former GstXOverlay) interface,
 182           so most applications can just remove the sync bus handler where they
 183           would set the window ID, and instead just set the window ID on playbin
 184           from the application thread before starting playback.
 185         </para>
 186         <para>
 187           playbin also proxies the GstColorBalance and GstNavigation interfaces,
 188           so applications that use this don't need to go fishing for elements
 189           that may implement those any more, but can just use them unconditionally.
 190         </para>
 191       </listitem>
 192       <listitem>
 193         <para>
 194           multifdsink, tcpclientsink, tcpclientsrc, tcpserversrc the protocol property
 195           is removed, use gdppay and gdpdepay.
 196         </para>
 197       </listitem>
 198       <listitem>
 199         <para>
 200           XML serialization was removed.
 201         </para>
 202       </listitem>
 203       <listitem>
 204         <para>
 205           Probes and pad blocking was merged into new pad probes.
 206         </para>
 207       </listitem>
 208       <listitem>
 209         <para>
 210           Position, duration and convert functions no longer use an inout parameter
 211           for the destination format.
 212         </para>
 213       </listitem>
 214       <listitem>
 215         <para>
 216           Video and audio caps were simplified. audio/x-raw-int and audio/x-raw-float
 217           are now all under the audio/x-raw media type. Similarly, video/x-raw-rgb
 218           and video/x-raw-yuv are now video/x-raw.
 219         </para>
 220       </listitem>
 221       <listitem>
 222         <para>
 223           ffmpegcolorspace was removed and replaced with videoconvert.
 224         </para>
 225       </listitem>
 226       <listitem>
 227         <para>
 228           GstMixerInterface / GstTunerInterface were removed without replacement.
 229         </para>
 230       </listitem>
 231       <listitem>
 232         <para>
 233           The GstXOverlay interface was renamed to GstVideoOverlay, and now part
 234           of the video library in gst-plugins-base, as the interfaces library
 235           no longer exists.
 236         </para>
 237         <para>
 238           The name of the GstXOverlay "prepare-xwindow-id" message has changed
 239           to "prepare-window-handle" (and GstXOverlay has been renamed to
 240           GstVideoOverlay). Code that checks for the string directly should be
 241           changed to use gst_is_video_overlay_prepare_window_handle_message(message)
 242           instead.
 243         </para>
 244       </listitem>
 245       <listitem>
 246         <para>
 247           The GstPropertyProbe interface was removed. the is no replacement yet,
 248           but a more featureful replacement for device discovery and feature
 249           querying is planned, see https://bugzilla.gnome.org/show_bug.cgi?id=678402
 250         </para>
 251       </listitem>
 252       <listitem>
 253         <para>
 254           gst_uri_handler_get_uri() and the get_uri vfunc now return a copy of
 255           the URI string
 256         </para>
 257         <para>
 258           gst_uri_handler_set_uri() and the set_uri vfunc now take an additional
 259           GError argument so the handler can notify the caller why it didn't
 260           accept a particular URI.
 261         </para>
 262         <para>
 263           gst_uri_handler_set_uri() now checks if the protocol of the URI passed
 264           is one of the protocols advertised by the uri handler, so set_uri vfunc
 265           implementations no longer need to check that as well.
 266         </para>
 267       </listitem>
 268       <listitem>
 269         <para>
 270           GstTagList is now an opaque mini object instead of being typedefed to a
 271           GstStructure. While it was previously okay (and in some cases required because of
 272           missing taglist API) to cast a GstTagList to a GstStructure or use
 273           gst_structure_* API on taglists, you can no longer do that. Doing so will
 274           cause crashes.
 275         </para>
 276         <para>
 277           Also, tag lists are refcounted now, and can therefore not be freely
 278           modified any longer. Make sure to call gst_tag_list_make_writable (taglist)
 279           before adding, removing or changing tags in the taglist.
 280         </para>
 281         <para>
 282           GST_TAG_IMAGE, GST_TAG_PREVIEW_IMAGE, GST_TAG_ATTACHMENT: many tags that
 283           used to be of type GstBuffer are now of type GstSample (which is basically
 284           a struct containing a buffer alongside caps and some other info).
 285         </para>
 286       </listitem>
 287       <listitem>
 288         <para>
 289           GstController has now been merged into GstObject. It does not exists as an
 290           individual object anymore. In addition core contains a GstControlSource base
 291           class and the GstControlBinding. The actual control sources are in the controller
 292           library as before. The 2nd big change is that control sources generate
 293           a sequence of gdouble values and those are mapped to the property type and
 294           value range by GstControlBindings.
 295         </para>
 296         <para>
 297           The whole gst_controller_* API is gone and now available in simplified form
 298           under gst_object_*. ControlSources are now attached via GstControlBinding
 299           to properties. There are no GValue arguments used anymore when programming
 300           control sources.
 301         </para>
 302       </listitem>
 303     </itemizedlist>
 304   </sect1>
 305 </chapter>