docs/pwg/appendix-checklist.xml

   1 <chapter id="chapter-checklist-element">
   2   <title>Things to check when writing an element</title>
   3   <para>
   4     This chapter contains a fairly random selection of things to take care
   5     of when writing an element. It's up to you how far you're going to stick
   6     to those guidelines. However, keep in mind that when you're writing an
   7     element and hope for it to be included in the mainstream &GStreamer;
   8     distribution, it <emphasis>has to</emphasis> meet those requirements.
   9     As far as possible, we will try to explain why those requirements are
  10     set.
  11   </para>
  12
  13   <sect1 id="section-checklist-states">
  14     <title>About states</title>
  15
  16     <itemizedlist>
  17       <listitem>
  18         <para>
  19           Make sure the state of an element gets reset when going to
  20           <classname>NULL</classname>. Ideally, this should set all
  21           object properties to their original state. This function
  22           should also be called from _init.
  23         </para>
  24       </listitem>
  25       <listitem>
  26         <para>
  27           Make sure an element forgets <emphasis>everything</emphasis>
  28           about its contained stream when going from
  29           <classname>PAUSED</classname> to <classname>READY</classname>. In
  30           <classname>READY</classname>, all stream states are reset. An
  31           element that goes from <classname>PAUSED</classname> to
  32           <classname>READY</classname> and back to
  33           <classname>PAUSED</classname> should start reading the
  34           stream from he start again.
  35         </para>
  36       </listitem>
  37       <listitem>
  38         <para>
  39           People that use <command>gst-launch</command> for testing have
  40           the tendency to not care about cleaning up. This is
  41           <emphasis>wrong</emphasis>. An element should be tested using
  42           various applications, where testing not only means to <quote>make
  43           sure it doesn't crash</quote>, but also to test for memory leaks
  44           using tools such as <command>valgrind</command>. Elements have to
  45           be reusable in a pipeline after having been reset.
  46         </para>
  47       </listitem>
  48     </itemizedlist>
  49   </sect1>
  50
  51   <sect1 id="section-checklist-debug">
  52     <title>Debugging</title>
  53
  54     <itemizedlist>
  55       <listitem>
  56         <para>
  57           Elements should <emphasis>never</emphasis> use their standard
  58           output for debugging (using functions such as <function>printf
  59           ()</function> or <function>g_print ()</function>). Instead,
  60           elements should use the logging functions provided by &GStreamer;,
  61           named <function>GST_DEBUG ()</function>,
  62           <function>GST_INFO ()</function>, <function>GST_INFO ()</function>,
  63           <function>GST_WARNING ()</function> and
  64           <function>GST_ERROR ()</function>. The various logging levels can
  65           be turned on and off at runtime and can thus be used for solving
  66           issues as they turn up.
  67         </para>
  68       </listitem>
  69       <listitem>
  70         <para>
  71           Ideally, elements should use their own debugging category. Most
  72           elements use the following code to do that:
  73         </para>
  74         <programlisting>
  75 GST_DEBUG_CATEGORY_STATIC (myelement_debug);
  76 #define GST_CAT_DEFAULT myelement_debug
  77
  78 [..]
  79
  80 static void
  81 gst_myelement_class_init (GstMyelementClass *klass)
  82 {
  83 [..]
  84   GST_DEBUG_CATEGORY_INIT (myelement_debug, "myelement",
  85                            0, "My own element");
  86 }
  87         </programlisting>
  88         <para>
  89           At runtime, you can turn on debugging using the commandline
  90           <command>--gst-debug=myelement:5</command>.
  91         </para>
  92       </listitem>
  93     </itemizedlist>
  94   </sect1>
  95
  96   <sect1 id="section-checklist-query">
  97     <title>Querying, events and the like</title>
  98
  99     <itemizedlist>
 100       <listitem>
 101         <para>
 102           All elements to which it applies (sources, sinks, demuxers)
 103           should implement query functions on their pads, so that
 104           applications and neighbour elements can request the current
 105           position, the stream length (if known) and so on.
 106         </para>
 107       </listitem>
 108       <listitem>
 109         <para>
 110           All elements that are event-aware (their
 111           <classname>GST_ELEMENT_EVENT_AWARE</classname> flag is set)
 112           should implement event handling for <emphasis>all</emphasis>
 113           events, either specifically or using
 114           <function>gst_pad_event_default ()</function>. Elements that
 115           you should handle specifically are the interrupt event, in
 116           order to properly bail out as soon as possible if state is
 117           changed. Events may never be dropped unless specifically
 118           intended.
 119         </para>
 120       </listitem>
 121       <listitem>
 122         <para>
 123           Loop-based elements should always implement event handling,
 124           in order to prevent hangs (infinite loop) on state changes.
 125         </para>
 126       </listitem>
 127     </itemizedlist>
 128   </sect1>
 129
 130   <sect1 id="section-checklist-testing">
 131     <title>Testing your element</title>
 132
 133     <itemizedlist>
 134       <listitem>
 135         <para>
 136           <command>gst-launch</command> is <emphasis>not</emphasis> a good
 137           tool to show that your element is finished. Applications such as
 138           Rhythmbox and Totem (for GNOME) or AmaroK (for KDE)
 139           <emphasis>are</emphasis>. <command>gst-launch</command> will not
 140           test various things such as proper clean-up on reset, interrupt
 141           event handling, querying and so on.
 142         </para>
 143       </listitem>
 144       <listitem>
 145         <para>
 146           Parsers and demuxers should make sure to check their input. Input
 147           cannot be trusted. Prevent possible buffer overflows and the like.
 148           Feel free to error out on unrecoverable stream errors. Test your
 149           demuxer using stream corruption elements such as
 150           <classname>breakmydata</classname> (included in gst-plugins). It
 151           will randomly insert, delete and modify bytes in a stream, and is
 152           therefore a good test for robustness. If your element crashes
 153           when adding this element, your element needs fixing. If it errors
 154           out properly, it's good enough. Ideally, it'd just continue to
 155           work and forward data as much as possible.
 156         </para>
 157       </listitem>
 158       <listitem>
 159         <para>
 160           Demuxers should not assume that seeking works. Be prepared to
 161           work with unseekable input streams (e.g. network sources) as
 162           well.
 163         </para>
 164       </listitem>
 165       <listitem>
 166         <para>
 167           Sources and sinks should be prepared to be assigned another clock
 168           then the one they expose themselves. Always use the provided clock
 169           for synchronization, else you'll get A/V sync issues.
 170         </para>
 171       </listitem>
 172     </itemizedlist>
 173   </sect1>
 174 </chapter>