path: root/tde-i18n-da/docs/tdemultimedia/artsbuilder/apis.docbook

<!-- <?xml version="1.0" ?>
<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd">
To validate or process this file as a standalone document, uncomment
this prolog. Be sure to comment it out again when you are done -->

<chapter id="arts-apis">
<title>&arts; programmeringsgrænseflade</title>

<sect1 id="api-overview">
<title>Oversigt</title>
<para>aRts er ikke kun et program, den sørger for også et antal forskellige programmeringsgrænseflader (API) til forskellige formål. I dette afsnit, forsøger jeg at beskrive "helhedsbilledet", et hurtigt overblik over hvad disse grænseflader er tænkte at bruges til, og hvordan de hænger sammen. </para>

<para>Der er en vigtig distinktion som skal gøres: De fleste grænseflader er <emphasis> sprog- og pladsuafhængige</emphasis> eftersom de er specificerede som <emphasis>mcopidl</emphasis>. Dette betyder at man egentlig kan bruge den tjeneste de sørger for fra et hvilket som helst sprog, implementere dem i et hvilket som helst sprog, og man behøver ikke tage sig af om man taler med lokal- eller fjernobjekter. Her er først en liste af dem: </para>


<variablelist>
<varlistentry>
<term>core.idl</term>
  <listitem><para>Grundlæggende definitioner som danner kernen i MCOP-funktionen, såsom selve protokollen, definitioner af objekter, handleren, flowsystemet og så videre. </para></listitem>

</varlistentry>

<varlistentry>
<term>artsflow.idl</term>

  <listitem><para>Disse indeholder flowsystemet som man bruger til at forbinde lydstrømmene, definitionen af <emphasis>Arts::SynthModule</emphasis> som er grundlaget for alle grænseflade som har strømme, og til slut nogle nyttige lydobjekter. </para></listitem>

</varlistentry>

<varlistentry>
<term>kmedia2.idl</term>


  <listitem><para>Her defineres <emphasis>Arts::PlayObject</emphasis>, et objekt som kan spille en mediatype. Mediaspillere såsom KDE's mediespiller noatun vil kunne afspille hvilket som helst medie som har et PlayObject. Derfor giver det mening at implementere PlayObject for forskellige formater (såsom mp3, mpg video, midi, wav, ...) med dette som grundlag, og der findes allerede mange. </para></listitem>

</varlistentry>

<varlistentry>
<term>soundserver.idl</term>

  <listitem><para>Her defineres en grænseflade for systemets lydserver artsd. Grænsefladen benævnes <emphasis>Arts::SoundServer</emphasis>, og implementerer funktioner såsom at tage imod strømme fra netværket, spille samplinger, oprette andre egne aRts-objekter og så videre. Netværkstransparens er underforstået eftersom MCOP bruges (som for alt øvrigt her). </para></listitem>

</varlistentry>

<varlistentry>
<term>artsbuilder.idl</term>
  <listitem><para>Dette modul definerer grundlæggende flowfunktioner, dvs. kombinerer enklere objekter til mere komplekse ved at definere en graf som binder dem sammen. Den definerer den grundlæggende grænseflade <emphasis>Arts::StructureDesc</emphasis>, <emphasis>Arts::ModuleDesc</emphasis> og <emphasis>Arts::PortDesc</emphasis> som indeholder en beskrivelse af en struktur, modul og port. Der er også en måde at oprette et "levende netværk af objekter" fra disse forbindelser og værdibeskrivelserne ved brug af en fabrik. </para></listitem>

</varlistentry>

<varlistentry>
<term>artsmidi.idl</term>

  <listitem><para>Dette modulet definerer grundlæggende midi-funktioner, såsom objekter som laver midi-begivenheder, hvad en midi-begivenhed er, og <emphasis>Arts::MidiManager</emphasis> til at forbinde producenter og konsumenter af midi-begivenheder, og så videre. Som altid er netværkstransparens underforstået. </para></listitem>

