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.
26 /* The ElementDetails structure gives a human-readable description of the
27 * plugin, as well as author and version data. Use the GST_ELEMENT_DETAILS
28 * macro when defining it.
30 static GstElementDetails example_details = GST_ELEMENT_DETAILS (
32 "Example/FirstExample",
33 "Shows the basic structure of a plugin",
34 "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 GstStaticPadTemplate sink_template = GST_STATIC_PAD_TEMPLATE (
61 "sink", /* The name of the pad */
62 GST_PAD_SINK, /* Direction of the pad */
63 GST_PAD_ALWAYS, /* The pad exists for every instance */
65 "unknown/unknown, " /* The MIME media type */
66 "foo:int=1, " /* an integer property */
67 "bar:boolean=true, " /* a boolean property */
68 "baz:int={ 1, 3 }" /* a list of values */
72 /* This factory is much simpler, and defines the source pad. */
73 GstStaticPadTemplate src_template = GST_STATIC_PAD_TEMPLATE (
83 /* A number of functon prototypes are given so we can refer to them later. */
84 static void gst_example_class_init (GstExampleClass *klass);
85 static void gst_example_init (GstExample *example);
87 static void gst_example_chain (GstPad *pad, GstData *_data);
89 static void gst_example_set_property (GObject *object, guint prop_id,
90 const GValue *value, GParamSpec *pspec);
91 static void gst_example_get_property (GObject *object, guint prop_id,
92 GValue *value, GParamSpec *pspec);
93 static GstElementStateReturn
94 gst_example_change_state (GstElement *element);
96 /* The parent class pointer needs to be kept around for some object
99 static GstElementClass *parent_class = NULL;
101 /* This array holds the ids of the signals registered for this object.
102 * The array indexes are based on the enum up above.
104 static guint gst_example_signals[LAST_SIGNAL] = { 0 };
106 /* This function is used to register and subsequently return the type
107 * identifier for this object class. On first invocation, it will
108 * register the type, providing the name of the class, struct sizes,
109 * and pointers to the various functions that define the class.
112 gst_example_get_type(void)
114 static GType example_type = 0;
117 static const GTypeInfo example_info = {
118 sizeof(GstExampleClass),
121 (GClassInitFunc)gst_example_class_init,
126 (GInstanceInitFunc)gst_example_init,
128 example_type = g_type_register_static(GST_TYPE_ELEMENT, "GstExample", &example_info, 0);
133 /* In order to create an instance of an object, the class must be
134 * initialized by this function. GObject will take care of running
135 * it, based on the pointer to the function provided above.
138 gst_example_class_init (GstExampleClass *klass)
140 /* Class pointers are needed to supply pointers to the private
141 * implementations of parent class methods.
143 GObjectClass *gobject_class;
144 GstElementClass *gstelement_class;
146 /* Since the example class contains the parent classes, you can simply
147 * cast the pointer to get access to the parent classes.
149 gobject_class = (GObjectClass*)klass;
150 gstelement_class = (GstElementClass*)klass;
152 /* The parent class is needed for class method overrides. */
153 parent_class = g_type_class_ref(GST_TYPE_ELEMENT);
155 /* Here we add an argument to the object. This argument is an integer,
156 * and can be both read and written.
158 g_object_class_install_property(G_OBJECT_CLASS(klass), ARG_ACTIVE,
159 g_param_spec_int("active","active","active",
160 G_MININT,G_MAXINT,0,G_PARAM_READWRITE)); /* CHECKME */
162 /* Here we add a signal to the object. This is avery useless signal
163 * called asdf. The signal will also pass a pointer to the listeners
164 * which happens to be the example element itself */
165 gst_example_signals[ASDF] =
166 g_signal_new("asdf", G_TYPE_FROM_CLASS(klass), G_SIGNAL_RUN_LAST,
167 G_STRUCT_OFFSET (GstExampleClass, asdf), NULL, NULL,
168 g_cclosure_marshal_VOID__POINTER, G_TYPE_NONE, 1,
172 /* The last thing is to provide the functions that implement get and set
175 gobject_class->set_property = gst_example_set_property;
176 gobject_class->get_property = gst_example_get_property;
178 /* we also override the default state change handler with our own
180 gstelement_class->change_state = gst_example_change_state;
181 /* We can now provide the details for this element, that we defined earlier. */
182 gst_element_class_set_details (gstelement_class, &example_details);
183 /* The pad templates can be easily generated from the factories above,
184 * and then added to the list of padtemplates for the class.
186 gst_element_class_add_pad_template (gstelement_class,
187 gst_static_pad_template_get (&sink_template));
188 gst_element_class_add_pad_template (gstelement_class,
189 gst_static_pad_template_get (&src_template));
192 /* This function is responsible for initializing a specific instance of
196 gst_example_init(GstExample *example)
198 /* First we create the sink pad, which is the input to the element.
199 * We will use the template constructed by the factory.
201 example->sinkpad = gst_pad_new_from_template (
202 gst_static_pad_template_get (&sink_template), "sink");
203 /* Setting the chain function allows us to supply the function that will
204 * actually be performing the work. Without this, the element would do
205 * nothing, with undefined results (assertion failures and such).
207 gst_pad_set_chain_function(example->sinkpad,gst_example_chain);
208 /* We then must add this pad to the element's list of pads. The base
209 * element class manages the list of pads, and provides accessors to it.
211 gst_element_add_pad(GST_ELEMENT(example),example->sinkpad);
213 /* The src pad, the output of the element, is created and registered
214 * in the same way, with the exception of the chain function. Source
215 * pads don't have chain functions, because they can't accept buffers,
216 * they only produce them.
218 example->srcpad = gst_pad_new_from_template (
219 gst_static_pad_template_get (&src_template), "src");
220 gst_element_add_pad(GST_ELEMENT(example),example->srcpad);
222 /* Initialization of element's private variables. */
223 example->active = FALSE;
226 /* The chain function is the heart of the element. It's where all the
227 * work is done. It is passed a pointer to the pad in question, as well
228 * as the buffer provided by the peer element.
231 gst_example_chain (GstPad *pad, GstData *_data)
233 GstBuffer *buf = GST_BUFFER (_data);
237 /* Some of these checks are of dubious value, since if there were not
238 * already true, the chain function would never be called.
240 g_return_if_fail(pad != NULL);
241 g_return_if_fail(GST_IS_PAD(pad));
242 g_return_if_fail(buf != NULL);
244 /* We need to get a pointer to the element this pad belogs to. */
245 example = GST_EXAMPLE(gst_pad_get_parent (pad));
247 /* A few more sanity checks to make sure that the element that owns
248 * this pad is the right kind of element, in case something got confused.
250 g_return_if_fail(example != NULL);
251 g_return_if_fail(GST_IS_EXAMPLE(example));
253 /* If we are supposed to be doing something, here's where it happens. */
254 if (example->active) {
255 /* In this example we're going to copy the buffer to another one,
256 * so we need to allocate a new buffer first. */
257 outbuf = gst_buffer_new();
259 /* We need to copy the size and offset of the buffer at a minimum. */
260 GST_BUFFER_SIZE (outbuf) = GST_BUFFER_SIZE (buf);
261 GST_BUFFER_OFFSET (outbuf) = GST_BUFFER_OFFSET (buf);
263 /* Then allocate the memory for the new buffer */
264 GST_BUFFER_DATA (outbuf) = (guchar *)g_malloc (GST_BUFFER_SIZE (outbuf));
266 /* Then copy the data in the incoming buffer into the new buffer. */
267 memcpy (GST_BUFFER_DATA (outbuf), GST_BUFFER_DATA (buf), GST_BUFFER_SIZE (outbuf));
269 /* we don't need the incomming buffer anymore so we unref it. When we are
270 * the last plugin with a handle to the buffer, its memory will be freed */
271 gst_buffer_unref (buf);
273 /* When we're done with the buffer, we push it on to the next element
274 * in the pipeline, through the element's source pad, which is stored
275 * in the element's structure.
277 gst_pad_push(example->srcpad,GST_DATA (outbuf));
279 /* For fun we'll emit our useless signal here */
280 g_signal_emit(G_OBJECT (example), gst_example_signals[ASDF], 0,
283 /* If we're not doing something, just send the original incoming buffer. */
285 gst_pad_push(example->srcpad,GST_DATA (buf));
289 /* Arguments are part of the Gtk+ object system, and these functions
290 * enable the element to respond to various arguments.
293 gst_example_set_property (GObject *object, guint prop_id, const GValue *value, GParamSpec *pspec)
297 /* It's not null if we got it, but it might not be ours */
298 g_return_if_fail(GST_IS_EXAMPLE(object));
300 /* Get a pointer of the right type. */
301 example = GST_EXAMPLE(object);
303 /* Check the argument id to see which argument we're setting. */
306 /* Here we simply copy the value of the argument to our private
307 * storage. More complex operations can be done, but beware that
308 * they may occur at any time, possibly even while your chain function
309 * is running, if you are using threads.
311 example->active = g_value_get_int (value);
312 g_print("example: set active to %d\n",example->active);
319 /* The set function is simply the inverse of the get fuction. */
321 gst_example_get_property (GObject *object, guint prop_id, GValue *value, GParamSpec *pspec)
325 /* It's not null if we got it, but it might not be ours */
326 g_return_if_fail(GST_IS_EXAMPLE(object));
327 example = GST_EXAMPLE(object);
331 g_value_set_int (value, example->active);
334 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
339 /* This is the state change function that will be called when
340 * the element goes through the different state changes.
341 * The plugin can prepare itself and its internal data structures
342 * in the various state transitions.
344 static GstElementStateReturn
345 gst_example_change_state (GstElement *element)
349 /* cast to our plugin */
350 example = GST_EXAMPLE(element);
352 /* we perform our actions based on the state transition
354 switch (GST_STATE_TRANSITION (element)) {
355 /* The NULL to READY transition is used to
356 * create threads (if any) */
357 case GST_STATE_NULL_TO_READY:
359 /* In the READY to PAUSED state, the element should
360 * open devices (if any) */
361 case GST_STATE_READY_TO_PAUSED:
363 /* In the PAUSED to PLAYING state, the element should
364 * prepare itself for operation or continue after a PAUSE */
365 case GST_STATE_PAUSED_TO_PLAYING:
367 /* In the PLAYING to PAUSED state, the element should
368 * PAUSE itself and make sure it can resume operation */
369 case GST_STATE_PLAYING_TO_PAUSED:
371 /* In the PAUSED to READY state, the element should reset
372 * its internal state and close any devices. */
373 case GST_STATE_PAUSED_TO_READY:
375 /* The element should free all resources, terminate threads
376 * and put itself into its initial state again */
377 case GST_STATE_READY_TO_NULL:
381 /* Then we call the parent state change handler */
382 return parent_class->change_state (element);
386 /* This is the entry into the plugin itself. When the plugin loads,
387 * this function is called to register everything that the plugin provides.
390 plugin_init (GstPlugin *plugin)
392 /* We need to register each element we provide with the plugin. This consists
393 * of the name of the element, a rank that gives the importance of the element
394 * when compared to similar plugins and the GType identifier.
396 if (!gst_element_register (plugin, "example", GST_RANK_MARGINAL, GST_TYPE_EXAMPLE))
399 /* Now we can return successfully. */
402 /* At this point, the GStreamer core registers the plugin, its
403 * elementfactories, padtemplates, etc., for use in your application.
407 /* This structure describes the plugin to the system for dynamically loading
408 * plugins, so that the version number and name can be checked in a uniform
411 * The symbol pointing to this structure is the only symbol looked up when
412 * loading the plugin.
415 GST_VERSION_MAJOR, /* The major version of the core that this was built with */
416 GST_VERSION_MINOR, /* The minor version of the core that this was built with */
417 "example", /* The name of the plugin. This must be unique: plugins with
418 * the same name will be assumed to be identical, and only
419 * one will be loaded. */
420 "an example plugin", /* a short description of the plugin in English */
421 plugin_init, /* Pointer to the initialisation function for the plugin. */
422 "0.1", /* The version number of the plugin */
423 "LGPL", /* ieffective license the plugin can be shipped with. Must be
424 * valid for all libraries it links to, too. */
425 "my nifty plugin package",
426 /* package this plugin belongs to. */
427 "http://www.mydomain.com"
428 /* originating URL for this plugin. This is the place to look
429 * for updates, information and so on. */