tests/old/examples/plugins/example.c

   1 /* GStreamer
   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 <string.h>
  24 #include "example.h"
  25
  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.
  29  */
  30 static GstElementDetails example_details =
  31 GST_ELEMENT_DETAILS ("An example plugin",
  32     "Example/FirstExample",
  33     "Shows the basic structure of a plugin",
  34     "your name <your.name@your.isp>");
  35
  36 /* These are the signals that this element can fire.  They are zero-
  37  * based because the numbers themselves are private to the object.
  38  * LAST_SIGNAL is used for initialization of the signal array.
  39  */
  40 enum
  41 {
  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 {
  52   ARG_0,
  53   ARG_ACTIVE
  54       /* FILL ME */
  55 };
  56
  57 /* The PadFactory structures describe what pads the element has or
  58  * can have.  They can be quite complex, but for this example plugin
  59  * they are rather simple.
  60  */
  61 GstStaticPadTemplate sink_template = GST_STATIC_PAD_TEMPLATE ("sink",   /* The name of the pad */
  62     GST_PAD_SINK,               /* Direction of the pad */
  63     GST_PAD_ALWAYS,             /* The pad exists for every instance */
  64     GST_STATIC_CAPS ("unknown/unknown, "        /* The MIME media type */
  65         "foo:int=1, "           /* an integer property */
  66         "bar:boolean=true, "    /* a boolean property */
  67         "baz:int={ 1, 3 }"      /* a list of values */
  68     )
  69     );
  70
  71 /* This factory is much simpler, and defines the source pad. */
  72 GstStaticPadTemplate src_template = GST_STATIC_PAD_TEMPLATE ("src",
  73     GST_PAD_SRC,
  74     GST_PAD_ALWAYS,
  75     GST_STATIC_CAPS ("unknown/unknown")
  76     );
  77
  78
  79 /* A number of functon prototypes are given so we can refer to them later. */
  80 static void gst_example_class_init (GstExampleClass * klass);
  81 static void gst_example_init (GstExample * example);
  82
  83 static void gst_example_chain (GstPad * pad, GstData * _data);
  84
  85 static void gst_example_set_property (GObject * object, guint prop_id,
  86     const GValue * value, GParamSpec * pspec);
  87 static void gst_example_get_property (GObject * object, guint prop_id,
  88     GValue * value, GParamSpec * pspec);
  89 static GstElementStateReturn gst_example_change_state (GstElement * element);
  90
  91 /* The parent class pointer needs to be kept around for some object
  92  * operations.
  93  */
  94 static GstElementClass *parent_class = NULL;
  95
  96 /* This array holds the ids of the signals registered for this object.
  97  * The array indexes are based on the enum up above.
  98  */
  99 static guint gst_example_signals[LAST_SIGNAL] = { 0 };
 100
 101 /* This function is used to register and subsequently return the type
 102  * identifier for this object class.  On first invocation, it will
 103  * register the type, providing the name of the class, struct sizes,
 104  * and pointers to the various functions that define the class.
 105  */
 106 GType
 107 gst_example_get_type (void)
 108 {
 109   static GType example_type = 0;
 110
 111   if (!example_type) {
 112     static const GTypeInfo example_info = {
 113       sizeof (GstExampleClass),
 114       NULL,
 115       NULL,
 116       (GClassInitFunc) gst_example_class_init,
 117       NULL,
 118       NULL,
 119       sizeof (GstExample),
 120       0,
 121       (GInstanceInitFunc) gst_example_init,
 122     };
 123
 124     example_type =
 125         g_type_register_static (GST_TYPE_ELEMENT, "GstExample", &example_info,
 126         0);
 127   }
 128   return example_type;
 129 }
 130
 131 /* In order to create an instance of an object, the class must be
 132  * initialized by this function.  GObject will take care of running
 133  * it, based on the pointer to the function provided above.
 134  */
 135 static void
 136 gst_example_class_init (GstExampleClass * klass)
 137 {
 138   /* Class pointers are needed to supply pointers to the private
 139    * implementations of parent class methods.
 140    */
 141   GObjectClass *gobject_class;
 142   GstElementClass *gstelement_class;
 143
 144   /* Since the example class contains the parent classes, you can simply
 145    * cast the pointer to get access to the parent classes.
 146    */
 147   gobject_class = (GObjectClass *) klass;
 148   gstelement_class = (GstElementClass *) klass;
 149
 150   /* The parent class is needed for class method overrides. */
 151   parent_class = g_type_class_ref (GST_TYPE_ELEMENT);
 152
 153   /* Here we add an argument to the object.  This argument is an integer,
 154    * and can be both read and written.
 155    */
 156   g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_ACTIVE, g_param_spec_int ("active", "active", "active", G_MININT, G_MAXINT, 0, G_PARAM_READWRITE));      /* CHECKME */
 157
 158   /* Here we add a signal to the object. This is avery useless signal
 159    * called asdf. The signal will also pass a pointer to the listeners
 160    * which happens to be the example element itself */
 161   gst_example_signals[ASDF] =
 162       g_signal_new ("asdf", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 163       G_STRUCT_OFFSET (GstExampleClass, asdf), NULL, NULL,
 164       g_cclosure_marshal_VOID__POINTER, G_TYPE_NONE, 1, GST_TYPE_EXAMPLE);
 165
 166
 167   /* The last thing is to provide the functions that implement get and set
 168    * of arguments.
 169    */
 170   gobject_class->set_property = gst_example_set_property;
 171   gobject_class->get_property = gst_example_get_property;
 172
 173   /* we also override the default state change handler with our own
 174    * implementation */
 175   gstelement_class->change_state = gst_example_change_state;
 176   /* We can now provide the details for this element, that we defined earlier. */
 177   gst_element_class_set_details (gstelement_class, &example_details);
 178   /* The pad templates can be easily generated from the factories above,
 179    * and then added to the list of padtemplates for the class.
 180    */
 181   gst_element_class_add_pad_template (gstelement_class,
 182       gst_static_pad_template_get (&sink_template));
 183   gst_element_class_add_pad_template (gstelement_class,
 184       gst_static_pad_template_get (&src_template));
 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 template constructed by the factory.
 195    */
 196   example->sinkpad =
 197       gst_pad_new_from_template (gst_static_pad_template_get (&sink_template),
 198       "sink");
 199   /* Setting the chain function allows us to supply the function that will
 200    * actually be performing the work.  Without this, the element would do
 201    * nothing, with undefined results (assertion failures and such).
 202    */
 203   gst_pad_set_chain_function (example->sinkpad, gst_example_chain);
 204   /* We then must add this pad to the element's list of pads.  The base
 205    * element class manages the list of pads, and provides accessors to it.
 206    */
 207   gst_element_add_pad (GST_ELEMENT (example), example->sinkpad);
 208
 209   /* The src pad, the output of the element, is created and registered
 210    * in the same way, with the exception of the chain function.  Source
 211    * pads don't have chain functions, because they can't accept buffers,
 212    * they only produce them.
 213    */
 214   example->srcpad =
 215       gst_pad_new_from_template (gst_static_pad_template_get (&src_template),
 216       "src");
 217   gst_element_add_pad (GST_ELEMENT (example), example->srcpad);
 218
 219   /* Initialization of element's private variables. */
 220   example->active = FALSE;
 221 }
 222
 223 /* The chain function is the heart of the element.  It's where all the
 224  * work is done.  It is passed a pointer to the pad in question, as well
 225  * as the buffer provided by the peer element.
 226  */
 227 static void
 228 gst_example_chain (GstPad * pad, GstData * _data)
 229 {
 230   GstBuffer *buf = GST_BUFFER (_data);
 231   GstExample *example;
 232   GstBuffer *outbuf;
 233
 234   /* Some of these checks are of dubious value, since if there were not
 235    * already true, the chain function would never be called.
 236    */
 237   g_return_if_fail (pad != NULL);
 238   g_return_if_fail (GST_IS_PAD (pad));
 239   g_return_if_fail (buf != NULL);
 240
 241   /* We need to get a pointer to the element this pad belogs to. */
 242   example = GST_EXAMPLE (gst_pad_get_parent (pad));
 243
 244   /* A few more sanity checks to make sure that the element that owns
 245    * this pad is the right kind of element, in case something got confused.
 246    */
 247   g_return_if_fail (example != NULL);
 248   g_return_if_fail (GST_IS_EXAMPLE (example));
 249
 250   /* If we are supposed to be doing something, here's where it happens. */
 251   if (example->active) {
 252     /* In this example we're going to copy the buffer to another one,
 253      * so we need to allocate a new buffer first. */
 254     outbuf = gst_buffer_new ();
 255
 256     /* We need to copy the size and offset of the buffer at a minimum. */
 257     GST_BUFFER_SIZE (outbuf) = GST_BUFFER_SIZE (buf);
 258     GST_BUFFER_OFFSET (outbuf) = GST_BUFFER_OFFSET (buf);
 259
 260     /* Then allocate the memory for the new buffer */
 261     GST_BUFFER_DATA (outbuf) = (guchar *) g_malloc (GST_BUFFER_SIZE (outbuf));
 262
 263     /* Then copy the data in the incoming buffer into the new buffer. */
 264     memcpy (GST_BUFFER_DATA (outbuf), GST_BUFFER_DATA (buf),
 265         GST_BUFFER_SIZE (outbuf));
 266
 267     /* we don't need the incomming buffer anymore so we unref it. When we are
 268      * the last plugin with a handle to the buffer, its memory will be freed */
 269     gst_buffer_unref (buf);
 270
 271     /* When we're done with the buffer, we push it on to the next element
 272      * in the pipeline, through the element's source pad, which is stored
 273      * in the element's structure.
 274      */
 275     gst_pad_push (example->srcpad, GST_DATA (outbuf));
 276
 277     /* For fun we'll emit our useless signal here */
 278     g_signal_emit (G_OBJECT (example), gst_example_signals[ASDF], 0, example);
 279
 280     /* If we're not doing something, just send the original incoming buffer. */
 281   } else {
 282     gst_pad_push (example->srcpad, GST_DATA (buf));
 283   }
 284 }
 285
 286 /* Arguments are part of the Gtk+ object system, and these functions
 287  * enable the element to respond to various arguments.
 288  */
 289 static void
 290 gst_example_set_property (GObject * object, guint prop_id, const GValue * value,
 291     GParamSpec * pspec)
 292 {
 293   GstExample *example;
 294
 295   /* It's not null if we got it, but it might not be ours */
 296   g_return_if_fail (GST_IS_EXAMPLE (object));
 297
 298   /* Get a pointer of the right type. */
 299   example = GST_EXAMPLE (object);
 300
 301   /* Check the argument id to see which argument we're setting. */
 302   switch (prop_id) {
 303     case ARG_ACTIVE:
 304       /* Here we simply copy the value of the argument to our private
 305        * storage.  More complex operations can be done, but beware that
 306        * they may occur at any time, possibly even while your chain function
 307        * is running, if you are using threads.
 308        */
 309       example->active = g_value_get_int (value);
 310       g_print ("example: set active to %d\n", example->active);
 311       break;
 312     default:
 313       break;
 314   }
 315 }
 316
 317 /* The set function is simply the inverse of the get fuction. */
 318 static void
 319 gst_example_get_property (GObject * object, guint prop_id, GValue * value,
 320     GParamSpec * pspec)
 321 {
 322   GstExample *example;
 323
 324   /* It's not null if we got it, but it might not be ours */
 325   g_return_if_fail (GST_IS_EXAMPLE (object));
 326   example = GST_EXAMPLE (object);
 327
 328   switch (prop_id) {
 329     case ARG_ACTIVE:
 330       g_value_set_int (value, example->active);
 331       break;
 332     default:
 333       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 334       break;
 335   }
 336 }
 337
 338 /* This is the state change function that will be called when
 339  * the element goes through the different state changes.
 340  * The plugin can prepare itself and its internal data structures
 341  * in the various state transitions.
 342  */
 343 static GstElementStateReturn
 344 gst_example_change_state (GstElement * element)
 345 {
 346   GstExample *example;
 347
 348   /* cast to our plugin */
 349   example = GST_EXAMPLE (element);
 350
 351   /* we perform our actions based on the state transition
 352    * of the element */
 353   switch (GST_STATE_TRANSITION (element)) {
 354       /* The NULL to READY transition is used to
 355        * create threads (if any) */
 356     case GST_STATE_NULL_TO_READY:
 357       break;
 358       /* In the READY to PAUSED state, the element should
 359        * open devices (if any) */
 360     case GST_STATE_READY_TO_PAUSED:
 361       break;
 362       /* In the PAUSED to PLAYING state, the element should
 363        * prepare itself for operation or continue after a PAUSE */
 364     case GST_STATE_PAUSED_TO_PLAYING:
 365       break;
 366       /* In the PLAYING to PAUSED state, the element should
 367        * PAUSE itself and make sure it can resume operation */
 368     case GST_STATE_PLAYING_TO_PAUSED:
 369       break;
 370       /* In the PAUSED to READY state, the element should reset
 371        * its internal state and close any devices. */
 372     case GST_STATE_PAUSED_TO_READY:
 373       break;
 374       /* The element should free all resources, terminate threads
 375        * and put itself into its initial state again */
 376     case GST_STATE_READY_TO_NULL:
 377       break;
 378   }
 379
 380   /* Then we call the parent state change handler */
 381   return parent_class->change_state (element);
 382 }
 383
 384
 385 /* This is the entry into the plugin itself.  When the plugin loads,
 386  * this function is called to register everything that the plugin provides.
 387  */
 388 static gboolean
 389 plugin_init (GstPlugin * plugin)
 390 {
 391   /* We need to register each element we provide with the plugin. This consists
 392    * of the name of the element, a rank that gives the importance of the element
 393    * when compared to similar plugins and the GType identifier.
 394    */
 395   if (!gst_element_register (plugin, "example", GST_RANK_MARGINAL,
 396           GST_TYPE_EXAMPLE))
 397     return FALSE;
 398
 399   /* Now we can return successfully. */
 400   return TRUE;
 401
 402   /* At this point, the GStreamer core registers the plugin, its
 403    * elementfactories, padtemplates, etc., for use in your application.
 404    */
 405 }
 406
 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
 409  * way.
 410  *
 411  * The symbol pointing to this structure is the only symbol looked up when
 412  * loading the plugin.
 413  */
 414 GST_PLUGIN_DEFINE (GST_VERSION_MAJOR,   /* The major version of the core that this was built with */
 415     GST_VERSION_MINOR,          /* The minor version of the core that this was built with */
 416     "example",                  /* The name of the plugin.  This must be unique: plugins with
 417                                  * the same name will be assumed to be identical, and only
 418                                  * one will be loaded. */
 419     "an example plugin",        /* a short description of the plugin in English */
 420     plugin_init,                /* Pointer to the initialisation function for the plugin. */
 421     "0.1",                      /* The version number of the plugin */
 422     "LGPL",                     /* ieffective license the plugin can be shipped with. Must be
 423                                  * valid for all libraries it links to, too. */
 424     "my nifty plugin package",
 425     /* package this plugin belongs to. */
 426     "http://www.mydomain.com"
 427     /* originating URL for this plugin. This is the place to look
 428      * for updates, information and so on. */
 429     );