tests/old/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",
  31   "Shows the basic structure of a plugin",
  32   VERSION,
  33   "your name <your.name@your.isp>",
  34   "(C) 2000",
  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   /* The last thing is to provide the functions that implement get and set
 169    * of arguments.
 170    */
 171   gtkobject_class->set_arg = gst_example_set_arg;
 172   gtkobject_class->get_arg = gst_example_get_arg;
 173 }
 174
 175 /* This function is responsible for initializing a specific instance of
 176  * the plugin.
 177  */
 178 static void
 179 gst_example_init(GstExample *example)
 180 {
 181   /* First we create the sink pad, which is the input to the element.
 182    * We will use the sink_template constructed in the plugin_init function
 183    * (below) to quickly generate the pad we need.
 184    */
 185   example->sinkpad = gst_pad_new_from_template (sink_template, "sink");
 186   /* Setting the chain function allows us to supply the function that will
 187    * actually be performing the work.  Without this, the element would do
 188    * nothing, with undefined results (assertion failures and such).
 189    */
 190   gst_pad_set_chain_function(example->sinkpad,gst_example_chain);
 191   /* We then must add this pad to the element's list of pads.  The base
 192    * element class manages the list of pads, and provides accessors to it.
 193    */
 194   gst_element_add_pad(GST_ELEMENT(example),example->sinkpad);
 195
 196   /* The src pad, the output of the element, is created and registered
 197    * in the same way, with the exception of the chain function.  Source
 198    * pads don't have chain functions, because they can't accept buffers,
 199    * they only produce them.
 200    */
 201   example->srcpad = gst_pad_new_from_template (src_template, "src");
 202   gst_element_add_pad(GST_ELEMENT(example),example->srcpad);
 203
 204   /* Initialization of element's private variables. */
 205   example->active = FALSE;
 206 }
 207
 208 /* The chain function is the heart of the element.  It's where all the
 209  * work is done.  It is passed a pointer to the pad in question, as well
 210  * as the buffer provided by the peer element.
 211  */
 212 static void
 213 gst_example_chain (GstPad *pad, GstBuffer *buf)
 214 {
 215   GstExample *example;
 216   GstBuffer *outbuf;
 217
 218   /* Some of these checks are of dubious value, since if there were not
 219    * already true, the chain function would never be called.
 220    */
 221   g_return_if_fail(pad != NULL);
 222   g_return_if_fail(GST_IS_PAD(pad));
 223   g_return_if_fail(buf != NULL);
 224   g_return_if_fail(GST_IS_BUFFER(buf));
 225
 226   /* We need to get a pointer to the element this pad belogs to. */
 227   example = GST_EXAMPLE(gst_pad_get_parent (pad));
 228
 229   /* A few more sanity checks to make sure that the element that owns
 230    * this pad is the right kind of element, in case something got confused.
 231    */
 232   g_return_if_fail(example != NULL);
 233   g_return_if_fail(GST_IS_EXAMPLE(example));
 234
 235   /* If we are supposed to be doing something, here's where it happens. */
 236   if (example->active) {
 237     /* In this example we're going to copy the buffer to another one,
 238      * so we need to allocate a new buffer first.
 239     outbuf = gst_buffer_new();
 240
 241     /* We need to copy the size and offset of the buffer at a minimum. */
 242     GST_BUFFER_SIZE (outbuf) = GST_BUFFER_SIZE (buf);
 243     GST_BUFFER_OFFSET (outbuf) = GST_BUFFER_OFFSET (buf);
 244
 245     /* Then allocate the memory for the new buffer */
 246     GST_BUFFER_DATA (outbuf) = (guchar *)g_malloc (GST_BUFFER_SIZE (outbuf));
 247
 248     /* Then copy the data in the incoming buffer into the new buffer. */
 249     memcpy (GST_BUFFER_DATA (outbuf), GST_BUFFER_DATA (buf), GST_BUFFER_SIZE (outbuf));
 250
 251     /* When we're done with the buffer, we push it on to the next element
 252      * in the pipeline, through the element's source pad, which is stored
 253      * in the element's structure.
 254      */
 255     gst_pad_push(example->srcpad,outbuf);
 256
 257   /* If we're not doing something, just send the original incoming buffer. */
 258   } else {
 259     gst_pad_push(example->srcpad,buf);
 260   }
 261 }
 262
 263 /* Arguments are part of the Gtk+ object system, and these functions
 264  * enable the element to respond to various arguments.
 265  */
 266 static void
 267 gst_example_set_arg (GtkObject *object,GtkArg *arg,guint id)
 268 {
 269   GstExample *example;
 270
 271   /* It's not null if we got it, but it might not be ours */
 272   g_return_if_fail(GST_IS_EXAMPLE(object));
 273
 274   /* Get a pointer of the right type. */
 275   example = GST_EXAMPLE(object);
 276
 277   /* Check the argument id to see which argument we're setting. */
 278   switch (id) {
 279     case ARG_ACTIVE:
 280       /* Here we simply copy the value of the argument to our private
 281        * storage.  More complex operations can be done, but beware that
 282        * they may occur at any time, possibly even while your chain function
 283        * is running, if you are using threads.
 284        */
 285       example->active = GTK_VALUE_INT(*arg);
 286       g_print("example: set active to %d\n",example->active);
 287       break;
 288     default:
 289       break;
 290   }
 291 }
 292
 293 /* The set function is simply the inverse of the get fuction. */
 294 static void
 295 gst_example_get_arg (GtkObject *object,GtkArg *arg,guint id)
 296 {
 297   GstExample *example;
 298
 299   /* It's not null if we got it, but it might not be ours */
 300   g_return_if_fail(GST_IS_EXAMPLE(object));
 301   example = GST_EXAMPLE(object);
 302
 303   switch (id) {
 304     case ARG_ACTIVE:
 305       GTK_VALUE_INT(*arg) = example->active;
 306       break;
 307     default:
 308       arg->type = GTK_TYPE_INVALID;
 309       break;
 310   }
 311 }
 312
 313 /* This is the entry into the plugin itself.  When the plugin loads,
 314  * this function is called to register everything that the plugin provides.
 315  */
 316 GstPlugin*
 317 plugin_init (GModule *module)
 318 {
 319   GstPlugin *plugin;
 320   GstElementFactory *factory;
 321
 322   /* First we try to create a new Plugin structure. */
 323   plugin = gst_plugin_new("example");
 324   /* If we get a NULL back, chances are we're already loaded. */
 325   g_return_val_if_fail(plugin != NULL, NULL);
 326
 327   /* We need to create an ElementFactory for each element we provide.
 328    * This consists of the name of the element, the GtkType identifier,
 329    * and a pointer to the details structure at the top of the file.
 330    */
 331   factory = gst_elementfactory_new("example", GST_TYPE_EXAMPLE, &example_details);
 332   g_return_val_if_fail(factory != NULL, NULL);
 333
 334   /* The pad templates can be easily generated from the factories above,
 335    * and then added to the list of padtemplates for the elementfactory.
 336    * Note that the generated padtemplates are stored in static global
 337    * variables, for the gst_example_init function to use later on.
 338    */
 339   sink_template = gst_padtemplate_new (&sink_factory);
 340   gst_elementfactory_add_padtemplate (factory, sink_template);
 341
 342   src_template = gst_padtemplate_new (&src_factory);
 343   gst_elementfactory_add_padtemplate (factory, src_template);
 344
 345   /* The very last thing is to register the elementfactory with the plugin. */
 346   gst_plugin_add_factory (plugin, factory);
 347
 348   /* Now we can return the pointer to the newly created Plugin object. */
 349   return plugin;
 350
 351   /* At this point, the GStreamer core registers the plugin, its
 352    * elementfactories, padtemplates, etc., for use in you application.
 353    */
 354 }