New directory tree, with preprocessor/ inside interpretor/.
[Faustine.git] / interpretor / preprocessor / faust-0.9.47mr3 / tools / faust2ck-1.0 / README
1
2 faust2ck - A FAUST wrapper-generator for ChucK Ugens.
3 ========
4
5 FAUST is a functional language for defining DSP structures that can be
6 used for real-time audio computing. It can generate block diagrams
7 and also C++ code which will execute the given routine.
8
9 This is an ideal way to create unit generators (UGens) for ChucK. The
10 ChucK data structures can be a bit weird and the learning curve for
11 hacking on ChucK can be a little steap. Using FAUST, you can
12 concentrate on the DSP algorithm, and allow faust2ck to take care of
13 creating ChucK-compatible C++ code so that you can instantiate your
14 new DSP object in a ChucK program.
15
16 That said, in order to take advantage of faust2ck, you'll need a
17 little C++ knowledge. At least enough to know how to compile ChucK
18 and add a line or two to its source code, which is explained in this
19 document.
20
21 Please see the FAUST websites for more details, online tutorials, and
22 even an online compiler that you can try:
23
24 http://faust.grame.fr/
25 http://sourceforge.net/projects/faudiostream/
26
27 This document describes how to use faust2ck.
28
29
30 Usage
31 =====
32
33 Running faust2ck with no parameters will give you a usage string:
34
35 $ ./faust2ck
36 Usage: faust2ck <filename.dsp.xml>
37
38 You can see that it requires a single input, the name of an XML file.
39 This XML file can be generated with FAUST by giving it the "-xml"
40 parameter:
41
42 $ faust -xml filename.dsp
43
44 faust2ck will then generate a file called "filename.dsp-wrapper.cpp".
45 (Where "filename" is whatever your file is called.)
46
47 This program is yet another input for FAUST. It is a C++ file, but it
48 has some tags in it that tell FAUST where to put the DSP code. So you
49 must run FAUST again, this time telling it to use the wrapper:
50
51 $ faust -a filename.dsp-wrapper.cpp -o filename.cpp filename.dsp
52
53 This gives you a final C++ file containing the algorithm along with
54 routines necessary to plug it in to ChucK.
55
56
57 Adding to ChucK
58 ---------------
59
60 Unfortunately there are a couple of manual steps necessary here.
61 ChucK does not currently support (rightly in my opinion) loadable
62 external modules, like other audio programs such as PureData.
63
64 So, you need to re-compile ChucK. First, we need to tell it about our
65 new C++ file. The first thing to do is create a header file. It only
66 needs to contain one line of code, enough to tell ChucK about a single
67 function declared in the C++ file.
68
69 If your DSP object is called 'mydsp', then your file, mydsp.h, should
70 look like this:
71
72 #ifndef __MYDSP_H__
73 #define __MYDSP_H__
74
75 DLL_QUERY mydsp_query( Chuck_DL_Query * QUERY );
76
77 #endif // __MYDSP_H__
78
79 Put this file in the ChucK source directory. Now you just have to add
80 a few lines to the file, 'chuck_compile.cpp'.
81
82 At the top of chuck_compile.cpp, add an #include statement for our
83 header file:
84
85 #include "mydsp.h"
86
87 Now, find the function "load_internal_modules()", which should be
88 around line 516. Add the necessary code to load your new module,
89 which is done by passing ChucK the "mydsp_query" function, where
90 "mydsp" is the name of your FAUST object.
91
92 EM_log( CK_LOG_SEVERE, "class 'mydsp'..." );
93 if( !load_module( env, mydsp_query, "mydsp", "global" ) ) goto error;
94
95 That's it!
96
97 The last thing to do is to add your C++ file to the makefile so that
98 it gets compiled along with ChucK. Depending on which operating
99 system you are using, load "makefile.alsa" for Linux, or
100 "makefile.win32" for Windows, or "makefile.osx" for OS X, etc.
101
102 There is a big list of filenames in a variable called OBJS. You need
103 to add "mydsp.o" to this list.
104
105 Lastly, you need to add a build target for mydsp.o to the bottom of
106 the file:
107
108 mydsp.o: mydsp.h mydsp.cpp
109 $(CXX) $(FLAGS) mydsp.cpp
110
111 Now, run "make", and if all goes well, ChucK will be built with your
112 object.
113
114 $ make
115
116 Time to create a test program! Make a simple ChucK program that looks
117 something like the following:
118
119 Impulse i => mydsp m => dac;
120 100 => t;
121 1 => i.next;
122 while (t>0) {
123 <<<m.last()>>>;
124 t--;
125 samp => now;
126 }
127
128 This will print the impulse response your object to the console. Good
129 luck! Have fun!
130
131 If you have any questions you can email me at:
132
133 Stephen Sinclair <radarsat1@gmail.com>
134
135
136 License
137 =======
138
139 This code is licensed under the GNU General Public License (GPL) v2 or
140 above. Please see COPYING for details, or visit:
141
142 http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
143
144
145
146 Technical
147 =========
148
149 You wrote a string parsing and XML reading program
150 like this, in 2008, in C ???! Are you mad?
151 --------------------------------------------------
152
153 Yes, a sane person would probably not do such a thing. The FAUST XML
154 output is so simple, however, and generally predictable, that I didn't
155 feel it was necessary to bring in a lot of external dependencies for
156 such a small application. So I ended up basically writing a small,
157 inadequate macro replacement parser, which was actually kind of fun.
158 Of course, if it ever called for more a complex solution I'd probably
159 re-do it in Perl or Python. But this'll do for now, and it means the
160 program is tiny and easy to execute on any computer without installing
161 huge libraries.
162
163 Of course, it does depend on 'sed' to generate the template for
164 inclusion in the final program. I wanted to include it right in the
165 executable instead of having faust2ck load an external file that would
166 always be exactly the same. Unfortunately the C preprocessor doesn't
167 make it easy, so sed is just used to wrap lines of the template file
168 in double-quotes ("") and backslash-escape a few special characters.
169
170 faust2ck is distributed with the template already generated so that it
171 can be compiled without needing to have sed around.
172
173
174 Why generate the C++ wrapper on demand instead of just writing a
175 better wrapper that doesn't need to change?
176 ----------------------------------------------------------------
177
178 If you look at the FAUST wrappers for PureData and Max/MSP, for
179 example, they are just a single file where FAUST replaces a certain
180 line with the DSP code class.
181
182 Unfortunately FAUST doesn't provide much for dynamically generating
183 code from the wrapper, other than a single replacement within the file
184 where it provides the DSP class. Specifically, for parameters
185 (declared in FAUST with "UI" elements like hslider and vslider), it
186 calls a function at run-time to inform the UI code about each
187 parameter. In the case of PureData and Max/MSP, it's possible to
188 instantiate parameters (inlets) at run-time, so this works well. In
189 ChucK however, each parameter needs a getter and setting function,
190 called "cget" and "ctrl", which must be made available statically at
191 compile time. (This isn't strictly true, these functions are "linked
192 in" to the rest of ChucK at run-time, but ChucK doesn't provide the
193 function with enough information to figure out which parameter it's
194 modifying, so each parameter needs its own function.)
195
196 Now, before writing faust2ck, I tried very hard to come up with some
197 kind of combination of preprocessor macros or C++ templates that would
198 do the job of instantiating a cget and ctrl function for each
199 parameter, but I just couldn't figure out a way to do it. If anyone
200 wants to give it a try, it's a nice challenging problem. In any case,
201 I realized I was wasting my time when a quick little program could
202 generate the appropriate wrapper easily enough, hence faust2ck.