%---------------------------------------------------
\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}[htp]
\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{Some of the 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;
  virtual void shutdown(shutdown_callback cb, void* arg)  {}
  virtual int getBufferSize() = 0;
  virtual int getSampleRate() = 0;
    
  virtual int getNumInputs() = 0;
  virtual int getNumOutputs() = 0;
    
  virtual float getCPULoad() { return 0.f; }
};
\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 some of the audio architectures currently available for various operating systems.
\begin{table}[htp]
\begin{center}
\begin{tabular}{|c|c|}
\hline
\bf{Audio system} & \bf{Operating system} \\
\hline
Alsa  & Linux \\
CoreAudio 		& Mac OS X, iOS \\
JACK 			& Linux, Mac OS X, Windows \\
PortAudio 			& Linux, Mac OS X, Windows \\
OSC				& 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 			& Linux, Mac OS X, Windows \\
\hline
\end{tabular}
\end{center}
\caption{Some of \faust audio architectures.}
\label{tab:aarch}
\end{table}%
 

% \begin{table}[htp]
% \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}[htp]
\begin{center}
%\begin{lstlisting}[basicstyle=\ttfamily\tiny\color{yotxt}]
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]

#ifndef FAUSTFLOAT
#define FAUSTFLOAT float
#endif

class UI
{
 public:
           UI() {}
  virtual ~UI() {}
  
     -- 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;

   -- active widgets
  virtual void addButton(const char* l, FAUSTFLOAT* z)      
  	 = 0;
  virtual void addCheckButton(const char* l, FAUSTFLOAT* z) 
  	 = 0;
  
  virtual void addVerticalSlider(const char* l,
          FAUSTFLOAT* z, 
          FAUSTFLOAT init, FAUSTFLOAT min, 
          FAUSTFLOAT max, FAUSTFLOAT step) = 0;
          
  virtual void addHorizontalSlider(const char* l, 
          FAUSTFLOAT* z, 
          FAUSTFLOAT init, FAUSTFLOAT min,
          FAUSTFLOAT max, FAUSTFLOAT step) = 0;
          
  virtual void addNumEntry(const char* l, FAUSTFLOAT* z, 
          FAUSTFLOAT init, FAUSTFLOAT min,
          FAUSTFLOAT max, FAUSTFLOAT step)  = 0;
      
   -- passive widgets
  virtual void addHorizontalBargraph(const char* l,
                        FAUSTFLOAT* z, FAUSTFLOAT min, 
                        FAUSTFLOAT max) = 0;
                        
  virtual void addVerticalBargraph(const char* l, 
                        FAUSTFLOAT* z, FAUSTFLOAT min, 
                        FAUSTFLOAT max) = 0; 
                        
