<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>
projects / platform / upstream / gstreamer.git / commitdiff