%---------------------------------------------------
\chapter{Architecture files} \label{sec:audio}
%---------------------------------------------------

A \faust program describes a \emph{signal processor}, a pure computation that maps \emph{input signals} to \emph{output signals}. It says nothing about audio drivers or GUI toolkits. This missing information is provided by \emph{architecture files}. 

%The role of \emph{architecture files} is to provide this missing information. 


An \emph{architecture file} describes how to relate a \faust program to the external world, in particular the audio drivers and the user interface to be used. This approach allows a single \faust program to be easily deployed to a large variety of audio standards (Max/MSP externals, PD externals, VST plugins, CoreAudio applications, Jack applications, iPhone, etc.). 

The architecture to be used is specified at compile time with the \lstinline'-a' options. For example
\lstinline'faust -a jack-gtk.cpp foo.dsp' indicates to use the Jack GTK architecture when compiling \code{foo.dsp}.

\begin{table}[htdp]
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
\textbf{File name}			& \textbf{Description}   \\
\hline
\texttt{alchemy-as.cpp} 	& Flash - ActionScript plugin \\
\texttt{ca-qt.cpp} 			& CoreAudio QT4 standalone application  \\
\texttt{jack-gtk.cpp} 		& Jack GTK standalone application  \\
\texttt{jack-qt.cpp} 		& Jack QT4 standalone application  \\
\texttt{jack-console.cpp} 	& Jack command line application  \\
\texttt{jack-internal.cpp} 	& Jack server plugin  \\
%%\texttt{jack-wx.cpp} 		& Jack wxWindows standalone application  \\
\texttt{alsa-gtk.cpp} 		& ALSA GTK standalone application  \\
\texttt{alsa-qt.cpp} 		& ALSA QT4 standalone application  \\
\texttt{oss-gtk.cpp} 		& OSS GTK standalone application  \\
%%\texttt{oss-wx.cpp} 		& OSS wxWindows standalone application  \\
\texttt{pa-gtk.cpp} 		& PortAudio GTK standalone application  \\
\texttt{pa-qt.cpp} 			& PortAudio QT4 standalone application  \\
%%\texttt{pa-wx.cpp} 		& PortAudio wxWindows standalone application  \\
\hline
\texttt{max-msp.cpp} 		& Max/MSP external  \\
\texttt{vst.cpp} 			& VST plugin  \\
\texttt{vst2p4.cpp} 		& VST 2.4 plugin  \\
\texttt{vsti-mono.cpp} 		& VSTi mono instrument  \\
\texttt{vsti-poly.cpp} 		& VSTi polyphonic instrument  \\
\texttt{ladspa.cpp} 		& LADSPA plugin  \\
\texttt{q.cpp} 				& Q language plugin  \\
\texttt{supercollider.cpp} 	& SuperCollider Unit Generator  \\
\texttt{snd-rt-gtk.cpp} 	& Snd-RT music programming language  \\
\texttt{csound.cpp} 		& CSOUND opcode  \\
\texttt{puredata.cpp} 		& PD external  \\
\hline
\texttt{sndfile.cpp} 		& sound file transformation command \\
\texttt{bench.cpp} 			& speed benchmark   \\
\texttt{octave.cpp} 		& Octave plugin   \\
\texttt{plot.cpp} 			& Command line application    \\
\texttt{sndfile.cpp} 		& Command line application    \\
\hline
\end{tabular}
\end{center}
\caption{Available architectures.}
\label{tab:availablearch}
\end{table}%


The main available architecture files are listed table \ref{tab:availablearch}. Since \faust 0.9.40 some of these architectures are a modular combination of an \emph{audio module} and one or more \emph{user interface modules}. Among these user interface modules OSCUI provide supports for Open Sound Control allowing \faust programs to be controlled by OSC messages. 