</varlistentry>

<varlistentry>
<term>artsmodules.idl</term>
  <listitem><para>Her er der diverse yderligere filtre, oscillatorer, lydeffekter, forsinkelser og så videre, alt som behøves for rigtig nyttig signalbehandling, og for at opbygge komplekse instrumenter og effekter fra disse grundlæggende byggeblokke. </para></listitem>

</varlistentry>

<varlistentry>
<term>artsgui.idl</term>

  <listitem><para>Denne tager sig af synlige objekter. Den definerer den grundlæggende type <emphasis> Arts::Widget</emphasis> som alle moduler med en grafisk grænseflade udgår fra. Dette giver uafhængighed af værktøjskasse, og ... visuel redigering af den grafiske grænseflade, og mulighed for at serialisere den grafiske grænseflade. Desuden, eftersom de grafiske komponenter har normale egenskaber, kan deres værdier på en ligetil måde forbindes til visse signalbehandlingsmoduler. (dvs. værdien af en skyder til klipning for et filter). Som altid, netværkstransparent. </para></listitem>

</varlistentry>

</variablelist>
<para>Hvor det er muligt implementeres aRts selv med IDL. På den anden side er der nogle <emphasis>sprogspecifikke</emphasis> programmeringsgrænseflader, som enten bruger enkel C++ eller C. Det er ofte fornuftigt at bruge IDL-grænseflade hvis muligt, og de øvrige grænseflader når det er nødvendigt. Her er en liste over sprogspecifikke programmeringsgrænseflade: </para>

<variablelist>

<varlistentry>
<term>KNotify, KAudioPlayer (indgår i libtdecore)</term>

  <listitem><para>Disse er KDE's programmeringsgrænseflader for bekvemmelighed med de enkle og vældigt almindelige tilfælde, hvor man kun vil afspille en sampling. Grænsefladen er enkel C++, Qt/KDE-optimerede, og så enkle som de kan være. </para></listitem>

</varlistentry>

<varlistentry>
<term>libartsc</term>
  <listitem><para>Enkel C-grænseflade for lydserveren. Meget nyttig for at tilrette gamle programmer. </para></listitem>

</varlistentry>

<varlistentry>
<term>libmcop</term>

  <listitem><para>Her sker al magi som har med MCOP at gøre. Biblioteket indeholder de grundlæggende ting som behøves for at skrive et enkelt MCOP-program, afsenderen, tidtagning, I/O-håndtering, men også de interne funktioner som behøves for at selve MCOP-protokollen skal fungere. </para></listitem>

</varlistentry>

<varlistentry>
<term>libartsflow</term>
  <listitem><para>Foruden implementeringen af artsflow.idl, nogle nyttige værktøjer for konvertering af samplingsrater. </para></listitem>

</varlistentry>

<varlistentry>
<term>libqiomanager</term>

  <listitem><para>Integration af MCOP i Qt's begivenhedsløkke, når man skriver Qt-programmer som bruger MCOP. </para></listitem>

</varlistentry>

</variablelist>



</sect1>
<sect1 id="knotify">
<title>knotify</title>
<para>Endnu ikke skrevet </para>
</sect1>

<sect1 id="kaudioplayer">
<title>kaudioplayer</title>
<para>Endnu ikke skrevet </para>
</sect1>

<sect1 id="libkmid">
<title>libkmid</title>
<para>Endnu ikke skrevet </para>
</sect1>

<sect1 id="kmedia2">
<title>kmedia2</title>
<para>Endnu ikke skrevet </para>
</sect1>

<sect1 id="soundserver">
<title>lydserver</title>
<para>Endnu ikke skrevet </para>
</sect1>

<sect1 id="artsflow">
<title>artsflow</title>
<para>Endnu ikke skrevet </para>
</sect1>

<sect1 id="capi">
<title>C <acronym>API</acronym></title>

<sect2 id="capiintro">
<title>Indledning</title>

