docs/manual/appendix-porting.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>