   -- metadata declarations
  virtual void declare(FAUSTFLOAT*, 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, using the FAUSTFLOAT macro type (defined at compile time as either float or double).
The widget currently considered are \code{Button},  \code{CheckButton},  \code{VerticalSlider},  \code{HorizontalSlider} and  \code{NumEntry}. \\
A GUI architecture must implement a method \\
\code{addXxx(const char* name, FAUSTFLOAT* zone, ...)} for each active widget.
Additional parameters are available for \code{Slider} and \code{NumEntry}: the \code{init},  \code{min},  \code{max} and \code{step} values.

%---------------------------------------------------
\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{HorizontalBarGraph} and  \code{VerticalBarGraph}. \\
A UI architecture must implement a method \\
\code{addXxx(const char* name, FAUSTFLOAT* 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.

%%Table \ref{tab:uiarch} gives some of the UI architectures currently available.
\begin{table}[htp]
\begin{center}
\begin{tabular}{|c|l|}
\hline
\bf{UI} & \bf{Comment} \\
\hline
console & a textual command line UI \\
GTKUI & a GTK-based GUI \\
QTGUI & a multi-platform QT-based GUI \\
FUI & a file-based UI to store and recall modules states \\
OSCUI & OSC control (see section \ref{sec:osc}) \\
httpdUI & HTTP control (see section \ref{sec:http}) \\
...  & ... \\
\hline
\end{tabular}
\end{center}
\caption{Some of the available UI architectures.}
\label{tab:uiarch}
\end{table}%

%---------------------------------------------------
\subsection{Metadata}
\label{sec:metadata}
The \faust language allows widget labels to contain metadata enclosed in square brackets as key/value pairs. 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(FAUSTFLOAT* zone, const char* key, const char* value)} \\

Here is the table of currently supported general medatada (look at section \ref{sec:osc} for OSC specific metadata and section \ref{sec:midi} for MIDI specific metadata):

%%Table \ref{tab:uiarch} gives some of the UI architectures currently available.
\begin{table}[htp]
\begin{center}
\begin{tabular}{|c|l|}
\hline
\bf{Key} & \bf{Value} \\
\hline
tooltip & actual string content \\
hidden & \code{0} or \code{1} \\
size & actual value \\
unit & \code{Hz} or \code{dB} \\
scale & \code{log} or \code{exp} \\
style & \code{knob} or \code{led} or \code{numerical} \\
style & \code{radio\{\'label1\':v1;\'label2\':v2...\}}  \\
style & \code{menu\{\'label1\':v1;\'label2\':v2...\}}  \\
acc & \code{axe curve amin amid amax}  \\
gyr & \code{axe curve amin amid amax}  \\
screencolor & \code{red} or \code{green}  or \code{blue} or \code{white}    \\

\hline
\end{tabular}
\end{center}
\caption{Supported medatada.}
\label{tab:metadata}
\end{table}%

Some typical example where several metadata are defined could be: 

 \htab\code{nentry("freq [unit:Hz][scale:log][acc:0 0 -30 0 30][style:menu\{\'white noise\':0;\'pink noise\':1;\'sine\':2\}][hidden:0]", 0, 20, 100, 1)} 
 
 or: 
 
 \htab\code{vslider("freq [unit:dB][style:knob][gyr:0 0 -30 0 30]", 0, 20, 100, 1)} 
 
 Note that medatada are not supported in all architecture files. Some of them like (\code{acc} or \code{gyr} for exemple) only make sense on platforms with accelerometers or gyroscopes sensors. The set of medatada may be extended in the future. 

%---------------------------------------------------
\section{Developing a new architecture file}
\label{sec:architecture}

Developing a new architecture file typically means writing a generic C++ file, that will be populated with the actual output of the \faust compiler, in order to produce a complete C++ file, ready to be compiled as a standalone application or plugin. 

The architecture to be used is specified at compile time with the \lstinline'-a' option. It must contain the \code{<<includeIntrinsic>>} and \code{<<includeclass>>} lines that will be looked at by the \faust compiler, and replaced by the generated C++ class. 

Look at the \code{minimal.cpp} example located in the architecture folder:

\begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]
#include "faust/gui/PrintUI.h"
#include "faust/gui/meta.h"
#include "faust/audio/dummy-audio.h"

using std::max;
using std::min;

//-------------------------------------------------
//  FAUST generated signal processor
//-------------------------------------------------

<<includeIntrinsic>>

<<includeclass>>

int main(int argc, char *argv[])
{
    mydsp DSP;
    PrintUI ui;
    
    // Activate the UI
    // (here that only prints the control paths)
    DSP.buildUserInterface(&ui);

    // Allocate the audio driver to render 
    // 5 buffers of 512 frames
    dummyaudio audio(5);
    audio.init("Test", &DSP);
    
    // Render buffers...
    audio.start();
    
    audio.stop();
}
\end{lstlisting} 

Calling \lstinline'faust -a minimal.cpp noise.dsp -a noise.cpp' will produce a ready to compile  \code{noise.cpp} file:

\begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]
#include "faust/gui/PrintUI.h"
#include "faust/gui/meta.h"
#include "faust/audio/dummy-audio.h"

using std::max;
using std::min;

//---------------------------------------------------
//  FAUST generated signal processor
//--------------------------------------------------

#ifndef FAUSTFLOAT
#define FAUSTFLOAT float
#endif  

#ifndef FAUSTCLASS 
#define FAUSTCLASS mydsp
#endif

class mydsp : public dsp {
  private:
	FAUSTFLOAT fslider0;
	int iRec0[2];
	int fSamplingFreq;

  public:
	virtual void metadata(Meta* m) { 
		m->declare("name", "Noise");
		m->declare("version", "1.1");
		m->declare("author", "Grame");
		m->declare("license", "BSD");
		m->declare("copyright", "(c)GRAME 2009");
	}

	virtual int getNumInputs() { return 0; }
	virtual int getNumOutputs() { return 1; }
	static void classInit(int samplingFreq) {
	}
	virtual void instanceConstants(int samplingFreq) {
		fSamplingFreq = samplingFreq;
	}
	virtual void instanceResetUserInterface() {
		fslider0 = 0.5f;
	}
	virtual void instanceClear() {
		for (int i=0; i<2; i++) iRec0[i] = 0;
	}
	virtual void init(int samplingFreq) {
		classInit(samplingFreq);
		instanceInit(samplingFreq);
	}
	virtual void instanceInit(int samplingFreq) {
		instanceConstants(samplingFreq);
		instanceResetUserInterface();
		instanceClear();
	}
	virtual mydsp* clone() {
		return new mydsp();
	}
	virtual int getSampleRate() {
		return fSamplingFreq;
	}
	virtual void buildUserInterface(UI* ui_interface) {
		ui_interface->openVerticalBox("Noise");
		ui_interface->declare(&fslider0, "acc", "0 0 -10 0 10");
		ui_interface->declare(&fslider0, "style", "knob");
		ui_interface->addVerticalSlider("Volume", &fslider0, 0.5f, 0.0f, 1.0f, 0.1f);
		ui_interface->closeBox();
	}
	virtual void compute (int count, FAUSTFLOAT** input, FAUSTFLOAT** output) {
		float fSlow0 = (4.656613e-10f * float(fslider0));
		FAUSTFLOAT* output0 = output[0];
		for (int i=0; i<count; i++) {
			iRec0[0] = ((1103515245 * iRec0[1]) + 12345);
			output0[i] = (FAUSTFLOAT)(fSlow0 * iRec0[0]);
			// post processing
			iRec0[1] = iRec0[0];
		}
	}
};

int main(int argc, char* argv[])
{
    mydsp DSP;
    PrintUI ui;
    
    // Activate the UI
    // (here that only prints the control paths)
    DSP.buildUserInterface(&ui);

    // Allocate the audio driver to render 
    // 5 buffers of 512 frames
    dummyaudio audio(5);
    audio.init("Test", &DSP);
    
    // Render buffers...
    audio.start();
    
    audio.stop();
}
\end{lstlisting} 

You can possibly add the \lstinline'-i' option to actually inline all \code{#include "faust/xxx/yyy"} headers (all files starting with "faust"). Then you will have to write a \code{faust2xxx} script that will chain the \faust compilation step and the C++ compilation one. Look at scripts in the tools/faust2appls folder for real examples. 

Developing the adapted C++ file may require "aggregating" the generated \code{mydsp} class (subclass of \code{dsp} base class defined in faust/dsp/dsp.h header) in your specific class, or "subclassing" and extend it.  So you will have to write something like:

\begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]
class my_class : public base_interface {

  private:
	 
	mydsp fDSP;
		
  public:
  
	my_class()
	{
		// Do something specific
	}
	
	virtual ~my_class()
	{
		// Do something specific
	}
	
	// Do something specific
	
	void my_compute(int count, 
		FAUSTFLOAT** inputs, 
		FAUSTFLOAT** outputs,....)
	{
		// Do something specific
		fDSP.compute(count,  inputs,  outputs);
	}
	
	// Do something specific
};

\end{lstlisting} 

or:

\begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]
class my_class : public mydsp  {

  private:
  
  	// Do something specific
		
  public:
  
	my_class()
	{
		// Do something specific
	}
	
	virtual ~my_class()
	{
		// Do something specific
	}
	
	// Do something specific
	
	void my_compute(int count, 
		FAUSTFLOAT** inputs, 
		FAUSTFLOAT** outputs,....)
	{
		// Do something specific
		compute(count,  inputs,  outputs);
	}
	
	// Do something specific
};
\end{lstlisting} 

This way your architecture file will be adapted to any "shape" of the generated code. That is, depending if you generate purely scalar, or vector code (using the \lstinline'-vec' option), or any other option, the generated \code{mydsp}  class will always be correctly inserted in the final C++ file. Look for instance at \code{csound.cpp} and \code{unity.cpp} architecture files in the architecture folder for real examples.