mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-07-30 10:15:07 +00:00
835e826907
Original commit message from CVS: * docs/pwg/advanced-clock.xml: * docs/pwg/appendix-porting.xml: * docs/pwg/intro-preface.xml: * docs/pwg/other-base.xml: * docs/pwg/other-manager.xml: * docs/pwg/other-nton.xml: * docs/pwg/other-ntoone.xml: * docs/pwg/other-oneton.xml: * docs/pwg/pwg.xml: Document base classes, update sections of n-to-1 and 1-to-n (muxer, demuxer), remove n-to-n (was never written), fix some code examples and links and update the porting section to include all this.
97 lines
4.8 KiB
XML
97 lines
4.8 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>
|
|
</itemizedlist>
|
|
</sect1>
|
|
</chapter>
|