<para>C-grænsefladen for &arts; oprettedes for at gøre det let at skrive og overføre enkle C-programmer til &arts; lydserver. Den sørger for strømningsfunktioner (at sende samplingsstrømme til <application>artsd</application>), enten med eller uden blokering. For de fleste programmer tager man helt enkelt de få systemkald væk som håndterer lydenheden og skifter dem ud mod passende kald til &arts;.</para>

<para>Jeg lavede to overførsler for at verificere idéen: <application>mpg123</application> og <application>quake</application>. Du kan skaffe programrettelserne <ulink url="http://space.twc.de/~stefan/kde/download/artsc-patches.tar.gz">herfra</ulink>. Bidrag gerne med dine egne programrettelser til vedligeholderen af  &arts; eller til programmelpakken for multimedia så de kan integrere understøttelsen for &arts; i deres kode.</para>

</sect2>

<sect2 id="capiwalkthru">
<title>Hurtig gennemgang</title>

<para>At sende lyd til lydserveren med grænsefladen er meget enkelt:</para>
<procedure>
<step><para>indsæt deklarationsfilen med <userinput>#include &lt;artsc.h&gt;</userinput></para></step>
<step><para>initiér grænsefladen med <function>arts_init()</function></para></step>
<step><para>opret en strøm med <function>arts_play_stream()</function></para></step>
<step><para>indstil særlige parametre med <function>arts_stream_set()</function></para></step>
<step><para>skriv samplingsdata til strømmen med <function>arts_write()</function></para></step>
<step><para>luk strømmen med <function>arts_close_stream()</function></para></step>
<step><para>frigør grænsefladen med <function>arts_free()</function></para></step>
</procedure>

<para>Her er et eksempel på et lille program som viser dette:</para>

<programlisting>#include &lt;stdio.h&gt;
#include &lt;artsc.h&gt;
int main()
{
    arts_stream_t stream;
    char buffer[8192];
    int bytes;
    int errorcode;

    errorcode = arts_init();
    if (errorcode &lt; 0)
    {
        fprintf(stderr, "arts_init fejl: %s\n", arts_error_text(errorcode));
        return 1;
    }

    stream = arts_play_stream(44100, 16, 2, "artsctest");

    while((bytes = fread(buffer, 1, 8192, stdin)) &gt; 0)
    {
        errorcode = arts_write(stream, buffer, bytes);
        if(errorcode &lt; 0)
        {
            fprintf(stderr, "arts_write fejl: %s\n", arts_error_text(errorcode));
            return 1;
        }
    }

    arts_close_stream(stream);
    arts_free();

    return 0;
}
</programlisting>
</sect2>

<sect2 id="capiartscconfig">
<title>Kompilere og linke: <application>artsc-config</application></title>

<para>For let at kunne kompilere og linke programmer med &arts; C-grænseflade, findes værktøjet <application>artsc-config</application> som kender til hvilke biblioteker som man skal linke med og hvor deklarationsfilerne findes. Det kaldes med</para>

<screen><userinput><command>artsc-config</command> <option>--libs</option></userinput>
</screen>

<para>for at finde ud af bibliotekerne og </para>

<screen><userinput><command>artsc-config</command> <option>--cflags</option></userinput>
</screen>

<para>for at finde ud af yderligere C-oversætterflag. Eksemplet ovenfor ville være kunnet kompileres med kommandolinjen:</para>

<screen><userinput><command>cc</command> <option>-o artsctest artsctest.c `artsc-config --cflags` `artsc-config --libs`</option></userinput>

<userinput><command>cc</command> <option>-o artsctest</option> <option>artsctest.c</option> <option>`artsc-config --cflags`</option> <option>`artsc-config --libs`</option></userinput>
</screen>

</sect2>

<sect2 id="c-api-reference">
<title>Biblioteksreference</title>

<para>[HUSK: opret dokumentation for artsc.h med kdoc] </para>

</sect2>

</sect1>
</chapter>