Merge branch 'master' into 0.11
[platform/upstream/gstreamer.git] / docs / manual / advanced-dataaccess.xml
1 <chapter id="chapter-dataaccess">
2   <title>Pipeline manipulation</title>
3   <para>
4     This chapter will discuss how you can manipulate your pipeline in several
5     ways from your application on. Parts of this chapter are downright
6     hackish, so be assured that you'll need some programming knowledge
7     before you start reading this.
8   </para>
9   <para>
10     Topics that will be discussed here include how you can insert data into
11     a pipeline from your application, how to read data from a pipeline,
12     how to manipulate the pipeline's speed, length, starting point and how
13     to listen to a pipeline's data processing.
14   </para>
15
16   <sect1 id="section-data-probe">
17     <title>Data probing</title>
18     <para>
19       Probing is best envisioned as a pad listener. Technically, a probe is
20       nothing more than a signal callback that can be attached to a pad.
21       Those signals are by default not fired at all (since that may have a
22       negative impact on performance), but can be enabled by attaching a
23       probe using <function>gst_pad_add_buffer_probe ()</function>,
24       <function>gst_pad_add_event_probe ()</function>, or
25       <function>gst_pad_add_data_probe ()</function>.
26       Those functions attach the signal handler and
27       enable the actual signal emission. Similarly, one can use the
28       <function>gst_pad_remove_buffer_probe ()</function>,
29       <function>gst_pad_remove_event_probe ()</function>, or
30       <function>gst_pad_remove_data_probe ()</function>
31       to remove the signal handlers again.
32     </para>
33     <para>
34       Probes run in pipeline threading context, so callbacks should try to
35       not block and generally not do any weird stuff, since this could
36       have a negative impact on pipeline performance or, in case of bugs,
37       cause deadlocks or crashes. More precisely, one should usually not
38       call any GUI-related functions from within a probe callback, nor try
39       to change the state of the pipeline.  An application may post custom
40       messages on the pipeline's bus though to communicate with the main
41       application thread and have it do things like stop the pipeline.
42     </para>
43     <para>
44       In any case, most common buffer operations
45       that elements can do in <function>_chain ()</function> functions, can
46       be done in probe callbacks as well. The example below gives a short
47       impression on how to use them (even if this usage is not entirely
48       correct, but more on that below):
49     </para>
50     <programlisting><!-- example-begin probe.c -->
51 #include &lt;gst/gst.h&gt;
52
53 static gboolean
54 cb_have_data (GstPad    *pad,
55               GstBuffer *buffer,
56               gpointer   u_data)
57 {
58   gint x, y;
59   GstMapInfo info;
60   guint16 *ptr, t;
61   
62   gst_buffer_map (buffer, &amp;info, GST_MAP_WRITE);
63
64   ptr = info.data;
65   /* invert data */
66   for (y = 0; y &lt; 288; y++) {
67     for (x = 0; x &lt; 384 / 2; x++) {
68       t = ptr[384 - 1 - x];
69       ptr[384 - 1 - x] = ptr[x];
70       ptr[x] = t;
71     }
72     ptr += 384;
73   }
74   gst_buffer_unmap (buffer, &amp;info);
75
76   return TRUE;
77 }
78
79 gint
80 main (gint   argc,
81       gchar *argv[])
82 {
83   GMainLoop *loop;
84   GstElement *pipeline, *src, *sink, *filter, *csp;
85   GstCaps *filtercaps;
86   GstPad *pad;
87
88   /* init GStreamer */
89   gst_init (&amp;argc, &amp;argv);
90   loop = g_main_loop_new (NULL, FALSE);
91
92   /* build */
93   pipeline = gst_pipeline_new ("my-pipeline");
94   src = gst_element_factory_make ("videotestsrc", "src");
95   if (src == NULL)
96     g_error ("Could not create 'videotestsrc' element");
97
98   filter = gst_element_factory_make ("capsfilter", "filter");
99   g_assert (filter != NULL); /* should always exist */
100
101   csp = gst_element_factory_make ("ffmpegcolorspace", "csp");
102   if (csp == NULL)
103     g_error ("Could not create 'ffmpegcolorspace' element");
104
105   sink = gst_element_factory_make ("xvimagesink", "sink");
106   if (sink == NULL) {
107     sink = gst_element_factory_make ("ximagesink", "sink");
108     if (sink == NULL)
109       g_error ("Could not create neither 'xvimagesink' nor 'ximagesink' element");
110   }
111
112   gst_bin_add_many (GST_BIN (pipeline), src, filter, csp, sink, NULL);
113   gst_element_link_many (src, filter, csp, sink, NULL);
114   filtercaps = gst_caps_new_simple ("video/x-raw-rgb",
115                            "width", G_TYPE_INT, 384,
116                            "height", G_TYPE_INT, 288,
117                            "framerate", GST_TYPE_FRACTION, 25, 1,
118                            "bpp", G_TYPE_INT, 16,
119                            "depth", G_TYPE_INT, 16,
120                            "endianness", G_TYPE_INT, G_BYTE_ORDER,
121                            NULL);
122   g_object_set (G_OBJECT (filter), "caps", filtercaps, NULL);
123   gst_caps_unref (filtercaps);
124
125   pad = gst_element_get_pad (src, "src");
126   gst_pad_add_buffer_probe (pad, G_CALLBACK (cb_have_data), NULL);
127   gst_object_unref (pad);
128
129   /* run */
130   gst_element_set_state (pipeline, GST_STATE_PLAYING);
131
132   /* wait until it's up and running or failed */
133   if (gst_element_get_state (pipeline, NULL, NULL, -1) == GST_STATE_CHANGE_FAILURE) {
134     g_error ("Failed to go into PLAYING state");
135   }
136
137   g_print ("Running ...\n");
138   g_main_loop_run (loop);
139
140   /* exit */
141   gst_element_set_state (pipeline, GST_STATE_NULL);
142   gst_object_unref (pipeline);
143
144   return 0;
145 }
146     <!-- example-end probe.c --></programlisting>
147     <para>
148       Compare that output with the output of <quote>gst-launch-0.10
149       videotestsrc ! xvimagesink</quote>, just so you know what you're
150       looking for.
151     </para>
152     <para>
153       The above example is not really correct though.  Strictly speaking, a
154       pad probe callback is only allowed to modify the buffer content if the
155       buffer is writable, and it is only allowed to modify buffer metadata like
156       timestamps, caps, etc. if the buffer metadata is writable.  Whether this
157       is the case or not depends a lot on the pipeline and the elements
158       involved.  Often enough, this is the case, but sometimes it is not,
159       and if it is not then unexpected modification of the data or metadata
160       can introduce bugs that are very hard to debug and track down. You can
161       check if a buffer and its metadata are writable with
162       <function>gst_buffer_is_writable ()</function> and
163       <function>gst_buffer_is_metadata_writable ()</function>.  Since you
164       can't pass back a different buffer than the one passed in, there is no
165       point of making a buffer writable in the callback function.
166     </para>
167     <para>
168       Pad probes are suited best for looking at data as it passes through
169       the pipeline. If you need to modify data, you should write your own
170       GStreamer element. Base classes like GstAudioFilter, GstVideoFilter or
171       GstBaseTransform make this fairly easy.
172     </para>
173     <para>
174       If you just want to inspect buffers as they pass through the pipeline,
175       you don't even need to set up pad probes. You could also just insert
176       an identity element into the pipeline and connect to its "handoff"
177       signal. The identity element also provides a few useful debugging tools
178       like the "dump" property or the "last-message" property (the latter is
179       enabled by passing the '-v' switch to gst-launch).
180     </para>
181   </sect1>
182
183   <sect1 id="section-data-spoof">
184     <title>Manually adding or removing data from/to a pipeline</title>
185     <para>
186       Many people have expressed the wish to use their own sources to inject
187       data into a pipeline. Some people have also expressed the wish to grab
188       the output in a pipeline and take care of the actual output inside
189       their application. While either of these methods are stongly
190       discouraged, &GStreamer; offers hacks to do this. <emphasis>However,
191       there is no support for those methods.</emphasis> If it doesn't work,
192       you're on your own. Also, synchronization, thread-safety and other
193       things that you've been able to take for granted so far are no longer
194       guaranteed if you use any of those methods. It's always better to
195       simply write a plugin and have the pipeline schedule and manage it.
196       See the Plugin Writer's Guide for more information on this topic. Also
197       see the next section, which will explain how to embed plugins statically
198       in your application.
199     </para>
200     <note><para>
201         <ulink type="http"
202           url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-libs/html/gstreamer-app.html">New
203           API</ulink> was developed to make data insertion and extraction easy
204         for applications. It can be found as GstAppSrc and GstAppSink in the
205         <ulink type="http"
206           url="http://gstreamer.freedesktop.org/modules/gst-plugins-base.html">
207           gst-plugins-base</ulink> module.
208     </para></note>
209     <para>
210       After all those disclaimers, let's start. There's three possible
211       elements that you can use for the above-mentioned purposes. Those are
212       called <quote>fakesrc</quote> (an imaginary source),
213       <quote>fakesink</quote> (an imaginary sink) and <quote>identity</quote>
214       (an imaginary filter). The same method applies to each of those
215       elements. Here, we will discuss how to use those elements to insert
216       (using fakesrc) or grab (using fakesink or identity) data from a
217       pipeline, and how to set negotiation.
218     </para>
219     <para>
220       Those who're paying close attention will notice that the purpose
221       of identity is almost identical to that of probes. Indeed, this is
222       true. Probes allow for the same purpose, and a bunch more, and
223       with less overhead plus dynamic removing/adding of handlers, but
224       apart from those, probes and identity have the same purpose, just
225       in a completely different implementation type.
226     </para>
227
228     <sect2 id="section-spoof-handoff">
229       <title>Inserting or grabbing data</title>
230       <para>
231         The three before-mentioned elements (fakesrc, fakesink and identity)
232         each have a <quote>handoff</quote> signal that will be called in
233         the <function>_get ()</function>- (fakesrc) or <function>_chain
234         ()</function>-function (identity, fakesink). In the signal handler,
235         you can set (fakesrc) or get (identity, fakesink) data to/from the
236         provided buffer. Note that in the case of fakesrc, you have to set
237         the size of the provided buffer using the <quote>sizemax</quote>
238         property. For both fakesrc and fakesink, you also have to set the
239         <quote>signal-handoffs</quote> property for this method to work.
240       </para>
241       <para>
242         Note that your handoff function should <emphasis>not</emphasis>
243         block, since this will block pipeline iteration. Also, do not try
244         to use all sort of weird hacks in such functions to accomplish
245         something that looks like synchronization or so; it's not the right
246         way and will lead to issues elsewhere. If you're doing any of this,
247         you're basically misunderstanding the &GStreamer; design.
248       </para>
249     </sect2>
250
251     <sect2 id="section-spoof-format">
252       <title>Forcing a format</title>
253       <para>
254         Sometimes, when using fakesrc as a source in your pipeline, you'll
255         want to set a specific format, for example a video size and format
256         or an audio bitsize and number of channels. You can do this by
257         forcing a specific <classname>GstCaps</classname> on the pipeline,
258         which is possible by using <emphasis>filtered caps</emphasis>. You
259         can set a filtered caps on a link by using the
260         <quote>capsfilter</quote> element in between the two elements, and
261         specifying a <classname>GstCaps</classname> as
262         <quote>caps</quote> property on this element. It will then
263         only allow types matching that specified capability set for
264         negotiation.  See also <xref linkend="section-caps-filter"/>.
265       </para>
266     </sect2>
267
268     <sect2 id="section-spoof-example">
269       <title>Example application</title>
270       <para>
271         This example application will generate black/white (it switches
272         every second) video to an X-window output by using fakesrc as a
273         source and using filtered caps to force a format. Since the depth
274         of the image depends on your X-server settings, we use a colorspace
275         conversion element to make sure that the output to your X server
276         will have the correct bitdepth. You can also set timestamps on the
277         provided buffers to override the fixed framerate.
278       </para>
279       <programlisting><!-- example-begin fakesrc.c -->
280 #include &lt;string.h&gt; /* for memset () */
281 #include &lt;gst/gst.h&gt;
282
283 static void
284 cb_handoff (GstElement *fakesrc,
285             GstBuffer  *buffer,
286             GstPad     *pad,
287             gpointer    user_data)
288 {
289   static gboolean white = FALSE;
290   GstMapInfo info;
291   
292   gst_buffer_map (buffer, &amp;info, GST_MAP_WRITE);
293
294   /* this makes the image black/white */
295   memset (info.data, white ? 0xff : 0x0, info.size);
296   white = !white;
297
298   gst_buffer_unmap (buffer, &amp;info);
299 }
300
301 gint
302 main (gint   argc,
303       gchar *argv[])
304 {
305   GstElement *pipeline, *fakesrc, *flt, *conv, *videosink;
306   GMainLoop *loop;
307
308   /* init GStreamer */
309   gst_init (&amp;argc, &amp;argv);
310   loop = g_main_loop_new (NULL, FALSE);
311
312   /* setup pipeline */
313   pipeline = gst_pipeline_new ("pipeline");
314   fakesrc = gst_element_factory_make ("fakesrc", "source");
315   flt = gst_element_factory_make ("capsfilter", "flt");
316   conv = gst_element_factory_make ("ffmpegcolorspace", "conv");
317   videosink = gst_element_factory_make ("xvimagesink", "videosink");
318
319   /* setup */
320   g_object_set (G_OBJECT (flt), "caps",
321                 gst_caps_new_simple ("video/x-raw-rgb",
322                                      "width", G_TYPE_INT, 384,
323                                      "height", G_TYPE_INT, 288,
324                                      "framerate", GST_TYPE_FRACTION, 1, 1,
325                                      "bpp", G_TYPE_INT, 16,
326                                      "depth", G_TYPE_INT, 16,
327                                      "endianness", G_TYPE_INT, G_BYTE_ORDER,
328                                      NULL), NULL);
329   gst_bin_add_many (GST_BIN (pipeline), fakesrc, flt, conv, videosink, NULL);
330   gst_element_link_many (fakesrc, flt, conv, videosink, NULL);
331
332   /* setup fake source */
333   g_object_set (G_OBJECT (fakesrc),
334                 "signal-handoffs", TRUE,
335                 "sizemax", 384 * 288 * 2,
336                 "sizetype", 2, NULL);
337   g_signal_connect (fakesrc, "handoff", G_CALLBACK (cb_handoff), NULL);
338
339   /* play */
340   gst_element_set_state (pipeline, GST_STATE_PLAYING);
341   g_main_loop_run (loop);
342
343   /* clean up */
344   gst_element_set_state (pipeline, GST_STATE_NULL);
345   gst_object_unref (GST_OBJECT (pipeline));
346
347   return 0;
348 }
349       <!-- example-end fakesrc.c --></programlisting>
350     </sect2>
351   </sect1>
352
353   <sect1 id="section-data-manager">
354     <title>Embedding static elements in your application</title>
355     <para>
356       The <ulink type="http"
357       url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/index.html">Plugin
358       Writer's Guide</ulink> describes in great detail how to write elements
359       for the &GStreamer; framework. In this section, we will solely discuss
360       how to embed such elements statically in your application. This can be
361       useful for application-specific elements that have no use elsewhere in
362       &GStreamer;.
363     </para>
364     <para>
365       Dynamically loaded plugins contain a structure that's defined using
366       <function>GST_PLUGIN_DEFINE ()</function>. This structure is loaded
367       when the plugin is loaded by the &GStreamer; core. The structure
368       contains an initialization function (usually called
369       <function>plugin_init</function>) that will be called right after that.
370       It's purpose is to register the elements provided by the plugin with
371       the &GStreamer; framework. If you want to embed elements directly in
372       your application, the only thing you need to do is to replace
373           <function>GST_PLUGIN_DEFINE ()</function> with
374           <function>GST_PLUGIN_DEFINE_STATIC ()</function>. This will cause the
375       elements to be registered when your application loads, and the elements
376       will from then on be available like any other element, without them
377       having to be dynamically loadable libraries. In the example below, you
378       would be able to call <function>gst_element_factory_make
379       ("my-element-name", "some-name")</function> to create an instance of the
380       element.
381     </para>
382
383     <programlisting>
384 /*
385  * Here, you would write the actual plugin code.
386  */
387
388 [..]
389
390 static gboolean
391 register_elements (GstPlugin *plugin)
392 {
393   return gst_element_register (plugin, "my-element-name",
394                                GST_RANK_NONE, MY_PLUGIN_TYPE);
395 }
396
397 GST_PLUGIN_DEFINE_STATIC (
398   GST_VERSION_MAJOR,
399   GST_VERSION_MINOR,
400   "my-private-plugins",
401   "Private elements of my application",
402   register_elements,
403   VERSION,
404   "LGPL",
405   "my-application",
406   "http://www.my-application.net/"
407 )
408     </programlisting>
409   </sect1>
410 </chapter>