2 title: Porting 0.8 plug-ins to 0.10
5 # Porting 0.8 plug-ins to 0.10
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.
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).
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-negotiation.md) for more details.
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.
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-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.
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-negotiation.md).
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.
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
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.
82 - `GstValueFixedList` and all `*_fixed_list_* ()` functions were
83 renamed to `GstValueArray` and `*_array_*
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-statemanage-states.md).
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.
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.
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.
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 ()`
129 If the element is derived from a `GstBase` class, then override the
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 ()`.