<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <HTML ><HEAD ><TITLE >Defining Parameter Specificiations</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK REL="HOME" TITLE="GStreamer Plugin Writer's Guide" HREF="index.html"><LINK REL="UP" TITLE="Supporting Dynamic Parameters" HREF="chapter-dparams.html"><LINK REL="PREVIOUS" TITLE="Getting Started" HREF="section-dparam-start.html"><LINK REL="NEXT" TITLE="The Data Processing Loop" HREF="chapter-dparam-loop.html"></HEAD ><BODY CLASS="sect1" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" ><SPAN CLASS="application" >GStreamer</SPAN > Plugin Writer's Guide</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="section-dparam-start.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" >Chapter 16. Supporting Dynamic Parameters</TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="chapter-dparam-loop.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="sect1" ><H1 CLASS="sect1" ><A NAME="section-dparam-define" >16.3. Defining Parameter Specificiations</A ></H1 ><P > You can define the dparams you need anywhere within your element but will usually need to do so in only a couple of places: <P ></P ><UL ><LI ><P > In the element <TT CLASS="filename" >init</TT > function, just after the call to <TT CLASS="filename" >gst_dpman_new</TT > </P ></LI ><LI ><P > Whenever a new pad is created so that parameters can affect data going into or out of a specific pad. An example of this would be a mixer element where a seperate volume parameter is needed on every pad. </P ></LI ></UL > </P ><P > There are three different ways the dparams subsystem can pass parameters into your element. Which one you use will depend on how that parameter is used within your element. Each of these methods has its own function to define a required dparam: <P ></P ><UL ><LI ><P ><TT CLASS="filename" >gst_dpman_add_required_dparam_direct</TT ></P ></LI ><LI ><P ><TT CLASS="filename" >gst_dpman_add_required_dparam_callback</TT ></P ></LI ><LI ><P ><TT CLASS="filename" >gst_dpman_add_required_dparam_array</TT ></P ></LI ></UL > These functions will return TRUE if the required dparam was added successfully. </P ><P > The following function will be used as an example. <PRE CLASS="programlisting" > gboolean gst_dpman_add_required_dparam_direct (GstDParamManager *dpman, GParamSpec *param_spec, gboolean is_log, gboolean is_rate, gpointer update_data) </PRE > The common parameters to these functions are: <P ></P ><UL ><LI ><P > <TT CLASS="filename" >GstDParamManager *dpman</TT > the element's dparam manager </P ></LI ><LI ><P > <TT CLASS="filename" >GParamSpec *param_spec</TT > the param spec which defines the required dparam </P ></LI ><LI ><P > <TT CLASS="filename" >gboolean is_log</TT > whether this dparam value should be interpreted on a log scale (such as a frequency or a decibel value) </P ></LI ><LI ><P > <TT CLASS="filename" >gboolean is_rate</TT > whether this dparam value is a proportion of the sample rate. For example with a sample rate of 44100, 0.5 would be 22050 Hz and 0.25 would be 11025 Hz. </P ></LI ></UL > </P ><DIV CLASS="sect2" ><H2 CLASS="sect2" ><A NAME="section-dparam-direct" >16.3.1. Direct Method</A ></H2 ><P > This method is the simplest and has the lowest overhead for parameters which change less frequently than the sample rate. First you need somewhere to store the parameter - this will usually be in your element's stuct. </P ><PRE CLASS="programlisting" > struct _GstExample { GstElement element; ... GstDParamManager *dpman; gfloat volume; ... }; </PRE ><P > Then to define the required dparam just call <TT CLASS="filename" >gst_dpman_add_required_dparam_direct</TT > and pass in the location of the parameter to change. In this case the location is <TT CLASS="filename" >&(example->volume)</TT >. </P ><PRE CLASS="programlisting" > gst_dpman_add_required_dparam_direct ( example->dpman, g_param_spec_float("volume","Volume","Volume of the audio", 0.0, 1.0, 0.8, G_PARAM_READWRITE), FALSE, FALSE, &(example->volume) ); </PRE ><P > You can now use <TT CLASS="filename" >example->volume</TT > anywhere in your element knowing that it will always contain the correct value to use. </P ></DIV ><DIV CLASS="sect2" ><H2 CLASS="sect2" ><A NAME="section-dparam-callback" >16.3.2. Callback Method</A ></H2 ><P > This should be used if the you have other values to calculate whenever a parameter changes. If you used the direct method you wouldn't know if a parameter had changed so you would have to recalculate the other values every time you needed them. By using the callback method, other values only have to be recalculated when the dparam value actually changes. </P ><P > The following code illustrates an instance where you might want to use the callback method. If you had a volume dparam which was represented by a gfloat number, your element may only deal with integer arithmatic. The callback could be used to calculate the integer scaler when the volume changes. First you will need somewhere to store these values. </P ><PRE CLASS="programlisting" > struct _GstExample { GstElement element; ... GstDParamManager *dpman; gfloat volume_f; gint volume_i; ... }; </PRE ><P > When the required dparam is defined, the callback function <TT CLASS="filename" >gst_example_update_volume</TT > and some user data (which in this case is our element instance) is passed in to the call to <TT CLASS="filename" >gst_dpman_add_required_dparam_callback</TT >. </P ><PRE CLASS="programlisting" > gst_dpman_add_required_dparam_callback ( example->dpman, g_param_spec_float("volume","Volume","Volume of the audio", 0.0, 1.0, 0.8, G_PARAM_READWRITE), FALSE, FALSE, gst_example_update_volume, example ); </PRE ><P > The callback function needs to conform to this signiture </P ><PRE CLASS="programlisting" > typedef void (*GstDPMUpdateFunction) (GValue *value, gpointer data); </PRE ><P > In our example the callback function looks like this </P ><PRE CLASS="programlisting" > static void gst_example_update_volume(GValue *value, gpointer data) { GstExample *example = (GstExample*)data; g_return_if_fail(GST_IS_EXAMPLE(example)); example->volume_f = g_value_get_float(value); example->volume_i = example->volume_f * 8192; } </PRE ><P > Now <TT CLASS="filename" >example->volume_i</TT > can be used elsewhere and it will always contain the correct value. </P ></DIV ><DIV CLASS="sect2" ><H2 CLASS="sect2" ><A NAME="section-dparam-array" >16.3.3. Array Method</A ></H2 ><P > This method is quite different from the other two. It could be thought of as a specialised method which should only be used if you need the advantages that it provides. Instead of giving the element a single value it provides an array of values where each item in the array corresponds to a sample of audio in your buffer. There are a couple of reasons why this might be useful. </P ><P ></P ><UL ><LI ><P > Certain optimisations may be possible since you can iterate over your dparams array and your buffer data together. </P ></LI ><LI ><P > Some dparams may be able to interpolate changing values at the sample rate. This would allow the array to contain very smoothly changing values which may be required for the stability and quality of some DSP algorithms. </P ></LI ></UL ><P > The array method is currently the least mature of the three methods and is not yet ready to be used in elements, but plugin writers should be aware of its existance for the future. </P ></DIV ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="section-dparam-start.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="chapter-dparam-loop.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Getting Started</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="chapter-dparams.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >The Data Processing Loop</TD ></TR ></TABLE ></DIV ></BODY ></HTML >