summaryrefslogtreecommitdiffstats
path: root/tde-i18n-da/docs/tdemultimedia/artsbuilder/apis.docbook
blob: c9544b05d6846e9988590f68906c277c58a9810d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
<!-- <?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>