Added --enable-plugin-docs configure option, to enable build of the plugin documentat...
[platform/upstream/gstreamer.git] / examples / plugins / example.c
1 /* Gnome-Streamer
2  * Copyright (C) <1999> Erik Walthinsen <omega@cse.ogi.edu>
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Library General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Library General Public License for more details.
13  *
14  * You should have received a copy of the GNU Library General Public
15  * License along with this library; if not, write to the
16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17  * Boston, MA 02111-1307, USA.
18  */
19
20 /* First, include the header file for the plugin, to bring in the
21  * object definition and other useful things.
22  */
23 #include "example.h"
24
25 /* The ElementDetails structure gives a human-readable description
26  * of the plugin, as well as author and version data.
27  */
28 static GstElementDetails example_details = {
29   "An example plugin",
30   "Example/FirstExample",
31   "Shows the basic structure of a plugin",
32   VERSION,
33   "your name <your.name@your.isp>",
34   "(C) 2001",
35 };
36
37 /* These are the signals that this element can fire.  They are zero-
38  * based because the numbers themselves are private to the object.
39  * LAST_SIGNAL is used for initialization of the signal array.
40  */
41 enum {
42   ASDF,
43   /* FILL ME */
44   LAST_SIGNAL
45 };
46
47 /* Arguments are identified the same way, but cannot be zero, so you
48  * must leave the ARG_0 entry in as a placeholder.
49  */
50 enum {
51   ARG_0,
52   ARG_ACTIVE,
53   /* FILL ME */
54 };
55
56 /* The PadFactory structures describe what pads the element has or
57  * can have.  They can be quite complex, but for this example plugin
58  * they are rather simple.
59  */
60 static GstPadFactory sink_factory = {
61   "sink",                       /* The name of the pad */
62   GST_PAD_FACTORY_SINK,         /* Direction of the pad */
63   GST_PAD_FACTORY_ALWAYS,       /* The pad exists for every instance */
64   GST_PAD_FACTORY_CAPS(         /* This factory has specific capabilities */
65   "example_sink",                               /* The name of the caps */
66      "unknown/unknown",                         /* The overall MIME/type */
67      "foo",     GST_PROPS_INT (1),              /* An integer property */
68      "bar",     GST_PROPS_BOOLEAN (TRUE),       /* A boolean */
69      "baz",     GST_PROPS_LIST (                /* A list of values for */
70                         GST_PROPS_INT (1),
71                         GST_PROPS_INT (3)
72                 )
73   ),
74   NULL                          /* All factories must be NULL-terminated */
75 };
76
77 /* This factory is much simpler, and defines the source pad. */
78 static GstPadFactory src_factory = {
79   "src",
80   GST_PAD_FACTORY_SRC,
81   GST_PAD_FACTORY_ALWAYS,
82   GST_PAD_FACTORY_CAPS(
83   "example_src",
84     "unknown/unknown"
85   ),
86   NULL
87 };
88
89
90 /* A number of functon prototypes are given so we can refer to them later. */
91 static void     gst_example_class_init  (GstExampleClass *klass);
92 static void     gst_example_init        (GstExample *example);
93
94 static void     gst_example_chain       (GstPad *pad, GstBuffer *buf);
95
96 static void     gst_example_set_arg     (GtkObject *object,GtkArg *arg,guint id);
97 static void     gst_example_get_arg     (GtkObject *object,GtkArg *arg,guint id);
98
99 /* These hold the constructed pad templates, which are created during
100  * plugin load, and used during element instantiation.
101  */
102 static GstPadTemplate *src_template, *sink_template;
103
104 /* The parent class pointer needs to be kept around for some object
105  * operations.
106  */
107 static GstElementClass *parent_class = NULL;
108
109 /* This array holds the ids of the signals registered for this object.
110  * The array indexes are based on the enum up above.
111  */
112 static guint gst_example_signals[LAST_SIGNAL] = { 0 };
113
114 /* This function is used to register and subsequently return the type
115  * identifier for this object class.  On first invocation, it will
116  * register the type, providing the name of the class, struct sizes,
117  * and pointers to the various functions that define the class.
118  */
119 GtkType
120 gst_example_get_type(void)
121 {
122   static GtkType example_type = 0;
123
124   if (!example_type) {
125     static const GtkTypeInfo example_info = {
126       "GstExample",
127       sizeof(GstExample),
128       sizeof(GstExampleClass),
129       (GtkClassInitFunc)gst_example_class_init,
130       (GtkObjectInitFunc)gst_example_init,
131       (GtkArgSetFunc)NULL,      /* These last three are depracated */
132       (GtkArgGetFunc)NULL,
133       (GtkClassInitFunc)NULL,
134     };
135     example_type = gtk_type_unique(GST_TYPE_ELEMENT,&example_info);
136   }
137   return example_type;
138 }
139
140 /* In order to create an instance of an object, the class must be
141  * initialized by this function.  GtkObject will take care of running
142  * it, based on the pointer to the function provided above.
143  */
144 static void
145 gst_example_class_init (GstExampleClass *klass)
146 {
147   /* Class pointers are needed to supply pointers to the private
148    * implementations of parent class methods.
149    */
150   GtkObjectClass *gtkobject_class;
151   GstElementClass *gstelement_class;
152
153   /* Since the example class contains the parent classes, you can simply
154    * cast the pointer to get access to the parent classes.
155    */
156   gtkobject_class = (GtkObjectClass*)klass;
157   gstelement_class = (GstElementClass*)klass;
158
159   /* The parent class is needed for class method overrides. */
160   parent_class = gtk_type_class(GST_TYPE_ELEMENT);
161
162   /* Here we add an argument to the object.  This argument is an integer,
163    * and can be both read and written.
164    */
165   gtk_object_add_arg_type("GstExample::active", GTK_TYPE_INT,
166                           GTK_ARG_READWRITE, ARG_ACTIVE);
167
168   /* Here we add a signal to the object. This is avery useless signal
169    * called asdf. The signal will also pass a pointer to the listeners
170    * which happens to be the example element itself */
171   gst_example_signals[ASDF] =
172     gtk_signal_new("asdf", GTK_RUN_LAST, gtkobject_class->type,
173                    GTK_SIGNAL_OFFSET (GstExampleClass, asdf),
174                    gtk_marshal_NONE__POINTER, GTK_TYPE_NONE, 1,
175                    GST_TYPE_EXAMPLE);
176
177   gtk_object_class_add_signals (gtkobject_class, gst_example_signals,
178                                 LAST_SIGNAL);
179
180   /* The last thing is to provide the functions that implement get and set
181    * of arguments.
182    */
183   gtkobject_class->set_arg = gst_example_set_arg;
184   gtkobject_class->get_arg = gst_example_get_arg;
185 }
186
187 /* This function is responsible for initializing a specific instance of
188  * the plugin.
189  */
190 static void
191 gst_example_init(GstExample *example)
192 {
193   /* First we create the sink pad, which is the input to the element.
194    * We will use the sink_template constructed in the plugin_init function
195    * (below) to quickly generate the pad we need.
196    */
197   example->sinkpad = gst_pad_new_from_template (sink_template, "sink");
198   /* Setting the chain function allows us to supply the function that will
199    * actually be performing the work.  Without this, the element would do
200    * nothing, with undefined results (assertion failures and such).
201    */
202   gst_pad_set_chain_function(example->sinkpad,gst_example_chain);
203   /* We then must add this pad to the element's list of pads.  The base
204    * element class manages the list of pads, and provides accessors to it.
205    */
206   gst_element_add_pad(GST_ELEMENT(example),example->sinkpad);
207
208   /* The src pad, the output of the element, is created and registered
209    * in the same way, with the exception of the chain function.  Source
210    * pads don't have chain functions, because they can't accept buffers,
211    * they only produce them.
212    */
213   example->srcpad = gst_pad_new_from_template (src_template, "src");
214   gst_element_add_pad(GST_ELEMENT(example),example->srcpad);
215
216   /* Initialization of element's private variables. */
217   example->active = FALSE;
218 }
219
220 /* The chain function is the heart of the element.  It's where all the
221  * work is done.  It is passed a pointer to the pad in question, as well
222  * as the buffer provided by the peer element.
223  */
224 static void
225 gst_example_chain (GstPad *pad, GstBuffer *buf)
226 {
227   GstExample *example;
228   GstBuffer *outbuf;
229
230   /* Some of these checks are of dubious value, since if there were not
231    * already true, the chain function would never be called.
232    */
233   g_return_if_fail(pad != NULL);
234   g_return_if_fail(GST_IS_PAD(pad));
235   g_return_if_fail(buf != NULL);
236
237   /* We need to get a pointer to the element this pad belogs to. */
238   example = GST_EXAMPLE(gst_pad_get_parent (pad));
239
240   /* A few more sanity checks to make sure that the element that owns
241    * this pad is the right kind of element, in case something got confused.
242    */
243   g_return_if_fail(example != NULL);
244   g_return_if_fail(GST_IS_EXAMPLE(example));
245
246   /* If we are supposed to be doing something, here's where it happens. */
247   if (example->active) {
248     /* In this example we're going to copy the buffer to another one, 
249      * so we need to allocate a new buffer first. */
250     outbuf = gst_buffer_new();
251
252     /* We need to copy the size and offset of the buffer at a minimum. */
253     GST_BUFFER_SIZE (outbuf) = GST_BUFFER_SIZE (buf);
254     GST_BUFFER_OFFSET (outbuf) = GST_BUFFER_OFFSET (buf);
255
256     /* Then allocate the memory for the new buffer */
257     GST_BUFFER_DATA (outbuf) = (guchar *)g_malloc (GST_BUFFER_SIZE (outbuf));
258
259     /* Then copy the data in the incoming buffer into the new buffer. */
260     memcpy (GST_BUFFER_DATA (outbuf), GST_BUFFER_DATA (buf), GST_BUFFER_SIZE (outbuf));
261
262     /* When we're done with the buffer, we push it on to the next element
263      * in the pipeline, through the element's source pad, which is stored
264      * in the element's structure.
265      */
266     gst_pad_push(example->srcpad,outbuf);
267
268     /* For fun we'll emit our useless signal here */
269     gtk_signal_emit (GTK_OBJECT (example), gst_example_signals[ASDF],
270                      example);
271
272   /* If we're not doing something, just send the original incoming buffer. */
273   } else {
274     gst_pad_push(example->srcpad,buf);
275   }
276 }
277
278 /* Arguments are part of the Gtk+ object system, and these functions
279  * enable the element to respond to various arguments.
280  */
281 static void
282 gst_example_set_arg (GtkObject *object,GtkArg *arg,guint id)
283 {
284   GstExample *example;
285
286   /* It's not null if we got it, but it might not be ours */
287   g_return_if_fail(GST_IS_EXAMPLE(object));
288
289   /* Get a pointer of the right type. */
290   example = GST_EXAMPLE(object);
291
292   /* Check the argument id to see which argument we're setting. */
293   switch (id) {
294     case ARG_ACTIVE:
295       /* Here we simply copy the value of the argument to our private
296        * storage.  More complex operations can be done, but beware that
297        * they may occur at any time, possibly even while your chain function
298        * is running, if you are using threads.
299        */
300       example->active = GTK_VALUE_INT(*arg);
301       g_print("example: set active to %d\n",example->active);
302       break;
303     default:
304       break;
305   }
306 }
307
308 /* The set function is simply the inverse of the get fuction. */
309 static void
310 gst_example_get_arg (GtkObject *object,GtkArg *arg,guint id)
311 {
312   GstExample *example;
313
314   /* It's not null if we got it, but it might not be ours */
315   g_return_if_fail(GST_IS_EXAMPLE(object));
316   example = GST_EXAMPLE(object);
317
318   switch (id) {
319     case ARG_ACTIVE:
320       GTK_VALUE_INT(*arg) = example->active;
321       break;
322     default:
323       arg->type = GTK_TYPE_INVALID;
324       break;
325   }
326 }
327
328 /* This is the entry into the plugin itself.  When the plugin loads,
329  * this function is called to register everything that the plugin provides.
330  */
331 GstPlugin*
332 plugin_init (GModule *module)
333 {
334   GstPlugin *plugin;
335   GstElementFactory *factory;
336
337   /* First we try to create a new Plugin structure. */
338   plugin = gst_plugin_new("example");
339   /* If we get a NULL back, chances are we're already loaded. */
340   g_return_val_if_fail(plugin != NULL, NULL);
341
342   /* We need to create an ElementFactory for each element we provide.
343    * This consists of the name of the element, the GtkType identifier,
344    * and a pointer to the details structure at the top of the file.
345    */
346   factory = gst_elementfactory_new("example", GST_TYPE_EXAMPLE, &example_details);
347   g_return_val_if_fail(factory != NULL, NULL);
348
349   /* The pad templates can be easily generated from the factories above,
350    * and then added to the list of padtemplates for the elementfactory.
351    * Note that the generated padtemplates are stored in static global
352    * variables, for the gst_example_init function to use later on.
353    */
354   sink_template = gst_padtemplate_new (&sink_factory);
355   gst_elementfactory_add_padtemplate (factory, sink_template);
356
357   src_template = gst_padtemplate_new (&src_factory);
358   gst_elementfactory_add_padtemplate (factory, src_template);
359
360   /* The very last thing is to register the elementfactory with the plugin. */
361   gst_plugin_add_factory (plugin, factory);
362
363   /* Now we can return the pointer to the newly created Plugin object. */
364   return plugin;
365
366   /* At this point, the GStreamer core registers the plugin, its
367    * elementfactories, padtemplates, etc., for use in you application.
368    */
369 }