gstreamer/docs/pwg/appendix-porting.xml
Ronald S. Bultje 8e12a91943 docs/: Document new-pad/state-change signal renames and the FixedList type rename.
Original commit message from CVS:
* docs/manual/appendix-porting.xml:
* docs/pwg/appendix-porting.xml:
Document new-pad/state-change signal renames and the FixedList
type rename.
2005-07-20 17:22:27 +00:00

104 lines
5.1 KiB
XML

<chapter id="chapter-porting">
<title>Porting 0.8 plug-ins to 0.9</title>
<para>
This section of the appendix will discuss shortly what changes to
plugins will be needed to quickly and conveniently port most
applications from &GStreamer;-0.8 to &GStreamer;-0.9, 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
&GStreamer;-0.9 in less than a day. Exceptions are elements that will
require a base class in 0.9 (sources, sinks), in which case it may take
a lot longer, depending on the coder's skills (however, when using the
<classname>GstBaseSink</classname> and <classname>GstBaseSrc</classname>
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.
</para>
<sect1 id="section-porting-objects">
<title>List of changes</title>
<itemizedlist>
<listitem>
<para>
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 threadsafety. This means, effectively,
that return values of functions such as
<function>gst_element_get_pad ()</function>,
<function>gst_pad_get_name ()</function> 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.
</para>
</listitem>
<listitem>
<para>
In 0.8, scheduling could happen in any way. Source elements could
be <function>_get ()</function>-based or <function>_loop
()</function>-based, and any other element could be <function>_chain
()</function>-based or <function>_loop ()</function>-based, with
no limitations. Scheduling in 0.9 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 <xref
linkend="chapter-scheduling"/>. As a result of this, the bytestream
object no longer exists. Elements requiring byte-level access should
now use random access on their sinkpads.
</para>
</listitem>
<listitem>
<para>
Negotiation is asynchronous. This means that negotiation is,
downstream, done as data comes in and, upstream, as renegotiation
is required. All details are described in <xref
linkend="chapter-negotiation"/>.
</para>
</listitem>
<listitem>
<para>
For as far as possible, elements should try to use existing base
classes in 0.9. Sink and source elements, for example, could derive
from <classname>GstBaseSrc</classname> and
<classname>GstBaseSink</classname>. Audio sinks or sources could even
derive from audio-specific base classes. All existing base classes
have been discussed in <xref linkend="chapter-other-base"/> and the
next few chapters.
</para>
</listitem>
<listitem>
<para>
In 0.9, event handling and buffers are separated once again. This
means that in order to receive events, one no longer has to set the
<classname>GST_FLAG_EVENT_AWARE</classname> flag, but can simply
set an event handling function on its sinkpad(s), using the function
<function>gst_pad_set_event_function ()</function>. The
<function>_chain ()</function>-function will only receive buffers.
</para>
</listitem>
<listitem>
<para>
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
<function>GST_LOCK ()</function> and <function>GST_UNLOCK
()</function> helpers in most cases, fortunately, which grabs the
default property lock of the element.
</para>
</listitem>
<listitem>
<para>
<classname>GstValueFixedList</classname> and all
<function>*_fixed_list_* ()</function> functions were renamed to
<classname>GstValueArray</classname> and <function>*_array_*
()</function>.
</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>