mobile/docs/pwg/appendix-porting.xml

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