diff options
Diffstat (limited to 'doc/artsbuilder/apis.docbook')
| -rw-r--r-- | doc/artsbuilder/apis.docbook | 357 |
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 +<artsc.h></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 <stdio.h> +#include <artsc.h> +int main() +{ + arts_stream_t stream; + char buffer[8192]; + int bytes; + int errorcode; + + errorcode = arts_init(); + if (errorcode < 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)) > 0) + { + errorcode = arts_write(stream, buffer, bytes); + if(errorcode < 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> |