markdown/pwg/appendix/porting.md

   1 ---
   2 title: Porting 0.8 plug-ins to 0.10
   3 ...
   4
   5 # Porting 0.8 plug-ins to 0.10
   6
   7 This section of the appendix will discuss shortly what changes to
   8 plugins 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 Plugin Writer's Guide where needed. With
  11 this list, it should be possible to port most plugins to GStreamer-0.10
  12 in less than a day. Exceptions are elements that will require a base
  13 class in 0.10 (sources, sinks), in which case it may take a lot longer,
  14 depending on the coder's skills (however, when using the `GstBaseSink`
  15 and `GstBaseSrc` base-classes, it shouldn't be all too bad), and
  16 elements requiring the deprecated bytestream interface, which should
  17 take 1-2 days with random access. The scheduling parts of muxers will
  18 also need a rewrite, which will take about the same amount of time.
  19
  20 ## List of changes
  21
  22   - Discont events have been replaced by newsegment events. In 0.10, it
  23     is essential that you send a newsegment event downstream before you
  24     send your first buffer (in 0.8 the scheduler would invent discont
  25     events if you forgot them, in 0.10 this is no longer the case).
  26
  27   - In 0.10, buffers have caps attached to them. Elements should
  28     allocate new buffers with `gst_pad_alloc_buffer ()`. See [Caps
  29     negotiation](pwg/advanced/negotiation.md) for more details.
  30
  31   - Most functions returning an object or an object property have been
  32     changed to return its own reference rather than a constant reference
  33     of the one owned by the object itself. The reason for this change is
  34     primarily thread-safety. This means effectively that return values
  35     of functions such as `gst_element_get_pad ()`, `gst_pad_get_name
  36     ()`, `gst_pad_get_parent ()`, `gst_object_get_parent ()`, and many
  37     more like these have to be free'ed or unreferenced after use. Check
  38     the API references of each function to know for sure whether return
  39     values should be free'ed or not.
  40
  41   - In 0.8, scheduling could happen in any way. Source elements could be
  42     `_get ()`-based or `_loop
  43                                             ()`-based, and any other element could be `_chain
  44                                             ()`-based or `_loop ()`-based, with no limitations. Scheduling in
  45     0.10 is simpler for the scheduler, and the element is expected to do
  46     some more work. Pads get assigned a scheduling mode, based on which
  47     they can either operate in random access-mode, in pipeline driving
  48     mode or in push-mode. all this is documented in detail in [Different
  49     scheduling modes](pwg/advanced/scheduling.md). As a result of this, the
  50     bytestream object no longer exists. Elements requiring byte-level
  51     access should now use random access on their sinkpads.
  52
  53   - Negotiation is asynchronous. This means that downstream negotiation
  54     is done as data comes in and upstream negotiation is done whenever
  55     renegotiation is required. All details are described in [Caps
  56     negotiation](pwg/advanced/negotiation.md).
  57
  58   - For as far as possible, elements should try to use existing base
  59     classes in 0.10. Sink and source elements, for example, could derive
  60     from `GstBaseSrc` and `GstBaseSink`. Audio sinks or sources could
  61     even derive from audio-specific base classes. All existing base
  62     classes have been discussed in [Pre-made base
  63     classes](pwg/other/base.md) and the next few chapters.
  64
  65   - In 0.10, event handling and buffers are separated once again. This
  66     means that in order to receive events, one no longer has to set the
  67     `GST_FLAG_EVENT_AWARE` flag, but can simply set an event handling
  68     function on the element's sinkpad(s), using the function
  69     `gst_pad_set_event_function ()`. The `_chain ()`-function will only
  70     receive buffers.
  71
  72   - Although core will wrap most threading-related locking for you (e.g.
  73     it takes the stream lock before calling your data handling
  74     functions), you are still responsible for locking around certain
  75     functions, e.g. object properties. Be sure to lock properly here,
  76     since applications will change those properties in a different
  77     thread than the thread which does the actual data passing\! You can
  78     use the `GST_OBJECT_LOCK ()` and `GST_OBJECT_UNLOCK
  79                                             ()` helpers in most cases, fortunately, which grabs the default
  80     property lock of the element.
  81
  82   - `GstValueFixedList` and all `*_fixed_list_* ()` functions were
  83     renamed to `GstValueArray` and `*_array_*
  84                                             ()`.
  85
  86   - The semantics of `GST_STATE_PAUSED` and `GST_STATE_PLAYING` have
  87     changed for elements that are not sink elements. Non-sink elements
  88     need to be able to accept and process data already in the
  89     `GST_STATE_PAUSED` state now (i.e. when prerolling the pipeline).
  90     More details can be found in [What are
  91     states?](pwg/building/statemanage-states.md).
  92
  93   - If your plugin's state change function hasn't been superseded by
  94     virtual start() and stop() methods of one of the new base classes,
  95     then your plugin's state change functions may need to be changed in
  96     order to safely handle concurrent access by multiple threads. Your
  97     typical state change function will now first handle upwards state
  98     changes, then chain up to the state change function of the parent
  99     class (usually GstElementClass in these cases), and only then handle
 100     downwards state changes. See the vorbis decoder plugin in
 101     gst-plugins-base for an example.
 102
 103     The reason for this is that in the case of downwards state changes
 104     you don't want to destroy allocated resources while your plugin's
 105     chain function (for example) is still accessing those resources in
 106     another thread. Whether your chain function might be running or not
 107     depends on the state of your plugin's pads, and the state of those
 108     pads is closely linked to the state of the element. Pad states are
 109     handled in the GstElement class's state change function, including
 110     proper locking, that's why it is essential to chain up before
 111     destroying allocated resources.
 112
 113     As already mentioned above, you should really rewrite your plugin to
 114     derive from one of the new base classes though, so you don't have to
 115     worry about these things, as the base class will handle it for you.
 116     There are no base classes for decoders and encoders yet, so the
 117     above paragraphs about state changes definitively apply if your
 118     plugin is a decoder or an encoder.
 119
 120   - `gst_pad_set_link_function ()`, which used to set a function that
 121     would be called when a format was negotiated between two `GstPad`s,
 122     now sets a function that is called when two elements are linked
 123     together in an application. For all practical purposes, you most
 124     likely want to use the function `gst_pad_set_setcaps_function ()`,
 125     nowadays, which sets a function that is called when the format
 126     streaming over a pad changes (so similar to `_set_link_function ()`
 127     in GStreamer-0.8).
 128
 129     If the element is derived from a `GstBase` class, then override the
 130     `set_caps ()`.
 131
 132   - `gst_pad_use_explicit_caps ()` has been replaced by
 133     `gst_pad_use_fixed_caps ()`. You can then set the fixed caps to use
 134     on a pad with `gst_pad_set_caps ()`.