summaryrefslogtreecommitdiffstats
path: root/tde-i18n-ru/docs/tdemultimedia/artsbuilder/apis.docbook
blob: 736a17000fb5f97a7b77a45b0237acff1f0aa350 (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>API интерфейс &arts;</title>

<sect1 id="api-overview">
<title>Обзор</title>
<para>aRts - это не просто какая-то программа, в нём поддерживается API для выполнения самых разных задач. В этом разделе будет рассказано о возможностях взаимодействия aRts с другими программами с помощью API. </para>

<para>Надо сразу отметить, что большинство возможностей API <emphasis>не зависят</emphasis>, от языка реализации и места вызова, поскольку они описаны на <emphasis>mcopidl</emphasis>. Вы можете использовать сервисы, которые они предлагают, на любом языке программирования, и не волноваться, работаете ли вы с локальным или с удалённым объектом. Вот список основных объектов: </para>


<variablelist>
<varlistentry>
<term>core.idl</term>
  <listitem><para>Основные определения из MCOP, например протокол, определения объектов, трейдер, менеджер потоков и т.д. </para></listitem>

</varlistentry>

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

  <listitem><para>Содержит менеджер, управляющий соединениями аудио потоков, определение <emphasis>Arts::SynthModule</emphasis>, базы любого интерфейса с потоками, а также несколько полезных аудио объектов. </para></listitem>

</varlistentry>

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


  <listitem><para>Здесь определен объект, который может проигрывать звук, <emphasis>Arts::PlayObject</emphasis>. Медиаплееры, наподобие noatun, смогут воспроизводить любой формат, для которого определён PlayObject. На этой базе уже реализованы форматы mp3, mpg video, midi, wav... </para></listitem>

</varlistentry>

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

  <listitem><para>Интерфейс с звуковым сервером artsd. Он называется <emphasis>Arts::SoundServer</emphasis>. Он позволяет получать потоки из сети, воспроизводить звук, создавать новые объекты aRts и т.д. Поддержка сети осуществляется прозрачным образом благодаря использованию MCOP (как и для всего прочего здесь). </para></listitem>

</varlistentry>

<varlistentry>
<term>artsbuilder.idl</term>
  <listitem><para>Этот модуль определяет основные функции управления синтезом звука, совмещая простые и более сложные объекты, за счёт составления из них структур. Это определяет основной интерфейс <emphasis>Arts::StructureDesc</emphasis>, <emphasis>Arts::ModuleDesc</emphasis> и <emphasis>Arts::PortDesc</emphasis>, которые содержат описания структур, модулей  и портов. Также есть возможность получить "живую сеть объектов" из этих описаний соединений и значений, используя factory. </para></listitem>

</varlistentry>

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

  <listitem><para>Этот модуль определяет основные функции midi, например объекты, которые создают события midi, описание события midi и <emphasis>Arts::MidiManager</emphasis> для связи "производителей" и "потребителей" событий midi и т. д. Также поддерживается прозрачная работа в сети. </para></listitem>

</varlistentry>

<varlistentry>
<term>artsmodules.idl</term>
  <listitem><para>Дополнительные фильтры, эффекты, задержки и т.д. Все они требуются для построения сложных инструментов и объектов обработки звука, которые выстраиваются из более простых объектов как из кирпичиков. </para></listitem>

</varlistentry>

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

  <listitem><para>Базовые типы для визуальных объектов. Из базового типа <emphasis> Arts::Widget</emphasis> происходят все модули графического интерфейса. Это позволяет создавать визуальные редакторы, независимые от конкретного набора библиотек. Также визуальные объекты могут служить для установки параметров напрямую через конкретный сигнал. (например значение ползунка соединено с фильтром обрезания частот). Также поддерживается прозрачная работа в сети. </para></listitem>

</varlistentry>

</variablelist>
<para>aRts написан на IDL везде, где это только возможно. С другой стороны есть некоторые <emphasis>языкозависимые</emphasis> API на C++ или C. Желательно использовать только интерфейсы IDL, а другие API только при необходимости. Вот список языкозависимых API: </para>

<variablelist>

<varlistentry>
<term>KNotify, KAudioPlayer (включено в libtdecore)</term>

  <listitem><para>Это API из KDE для случая, когда просто нужно проиграть звуковой буфер. Эта функция на C++ оптимизирована под Qt/KDE и очень простая. </para></listitem>

</varlistentry>

<varlistentry>
<term>libartsc</term>
  <listitem><para>Интерфейс C для звукового сервера. Используется для портирования программ. </para></listitem>

</varlistentry>

<varlistentry>
<term>libmcop</term>

  <listitem><para>Вот где проявляется магия MCOP. Библиотека содержит основные вещи для написания приложения MCOP, диспетчер, таймеры, а также внутренние классы для обеспечения протокола MCOP. </para></listitem>

</varlistentry>

<varlistentry>
<term>libartsflow</term>
  <listitem><para>Вместе с определением artsflow.idl, есть некоторые утилиты, например конвертация частоты дискретизации. </para></listitem>

</varlistentry>

<varlistentry>
<term>libqiomanager</term>

  <listitem><para>Интеграция MCOP в цикл событий Qt, нужно при написании приложений Qt с использованием MCOP. </para></listitem>

</varlistentry>

</variablelist>



</sect1>
<sect1 id="knotify">
<title>knotify</title>
<para>В процессе написания </para>
</sect1>

<sect1 id="kaudioplayer">
<title>kaudioplayer</title>
<para>В процессе написания </para>
</sect1>

<sect1 id="libkmid">
<title>libkmid</title>
<para>В процессе написания </para>
</sect1>

<sect1 id="kmedia2">
<title>kmedia2</title>
<para>В процессе написания </para>
</sect1>

<sect1 id="soundserver">
<title>sound server</title>
<para>В процессе написания </para>
</sect1>

<sect1 id="artsflow">
<title>artsflow</title>
<para>В процессе написания </para>
</sect1>

<sect1 id="capi">
<title><acronym>API</acronym> для языка С</title>

<sect2 id="capiintro">
<title>Введение</title>

<para>C <acronym>API</acronym> &arts; создано для упрощения написания и портирования приложений C в интерфейс звукового сервера &arts;. Это содержит функции потоков (отправка потоков в <application>artsd</application>), как блокирующих (синхронных), так и асинхронных.Для многих приложений вы должны просто заменить несколько системных вызовов, совместимых с вашим звуковым устройством, на соответствующие вызовы &arts;.</para>

<para>Для пробы я портировал две программы - <application>mpg123</application> и <application>quake</application>. Патчи для них можно взять <ulink url="http://space.twc.de/~stefan/kde/download/artsc-patches.tar.gz">здесь</ulink>. Вы можете также отправлять ваши собственные патчи создателям &arts; или мультимедиа программ, чтобы они могли бы встроить поддержку &arts; в код их программ.</para>

</sect2>

<sect2 id="capiwalkthru">
<title>Краткое обозрение</title>

<para>Отправка звука серверу через <acronym>API</acronym> делается очень просто:</para>
<procedure>
<step><para>подключите заголовочный файл: <userinput>#include &lt;artsc.h&gt;</userinput></para></step>
<step><para>инициализируйте <acronym>API</acronym> функцией <function>arts_init()</function></para></step>
<step><para>создайте поток <function>arts_play_stream()</function></para></step>
<step><para>укажите требуемые параметры с помощью <function>arts_stream_set()</function></para></step>
<step><para>отправьте аудио данные в поток функцией <function>arts_write()</function></para></step>
<step><para>закройте поток: <function>arts_close_stream()</function></para></step>
<step><para>освободите память, выделенную для <acronym>API</acronym>: <function>arts_free()</function></para></step>
</procedure>

<para>Вот иллюстрация:</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 error: %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 error: %s\n", arts_error_text(errorcode));
            return 1;
        }
    }

    arts_close_stream(stream);
    arts_free();

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

<sect2 id="capiartscconfig">
<title>Компиляция и сборка: <application>artsc-config</application></title>

<para>Для упрощения сборки программ, использующих C <acronym>API</acronym> &arts;, используется утилита <application>artsc-config</application>, которая самостоятельно определяет, функции каких библиотек вам нужно импортировать, где находятся заголовочные файлы. Она вызывается так:</para>

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

<para>для нахождения библиотек и так: </para>

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

<para>для нахождения дополнительных флагов компилятора C. Так, пример, описанный выше, можно скомпилировать из командной строки:</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>Библиотеки</title>

<para>Ещё не готово (см. информацию в artsc.h) </para>

</sect2>

</sect1>
</chapter>