mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-11-26 11:41:09 +00:00
Code Issues 1 Projects Releases Wiki Activity

docs/pwg/appendix-checklist.xml: Add some random notes on thinks to check when writing an element.

Browse source 
Original commit message from CVS:
* docs/pwg/appendix-checklist.xml:
Add some random notes on thinks to check when writing an element.
This list can be extended as people see fit.
This commit is contained in:
Ronald S. Bultje 2004-11-23 22:36:21 +00:00
parent 709bfe8a23
commit a6647422c9
2 changed files with 176 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
ChangeLog
View file

@ -1,3 +1,9 @@
2004-11-23 Ronald S. Bultje <rbultje@ronald.bitfreak.net>
* docs/pwg/appendix-checklist.xml:
Add some random notes on thinks to check when writing an element.
This list can be extended as people see fit.
2004-11-23 Martin Soto <martinsoto@users.sourceforge.net>
* gst/gstqueue.c (gst_queue_init, gst_queue_link_sink)

190
docs/pwg/appendix-checklist.xml
View file

@ -1,24 +1,174 @@
<chapter id="chapter-checklist-element">
<title>
Things to check when writing an element
</title>
<para>
Make sure the state of an element gets reset when going to NULL.
Ideally, this should set all object properties to their original state.
This function should also be called from _init.
</para>
</chapter>
<chapter id="chapter-checklist-filter">
<title>
Things to check when writing a filter
</title>
<para>
</para>
</chapter>
<chapter id="chapter-checklist-srcsink">
<title>
Things to check when writing a source or sink
</title>
<title>Things to check when writing an element</title>
<para>
This chapter contains a fairly random selection of things to take care
of when writing an element. It's up to you how far you're going to stick
to those guidelines. However, keep in mind that when you're writing an
element and hope for it to be included in the mainstream &GStreamer;
distribution, it <emphasis>has to</emphasis> meet those requirements.
As far as possible, we will try to explain why those requirements are
set.
</para>
<sect1 id="section-checklist-states">
<title>About states</title>
<itemizedlist>
<listitem>
<para>
Make sure the state of an element gets reset when going to
<classname>NULL</classname>. Ideally, this should set all
object properties to their original state. This function
should also be called from _init.
</para>
</listitem>
<listitem>
<para>
Make sure an element forgets <emphasis>everything</emphasis>
about its contained stream when going from
<classname>PAUSED</classname> to <classname>READY</classname>. In
<classname>READY</classname>, all stream states are reset. An
element that goes from <classname>PAUSED</classname> to
<classname>READY</classname> and back to
<classname>PAUSED</classname> should start reading the
stream from he start again.
</para>
</listitem>
<listitem>
<para>
People that use <command>gst-launch</command> for testing have
the tendency to not care about cleaning up. This is
<emphasis>wrong</emphasis>. An element should be tested using
various applications, where testing not only means to <quote>make
sure it doesn't crash</quote>, but also to test for memory leaks
using tools such as <command>valgrind</command>. Elements have to
be reusable in a pipeline after having been reset.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="section-checklist-debug">
<title>Debugging</title>
<itemizedlist>
<listitem>
<para>
Elements should <emphasis>never</emphasis> use their standard
output for debugging (using functions such as <function>printf
()</function> or <function>g_print ()</function>). Instead,
elements should use the logging functions provided by &GStreamer;,
named <function>GST_DEBUG ()</function>,
<function>GST_INFO ()</function>, <function>GST_INFO ()</function>,
<function>GST_WARNING ()</function> and
<function>GST_ERROR ()</function>. The various logging levels can
be turned on and off at runtime and can thus be used for solving
issues as they turn up.
</para>
</listitem>
<listitem>
<para>
Ideally, elements should use their own debugging category. Most
elements use the following code to do that:
</para>
<programlisting>
GST_DEBUG_CATEGORY_STATIC (myelement_debug);
#define GST_CAT_DEFAULT myelement_debug
[..]
static void
gst_myelement_class_init (GstMyelementClass *klass)
{
[..]
GST_DEBUG_CATEGORY_INIT (myelement_debug, "myelement",
0, "My own element");
}
</programlisting>
<para>
At runtime, you can turn on debugging using the commandline
<command>--gst-debug=myelement:5</command>.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="section-checklist-query">
<title>Querying, events and the like</title>
<itemizedlist>
<listitem>
<para>
All elements to which it applies (sources, sinks, demuxers)
should implement query functions on their pads, so that
applications and neighbour elements can request the current
position, the stream length (if known) and so on.
</para>
</listitem>
<listitem>
<para>
All elements that are event-aware (their
<classname>GST_ELEMENT_EVENT_AWARE</classname> flag is set)
should implement event handling for <emphasis>all</emphasis>
events, either specifically or using
<function>gst_pad_event_default ()</function>. Elements that
you should handle specifically are the interrupt event, in
order to properly bail out as soon as possible if state is
changed. Events may never be dropped unless specifically
intended.
</para>
</listitem>
<listitem>
<para>
Loop-based elements should always implement event handling,
in order to prevent hangs (infinite loop) on state changes.
</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="section-checklist-testing">
<title>Testing your element</title>
<itemizedlist>
<listitem>
<para>
<command>gst-launch</command> is <emphasis>not</emphasis> a good
tool to show that your element is finished. Applications such as
Rhythmbox and Totem (for GNOME) or AmaroK (for KDE)
<emphasis>are</emphasis>. <command>gst-launch</command> will not
test various things such as proper clean-up on reset, interrupt
event handling, querying and so on.
</para>
</listitem>
<listitem>
<para>
Parsers and demuxers should make sure to check their input. Input
cannot be trusted. Prevent possible buffer overflows and the like.
Feel free to error out on unrecoverable stream errors. Test your
demuxer using stream corruption elements such as
<classname>breakmydata</classname> (included in gst-plugins). It
will randomly insert, delete and modify bytes in a stream, and is
therefore a good test for robustness. If your element crashes
when adding this element, your element needs fixing. If it errors
out properly, it's good enough. Ideally, it'd just continue to
work and forward data as much as possible.
</para>
</listitem>
<listitem>
<para>
Demuxers should not assume that seeking works. Be prepared to
work with unseekable input streams (e.g. network sources) as
well.
</para>
</listitem>
<listitem>
<para>
Sources and sinks should be prepared to be assigned another clock
then the one they expose themselves. Always use the provided clock
for synchronization, else you'll get A/V sync issues.
</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>