\section{Audio architecture modules} 
An \emph{audio architecture module} typically connects a \faust program to the audio drivers.
It is responsible for allocating and releasing the audio channels and for calling the \faust \code{dsp::compute} method to handle incoming audio buffers and/or to produce audio output. It is also responsible for presenting the audio as non-interleaved float data, normalized between -1.0 and 1.0.

A \faust audio architecture module derives an \emph{audio} class defined as below:
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]
class audio {
 public:
           audio() {}
  virtual ~audio() {}
  virtual bool init(const char*, dsp*) = 0;
  virtual bool start()                 = 0;
  virtual void stop()                  = 0;
};
\end{lstlisting} 


The API is simple enough to give a great flexibility to audio architectures implementations. The \code{init} method should initialize the audio. At \code{init} exit, the system should be in a safe state to recall the \code{dsp} object state.

Table \ref{tab:aarch} gives the audio architectures currently available for various operating systems.
\begin{table}[htdp]
\begin{center}
\begin{tabular}{|c|c|}
\hline
\bf{Audio system} & \bf{Operating system} \\
\hline
Alsa  & Linux \\
Core audio 		& Mac OS X, iOS \\
Jack 				& Linux, Mac OS X, Windows \\
Portaudio 			& Linux, Mac OS X, Windows \\
OSC {\footnotesize (see \ref{sec:oscaudio})} & Linux, Mac OS X, Windows \\
VST					& Mac OS X, Windows \\
Max/MSP				& Mac OS X, Windows \\
CSound				& Linux, Mac OS X, Windows \\
SuperCollider		& Linux, Mac OS X, Windows \\
PureData			& Linux, Mac OS X, Windows \\
Pure \cite{graef09}				& Linux, Mac OS X, Windows \\
\hline
\end{tabular}
\end{center}
\caption{\faust audio architectures.}
\label{tab:aarch}
\end{table}%
 

