<appendix id="creatingplugins">
<title
>Lav yderligere plugin</title>
<para
>&kst; har en enkel og standardiseret grænseflade som tillader nemt at lave  oprette yderligere plugin. Udover at give detaljer om grundlæggende krav for plugin, beskriver følgende afsnit hvordan færdigskrevne deklarationsfiler kan bruges til at lave visse slags plugin. </para>

<sect1 id="creatingbasicplugin">
<title
>Lav et basalt plugin</title>
<para
>Et &kst;-plugin består af to filer: en KDE-desktoptjenestefil og en delt objektfil. </para>

<sect2 id="creatingbasicplugindesktopfile">
<title
>KDE-desktoptjenestefilen</title>
<para
>KDE-desktoptjenestefilen sørger for information om pluginnet for infrastrukturen i &kst; som indlæser plugin. Det følgende er et eksempel på en KDE-desktoptjenestefil for et &kst;-plugin: </para>

<informalexample>
<screen
>[Desktop Entry]
Encoding=UTF-8
Type=Service
ServiceTypes=Kst Data Object
X-KDE-ModuleType=Plugin
X-KDE-Library=kst_EKSEMPEL_plugin
X-Kst-Plugin-Author=EKSEMPEL
Name=EKSEMPEL-plugin
Comment=EKSEMPEL algoritme for Kst.
</screen>
</informalexample>

<para
>I almindelighed kan du bruge eksemplet ovenfor som en skabelon, og ændre EKSEMPEL så det passer til dit plugin. Som det fremgår af eksemplet, består desktoptjenestefilen af en følge af nøgleværdi par. Indgangen  <literal
>ServiceTypes</literal
> skal efterlades som den ser ud ovenfor. Denne nøgle angiver at pluginnet arver klassen KstDataObject. Se dokumentationen af programmeringsgrænsefladen for at finde grænsefladen som klassen eksponerer. Nøglen <literal
>X-KDE-Library</literal
> peger på den delte objektfil som implementerer dit plugin. Inkludér ikke den delte objektfils filendelse. </para>

<para
>Når du har gjort desktopfilen færdig, gemmes den som <filename
>[X-KDE-LIBRARY].desktop</filename
>, hvor <filename
>[X-KDE-LIBRARY]</filename
> er værdien på nøglen i desktopfilen. </para>

</sect2>

<sect2 id="creatingbasicpluginobjectfile">
<title
>Den delte objektfil</title>
<para
>Den delte objektfil indeholder pluginnets egentlige funktion. Følgende er kravene for den delte objektfil: </para>

<itemizedlist>

<listitem>
<para
>Objektet skal arve klassen KstDataObject: <informalexample
> <screen
>#ifndef EKSEMPELPLUGIN_H
#define EKSEMPELPLUGIN_H

#include &lt;ksddataobject.h&gt;

