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 = GST_ELEMENT_DETAILS (
  31   "An example plugin",
  32   "Example/FirstExample",
  33   "Shows the basic structure of a plugin",
  34   "your name <your.name@your.isp>"
  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 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 */
  64   GST_STATIC_CAPS (
  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 */
  69   )
  70 );
  71
  72 /* This factory is much simpler, and defines the source pad. */
  73 GstStaticPadTemplate src_template = GST_STATIC_PAD_TEMPLATE (
  74   "src",
  75   GST_PAD_SRC,
  76   GST_PAD_ALWAYS,
  77   GST_STATIC_CAPS (
  78     "unknown/unknown"
  79   )
  80 );
  81
  82
  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);
  86
  87 static void     gst_example_chain               (GstPad *pad, GstData *_data);
  88
  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);
  95
  96 /* The parent class pointer needs to be kept around for some object
  97  * operations.
  98  */
  99 static GstElementClass *parent_class = NULL;
 100
 101 /* This array holds the ids of the signals registered for this object.
 102  * The array indexes are based on the enum up above.
 103  */
 104 static guint gst_example_signals[LAST_SIGNAL] = { 0 };
 105
 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.
 110  */
 111 GType
 112 gst_example_get_type(void)
 113 {
 114   static GType example_type = 0;
 115
 116   if (!example_type) {
 117     static const GTypeInfo example_info = {
 118       sizeof(GstExampleClass),
 119       NULL,
 120       NULL,
 121       (GClassInitFunc)gst_example_class_init,
 122       NULL,
 123       NULL,
 124       sizeof(GstExample),
 125       0,
 126       (GInstanceInitFunc)gst_example_init,
 127     };
 128     example_type = g_type_register_static(GST_TYPE_ELEMENT, "GstExample", &example_info, 0);
 129   }
 130   return example_type;
 131 }
 132
 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.
 136  */
 137 static void
 138 gst_example_class_init (GstExampleClass *klass)
 139 {
 140   /* Class pointers are needed to supply pointers to the private
 141    * implementations of parent class methods.
 142    */
 143   GObjectClass *gobject_class;
 144   GstElementClass *gstelement_class;
 145
 146   /* Since the example class contains the parent classes, you can simply
 147    * cast the pointer to get access to the parent classes.
 148    */
 149   gobject_class = (GObjectClass*)klass;
 150   gstelement_class = (GstElementClass*)klass;
 151
 152   /* The parent class is needed for class method overrides. */
 153   parent_class = g_type_class_ref(GST_TYPE_ELEMENT);
 154
 155   /* Here we add an argument to the object.  This argument is an integer,
 156    * and can be both read and written.
 157    */
 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 */
 161
 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,
 169                    GST_TYPE_EXAMPLE);
 170
 171
 172   /* The last thing is to provide the functions that implement get and set
 173    * of arguments.
 174    */
 175   gobject_class->set_property = gst_example_set_property;
 176   gobject_class->get_property = gst_example_get_property;
 177
 178   /* we also override the default state change handler with our own
 179    * implementation */
 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.
 185    */
 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));
 190 }
 191
 192 /* This function is responsible for initializing a specific instance of
 193  * the plugin.
 194  */
 195 static void
 196 gst_example_init(GstExample *example)
 197 {
 198   /* First we create the sink pad, which is the input to the element.
 199    * We will use the template constructed by the factory.
 200    */
 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).
 206    */
 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.
 210    */
 211   gst_element_add_pad(GST_ELEMENT(example),example->sinkpad);
 212
 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.
 217    */
 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);
 221
 222   /* Initialization of element's private variables. */
 223   example->active = FALSE;
 224 }
 225
 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.
 229  */
 230 static void
 231 gst_example_chain (GstPad *pad, GstData *_data)
 232 {
 233   GstBuffer *buf = GST_BUFFER (_data);
 234   GstExample *example;
 235   GstBuffer *outbuf;
 236
 237   /* Some of these checks are of dubious value, since if there were not
 238    * already true, the chain function would never be called.
 239    */
 240   g_return_if_fail(pad != NULL);
 241   g_return_if_fail(GST_IS_PAD(pad));
 242   g_return_if_fail(buf != NULL);
 243
 244   /* We need to get a pointer to the element this pad belogs to. */
 245   example = GST_EXAMPLE(gst_pad_get_parent (pad));
 246
 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.
 249    */
 250   g_return_if_fail(example != NULL);
 251   g_return_if_fail(GST_IS_EXAMPLE(example));
 252
 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();
 258
 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);
 262
 263     /* Then allocate the memory for the new buffer */
 264     GST_BUFFER_DATA (outbuf) = (guchar *)g_malloc (GST_BUFFER_SIZE (outbuf));
 265
 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));
 268
 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);
 272
 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.
 276      */
 277     gst_pad_push(example->srcpad,GST_DATA (outbuf));
 278
 279     /* For fun we'll emit our useless signal here */
 280     g_signal_emit(G_OBJECT (example), gst_example_signals[ASDF], 0,
 281                   example);
 282
 283   /* If we're not doing something, just send the original incoming buffer. */
 284   } else {
 285     gst_pad_push(example->srcpad,GST_DATA (buf));
 286   }
 287 }
 288
 289 /* Arguments are part of the Gtk+ object system, and these functions
 290  * enable the element to respond to various arguments.
 291  */
 292 static void
 293 gst_example_set_property (GObject *object, guint prop_id, const GValue *value, GParamSpec *pspec)
 294 {
 295   GstExample *example;
 296
 297   /* It's not null if we got it, but it might not be ours */
 298   g_return_if_fail(GST_IS_EXAMPLE(object));
 299
 300   /* Get a pointer of the right type. */
 301   example = GST_EXAMPLE(object);
 302
 303   /* Check the argument id to see which argument we're setting. */
 304   switch (prop_id) {
 305     case ARG_ACTIVE:
 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.
 310        */
 311       example->active = g_value_get_int (value);
 312       g_print("example: set active to %d\n",example->active);
 313       break;
 314     default:
 315       break;
 316   }
 317 }
 318
 319 /* The set function is simply the inverse of the get fuction. */
 320 static void
 321 gst_example_get_property (GObject *object, guint prop_id, GValue *value, GParamSpec *pspec)
 322 {
 323   GstExample *example;
 324
 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);
 328
 329   switch (prop_id) {
 330     case ARG_ACTIVE:
 331       g_value_set_int (value, example->active);
 332       break;
 333     default:
 334       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 335       break;
 336   }
 337 }
 338
 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.
 343  */
 344 static GstElementStateReturn
 345 gst_example_change_state (GstElement *element)
 346 {
 347   GstExample *example;
 348
 349   /* cast to our plugin */
 350   example = GST_EXAMPLE(element);
 351
 352   /* we perform our actions based on the state transition
 353    * of the element */
 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:
 358       break;
 359     /* In the READY to PAUSED state, the element should
 360      * open devices (if any) */
 361     case GST_STATE_READY_TO_PAUSED:
 362       break;
 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:
 366       break;
 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:
 370       break;
 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:
 374       break;
 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:
 378       break;
 379   }
 380
 381   /* Then we call the parent state change handler */
 382   return parent_class->change_state (element);
 383 }
 384
 385
 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.
 388  */
 389 static gboolean
 390 plugin_init (GstPlugin *plugin)
 391 {
 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.
 395    */
 396   if (!gst_element_register (plugin, "example", GST_RANK_MARGINAL, 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 (
 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. */
 430 );
 431