% \begin{table}[htdp]
% \begin{center}
% \begin{tabular}{|c|l|}
% \hline
% Name 	& System \\
% \hline
% ladspa        & \href{http://www.ladspa.org/}{LADSPA} plugins \\
% csound        & \href{http://csounds.com/}{CSOUND} opcodes \\
% csounddouble  & double precision CSOUND opcodes \\
% maxmsp        & \href{http://cycling74.com/products/maxmspjitter/}{Max/MSP} externals \\
% vst           & native \href{http://en.wikipedia.org/wiki/Virtual_Studio_Technology}{VST} plugins \\
% w32vst        & windows VST plugins \\
% supercollider & \href{http://www.audiosynth.com/}{Supercollider} plugins \\
% puredata      & \href{http://puredata.info/}{Puredata} externals \\
% Q             & \href{http://q-lang.sourceforge.net/}{Q} plugins \\
% Pure          & \href{http://code.google.com/p/pure-lang/}{Pure} plugins \\
% \hline
% \end{tabular}
% \end{center}
% \caption{\faust plugins architectures}
% \label{tab:aarch}
% \end{table}%
% 


%---------------------------------------------------
\section{UI architecture modules} \label{sec:gui}
%---------------------------------------------------

A UI architecture module links user actions (via graphic widgets, command line parameters, OSC messages, etc.) with the \faust program to control. 
It is responsible for associating program parameters to user interface elements and to update parameter's values according to user actions. This association is triggered by the \code{dsp::buildUserInterface} call, where the \code{dsp} asks a UI object to build the DSP module controllers.

Since the interface is basically graphic oriented, the main concepts are \emph{widget} based: a UI architecture module is semantically oriented to handle active widgets, passive widgets and widgets layout.

A \faust UI architecture module derives an \emph{UI} class (Figure \ref{tab:ui}). 

\begin{figure}[htdp]
\begin{center}
%\begin{lstlisting}[basicstyle=\ttfamily\tiny\color{yotxt}]
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]
class UI
{
 public:
           UI() {}
  virtual ~UI() {}

   -- active widgets
  virtual void addButton(const char* l, float* z)       = 0;
  virtual void addToggleButton(const char* l, float* z) = 0;
  virtual void addCheckButton(const char* l, float* z)  = 0;
  
  virtual void addVerticalSlider(const char* l, float* z, 
          float init, float min, float max, float step) = 0;
          
  virtual void addHorizontalSlider(const char* l, float* z, 
          float init, float min, float max, float step) = 0;
          
  virtual void addNumEntry(const char* l, float* z, 
      float init, float min, float max, float step)     = 0;
      
   -- passive widgets
  virtual void addNumDisplay(const char* l, float* z,
                                                 int p) = 0;
                                                 
  virtual void addTextDisplay(const char* l, float* z, 
             const char* names[], float min, float max) = 0;
             
  virtual void addHorizontalBargraph(const char* l,
                        float* z, float min, float max) = 0;
                        
  virtual void addVerticalBargraph(const char* l, 
                        float* z, float min, float max) = 0; 
                        
   -- widget layouts
  virtual void openTabBox(const char* l)                = 0;
  virtual void openHorizontalBox(const char* l)         = 0;
  virtual void openVerticalBox(const char* l)           = 0;
  virtual void closeBox()                               = 0;
        
   -- metadata declarations
  virtual void declare(float*, const char*, const char* ) {}
};
\end{lstlisting} 
\end{center}
\caption{UI, the root user interface class.}
\label{tab:ui}
\end{figure}

%---------------------------------------------------
\subsection{Active widgets}
\label{sec:awidget}
Active widgets are graphical elements that control a parameter value. They are initialized with the widget name and a pointer to the linked value.
The widget currently considered are \code{Button},  \code{ToggleButton},  \code{CheckButton},  \code{VerticalSlider},  \code{HorizontalSlider} and  \code{NumEntry}. \\
A GUI architecture must implement a method \\
\code{addXxx (const char* name, float* zone, ...)} for each active widget.
Additional parameters are available for \code{Slider} and \code{NumEntry}: the \code{init} value, the \code{min} and \code{max} values and the \code{step}.

%---------------------------------------------------
\subsection{Passive widgets}
\label{sec:pwidget}
Passive widgets are graphical elements that reflect values. Similarly to active widgets, they are initialized with the widget name and a pointer to the linked value.
The widget currently considered are \code{NumDisplay},  \code{TextDisplay},  \code{HorizontalBarGraph} and  \code{VerticalBarGraph}. \\
A UI architecture must implement a method \\
\code{addxxx (const char* name, float* zone, ...)} for each passive widget.
Additional parameters are available, depending on the passive widget type.

%---------------------------------------------------
\subsection{Widgets layout}
\label{sec:wlayout}
Generally, a  GUI is hierarchically organized into boxes and/or tab boxes. 
A UI architecture must support the following methods to setup this hierarchy : \\
\htab\code{openTabBox (const char* label)} \\
\htab\code{openHorizontalBox (const char* label)} \\
\htab\code{openVerticalBox (const char* label)} \\
\htab\code{closeBox (const char* label)} \\
Note that all the widgets are added to the current box.

%---------------------------------------------------
\subsection{Metadata}
\label{sec:metadata}
The \faust language allows widget labels to contain metadata enclosed in square brackets. These metadata are handled at GUI level by a \code{declare} method taking as argument, a pointer to the widget associated zone, the metadata key and value: \\
\htab\code{declare(float* zone, const char* key, const char* value)} \\


%%Table \ref{tab:uiarch} gives the UI architectures currently available.
\begin{table}[htdp]
\begin{center}
\begin{tabular}{|c|l|}
\hline
\bf{UI} & \bf{Comment} \\
\hline
console  & a textual command line UI \\
GTK  & a GTK-based GUI \\
Qt   & a multi-platform Qt-based GUI \\
FUI  & a file-based UI to store and recall modules states \\
OSC  & OSC control (see \ref{sec:oscgui}) \\
\hline
\end{tabular}
\end{center}
\caption{Available UI architectures.}
\label{tab:uiarch}
\end{table}%

