docs/manual/appendix-porting.xml

   1 <chapter id="chapter-porting">
   2   <title>Porting 0.8 applications to 0.9</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.9, 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.9 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 threadsafety. 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.
  27         </para>
  28       </listitem>
  29       <listitem>
  30         <para>
  31           Applications should no longer use signal handlers to be notified
  32           of errors, end-of-stream and other similar pipeline events.
  33           Instead, they should use the <classname>GstBus</classname>, which
  34           has been discussed in <xref linkend="chapter-bus"/>. The bus will
  35           take care that the messages will be delivered in the context of
  36           mainloop, which is almost certainly the application's main thread.
  37           The big advantage of this is that applications no longer need to
  38           be thread-aware; they don't need to use <function>g_idle_add
  39           ()</function> in the signal handler and do the actual real work
  40           in the idle-callback. &GStreamer; now does all that internally.
  41         </para>
  42       </listitem>
  43       <listitem>
  44         <para>
  45           Related to this, <function>gst_bin_iterate ()</function> has been
  46           removed. Pipelines will iterate in their own thread, and applications
  47           can simply run a <classname>GMainLoop</classname> (or call the
  48           mainloop of their UI toolkit, such as <function>gtk_main
  49           ()</function>).
  50         </para>
  51       </listitem>
  52       <listitem>
  53         <para>
  54           State changes can be delayed; ASYNC.
  55         </para>
  56       </listitem>
  57       <listitem>
  58         <para>
  59           In 0.8, events and queries had to manually be sent to sinks in
  60           pipelines (unless you were using playbin). This is no longer
  61           the case in 0.9. In 0.9, queries and events can be sent to
  62           toplevel pipelines, and the pipeline will do the dispatching
  63           internally for you. This means less bookkeeping in your
  64           application. For a short code example, see <xref
  65           linkend="chapter-queryevents"/>. Related, seeking is now
  66           threadsafe, and your video output will show the new video
  67           position's frame while seeking, providing a better user
  68           experience.
  69         </para>
  70       </listitem>
  71       <listitem>
  72         <para>
  73           The <classname>GstThread</classname> object has been removed.
  74           Applications can now simply put elements in a pipeline with
  75           optionally some <quote>queue</quote> elements in between for
  76           buffering, and &GStreamer; will take care of creating threads
  77           internally. It is still possible to have parts of a pipeline
  78           run in different threads than others, by using the
  79           <quote>queue</quote> element. See <xref linkend="chapter-threads"/>
  80           for details.
  81         </para>
  82       </listitem>
  83       <listitem>
  84         <para>
  85           Filtered caps -> caps-filter.
  86         </para>
  87       </listitem>
  88       <listitem>
  89         <para>
  90           libgstgconf-0.9.la does not exist. Use the
  91           <quote>gconfvideosink</quote> and <quote>gconfaudiosink</quote>
  92           elements instead, which will do live-updates and require no library
  93           linking.
  94         </para>
  95       </listitem>
  96     </itemizedlist>
  97   </sect1>
  98 </chapter>