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
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% INVOKING THE COMPILER %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Invoking the \faust compiler}
The \faust compiler is invoked using the \texttt{faust} command. It translate \faust programs into C++ code.
The generated code can be wrapped into an optional \emph{architecture file} allowing to directly produce a fully operational program.
\begin{rail}
compiler : "faust" (options) (file +);
\end{rail}
For example \lstinline'faust noise.dsp' will compile \lstinline'noise.dsp' and output the corresponding C++ code on the standard output. The option \lstinline'-o' allows to choose the output file: \lstinline'faust noise.dsp -o noise.cpp'. The option \lstinline'-a' allows to choose the architecture file: \lstinline'faust -a alsa-gtk.cpp noise.dsp'.
To compile a \faust program into an ALSA application on Linux you can use the following commands:
\begin{lstlisting}
faust -a alsa-gtk.cpp noise.dsp -o noise.cpp
g++ -lpthread -lasound
`pkg-config --cflags --libs gtk+-2.0`
noise.cpp -o noise
\end{lstlisting}
\section{Structure of the generated code}
A \faust DSP C++ class derives from the base \emph{dsp} class defined as below:
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]
class dsp {
public:
dsp() {}
virtual ~dsp() {}
virtual int getNumInputs() = 0;
virtual int getNumOutputs() = 0
virtual void buildUserInterface(UI* ui_interface) = 0;
virtual int getSampleRate() = 0;
virtual void init(int samplingRate) = 0;
virtual void instanceInit(int samplingRate) = 0;
virtual void instanceConstants(int samplingRate) = 0;
virtual void instanceResetUserInterface() = 0;
virtual void instanceClear() = 0;
virtual dsp* clone() = 0;
virtual void metadata(Meta* m) = 0;
virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0;
virtual void compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs)
{
compute(count, inputs, outputs);
}
};
\end{lstlisting}
Here is the class generated with the command \lstinline'faust noise.dsp'. Methods are filled by the compiler with the actual code.
Several fine-grained initialization methods are available. The \lstinline'instanceInit' method calls several additional initialization methods. The \lstinline'instanceConstants' method sets the instance constant state. The \lstinline'instanceClear' method resets the instance dynamic state (delay lines...). The \lstinline'instanceResetUserInterface' method resets all control value to their default state. All of those methods can be used individually on an allocated instance to reset part of its state.
The \lstinline'classInit' static method will initialize static tables that are shared between all instances of the class, and is typically supposed to be called once.
Finally the \lstinline'init' method combines class static state and instance initialization.
When using a single instance, then calling \lstinline'init' is the simplest way to do what is needed. When using several instances, then all of them can be initialized using \lstinline'instanceInit' , whith a single call to \lstinline'classInit' to initialize the static shared state.
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]
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, "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];
}
}
};
\end{lstlisting}
\section{Compilation options}
Compilation options are listed in the following table :
\bigskip
\small
%%\begin{tabularx}{\textwidth}[t]{|l|l|X|}
\tablefirsthead{
\hline
\textbf{Short} & \textbf{Long} & \textbf{Description} \\
\hline
}
\tablehead{
\hline
\textbf{Short} & \textbf{Long} & \textbf{Description} \\
\hline
}
\tabletail{
\hline
\multicolumn{3}{|r|}{\small\sl continued on next page}\\
\hline
}
\tablelasttail{
\hline
}
\begin{supertabular}{|p{1.5cm}|p{4cm}|p{5cm}|}
\texttt{-h} & \texttt{--help} & print the help message \\
\texttt{-v} & \texttt{--version} & print version information \\
\texttt{-d} & \texttt{--details} & print compilation details \\
\texttt{-tg} & \texttt{--task-graph} & draw a graph of all internal computation loops as a .dot (graphviz) file. \\
\texttt{-sg} & \texttt{--signal-graph} & draw a graph of all internal signal expressions as a .dot (graphviz) file. \\
\texttt{-ps} & \texttt{--postscript} & generate block-diagram postscript files \\
\texttt{-svg} & \texttt{--svg} & generate block-diagram svg files \\
\texttt{-blur} & \texttt{--shadow-blur} & add a blur to boxes shadows \\
\texttt{-sd} & \texttt{--simplify-diagrams} & simplify block-diagram before drawing them \\
\texttt{-f \farg{n}} & \texttt{--fold \farg{n}} & max complexity of svg diagrams before splitting into several files (default 25 boxes) \\
\texttt{-mns \farg{n}} & \texttt{--max-name-size \farg{n}} & max character size used in svg diagram labels\\
\texttt{-sn} & \texttt{--simple-names} & use simple names (without arguments) for block-diagram (default max size : 40 chars) \\
\texttt{-xml} & \texttt{--xml} & generate an additional description file in xml format \\
\texttt{-uim} & \texttt{--user-interface-macros} & add user interface macro definitions to the C++ code \\
\texttt{-flist} & \texttt{--file-list} & list all the source files and libraries implied in a compilation \\
\texttt{-norm} & \texttt{--normalized-form} & prints the internal signals in normalized form and exits \\
\hline
\texttt{-lb} & \texttt{--left-balanced} & generate left-balanced expressions \\
\texttt{-mb} & \texttt{--mid-balanced} & generate mid-balanced expressions (default) \\
\texttt{-rb} & \texttt{--right-balanced} & generate right-balanced expressions \\
\texttt{-lt} & \texttt{--less-temporaries} & generate less temporaries in compiling delays \\
\texttt{-mcd \farg{n}} & \texttt{--max-copy-delay \farg{n}}& threshold between copy and ring buffer delays (default 16 samples)\\
\hline
\texttt{-vec} & \texttt{--vectorize} & generate easier to vectorize code \\
\texttt{-vs \farg{n}} & \texttt{--vec-size \farg{n}} & size of the vector (default 32 samples) when -vec \\
\texttt{-lv \farg{n}} & \texttt{--loop-variant \farg{n}} & loop variant [0:fastest (default), 1:simple] when -vec\\
\texttt{-dfs} & \texttt{--deepFirstScheduling} & schedule vector loops in deep first order when -vec \\
\hline
\texttt{-omp} & \texttt{--openMP} & generate parallel code using OpenMP (implies -vec) \\
\texttt{-sch} & \texttt{--scheduler} & generate parallel code using threads directly (implies -vec) \\
\texttt{-g} & \texttt{--groupTasks} & group sequential tasks together when -omp or -sch is used \\
\hline
\texttt{-single} & \texttt{--single-precision-floats} & use floats for internal computations (default) \\
\texttt{-double} & \texttt{--double-precision-floats} & use doubles for internal computations \\
\texttt{-quad} & \texttt{--quad-precision-floats} & use extended for internal computations \\
\hline
\texttt{-mdoc} & \texttt{--mathdoc} & generates the full mathematical description of a \faust program \\
\texttt{-mdlang \farg{l}} & \texttt{--mathdoc-lang \farg{l}} & choose the language of the mathematical description (\farg{l} = en, fr, ...) \\
\texttt{-stripmdoc} & \texttt{--strip-mdoc-tags} & remove documentation tags when printing \faust listings\\
\hline
\texttt{-cn \farg{name}} & \texttt{--class-name \farg{name}} & name of the dsp class to be used instead of 'mydsp' \\
\texttt{-t \farg{time}} & \texttt{--timeout \farg{time}} & time out of time seconds (default 600) for the compiler to abort \\
\texttt{-a \farg{file}} & & architecture file to use \\
\texttt{-o \farg{file}} & & C++ output file\\
%%\end{tabularx}
\end{supertabular}
\normalsize
\bigskip
|
