summaryrefslogtreecommitdiffstats
path: root/doc/artsbuilder/apis.docbook
diff options
context:
space:
mode:
Diffstat (limited to 'doc/artsbuilder/apis.docbook')
-rw-r--r--doc/artsbuilder/apis.docbook357
1 files changed, 357 insertions, 0 deletions
diff --git a/doc/artsbuilder/apis.docbook b/doc/artsbuilder/apis.docbook
new file mode 100644
index 00000000..65de23be
--- /dev/null
+++ b/doc/artsbuilder/apis.docbook
@@ -0,0 +1,357 @@
+<!-- <?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; Application Programming Interfaces</title>
+
+<sect1 id="api-overview">
+<title>Overview</title>
+<para>
+aRts is not only a piece of software, it also provides a variety of APIs
+for a variety of purposes. In this section, I will try to describe the "big
+picture", a brief glance what those APIs are supposed to do, and how they
+interact.
+</para>
+
+<para>
+There is one important distinction to make: most of the APIs are <emphasis>
+language and location independent</emphasis> because they are specified as
+<emphasis>mcopidl</emphasis>.
+That is, you can basically use the services they offer from any language,
+implement them in any language, and you will not have to care whether you
+are talking to local or remote objects. Here is a list of these first:
+</para>
+
+
+<variablelist>
+<varlistentry>
+<term>core.idl</term>
+ <listitem><para>
+ Basic definitions that form the core of the MCOP functionality, such as
+ the protocol itself, definitions of the object, the trader, the flow
+ system and so on.
+ </para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term>artsflow.idl</term>
+
+ <listitem><para>
+ These contain the flow system you will use for connecting audio streams, the
+ definition of <emphasis>Arts::SynthModule</emphasis> which is the base for
+ any interface that has streams, and finally a few useful audio objects
+ </para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term>kmedia2.idl</term>
+
+
+ <listitem><para>
+ Here, an object that can play a media, <emphasis>Arts::PlayObject</emphasis>
+ gets defined. Media players such as the KDE media player noatun will be able
+ to play any media for which a PlayObject can be found. So it makes sense to
+ implement PlayObjects for various formats (such as mp3, mpg video, midi, wav,
+ ...) on that base, and there are a lot already.
+ </para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term>soundserver.idl</term>
+
+ <listitem><para>
+ Here, an interface for the system wide sound server artsd is defined. The
+ interface is called <emphasis>Arts::SoundServer</emphasis>, which implements
+ functionality like accepting streams from the network, playing samples,
+ creating custom other aRts objects and so on. Network transparency is
+ implied due to the use of MCOP (as for everything else here).
+ </para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term>artsbuilder.idl</term>
+ <listitem><para>
+ This module defines basic flow graph functionality, that is, combining
+ simpler objects to more complex ones, by defining a graph of them. It defines
+ the basic interface <emphasis>Arts::StructureDesc</emphasis>,
+ <emphasis>Arts::ModuleDesc</emphasis> and <emphasis>Arts::PortDesc</emphasis>
+ which contain a description of a structure, module, and port. There is also
+ a way to get a "living network of objects" out of these connection and value
+ descriptions, using a factory.
+ </para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term>artsmidi.idl</term>
+
+ <listitem><para>
+ This module defines basic midi functionality, like objects that produce
+ midi events, what is a midi event, an <emphasis>Arts::MidiManager</emphasis>
+ to connect the producers and consumers of midi events, and so on. As always
+ network transparency implied.
+ </para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term>artsmodules.idl</term>
+ <listitem><para>
+ Here are various additional filters, oscillators, effects, delays and
+ so on, everything required for real useful signal processing, and to
+ build complex instruments and effects out of these basic building blocks.
+ </para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term>artsgui.idl</term>
+
+ <listitem><para>
+ This cares about visual objects. It defines the basic type <emphasis>
+ Arts::Widget</emphasis> from which all GUI modules derive. This will produce
+ toolkit independency, and ... visual GUI editing, and serializable GUIs.
+ Also, as the GUI elements have normal attributes, their values can be
+ straight forward connected to some signal processing modules. (I.e. the
+ value of a slider to the cutoff of a filter). As always: network transparent.
+ </para></listitem>
+
+</varlistentry>
+
+</variablelist>
+<para>
+Where possible, aRts itself is implemented using IDL. On the other hand, there
+are some <emphasis>language specific</emphasis> APIs, using either plain C++ or
+plain C. It is usually wise to use IDL interfaces where possible, and the
+other APIs where necessary. Here is a list of language specific APIs:
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term>KNotify, KAudioPlayer (included in libkdecore)</term>
+
+ <listitem><para>
+ These are convenience KDE APIs for the simple and common common case, where
+ you just want to play a sample. The APIs are plain C++, Qt/KDE optimized,
+ and as easy as it can get.
+ </para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term>libartsc</term>
+ <listitem><para>
+ Plain C interface for the sound server. Very useful for porting legacy
+ applications.
+ </para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term>libmcop</term>
+
+ <listitem><para>
+ Here all magic for MCOP happens. The library contains the basic things you
+ need to know for writing a simple MCOP application, the dispatcher, timers,
+ iomanagement, but also the internals to make the MCOP protocol itself work.
+ </para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term>libartsflow</term>
+ <listitem><para>
+ Besides the implementation of artsflow.idl, some useful utilities like
+ sampling rate conversion.
+ </para></listitem>
+
+</varlistentry>
+
+<varlistentry>
+<term>libqiomanager</term>
+
+ <listitem><para>
+ Integration of MCOP into the Qt event loop, when you write Qt applications
+ using MCOP.
+ </para></listitem>
+
+</varlistentry>
+
+</variablelist>
+
+
+
+</sect1>
+<sect1 id="knotify">
+<title>knotify</title>
+<para>
+Not yet written
+</para>
+</sect1>
+
+<sect1 id="kaudioplayer">
+<title>kaudioplayer</title>
+<para>
+Not yet written
+</para>
+</sect1>
+
+<sect1 id="libkmid">
+<title>libkmid</title>
+<para>
+Not yet written
+</para>
+</sect1>
+
+<sect1 id="kmedia2">
+<title>kmedia2</title>
+<para>
+Not yet written
+</para>
+</sect1>
+
+<sect1 id="soundserver">
+<title>sound server</title>
+<para>
+Not yet written
+</para>
+</sect1>
+
+<sect1 id="artsflow">
+<title>artsflow</title>
+<para>
+Not yet written
+</para>
+</sect1>
+
+<sect1 id="capi">
+<title>C <acronym>API</acronym></title>
+
+<sect2 id="capiintro">
+<title>Introduction</title>
+
+<para> The &arts; C <acronym>API</acronym> was designed to make it easy to
+writing and port plain C applications to the &arts; sound server. It provides
+streaming functionality (sending sample streams to
+<application>artsd</application>), either blocking or non-blocking. For most
+applications you simply remove the few system calls that deal with your audio
+device and replace them with the appropriate &arts; calls.</para>
+
+<para>I did two ports as a proof of concept: <application>mpg123</application>
+and <application>quake</application>. You can get the patches from <ulink
+url="http://space.twc.de/~stefan/kde/download/artsc-patches.tar.gz">here</ulink>.
+Feel free to submit your own patches to the maintainer of &arts; or of
+multimedia software packages so that they can integrate &arts; support into
+their code.</para>
+
+</sect2>
+
+<sect2 id="capiwalkthru">
+<title>Quick Walkthrough</title>
+
+<para>Sending audio to the sound server with the <acronym>API</acronym> is very
+simple:</para>
+<procedure>
+<step><para>include the header file using <userinput>#include
+&lt;artsc.h&gt;</userinput></para></step>
+<step><para>initialize the <acronym>API</acronym> with
+<function>arts_init()</function></para></step>
+<step><para>create a stream with
+<function>arts_play_stream()</function></para></step>
+<step><para>configure specific parameters with
+<function>arts_stream_set()</function></para></step>
+<step><para>write sampling data to the stream with
+<function>arts_write()</function></para></step>
+<step><para>close the stream with
+<function>arts_close_stream()</function></para></step>
+<step><para>free the <acronym>API</acronym> with
+<function>arts_free()</function></para></step>
+</procedure>
+
+<para>Here is a small example program that illustrates this:</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>Compiling and Linking: <application>artsc-config</application></title>
+
+<para>To easily compile and link programs using the &arts; C
+<acronym>API</acronym>, the <application>artsc-config</application> utility is
+provided which knows which libraries you need to link and where the includes
+are. It is called using</para>
+
+<screen>
+<userinput><command>artsc-config</command> <option>--libs</option></userinput>
+</screen>
+
+<para>to find out the libraries and </para>
+
+<screen>
+<userinput><command>artsc-config</command> <option>--cflags</option></userinput>
+</screen>
+
+<para>to find out additional C compiler flags. The example above could have been
+
+compiled using the command line:</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>Library Reference</title>
+
+<para>
+[TODO: generate the documentation for artsc.h using kdoc]
+</para>
+
+</sect2>
+
+</sect1>
+</chapter>