<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Porting 0.8 plug-ins to 0.10</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79;charset=UTF-8"><LINK
REL="HOME"
TITLE="GStreamer Plugin Writer's Guide (0.10.36)"
HREF="index.html"><LINK
REL="UP"
TITLE="Appendices"
HREF="part-appendix.html"><LINK
REL="PREVIOUS"
TITLE="Testing your element"
HREF="section-checklist-testing.html"><LINK
REL="NEXT"
TITLE="GStreamer licensing"
HREF="chapter-licensing-advisory.html"></HEAD
><BODY
CLASS="chapter"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
><SPAN
CLASS="application"
>GStreamer</SPAN
> Plugin Writer's Guide (0.10.36)</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="section-checklist-testing.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="chapter-licensing-advisory.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="chapter"
><H1
><A
NAME="chapter-porting"
></A
>Chapter 24. Porting 0.8 plug-ins to 0.10</H1
><P
> This section of the appendix will discuss shortly what changes to
plugins will be needed to quickly and conveniently port most
applications from <SPAN
CLASS="application"
>GStreamer</SPAN
>-0.8 to <SPAN
CLASS="application"
>GStreamer</SPAN
>-0.10, with references
to the relevant sections in this Plugin Writer's Guide where needed.
With this list, it should be possible to port most plugins to
<SPAN
CLASS="application"
>GStreamer</SPAN
>-0.10 in less than a day. Exceptions are elements that will
require a base class in 0.10 (sources, sinks), in which case it may take
a lot longer, depending on the coder's skills (however, when using the
<CODE
CLASS="classname"
>GstBaseSink</CODE
> and <CODE
CLASS="classname"
>GstBaseSrc</CODE
>
base-classes, it shouldn't be all too bad), and elements requiring
the deprecated bytestream interface, which should take 1-2 days with
random access. The scheduling parts of muxers will also need a rewrite,
which will take about the same amount of time.
</P
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="section-porting-objects"
>24.1. List of changes</A
></H1
><P
></P
><UL
><LI
><P
> Discont events have been replaced by newsegment events. In 0.10, it is
essential that you send a newsegment event downstream before you send
your first buffer (in 0.8 the scheduler would invent discont events if
you forgot them, in 0.10 this is no longer the case).
</P
></LI
><LI
><P
> In 0.10, buffers have caps attached to them. Elements should allocate
new buffers with <CODE
CLASS="function"
>gst_pad_alloc_buffer ()</CODE
>. See
<A
HREF="chapter-negotiation.html"
>Caps negotiation</A
> for more details.
</P
></LI
><LI
><P
> 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
<CODE
CLASS="function"
>gst_element_get_pad ()</CODE
>,
<CODE
CLASS="function"
>gst_pad_get_name ()</CODE
>,
<CODE
CLASS="function"
>gst_pad_get_parent ()</CODE
>,
<CODE
CLASS="function"
>gst_object_get_parent ()</CODE
>,
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.
</P
></LI
><LI
><P
> In 0.8, scheduling could happen in any way. Source elements could
be <CODE
CLASS="function"
>_get ()</CODE
>-based or <CODE
CLASS="function"
>_loop
()</CODE
>-based, and any other element could be <CODE
CLASS="function"
>_chain
()</CODE
>-based or <CODE
CLASS="function"
>_loop ()</CODE
>-based, with
no limitations. Scheduling in 0.10 is simpler for the scheduler,
and the element is expected to do some more work. Pads get
assigned a scheduling mode, based on which they can either
operate in random access-mode, in pipeline driving mode or in
push-mode. all this is documented in detail in <A
HREF="chapter-scheduling.html"
>Different scheduling modes</A
>. As a result of this, the bytestream
object no longer exists. Elements requiring byte-level access should
now use random access on their sinkpads.
</P
></LI
><LI
><P
> Negotiation is asynchronous. This means that downstream negotiation
is done as data comes in and upstream negotiation is done whenever
renegotiation is required. All details are described in
<A
HREF="chapter-negotiation.html"
>Caps negotiation</A
>.
</P
></LI
><LI
><P
> For as far as possible, elements should try to use existing base
classes in 0.10. Sink and source elements, for example, could derive
from <CODE
CLASS="classname"
>GstBaseSrc</CODE
> and
<CODE
CLASS="classname"
>GstBaseSink</CODE
>. Audio sinks or sources could even
derive from audio-specific base classes. All existing base classes
have been discussed in <A
HREF="chapter-other-base.html"
>Pre-made base classes</A
> and the
next few chapters.
</P
></LI
><LI
><P
> In 0.10, event handling and buffers are separated once again. This
means that in order to receive events, one no longer has to set the
<CODE
CLASS="classname"
>GST_FLAG_EVENT_AWARE</CODE
> flag, but can simply
set an event handling function on the element's sinkpad(s), using
the function <CODE
CLASS="function"
>gst_pad_set_event_function ()</CODE
>. The
<CODE
CLASS="function"
>_chain ()</CODE
>-function will only receive buffers.
</P
></LI
><LI
><P
> Although core will wrap most threading-related locking for you (e.g.
it takes the stream lock before calling your data handling
functions), you are still responsible for locking around certain
functions, e.g. object properties. Be sure to lock properly here,
since applications will change those properties in a different thread
than the thread which does the actual data passing! You can use the
<CODE
CLASS="function"
>GST_OBJECT_LOCK ()</CODE
> and <CODE
CLASS="function"
>GST_OBJECT_UNLOCK
()</CODE
> helpers in most cases, fortunately, which grabs the
default property lock of the element.
</P
></LI
><LI
><P
> <CODE
CLASS="classname"
>GstValueFixedList</CODE
> and all
<CODE
CLASS="function"
>*_fixed_list_* ()</CODE
> functions were renamed to
<CODE
CLASS="classname"
>GstValueArray</CODE
> and <CODE
CLASS="function"
>*_array_*
()</CODE
>.
</P
></LI
><LI
><P
> The semantics of <CODE
CLASS="symbol"
>GST_STATE_PAUSED</CODE
> and
<CODE
CLASS="symbol"
>GST_STATE_PLAYING</CODE
> have changed for elements that
are not sink elements. Non-sink elements need to be able to accept
and process data already in the <CODE
CLASS="symbol"
>GST_STATE_PAUSED</CODE
>
state now (i.e. when prerolling the pipeline). More details can be
found in <A
HREF="chapter-statemanage-states.html"
>Chapter 6</A
>.
</P
></LI
><LI
><P
> If your plugin's state change function hasn't been superseded by
virtual start() and stop() methods of one of the new base classes,
then your plugin's state change functions may need to be changed in
order to safely handle concurrent access by multiple threads. Your
typical state change function will now first handle upwards state
changes, then chain up to the state change function of the parent
class (usually GstElementClass in these cases), and only then handle
downwards state changes. See the vorbis decoder plugin in
gst-plugins-base for an example.
</P
><P
> The reason for this is that in the case of downwards state changes
you don't want to destroy allocated resources while your plugin's
chain function (for example) is still accessing those resources in
another thread. Whether your chain function might be running or not
depends on the state of your plugin's pads, and the state of those
pads is closely linked to the state of the element. Pad states are
handled in the GstElement class's state change function, including
proper locking, that's why it is essential to chain up before
destroying allocated resources.
</P
><P
> As already mentioned above, you should really rewrite your plugin
to derive from one of the new base classes though, so you don't have
to worry about these things, as the base class will handle it for you.
There are no base classes for decoders and encoders yet, so the above
paragraphs about state changes definitively apply if your plugin is a
decoder or an encoder.
</P
></LI
><LI
><P
> <CODE
CLASS="function"
>gst_pad_set_link_function ()</CODE
>, which used to set
a function that would be called when a format was negotiated between
two <CODE
CLASS="classname"
>GstPad</CODE
>s, now sets a function that is
called when two elements are linked together in an application. For
all practical purposes, you most likely want to use the function
<CODE
CLASS="function"
>gst_pad_set_setcaps_function ()</CODE
>, nowadays, which
sets a function that is called when the format streaming over a pad
changes (so similar to <CODE
CLASS="function"
>_set_link_function ()</CODE
> in
<SPAN
CLASS="application"
>GStreamer</SPAN
>-0.8).
</P
><P
> If the element is derived from a <CODE
CLASS="classname"
>GstBase</CODE
> class,
then override the <CODE
CLASS="function"
>set_caps ()</CODE
>.
</P
></LI
><LI
><P
> <CODE
CLASS="function"
>gst_pad_use_explicit_caps ()</CODE
> has been replaced by
<CODE
CLASS="function"
>gst_pad_use_fixed_caps ()</CODE
>. You can then set the
fixed caps to use on a pad with <CODE
CLASS="function"
>gst_pad_set_caps ()</CODE
>.
</P
></LI
></UL
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="section-checklist-testing.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="chapter-licensing-advisory.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Testing your element</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="part-appendix.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>GStreamer licensing</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
