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_LOG ()</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. Instead of <function>GST_LOG ()</function>
  67           (as an example), you can also use <function>GST_LOG_OBJECT
  68           ()</function> to print the object that you're logging output for.
  69         </para>
  70       </listitem>
  71       <listitem>
  72         <para>
  73           Ideally, elements should use their own debugging category. Most
  74           elements use the following code to do that:
  75         </para>
  76         <programlisting>
  77 GST_DEBUG_CATEGORY_STATIC (myelement_debug);
  78 #define GST_CAT_DEFAULT myelement_debug
  79
  80 [..]
  81
  82 static void
  83 gst_myelement_class_init (GstMyelementClass *klass)
  84 {
  85 [..]
  86   GST_DEBUG_CATEGORY_INIT (myelement_debug, "myelement",
  87                            0, "My own element");
  88 }
  89         </programlisting>
  90         <para>
  91           At runtime, you can turn on debugging using the commandline
  92           option <command>--gst-debug=myelement:5</command>.
  93         </para>
  94       </listitem>
  95       <listitem>
  96         <para>
  97           Elements should use GST_DEBUG_FUNCPTR when setting pad functions or
  98           overriding element class methods, for example:
  99           <programlisting>
 100 gst_pad_set_event_func (myelement->srcpad,
 101     GST_DEBUG_FUNCPTR (my_element_src_event));
 102           </programlisting>
 103           This makes debug output much easier to read later on.
 104         </para>
 105       </listitem>
 106       <listitem>
 107         <para>
 108           Elements that are aimed for inclusion into one of the GStreamer
 109           modules should ensure consistent naming of the element name,
 110           structures and function names. For example, if the element type is
 111           GstYellowFooDec, functions should be prefixed with
 112           gst_yellow_foo_dec_ and the element should be registered
 113           as 'yellowfoodec'. Separate words should be separate in this scheme,
 114           so it should be GstFooDec and gst_foo_dec, and not GstFoodec and
 115           gst_foodec.
 116         </para>
 117       </listitem>
 118     </itemizedlist>
 119   </sect1>
 120
 121   <sect1 id="section-checklist-query">
 122     <title>Querying, events and the like</title>
 123
 124     <itemizedlist>
 125       <listitem>
 126         <para>
 127           All elements to which it applies (sources, sinks, demuxers)
 128           should implement query functions on their pads, so that
 129           applications and neighbour elements can request the current
 130           position, the stream length (if known) and so on.
 131         </para>
 132       </listitem>
 133       <listitem>
 134         <para>
 135           Elements should make sure they forward events they do not
 136           handle with gst_pad_event_default (pad, event) instead of
 137           just dropping them. Events should never be dropped unless
 138           specifically intended.
 139         </para>
 140       </listitem>
 141       <listitem>
 142         <para>
 143           Elements should make sure they forward queries they do not
 144           handle with gst_pad_query_default (pad, query) instead of
 145           just dropping them.
 146         </para>
 147       </listitem>
 148       <listitem>
 149         <para>
 150           Elements should use gst_pad_get_parent() in event and query
 151           functions, so that they hold a reference to the element while they
 152           are operating. Note that gst_pad_get_parent() increases the
 153           reference count of the element, so you must be very careful to call
 154           gst_object_unref (element) before returning from your query or
 155           event function, otherwise you will leak memory.
 156         </para>
 157       </listitem>
 158     </itemizedlist>
 159   </sect1>
 160
 161   <sect1 id="section-checklist-testing">
 162     <title>Testing your element</title>
 163
 164     <itemizedlist>
 165       <listitem>
 166         <para>
 167           <command>gst-launch</command> is <emphasis>not</emphasis> a good
 168           tool to show that your element is finished. Applications such as
 169           Rhythmbox and Totem (for GNOME) or AmaroK (for KDE)
 170           <emphasis>are</emphasis>. <command>gst-launch</command> will not
 171           test various things such as proper clean-up on reset, interrupt
 172           event handling, querying and so on.
 173         </para>
 174       </listitem>
 175       <listitem>
 176         <para>
 177           Parsers and demuxers should make sure to check their input. Input
 178           cannot be trusted. Prevent possible buffer overflows and the like.
 179           Feel free to error out on unrecoverable stream errors. Test your
 180           demuxer using stream corruption elements such as
 181           <classname>breakmydata</classname> (included in gst-plugins). It
 182           will randomly insert, delete and modify bytes in a stream, and is
 183           therefore a good test for robustness. If your element crashes
 184           when adding this element, your element needs fixing. If it errors
 185           out properly, it's good enough. Ideally, it'd just continue to
 186           work and forward data as much as possible.
 187         </para>
 188       </listitem>
 189       <listitem>
 190         <para>
 191           Demuxers should not assume that seeking works. Be prepared to
 192           work with unseekable input streams (e.g. network sources) as
 193           well.
 194         </para>
 195       </listitem>
 196       <listitem>
 197         <para>
 198           Sources and sinks should be prepared to be assigned another clock
 199           then the one they expose themselves. Always use the provided clock
 200           for synchronization, else you'll get A/V sync issues.
 201         </para>
 202       </listitem>
 203     </itemizedlist>
 204   </sect1>
 205 </chapter>