gstreamer/examples/plugins/example.c
Andy Wingo e040bb2dbe gst/gstelement.h (GstState): Renamed from GstElementState, changed to be a normal enum instead of flags.
Original commit message from CVS:
2005-09-02  Andy Wingo  <wingo@pobox.com>

* gst/gstelement.h (GstState): Renamed from GstElementState,
changed to be a normal enum instead of flags.
(GstStateChangeReturn): Renamed from GstElementStateReturn, names
munged to be GST_STATE_CHANGE_*.
(GST_STATE_CHANGE): Renamed from GST_STATE_TRANSITION, updated to
work with the new state representation.
(GstStateChange): New enumeration of possible state transitions.
Replaces GST_STATE_FOO_TO_BAR with GST_STATE_CHANGE_FOO_TO_BAR.
(GstElementClass::change_state): Pass the GstStateChange along as
an argument. Helps language bindings, so they don't have to use
tricky lock-needing macros like GST_STATE_CHANGE ().

* scripts/update-states (file): New script. Run it on a file to
update it for state naming and API changes. Updates files in
place.

* All files updated for the new API.
2005-09-02 15:42:00 +00:00

426 lines
15 KiB
C

/* GStreamer
* Copyright (C) <1999> Erik Walthinsen <omega@cse.ogi.edu>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
/* First, include the header file for the plugin, to bring in the
* object definition and other useful things.
*/
#include <string.h>
#include "example.h"
/* The ElementDetails structure gives a human-readable description of the
* plugin, as well as author and version data. Use the GST_ELEMENT_DETAILS
* macro when defining it.
*/
static GstElementDetails example_details =
GST_ELEMENT_DETAILS ("An example plugin",
"Example/FirstExample",
"Shows the basic structure of a plugin",
"your name <your.name@your.isp>");
/* These are the signals that this element can fire. They are zero-
* based because the numbers themselves are private to the object.
* LAST_SIGNAL is used for initialization of the signal array.
*/
enum
{
ASDF,
/* FILL ME */
LAST_SIGNAL
};
/* Arguments are identified the same way, but cannot be zero, so you
* must leave the ARG_0 entry in as a placeholder.
*/
enum
{
ARG_0,
ARG_ACTIVE
/* FILL ME */
};
/* The PadFactory structures describe what pads the element has or
* can have. They can be quite complex, but for this example plugin
* they are rather simple.
*/
GstStaticPadTemplate sink_template = GST_STATIC_PAD_TEMPLATE ("sink", /* The name of the pad */
GST_PAD_SINK, /* Direction of the pad */
GST_PAD_ALWAYS, /* The pad exists for every instance */
GST_STATIC_CAPS ("unknown/unknown, " /* The MIME media type */
"foo:int=1, " /* an integer property */
"bar:boolean=true, " /* a boolean property */
"baz:int={ 1, 3 }" /* a list of values */
)
);
/* This factory is much simpler, and defines the source pad. */
GstStaticPadTemplate src_template = GST_STATIC_PAD_TEMPLATE ("src",
GST_PAD_SRC,
GST_PAD_ALWAYS,
GST_STATIC_CAPS ("unknown/unknown")
);
/* A number of function prototypes are given so we can refer to them later. */
static void gst_example_class_init (GstExampleClass * klass);
static void gst_example_init (GstExample * example);
static void gst_example_chain (GstPad * pad, GstData * _data);
static void gst_example_set_property (GObject * object, guint prop_id,
const GValue * value, GParamSpec * pspec);
static void gst_example_get_property (GObject * object, guint prop_id,
GValue * value, GParamSpec * pspec);
static GstStateChangeReturn gst_example_change_state (GstElement * element,
GstStateChange transition);
/* The parent class pointer needs to be kept around for some object
* operations.
*/
static GstElementClass *parent_class = NULL;
/* This array holds the ids of the signals registered for this object.
* The array indexes are based on the enum up above.
*/
static guint gst_example_signals[LAST_SIGNAL] = { 0 };
/* This function is used to register and subsequently return the type
* identifier for this object class. On first invocation, it will
* register the type, providing the name of the class, struct sizes,
* and pointers to the various functions that define the class.
*/
GType
gst_example_get_type (void)
{
static GType example_type = 0;
if (!example_type) {
static const GTypeInfo example_info = {
sizeof (GstExampleClass),
NULL,
NULL,
(GClassInitFunc) gst_example_class_init,
NULL,
NULL,
sizeof (GstExample),
0,
(GInstanceInitFunc) gst_example_init,
};
example_type =
g_type_register_static (GST_TYPE_ELEMENT, "GstExample", &example_info,
0);
}
return example_type;
}
/* In order to create an instance of an object, the class must be
* initialized by this function. GObject will take care of running
* it, based on the pointer to the function provided above.
*/
static void
gst_example_class_init (GstExampleClass * klass)
{
/* Class pointers are needed to supply pointers to the private
* implementations of parent class methods.
*/
GObjectClass *gobject_class;
GstElementClass *gstelement_class;
/* Since the example class contains the parent classes, you can simply
* cast the pointer to get access to the parent classes.
*/
gobject_class = (GObjectClass *) klass;
gstelement_class = (GstElementClass *) klass;
/* The parent class is needed for class method overrides. */
parent_class = g_type_class_ref (GST_TYPE_ELEMENT);
/* Here we add an argument to the object. This argument is an integer,
* and can be both read and written.
*/
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 */
/* Here we add a signal to the object. This is a very useless signal
* called asdf. The signal will also pass a pointer to the listeners
* which happens to be the example element itself */
gst_example_signals[ASDF] =
g_signal_new ("asdf", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GstExampleClass, asdf), NULL, NULL,
g_cclosure_marshal_VOID__POINTER, G_TYPE_NONE, 1, GST_TYPE_EXAMPLE);
/* The last thing is to provide the functions that implement get and set
* of arguments.
*/
gobject_class->set_property = gst_example_set_property;
gobject_class->get_property = gst_example_get_property;
/* we also override the default state change handler with our own
* implementation */
gstelement_class->change_state = gst_example_change_state;
/* We can now provide the details for this element, that we defined earlier. */
gst_element_class_set_details (gstelement_class, &example_details);
/* The pad templates can be easily generated from the factories above,
* and then added to the list of padtemplates for the class.
*/
gst_element_class_add_pad_template (gstelement_class,
gst_static_pad_template_get (&sink_template));
gst_element_class_add_pad_template (gstelement_class,
gst_static_pad_template_get (&src_template));
}
/* This function is responsible for initializing a specific instance of
* the plugin.
*/
static void
gst_example_init (GstExample * example)
{
/* First we create the sink pad, which is the input to the element.
* We will use the template constructed by the factory.
*/
example->sinkpad =
gst_pad_new_from_template (gst_static_pad_template_get (&sink_template),
"sink");
/* Setting the chain function allows us to supply the function that will
* actually be performing the work. Without this, the element would do
* nothing, with undefined results (assertion failures and such).
*/
gst_pad_set_chain_function (example->sinkpad, gst_example_chain);
/* We then must add this pad to the element's list of pads. The base
* element class manages the list of pads, and provides accessors to it.
*/
gst_element_add_pad (GST_ELEMENT (example), example->sinkpad);
/* The src pad, the output of the element, is created and registered
* in the same way, with the exception of the chain function. Source
* pads don't have chain functions, because they can't accept buffers,
* they only produce them.
*/
example->srcpad =
gst_pad_new_from_template (gst_static_pad_template_get (&src_template),
"src");
gst_element_add_pad (GST_ELEMENT (example), example->srcpad);
/* Initialization of element's private variables. */
example->active = FALSE;
}
/* The chain function is the heart of the element. It's where all the
* work is done. It is passed a pointer to the pad in question, as well
* as the buffer provided by the peer element.
*/
static void
gst_example_chain (GstPad * pad, GstData * _data)
{
GstBuffer *buf = GST_BUFFER (_data);
GstExample *example;
GstBuffer *outbuf;
/* Some of these checks are of dubious value, since if there were not
* already true, the chain function would never be called.
*/
g_return_if_fail (pad != NULL);
g_return_if_fail (GST_IS_PAD (pad));
g_return_if_fail (buf != NULL);
/* We need to get a pointer to the element this pad belongs to. */
example = GST_EXAMPLE (gst_pad_get_parent (pad));
/* A few more sanity checks to make sure that the element that owns
* this pad is the right kind of element, in case something got confused.
*/
g_return_if_fail (example != NULL);
g_return_if_fail (GST_IS_EXAMPLE (example));
/* If we are supposed to be doing something, here's where it happens. */
if (example->active) {
/* In this example we're going to copy the buffer to another one,
* so we need to allocate a new buffer first. */
outbuf = gst_buffer_new ();
/* We need to copy the size and offset of the buffer at a minimum. */
GST_BUFFER_SIZE (outbuf) = GST_BUFFER_SIZE (buf);
GST_BUFFER_OFFSET (outbuf) = GST_BUFFER_OFFSET (buf);
/* Then allocate the memory for the new buffer */
GST_BUFFER_DATA (outbuf) = (guchar *) g_malloc (GST_BUFFER_SIZE (outbuf));
/* Then copy the data in the incoming buffer into the new buffer. */
memcpy (GST_BUFFER_DATA (outbuf), GST_BUFFER_DATA (buf),
GST_BUFFER_SIZE (outbuf));
/* we don't need the incomming buffer anymore so we unref it. When we are
* the last plugin with a handle to the buffer, its memory will be freed */
gst_buffer_unref (buf);
/* When we're done with the buffer, we push it on to the next element
* in the pipeline, through the element's source pad, which is stored
* in the element's structure.
*/
gst_pad_push (example->srcpad, GST_DATA (outbuf));
/* For fun we'll emit our useless signal here */
g_signal_emit (G_OBJECT (example), gst_example_signals[ASDF], 0, example);
/* If we're not doing something, just send the original incoming buffer. */
} else {
gst_pad_push (example->srcpad, GST_DATA (buf));
}
}
/* Properties are part of the GLib+ object system, and these functions
* enable the element to respond to various properties.
*/
static void
gst_example_set_property (GObject * object, guint prop_id, const GValue * value,
GParamSpec * pspec)
{
GstExample *example;
g_return_if_fail (GST_IS_EXAMPLE (object));
/* Get a pointer of the right type. */
example = GST_EXAMPLE (object);
/* Check the argument id to see which argument we're setting. */
switch (prop_id) {
case ARG_ACTIVE:
/* Here we simply copy the value of the argument to our private
* storage. More complex operations can be done, but beware that
* they may occur at any time, possibly even while your chain function
* is running, if you are using threads.
*/
example->active = g_value_get_int (value);
g_print ("example: set active to %d\n", example->active);
break;
default:
break;
}
}
/* The set function is simply the inverse of the get fuction. */
static void
gst_example_get_property (GObject * object, guint prop_id, GValue * value,
GParamSpec * pspec)
{
GstExample *example;
g_return_if_fail (GST_IS_EXAMPLE (object));
example = GST_EXAMPLE (object);
switch (prop_id) {
case ARG_ACTIVE:
g_value_set_int (value, example->active);
break;
default:
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
break;
}
}
/* This is the state change function that will be called when
* the element goes through the different state changes.
* The plugin can prepare itself and its internal data structures
* in the various state transitions.
*/
static GstStateChangeReturn
gst_example_change_state (GstElement * element, GstStateChange transition)
{
GstExample *example;
/* cast to our plugin */
example = GST_EXAMPLE (element);
/* we perform our actions based on the state transition
* of the element */
switch (transition) {
/* The NULL to READY transition is used to
* create threads (if any), and/or open devices */
case GST_STATE_CHANGE_NULL_TO_READY:
break;
case GST_STATE_CHANGE_READY_TO_PAUSED:
break;
/* In the PAUSED to PLAYING state, the element should
* prepare itself for operation or continue after a PAUSE */
case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
break;
/* In the PLAYING to PAUSED state, the element should
* PAUSE itself and make sure it can resume operation */
case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
break;
/* In the PAUSED to READY state, the element should reset
* its internal state and close any devices. */
case GST_STATE_CHANGE_PAUSED_TO_READY:
break;
/* The element should free all resources, terminate threads
* and put itself into its initial state again */
case GST_STATE_CHANGE_READY_TO_NULL:
break;
}
/* Then we call the parent state change handler */
return parent_class->change_state (element, transition);
}
/* This is the entry into the plugin itself. When the plugin loads,
* this function is called to register everything that the plugin provides.
*/
static gboolean
plugin_init (GstPlugin * plugin)
{
/* We need to register each element we provide with the plugin. This consists
* of the name of the element, a rank that gives the importance of the element
* when compared to similar plugins and the GType identifier.
*/
if (!gst_element_register (plugin, "example", GST_RANK_MARGINAL,
GST_TYPE_EXAMPLE))
return FALSE;
/* Now we can return successfully. */
return TRUE;
/* At this point, the GStreamer core registers the plugin, its
* elementfactories, padtemplates, etc., for use in your application.
*/
}
/* This structure describes the plugin to the system for dynamically loading
* plugins, so that the version number and name can be checked in a uniform
* way.
*
* The symbol pointing to this structure is the only symbol looked up when
* loading the plugin.
*/
GST_PLUGIN_DEFINE (GST_VERSION_MAJOR, /* The major version of the core that this was built with */
GST_VERSION_MINOR, /* The minor version of the core that this was built with */
"example", /* The name of the plugin. This must be unique: plugins with
* the same name will be assumed to be identical, and only
* one will be loaded. */
"an example plugin", /* a short description of the plugin in English */
plugin_init, /* Pointer to the initialisation function for the plugin. */
"0.1", /* The version number of the plugin */
"LGPL", /* effective license the plugin can be shipped with. Must be
* valid for all libraries it links to, too. */
"my nifty plugin package",
/* package this plugin belongs to. */
"http://www.mydomain.com"
/* originating URL for this plugin. This is the place to look
* for updates, information and so on. */
);