2 * Copyright (C) <1999> Erik Walthinsen <omega@cse.ogi.edu>
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.
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.
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.
20 /* First, include the header file for the plugin, to bring in the
21 * object definition and other useful things.
25 /* The ElementDetails structure gives a human-readable description
26 * of the plugin, as well as author and version data.
28 static GstElementDetails example_details = {
30 "Example/FirstExample",
31 "Shows the basic structure of a plugin",
33 "your name <your.name@your.isp>",
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.
47 /* Arguments are identified the same way, but cannot be zero, so you
48 * must leave the ARG_0 entry in as a placeholder.
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.
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 */
74 NULL /* All factories must be NULL-terminated */
77 /* This factory is much simpler, and defines the source pad. */
78 static GstPadFactory src_factory = {
81 GST_PAD_FACTORY_ALWAYS,
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);
94 static void gst_example_chain (GstPad *pad, GstBuffer *buf);
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);
99 /* These hold the constructed pad templates, which are created during
100 * plugin load, and used during element instantiation.
102 static GstPadTemplate *src_template, *sink_template;
104 /* The parent class pointer needs to be kept around for some object
107 static GstElementClass *parent_class = NULL;
109 /* This array holds the ids of the signals registered for this object.
110 * The array indexes are based on the enum up above.
112 static guint gst_example_signals[LAST_SIGNAL] = { 0 };
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.
120 gst_example_get_type(void)
122 static GtkType example_type = 0;
125 static const GtkTypeInfo example_info = {
128 sizeof(GstExampleClass),
129 (GtkClassInitFunc)gst_example_class_init,
130 (GtkObjectInitFunc)gst_example_init,
131 (GtkArgSetFunc)NULL, /* These last three are depracated */
133 (GtkClassInitFunc)NULL,
135 example_type = gtk_type_unique(GST_TYPE_ELEMENT,&example_info);
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.
145 gst_example_class_init (GstExampleClass *klass)
147 /* Class pointers are needed to supply pointers to the private
148 * implementations of parent class methods.
150 GtkObjectClass *gtkobject_class;
151 GstElementClass *gstelement_class;
153 /* Since the example class contains the parent classes, you can simply
154 * cast the pointer to get access to the parent classes.
156 gtkobject_class = (GtkObjectClass*)klass;
157 gstelement_class = (GstElementClass*)klass;
159 /* The parent class is needed for class method overrides. */
160 parent_class = gtk_type_class(GST_TYPE_ELEMENT);
162 /* Here we add an argument to the object. This argument is an integer,
163 * and can be both read and written.
165 gtk_object_add_arg_type("GstExample::active", GTK_TYPE_INT,
166 GTK_ARG_READWRITE, ARG_ACTIVE);
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,
177 gtk_object_class_add_signals (gtkobject_class, gst_example_signals,
180 /* The last thing is to provide the functions that implement get and set
183 gtkobject_class->set_arg = gst_example_set_arg;
184 gtkobject_class->get_arg = gst_example_get_arg;
187 /* This function is responsible for initializing a specific instance of
191 gst_example_init(GstExample *example)
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.
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).
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.
206 gst_element_add_pad(GST_ELEMENT(example),example->sinkpad);
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.
213 example->srcpad = gst_pad_new_from_template (src_template, "src");
214 gst_element_add_pad(GST_ELEMENT(example),example->srcpad);
216 /* Initialization of element's private variables. */
217 example->active = FALSE;
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.
225 gst_example_chain (GstPad *pad, GstBuffer *buf)
230 /* Some of these checks are of dubious value, since if there were not
231 * already true, the chain function would never be called.
233 g_return_if_fail(pad != NULL);
234 g_return_if_fail(GST_IS_PAD(pad));
235 g_return_if_fail(buf != NULL);
237 /* We need to get a pointer to the element this pad belogs to. */
238 example = GST_EXAMPLE(gst_pad_get_parent (pad));
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.
243 g_return_if_fail(example != NULL);
244 g_return_if_fail(GST_IS_EXAMPLE(example));
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();
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);
256 /* Then allocate the memory for the new buffer */
257 GST_BUFFER_DATA (outbuf) = (guchar *)g_malloc (GST_BUFFER_SIZE (outbuf));
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));
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.
266 gst_pad_push(example->srcpad,outbuf);
268 /* For fun we'll emit our useless signal here */
269 gtk_signal_emit (GTK_OBJECT (example), gst_example_signals[ASDF],
272 /* If we're not doing something, just send the original incoming buffer. */
274 gst_pad_push(example->srcpad,buf);
278 /* Arguments are part of the Gtk+ object system, and these functions
279 * enable the element to respond to various arguments.
282 gst_example_set_arg (GtkObject *object,GtkArg *arg,guint id)
286 /* It's not null if we got it, but it might not be ours */
287 g_return_if_fail(GST_IS_EXAMPLE(object));
289 /* Get a pointer of the right type. */
290 example = GST_EXAMPLE(object);
292 /* Check the argument id to see which argument we're setting. */
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.
300 example->active = GTK_VALUE_INT(*arg);
301 g_print("example: set active to %d\n",example->active);
308 /* The set function is simply the inverse of the get fuction. */
310 gst_example_get_arg (GtkObject *object,GtkArg *arg,guint id)
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);
320 GTK_VALUE_INT(*arg) = example->active;
323 arg->type = GTK_TYPE_INVALID;
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.
332 plugin_init (GModule *module)
335 GstElementFactory *factory;
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);
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.
346 factory = gst_elementfactory_new("example", GST_TYPE_EXAMPLE, &example_details);
347 g_return_val_if_fail(factory != NULL, NULL);
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.
354 sink_template = gst_padtemplate_new (&sink_factory);
355 gst_elementfactory_add_padtemplate (factory, sink_template);
357 src_template = gst_padtemplate_new (&src_factory);
358 gst_elementfactory_add_padtemplate (factory, src_template);
360 /* The very last thing is to register the elementfactory with the plugin. */
361 gst_plugin_add_factory (plugin, factory);
363 /* Now we can return the pointer to the newly created Plugin object. */
366 /* At this point, the GStreamer core registers the plugin, its
367 * elementfactories, padtemplates, etc., for use in you application.