docs/pwg/building-testapp.xml

   1 <!-- ############ chapter ############# -->
   2
   3 <chapter id="chapter-building-testapp">
   4   <title>Building a Test Application</title>
   5   <para>
   6     Often, you will want to test your newly written plugin in an as small
   7     setting as possible. Ususally, <filename>gst-launch</filename> is a
   8     good first step at testing a plugin. However, you will often need more
   9     testing features than gst-launch can provide, such as seeking, events,
  10     interactivity and more. Writing your own small testing program is the
  11     easiest way to accomplish this. This section explains - in a few words
  12     - how to do that. For a complete application development guide, see the
  13     <ulink type="http" url="../manual/index.html">Application Development
  14     Manual</ulink>.
  15   </para>
  16
  17     <para>
  18       At the start, you need to initialize the &GStreamer; core library by
  19       calling <function>gst_init ()</function>. You can alternatively call
  20       <function>gst_init_with_popt_tables ()</function>, which will return
  21       a pointer to popt tables. You can then use libpopt to handle the
  22       given argument table, and this will finish the &GStreamer; intialization.
  23     </para>
  24
  25     <para>
  26       You can create elements using <function>gst_element_factory_make ()</function>,
  27       where the first argument is the element type that you want to create,
  28       and the second argument is a free-form name. The example at the end uses
  29       a simple filesource - decoder - soundcard output pipeline, but you can
  30       use specific debugging elements if that's necessary. For example, an
  31       <classname>identity</classname> element can be used in the middle of
  32       the pipeline to act as a data-to-application transmitter. This can be
  33       used to check the data for misbehaviours or correctness in your test
  34       application. Also, you can use a <classname>fakesink</classname>
  35       element at the end of the pipeline to dump your data to the stdout
  36       (in order to do this, set the <function>dump</function> property to
  37       TRUE). Lastly, you can use the <classname>efence</classname> element
  38       (indeed, an eletric fence memory debugger wrapper element) to check
  39       for memory errors.
  40     </para>
  41
  42     <para>
  43       During linking, your test application can use fixation or filtered caps
  44       as a way to drive a specific type of data to or from your element. This
  45       is a very simple and effective way of checking multiple types of input
  46       and output in your element.
  47     </para>
  48
  49     <para>
  50       Running the pipeline happens through the <function>gst_bin_iterate ()</function>
  51       function. Note that during running, you should connect to at least the
  52       <quote>error</quote> and <quote>eos</quote> signals on the pipeline
  53       and/or your plugin/element to check for correct handling of this. Also,
  54       you should add events into the pipeline and make sure your plugin handles
  55       these correctly (with respect to clocking, internal caching, etc.).
  56     </para>
  57
  58     <para>
  59       Never forget to clean up memory in your plugin or your test application.
  60       When going to the NULL state, your element should clean up allocated
  61       memory and caches. Also, it should close down any references held to
  62       possible support libraries. Your application should <function>unref ()</function>
  63       the pipeline and make sure it doesn't crash.
  64     </para>
  65
  66     <programlisting>
  67 #include &lt;gst/gst.h&gt;
  68
  69 gint
  70 main (gint   arcg,
  71       gchar *argv[])
  72 {
  73   GstElement *pipeline, *filesrc, *decoder, *filter, *sink;
  74
  75   /* initialization */
  76   gst_init (&amp;argc, &amp;argv);
  77
  78   /* create elements */
  79   pipeline = gst_pipeline_new ("my_pipeline");
  80
  81   filesrc  = gst_element_factory_make ("filesrc", "my_filesource");
  82   decoder  = gst_element_factory_make ("mad", "my_decoder");
  83   filter   = gst_element_factory_make ("my_filter", "my_filter");
  84   sink     = gst_element_factory_make ("osssink", "audiosink");
  85
  86   g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
  87
  88   /* link everything together */
  89   gst_element_link_many (filesrc, decoder, filter, sink, NULL);
  90   gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, filter, sink, NULL);
  91
  92   /* run */
  93   gst_element_set_state (pipeline, GST_STATE_PLAYING);
  94   while (gst_bin_iterate (GST_BIN (pipeline)));
  95
  96   /* clean up */
  97   gst_element_set_state (pipeline, GST_STATE_NULL);
  98   gst_object_unref (GST_OBJECT (pipeline));
  99
 100   return 0;
 101 }
 102     </programlisting>
 103 </chapter>