manual-porting.md

   1 ---
   2 title: Porting 0.8 applications to 0.10
   3 ...
   4
   5 # Porting 0.8 applications to 0.10
   6
   7 This section of the appendix will discuss shortly what changes to
   8 applications will be needed to quickly and conveniently port most
   9 applications from GStreamer-0.8 to GStreamer-0.10, with references to
  10 the relevant sections in this Application Development Manual where
  11 needed. With this list, it should be possible to port simple
  12 applications to GStreamer-0.10 in less than a day.
  13
  14 ## List of changes
  15
  16   - Most functions returning an object or an object property have been
  17     changed to return its own reference rather than a constant reference
  18     of the one owned by the object itself. The reason for this change is
  19     primarily thread safety. This means, effectively, that return values
  20     of functions such as `gst_element_get_pad ()`, `gst_pad_get_name ()`
  21     and many more like these have to be free'ed or unreferenced after
  22     use. Check the API references of each function to know for sure
  23     whether return values should be free'ed or not. It is important that
  24     all objects derived from GstObject are ref'ed/unref'ed using
  25     gst\_object\_ref() and gst\_object\_unref() respectively (instead of
  26     g\_object\_ref/unref).
  27
  28   - Applications should no longer use signal handlers to be notified of
  29     errors, end-of-stream and other similar pipeline events. Instead,
  30     they should use the `GstBus`, which has been discussed in
  31     [Bus](manual-bus.md). The bus will take care that the messages will
  32     be delivered in the context of a main loop, which is almost
  33     certainly the application's main thread. The big advantage of this
  34     is that applications no longer need to be thread-aware; they don't
  35     need to use `g_idle_add
  36                                             ()` in the signal handler and do the actual real work in the
  37     idle-callback. GStreamer now does all that internally.
  38
  39   - Related to this, `gst_bin_iterate ()` has been removed. Pipelines
  40     will iterate in their own thread, and applications can simply run a
  41     `GMainLoop` (or call the mainloop of their UI toolkit, such as
  42     `gtk_main
  43                                             ()`).
  44
  45   - State changes can be delayed (ASYNC). Due to the new fully threaded
  46     nature of GStreamer-0.10, state changes are not always immediate, in
  47     particular changes including the transition from READY to PAUSED
  48     state. This means two things in the context of porting applications:
  49     first of all, it is no longer always possible to do
  50     `gst_element_set_state ()` and check for a return value of
  51     GST\_STATE\_CHANGE\_SUCCESS, as the state change might be delayed
  52     (ASYNC) and the result will not be known until later. You should
  53     still check for GST\_STATE\_CHANGE\_FAILURE right away, it is just
  54     no longer possible to assume that everything that is not SUCCESS
  55     means failure. Secondly, state changes might not be immediate, so
  56     your code needs to take that into account. You can wait for a state
  57     change to complete if you use GST\_CLOCK\_TIME\_NONE as timeout
  58     interval with `gst_element_get_state ()`.
  59
  60   - In 0.8, events and queries had to manually be sent to sinks in
  61     pipelines (unless you were using playbin). This is no longer the
  62     case in 0.10. In 0.10, queries and events can be sent to toplevel
  63     pipelines, and the pipeline will do the dispatching internally for
  64     you. This means less bookkeeping in your application. For a short
  65     code example, see [Position tracking and
  66     seeking](manual-queryevents.md). Related, seeking is now
  67     threadsafe, and your video output will show the new video position's
  68     frame while seeking, providing a better user experience.
  69
  70   - The `GstThread` object has been removed. Applications can now simply
  71     put elements in a pipeline with optionally some “queue” elements in
  72     between for buffering, and GStreamer will take care of creating
  73     threads internally. It is still possible to have parts of a pipeline
  74     run in different threads than others, by using the “queue” element.
  75     See [Threads](manual-threads.md) for details.
  76
  77   - Filtered caps -\> capsfilter element (the pipeline syntax for
  78     gst-launch has not changed though).
  79
  80   - libgstgconf-0.10.la does not exist. Use the “gconfvideosink” and
  81     “gconfaudiosink” elements instead, which will do live-updates and
  82     require no library linking.
  83
  84   - The “new-pad” and “state-change” signals on `GstElement` were
  85     renamed to “pad-added” and “state-changed”.
  86
  87   - `gst_init_get_popt_table ()` has been removed in favour of the new
  88     GOption command line option API that was added to GLib 2.6.
  89     `gst_init_get_option_group ()` is the new GOption-based equivalent
  90     to `gst_init_get_ptop_table ()`.
  91