class EksempelPlugin : public KstDataObject {
  Q_OBJECT
public:
    EksempelPlugin(QObject *parent, const char *name, const QStringList &#038;args);
    virtual ~EksempelPlugin();

    virtual KstObject::UpdateType update(int);
    virtual QString propertyString() const;
    virtual KstDataObjectPtr makeDuplicate(KstDataObjectDataObjectMap&#038;);

protected slots:
    virtual void _showDialog();
};

#endif

</screen>
</informalexample>
</para>

</listitem>

</itemizedlist>

<para
>Følgende er et eksempel på den delte objektfils kildekode for et enkelt plugin: </para>
<informalexample>
<screen
>
</screen>
</informalexample>
</sect2>


<sect2 id="compilingplugin">
<title
>Kompilér pluginnet</title>
<para
>Hvis du bruger &gcc; til at kompilere pluginnet, kompileres objektfilen blot: <screen
><userinput
><command
>cc -Wall -c -o myplugin.o myplugin.c -fPIC -DPIC</command
></userinput
></screen>
</para>
<para
>og derefter oprettes det delte bibliotek: <screen
><userinput
><command
>ld -o myplugin.so -shared myplugin.o</command
></userinput
></screen>
</para>
<para
>De resulterende filer <filename
>*.so</filename
> og <filename
>*.xml</filename
> skal placeres i samme mappe. Når du bruger plugin-håndteringen i &kst; til at indlæse XML-filen, kigger den automatisk efter den delte objektfil i samme mappe. </para>

</sect2>
</sect1>

<sect1 id="creatinglinearfittingplugins">
<title
>Lav et plugin for lineærindstilling</title>
<para
>For at lave et plugin for lineærindstilling, kan du  implementere dine egne indstillingsalgoritmer og give passende vektorer som uddata. &kst; levereres dog allerede med deklarationsfiler som gør det enkelt for dig at implementere plugin for lineær mindste kvadratindstilling ved kun at sørge for nogle få funktioner. Dette afsnit beskriver hvordan man får nytte af disse filer. </para>

<sect2 id="headerslinearfittingplugins">
<title
>Deklarationsfiler</title>
<para
>Der sørges for to deklarationsfiler til at udføre lineærindstillinger, <filename
>linear.h</filename
> (for uvægtede lineærindstillinger) og <filename
>linear_weighted.h</filename
> (for vægtede lineærindstillinger). Begge findes under <filename
>kst(plugins/fits/ </filename
> i kildekodearkivet for &kst;. For at bruge filerne, inkluderes blot en af dem i dit plugins kildekode: <screen>
#include &lt;../linear.h&gt;
</screen
> eller <screen>
#include &lt;../linear_weighted.h&gt;
</screen
> (pr konvention placerer vi kildekoden for pluginnet et mappeniveau under stedet hvor deklarationsfilerne er). </para>

</sect2>

<sect2 id="reqfunctionsfittingplugins">
<title
>Implementér nødvendige funktioner</title>
<para
>Givet en generel lineær model: </para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="Formula-kst-generallinearmodel.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</para>
<para
>hvor <literal
>y</literal
> er en vektor med <literal
>n</literal
> observationer, <literal
>X</literal
> er en matrix med størrelsen <literal
>n</literal
> gange <literal
>p</literal
> med prediktorvariabler, og <literal
>c</literal
> er vektoren med <literal
>p</literal
> parametre for bedste indstilling som skal estimeres. Deklarationsfilen sørger for funktioner til at estimere <literal
>c</literal
> for et givet <literal
>y</literal
> og <literal
>X</literal
>. For at sørge for <literal
>X</literal
>, skal følgende funktion implementeres i pluginnets kildekode: <literallayout
><function
><returnvalue
>double</returnvalue
> calculate_matrix_entry( double <parameter
>dX</parameter
>, int <parameter
>iPos</parameter
> )</function
></literallayout>
</para>
<para
>Funktionen skal returnere værdien af resultatet i søjle <literal
>iPos</literal
> fra matricen med prediktorvariabler, ved at bruge <literal
>x</literal
>-værdien <literal
>dX</literal
>. Funktionen kaldes af linear.h eller linear_weighted.h. Implementeringen af funktionen afhænger af modellen du vil bruge til indstillingen, og er entydig for hvert plugin for lineærindstilling. For eksempel for at tilpasse en polynommodel, vil funktionen <function
>calculate_matrix_entry</function
> kunne implementeres på følgende måde: <informalexample
> <screen
>double calculate_matrix_entry( double dX, int iPos ) {
  double dY;
  dY = pow( dX, (double)iPos );
  return dY;
}
</screen>
</informalexample>
</para>

</sect2>

<sect2 id="callingfittingfunctionslinearfittingplugins">
<title
>Kalde tilpasningfunktionerne</title>
<para
>Når en passende deklarationsfil er inkluderet og funktionen <function
>calculate_matrix_entry</function
> er implementeret, kaldes en passende indstillingsfunktion som inkluderes fra deklarationsfilen: <screen>
<function
>kstfit_linear_unweighted( <parameter
>inArrays</parameter
>, <parameter
>inArrayLens</parameter
>,
                          <parameter
>outArrays</parameter
>, <parameter
>outArrayLens</parameter
>,
                          <parameter
>outScalars</parameter
>, <parameter
>iNumParams</parameter
> )</function
>;
</screen
> eller <screen
><function
>kstfit_linear_weighted( <parameter
>inArrays</parameter
>, <parameter
>inArrayLens</parameter
>,
                        <parameter
>outArrays</parameter
>, <parameter
>outArrayLens</parameter
>,
                        <parameter
>outScalars</parameter
>, <parameter
>iNumParams</parameter
> )</function
>;
</screen>
</para>
<para
>Hver funktion returnerer <literal
>0</literal
> når det lykkes, eller <literal
>-1</literal
> ved fejl, så det er en god idé at lade returværdien for den eksporterede C-funktion være den samme som returværdien for indstillingsfunktionen. For at holde det enkelt, kan koden for pluginnet blot sende argumenterne videre som gives til den eksporterede C-funktion til tilpasningsfunktionen. Bemærk dog at inArrays skal have følgende struktur: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> skal indeholde feltet med x-koordinater for datapunkterne </para>
</listitem>

<listitem>
<para
><varname
>inArrays[1]</varname
> skal indeholde feltet med y-koordinater for datapunkterne </para>
</listitem>

<listitem>
<para
><varname
>inArrays[2]</varname
> er der kun hvis <function
>kstfit_linear_weighted</function
> kaldes, og skal indeholde feltet med vægtninger for tilpasningen. </para>
</listitem>
</itemizedlist>
<para
>Den nemmeste måde at sikre at inArrays er rigtigt struktureret er at angive de n rigtige rækkefølge for inddatavektorer i pluginnets XML-fil. </para>
<para
><varname
>iNumParams</varname
> er antal parametre som indgår i den brugte tilpasningsmodel, hvilket skal være lig med antal søjler i matricen <literal
>X</literal
> med prediktorvariabler. <varname
>iNumParams</varname
> skal angives rigtigt før tilpasningsfunktionen kaldes. </para>
<para
>Efter funktionen <function
>kstfit_linear_unweighted</function
> eller <function
>kstfit_linear_weighted</function
> er kaldet, er <varname
>outArrays</varname
> og <varname
>outScalars</varname
> blevet tildelt følgende: </para>
<itemizedlist>
<listitem>
<para
><varname
>outArrays[0]</varname
> vil indeholde feltet med tilpassede y-værdier. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[1]</varname
> vil indeholde feltet med rester. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[2]</varname
> vil indeholde feltet med estimerede parametre for bedste tilpasning. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[3]</varname
> vil indeholde kovariansmatricen, returneret linje for linje i feltet. </para>
</listitem>

<listitem>
<para
><varname
>outScalars[0]</varname
> vil indeholde chi^2/nu, hvor chi^2 er den vægtede sum af kvadratresternes, og nu frihedsgraderne. </para>
</listitem>
</itemizedlist>
<para
><varname
>outArrayLens</varname
> vil have den rigtige værdi til at angive længden for hvert uddatafelt. </para>

<para
>Sørg for at angiven uddata i XML-filen passer sammen med dem som de eksporterede C-funktioner returnerer (hvilket i de fleste tilfælde simpelthen er uddata fra tilpasningsfunktionen). </para>


</sect2>

<sect2 id="examplelinearfittingplugins">
<title
>Eksempel</title>
<para
>Det følgende er et eksempel på kildekoden for et plugin for lineærindstilling. </para>
<informalexample>
<screen
>/*
 *  Polynomial fitting plugin for KST.
 *  Copyright 2004, The University of British Columbia
 *  Released under the terms of the GPL.
 */

#include "../linear.h"

double calculate_matrix_entry( double dX, int iPos ) {
  double dY;

  dY = pow( dX, (double)iPos );

  return dY;
}

extern "C" int kstfit_polynomial_unweighted(
  const double *const inArrays[],
  const int inArrayLens[],
  const double inScalars[],
  double *outArrays[], int outArrayLens[],
  double outScalars[]);

int kstfit_polynomial_unweighted(
  const double *const inArrays[],
  const int inArrayLens[],
        const double inScalars[],
        double *outArrays[], int outArrayLens[],
        double outScalars[])
{
  int iRetVal = -1;
  int iNumParams;

  iNumParams = 1 + (int)floor( inScalars[0] );
  if( iNumParams &gt; 0 ) {
    iRetVal = kstfit_linear_unweighted( inArrays, inArrayLens,
                                        outArrays, outArrayLens,
                                        outScalars, iNumParams );
  }

  return iRetVal;
}
</screen>
</informalexample>
</sect2>

</sect1>

<sect1 id="creatingnonlinearfitplugin">
<title
>Lav plugin for ikke-lineær indstilling</title>
<para
>&kst; sørger for deklarationsfiler for at forenkle implementeringen af plugin med ikke-lineære mindste kvadrat tilpasning. Brugen af deklarationsfilerne beskrives nedenfor. </para>

<sect2 id="headersnonlinearfittingplugins">
<title
>Deklarationsfiler og definitioner</title>
<para
>Deklarationsfilerne for ikke-lineær indstilling er under <filename
>kst(plugins/fits_nonlinear/</filename
> i kildekodearkivet for &kst;. Filerne hedder <filename
>non_linear.h</filename
> og <filename
>non_linear_weighted.h</filename
> for henholdsvis uvægtede og vægtede tilpasninger. For at bruge filerne, inkluderes kun en af dem i dit plugins kildekode: <screen>
#include &lt;../non_linear.h&gt;
</screen
> eller <screen>
#include &lt;../non_linear_weighted.h&gt;
</screen
> (pr konvention placerer vi kildekoden for pluginnet et mappeniveau under stedet hvor deklarationsfilerne er). </para>

<para
>Eftersom ikke-lineær tilpasning er en iterativ proces, skal du også definere et maksimalt antal iterationer som skal udføres. Algoritmen for ikke-lineær indstilling stopper når mindst en af følgende betingelser er sand: </para>
<itemizedlist>
<listitem>
<para
>Maksimalt antal iterationer er opnået. </para>
</listitem>
<listitem>
<para
>Præcisionen 10<superscript
>-4</superscript
> er opnået. </para>
</listitem>
</itemizedlist>
<para
>Desuden skal du definere antal parametre i modellen, eftersom de ikke eksplicit sendes til tilpasningsfunktionen. For at definere disse to værdier, inkluderes følgende længst oppe i din kildekode: </para>
<screen
>#define NUM_PARAMS [num1]
#define MAX_NUM_ITERATIONS [num2]
</screen>
<para
>som erstatter <literal
>[num1]</literal
> med antal parametre i modellen, og <literal
>[num2]</literal
> med maksimalt antal iterationer at udføre. </para>
</sect2>

<sect2 id="reqfunctionsnonlinearfittingplugins">
<title
>Implementér nødvendige funktioner</title>
<para
>For at bruge deklarationsfilen for ikke-lineær tilpasning, skal du sørge for funktionen som skal bruges som model, partielle afledede for funktionen med hensyn til hver parameter og de oprindelige estimater for parametrene for bedste tilpasning. For at gøre dette skal tre funktioner implementeres. Disse funktioner beskrives nedenfor. </para>
<variablelist>
<varlistentry>
<term
><function
><returnvalue
>double</returnvalue
> function_calculate( double <parameter
>dX</parameter
>, double* <parameter
>pdParameters</parameter
> )</function
></term>
<listitem>
<para
>Denne funktion beregner Y-værdien for tilpasningsmodellen for en given X-værdi <literal
>dX</literal
>, med det felt der sørges for med parametre <varname
>pdParameters</varname
>. Parametrenes rækkefølge i <varname
>pdParameters</varname
> er vilkårlig, men skal stemme overens med de to andre implementerede funktioner. For eksempel for en eksponentiel model, vil <function
>function_calculate</function
> kunne implementeres på følgende måde: </para>
<informalexample>
<screen
>double function_calculate( double dX, double* pdParameters ) {
  double dScale         = pdParameters[0];
  double dLambda = pdParameters[1];
  double dOffset = pdParameters[2];
  double dY;

  dY  = ( dScale * exp( -dLambda * dX ) ) + dOffset;

  return dY;
}
</screen>
</informalexample>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
><returnvalue
>void</returnvalue
> function_derivative( double <parameter
>dX</parameter
>, double* <parameter
>pdParameters</parameter
>, double* <parameter
>pdDerivatives</parameter
> )</function
></term>
<listitem>
<para
>Denne funktion beregner partielle afledede for modelfunktionen for en givet X-værdi <literal
>dX</literal
>. De partielle afledede skal returneres i <varname
>pdDerivatives</varname
>. Rækkefølgen af de partielle afledede i feltet <varname
>pdDerivatives</varname
> skal svare til rækkefølgen af parametrene i <varname
>pdParameters</varname
> (dvs. hvis <varname
>pdParameters[0]</varname
> indeholder parameteren lambda for en eksponentialmodel, skal <varname
>pdDerivatives[0]</varname
> indeholde den afledede for modellen med hensyn til lambda). </para>
</listitem>
</varlistentry>

<varlistentry>
<term
><function
><returnvalue
>void</returnvalue
> function_initial_estimate( const double* <parameter
>pdX</parameter
>, const double* <parameter
>pdY</parameter
>, int <parameter
>iLength</parameter
>, double* <parameter
>pdParameterEstimates</parameter
> )</function
></term>
<listitem>
<para
>Denne funktion sørger for et oprindelig estimat af parametrene for bedste tilpasning for tilpasningsfunktionen. Feltet med X- og Y-værdier for datapunkterne er henholdsvis i <varname
>pdX</varname
> og <varname
>pdY</varname
>, og antal datapunkter angives af <varname
>iLength</varname
>. Du kan bruge alle eller ingen af parametrene efter behag til at beregne det oprindelige estimat. Funktionen skal placere de beregnede oprindelige estimater i <varname
>pdParameterEstimates</varname
>, og lade estimaternes rækkefølge stemme med rækkefølgen for parametrene i <varname
>pdParameters</varname
> i <function
>function_calculate</function
> og <function
>function_derivative</function
>. Husk at det oprindelige estimat er vigtigt for at afgøre om tilpasningsfunktionen konvergerer mod en løsning. </para>
</listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2 id="callingnonlinearfittingplugins">
<title
>Kalde tilpasningfunktionerne</title>
<para
>Når alle nødvendige funktioner er implementeret, kan tilpasningsfunktionen fra den inkluderede deklarationsfil kaldes: <screen>
kstfit_nonlinear( <parameter
>inArrays</parameter
>, <parameter
>inArrayLens</parameter
>,
                  <parameter
>inScalars</parameter
>, <parameter
>outArrays</parameter
>,
                  <parameter
>outArrayLens</parameter
>, <parameter
>outScalars</parameter
> );
</screen
> eller <screen>
kstfit_nonlinear_weighted( <parameter
>inArrays</parameter
>, <parameter
>inArrayLens</parameter
>,
                           <parameter
>inScalars</parameter
>, <parameter
>outArrays</parameter
>,
                           <parameter
>outArrayLens</parameter
>, <parameter
>outScalars</parameter
> );
</screen
> afhængig af om du implementerer en uvægtet tilpasning eller en vægtet tilpasning. </para>

<para
>Funktionen returnerer <literal
>0</literal
> når det lykkes, eller <literal
>-1</literal
> ved en fejl, så det er nemmest at lade returværdien for den eksporterede C-funktion være den samme som returværdien for tilpasningsfunktionen. For at holde det enkelt, kan koden for pluginnet blot sende argumenterne som gives videre til den eksporterede C-funktion til tilpasningsfunktionen. Bemærk dog at inArrays skal have følgende struktur: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> skal indeholde feltet med x-koordinater for datapunkterne </para>
</listitem>

<listitem>
<para
><varname
>inArrays[1]</varname
> skal indeholde feltet med y-koordinater for datapunkterne </para>
</listitem>

<listitem>
<para
><varname
>inArrays[2]</varname
> er der kun hvis <function
>kstfit_linear_weighted</function
> kaldes, og skal indeholde feltet med vægtninger for tilpasningen. </para>
</listitem>
</itemizedlist>
<para
>Den nemmeste måde at sikre at inArrays er rigtigt struktureret er at angive de n rigtige rækkefølge for inddatavektorer i pluginnets XML-fil. </para>
<para
>Efter funktionen <function
>kstfit_linear_unweighted</function
> eller <function
>kstfit_linear_weighted</function
> er kaldet, er <varname
>outArrays</varname
> og <varname
>outScalars</varname
> blevet tildelt følgende: </para>
<itemizedlist>
<listitem>
<para
><varname
>outArrays[0]</varname
> vil indeholde feltet med tilpassede y-værdier. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[1]</varname
> vil indeholde feltet med rester. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[2]</varname
> vil indeholde feltet med estimerede parametre for bedste tilpasning. </para>
</listitem>

<listitem>
<para
><varname
>outArrays[3]</varname
> vil indeholde kovariansmatricen, returneret linje for linje i feltet. </para>
</listitem>

<listitem>
<para
><varname
>outScalars[0]</varname
> vil indeholde chi^2/nu, hvor chi^2 er den vægtede sum af kvadratresternes, og nu frihedsgraderne. </para>
</listitem>
</itemizedlist>
<para
><varname
>outArrayLens</varname
> vil have den rigtige værdi til at angive længden for hvert uddatafelt. </para>

<para
>Sørg for at angiven uddata i XML-filen passer sammen med dem som de eksporterede C-funktioner returnerer (hvilket i de fleste tilfælde simpelthen er uddata fra tilpasningsfunktionen). </para>

</sect2>

<sect2 id="nonlinearfittingpluginexample">
<title
>Eksempel</title>
<para
>Det følgende er et eksempel på et ikke-lineært tilpasningsplugin som udfører en tilpasning til en eksponentiel model.</para>
<informalexample>
<screen
>/*
 *  Exponential fit plugin for KST.
 *  Copyright 2004, The University of British Columbia
 *  Released under the terms of the GPL.
 */

#define NUM_PARAMS 3
#define MAX_NUM_ITERATIONS 500

#include "../non_linear.h"

void function_initial_estimate( const double* pdX, const double* pdY,
                                int iLength, double* pdParameterEstimates ) {
  KST_UNUSED( pdX )
  KST_UNUSED( pdY )
  KST_UNUSED( iLength )

  pdParameterEstimates[0] =  1.0;
  pdParameterEstimates[1] =  0.0;
  pdParameterEstimates[2] =  0.0;
}

double function_calculate( double dX, double* pdParameters ) {
  double dScale         = pdParameters[0];
  double dLambda = pdParameters[1];
  double dOffset = pdParameters[2];
  double dY;

  dY  = ( dScale * exp( -dLambda * dX ) ) + dOffset;

  return dY;
}

void function_derivative( double dX, double* pdParameters, double* pdDerivatives ) {
  double dScale         = pdParameters[0];
  double dLambda = pdParameters[1];
  double dExp;  
  double ddScale;
  double ddLambda;
  double ddOffset;
  
  dExp     = exp( -dLambda * dX );
  ddScale  = dExp;
  ddLambda = -dX * dScale * dExp;
  ddOffset = 1.0;

  pdDerivatives[0] = ddScale;
  pdDerivatives[1] = ddLambda;
  pdDerivatives[2] = ddOffset;
}

extern "C" int kstfit_eksponential(const double *const inArrays[], const int inArrayLens[],
                const double inScalars[],
                double *outArrays[], int outArrayLens[],
                double outScalars[]);

int kstfit_eksponential(const double *const inArrays[], const int inArrayLens[],
                const double inScalars[],
                double *outArrays[], int outArrayLens[],
                double outScalars[])
{
  return kstfit_nonlinear( inArrays, inArrayLens,
                           inScalars, outArrays,
                           outArrayLens, outScalars );
}
</screen>
</informalexample>

</sect2>
</sect1>

<sect1 id="creatingpassfilterplugins">
<title
>Lav plugin for passfilter</title>
<para
>&kst; sørger for deklarationsfiler for at forenkle implementeringen af plugin med passfilter. Brugen af deklarationsfilerne beskrives nedenfor. </para>
<sect2 id="creatingpassfilterpluginsheaderfiles">
<title
>Deklarationsfiler</title>
<para
>Deklarationsfilen for passfiltret er i <filename
>kst/plugins/pass_filters</filename
> i kildekodearkivet for &kst;. Filen hedder <filename
>filters.h</filename
>. For at bruge filen, inkluderes den i dit plugins kildekode: <screen>
#include &lt;../filters.h&gt;
</screen
> (pr konvention placerer vi kildekoden for pluginnet et mappeniveau under stedet hvor deklarationsfilerne er). </para>
</sect2>

<sect2 id="creatingpassfilterpluginsrequirements">
<title
>Nødvendige funktioner</title>
<para
>Deklarationsfilen <filename
>filters.h</filename
> indeholder en enkelt funktion som beregner Fouriertransformationen for en funktion der sørges for, anvender det filter der er sørget for på Fouriertransformationen og derefter beregner den inverse Fouriertransformation for den filtrerede transformen. For at sørge for filtret, skal følgende funktion implementeres i dit plugins kildekode: </para>
<para
><function
><returnvalue
>double</returnvalue
> filter_calculate( double <parameter
>dFreqValue</parameter
>, const double <parameter
>inScalars[]</parameter
> )</function
></para>
<para
>Funktionen skal beregne filtreret amplitude for frekvensen <literal
>dFreqValue</literal
>. <literal
>inScalars[]</literal
> indeholder de uændrede inddataskalarer for pluginnet, som angives i XML-filen. Sandsynligvis indeholder <literal
>inScalars[]</literal
> afskæringsfrekvenser eller andre egenskaber for filtret. For eksempel for at implementere et Butterworth højpassfilter, kan funktionen <function
>filter_calculate</function
> implementeres som følger: </para>
<informalexample>
<screen
>double filter_calculate( double dFreqValue, const double inScalars[] ) {
  double dValue;
  if( dFreqValue &gt; 0.0 ) {
    dValue = 1.0 / ( 1.0 +
                    pow( inScalars[1] / dFreqValue, 2.0 * (double)inScalars[0] ) );
  } else {
    dValue = 0.0;
  }
  return dValue;
}
</screen>
</informalexample>
</sect2>

<sect2 id="creatingpassfilterpluginscallingfunction">
<title
>Kald filterfunktionen</title>
<para
>Så snart den nødvendige <function
>filter_calculate</function
> er implementeret, kan filterfunktionen fra deklarationsfilen kaldes: </para>
<literallayout
><function
>kst_pass_filter( <parameter
>inArrays</parameter
>,
                 <parameter
>inArrayLens</parameter
>,
                 <parameter
>inScalars</parameter
>,
                 <parameter
>outArrays</parameter
>,
                 <parameter
>outArrayLens</parameter
>,
                 <parameter
>outScalars</parameter
> );</function
></literallayout>
<para
>Argumenterne som sendes til den eksporterede C-funktion kan sædvanligvis sendes til <function
>kst_pass_filter</function
> uden ændringer. Der er dog nogle begrænsninger for argumenterne: </para>
<itemizedlist>
<listitem>
<para
><varname
>inArrays[0]</varname
> skal indeholde feltet med data der skal filtreres. </para>
</listitem>

<listitem>
<para
><varname
>inScalars</varname
> skal indeholde filterspecifikke parametre som skal bruges af funktionen <function
>filter_calculate</function
>. </para>
</listitem>
</itemizedlist>
<para
>Efter funktionskaldet kommer <varname
>outArrays[0]</varname
> til at indeholde det filtrerede datafelt, og <varname
>outArrayLens</varname
> vil blive sat passende. Funktionen <function
>kst_pass_filter</function
> bruger ikke <varname
>outScalars</varname
>. </para>
</sect2>

<sect2 id="creatingpassfilterpluginsexample">
<title
>Eksempel</title>
<para
>Det følgende er et eksempel på et plugin med et passfilter som implementerer Butterworth højpassfiltrering. </para>
<informalexample>
<screen
>/*
 *  Butterworth low pass filter plugin for KST.
 *  Copyright 2004, The University of British Columbia
 *  Released under the terms of the GPL.
 */

#include &lt;stdlib.h&gt;
#include &lt;math.h&gt;
#include "../filters.h"

extern "C" int butterworth_highpass(const double *const inArrays[], const int inArrayLens[],
                const double inScalars[],
                double *outArrays[], int outArrayLens[],
                double outScalars[]);

int butterworth_highpass(const double *const inArrays[], const int inArrayLens[],
                const double inScalars[],
                double *outArrays[], int outArrayLens[],
                double outScalars[])
{
  int iReturn;

  iReturn = kst_pass_filter( inArrays,
                             inArrayLens,
                             inScalars,
                             outArrays,
                             outArrayLens,
                             outScalars );

  return iReturn;
}

double filter_calculate( double dFreqValue, const double inScalars[] ) {
  double dValue;

  if( dFreqValue &gt; 0.0 ) {
    dValue = 1.0 / ( 1.0 + pow( inScalars[1] / dFreqValue, 2.0 * (double)inScalars[0] ) );
  } else {
    dValue = 0.0;
  }

  return dValue;
}</screen>
</informalexample>
</sect2>

</sect1>
</appendix>


<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:true
sgml-parent-document:("index.docbook" "book" "appendix")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->