markdown/pwg/appendix/checklist-element.md

   1 ---
   2 title: Things to check when writing an element
   3 ...
   4
   5 # Things to check when writing an element
   6
   7 This chapter contains a fairly random selection of things to take care
   8 of when writing an element. It's up to you how far you're going to stick
   9 to those guidelines. However, keep in mind that when you're writing an
  10 element and hope for it to be included in the mainstream GStreamer
  11 distribution, it *has to* meet those requirements. As far as possible,
  12 we will try to explain why those requirements are set.
  13
  14 ## About states
  15
  16   - Make sure the state of an element gets reset when going to `NULL`.
  17     Ideally, this should set all object properties to their original
  18     state. This function should also be called from \_init.
  19
  20   - Make sure an element forgets *everything* about its contained stream
  21     when going from `PAUSED` to `READY`. In `READY`, all stream states
  22     are reset. An element that goes from `PAUSED` to `READY` and back to
  23     `PAUSED` should start reading the stream from the start again.
  24
  25   - People that use `gst-launch` for testing have the tendency to not
  26     care about cleaning up. This is *wrong*. An element should be tested
  27     using various applications, where testing not only means to “make
  28     sure it doesn't crash”, but also to test for memory leaks using
  29     tools such as `valgrind`. Elements have to be reusable in a pipeline
  30     after having been reset.
  31
  32 ## Debugging
  33
  34   - Elements should *never* use their standard output for debugging
  35     (using functions such as `printf
  36                                             ()` or `g_print ()`). Instead, elements should use the logging
  37     functions provided by GStreamer, named `GST_DEBUG ()`, `GST_LOG ()`,
  38     `GST_INFO ()`, `GST_WARNING ()` and `GST_ERROR ()`. The various
  39     logging levels can be turned on and off at runtime and can thus be
  40     used for solving issues as they turn up. Instead of `GST_LOG ()` (as
  41     an example), you can also use `GST_LOG_OBJECT
  42                                             ()` to print the object that you're logging output for.
  43
  44   - Ideally, elements should use their own debugging category. Most
  45     elements use the following code to do that:
  46
  47     ``` c
  48     GST_DEBUG_CATEGORY_STATIC (myelement_debug);
  49     #define GST_CAT_DEFAULT myelement_debug
  50
  51     [..]
  52
  53     static void
  54     gst_myelement_class_init (GstMyelementClass *klass)
  55     {
  56     [..]
  57       GST_DEBUG_CATEGORY_INIT (myelement_debug, "myelement",
  58                    0, "My own element");
  59     }
  60
  61     ```
  62
  63     At runtime, you can turn on debugging using the commandline option
  64     `--gst-debug=myelement:5`.
  65
  66   - Elements should use GST\_DEBUG\_FUNCPTR when setting pad functions
  67     or overriding element class methods, for example:
  68
  69     ``` c
  70     gst_pad_set_event_func (myelement->srcpad,
  71         GST_DEBUG_FUNCPTR (my_element_src_event));
  72
  73     ```
  74
  75     This makes debug output much easier to read later on.
  76
  77   - Elements that are aimed for inclusion into one of the GStreamer
  78     modules should ensure consistent naming of the element name,
  79     structures and function names. For example, if the element type is
  80     GstYellowFooDec, functions should be prefixed with
  81     gst\_yellow\_foo\_dec\_ and the element should be registered as
  82     'yellowfoodec'. Separate words should be separate in this scheme, so
  83     it should be GstFooDec and gst\_foo\_dec, and not GstFoodec and
  84     gst\_foodec.
  85
  86 ## Querying, events and the like
  87
  88   - All elements to which it applies (sources, sinks, demuxers) should
  89     implement query functions on their pads, so that applications and
  90     neighbour elements can request the current position, the stream
  91     length (if known) and so on.
  92
  93   - Elements should make sure they forward events they do not handle
  94     with gst\_pad\_event\_default (pad, parent, event) instead of just
  95     dropping them. Events should never be dropped unless specifically
  96     intended.
  97
  98   - Elements should make sure they forward queries they do not handle
  99     with gst\_pad\_query\_default (pad, parent, query) instead of just
 100     dropping them.
 101
 102 ## Testing your element
 103
 104   - `gst-launch` is *not* a good tool to show that your element is
 105     finished. Applications such as Rhythmbox and Totem (for GNOME) or
 106     AmaroK (for KDE) *are*. `gst-launch` will not test various things
 107     such as proper clean-up on reset, event handling, querying and so
 108     on.
 109
 110   - Parsers and demuxers should make sure to check their input. Input
 111     cannot be trusted. Prevent possible buffer overflows and the like.
 112     Feel free to error out on unrecoverable stream errors. Test your
 113     demuxer using stream corruption elements such as `breakmydata`
 114     (included in gst-plugins). It will randomly insert, delete and
 115     modify bytes in a stream, and is therefore a good test for
 116     robustness. If your element crashes when adding this element, your
 117     element needs fixing. If it errors out properly, it's good enough.
 118     Ideally, it'd just continue to work and forward data as much as
 119     possible.
 120
 121   - Demuxers should not assume that seeking works. Be prepared to work
 122     with unseekable input streams (e.g. network sources) as well.
 123
 124   - Sources and sinks should be prepared to be assigned another clock
 125     then the one they expose themselves. Always use the provided clock
 126     for synchronization, else you'll get A/V sync issues.