--- /dev/null
+
+faust2ck - A FAUST wrapper-generator for ChucK Ugens.
+========
+
+FAUST is a functional language for defining DSP structures that can be
+used for real-time audio computing. It can generate block diagrams
+and also C++ code which will execute the given routine.
+
+This is an ideal way to create unit generators (UGens) for ChucK. The
+ChucK data structures can be a bit weird and the learning curve for
+hacking on ChucK can be a little steap. Using FAUST, you can
+concentrate on the DSP algorithm, and allow faust2ck to take care of
+creating ChucK-compatible C++ code so that you can instantiate your
+new DSP object in a ChucK program.
+
+That said, in order to take advantage of faust2ck, you'll need a
+little C++ knowledge. At least enough to know how to compile ChucK
+and add a line or two to its source code, which is explained in this
+document.
+
+Please see the FAUST websites for more details, online tutorials, and
+even an online compiler that you can try:
+
+http://faust.grame.fr/
+http://sourceforge.net/projects/faudiostream/
+
+This document describes how to use faust2ck.
+
+
+Usage
+=====
+
+Running faust2ck with no parameters will give you a usage string:
+
+$ ./faust2ck
+Usage: faust2ck <filename.dsp.xml>
+
+You can see that it requires a single input, the name of an XML file.
+This XML file can be generated with FAUST by giving it the "-xml"
+parameter:
+
+$ faust -xml filename.dsp
+
+faust2ck will then generate a file called "filename.dsp-wrapper.cpp".
+(Where "filename" is whatever your file is called.)
+
+This program is yet another input for FAUST. It is a C++ file, but it
+has some tags in it that tell FAUST where to put the DSP code. So you
+must run FAUST again, this time telling it to use the wrapper:
+
+$ faust -a filename.dsp-wrapper.cpp -o filename.cpp filename.dsp
+
+This gives you a final C++ file containing the algorithm along with
+routines necessary to plug it in to ChucK.
+
+
+Adding to ChucK
+---------------
+
+Unfortunately there are a couple of manual steps necessary here.
+ChucK does not currently support (rightly in my opinion) loadable
+external modules, like other audio programs such as PureData.
+
+So, you need to re-compile ChucK. First, we need to tell it about our
+new C++ file. The first thing to do is create a header file. It only
+needs to contain one line of code, enough to tell ChucK about a single
+function declared in the C++ file.
+
+If your DSP object is called 'mydsp', then your file, mydsp.h, should
+look like this:
+
+ #ifndef __MYDSP_H__
+ #define __MYDSP_H__
+
+ DLL_QUERY mydsp_query( Chuck_DL_Query * QUERY );
+
+ #endif // __MYDSP_H__
+
+Put this file in the ChucK source directory. Now you just have to add
+a few lines to the file, 'chuck_compile.cpp'.
+
+At the top of chuck_compile.cpp, add an #include statement for our
+header file:
+
+ #include "mydsp.h"
+
+Now, find the function "load_internal_modules()", which should be
+around line 516. Add the necessary code to load your new module,
+which is done by passing ChucK the "mydsp_query" function, where
+"mydsp" is the name of your FAUST object.
+
+ EM_log( CK_LOG_SEVERE, "class 'mydsp'..." );
+ if( !load_module( env, mydsp_query, "mydsp", "global" ) ) goto error;
+
+That's it!
+
+The last thing to do is to add your C++ file to the makefile so that
+it gets compiled along with ChucK. Depending on which operating
+system you are using, load "makefile.alsa" for Linux, or
+"makefile.win32" for Windows, or "makefile.osx" for OS X, etc.
+
+There is a big list of filenames in a variable called OBJS. You need
+to add "mydsp.o" to this list.
+
+Lastly, you need to add a build target for mydsp.o to the bottom of
+the file:
+
+ mydsp.o: mydsp.h mydsp.cpp
+ $(CXX) $(FLAGS) mydsp.cpp
+
+Now, run "make", and if all goes well, ChucK will be built with your
+object.
+
+$ make
+
+Time to create a test program! Make a simple ChucK program that looks
+something like the following:
+
+ Impulse i => mydsp m => dac;
+ 100 => t;
+ 1 => i.next;
+ while (t>0) {
+ <<<m.last()>>>;
+ t--;
+ samp => now;
+ }
+
+This will print the impulse response your object to the console. Good
+luck! Have fun!
+
+If you have any questions you can email me at:
+
+Stephen Sinclair <radarsat1@gmail.com>
+
+
+License
+=======
+
+This code is licensed under the GNU General Public License (GPL) v2 or
+above. Please see COPYING for details, or visit:
+
+http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+
+
+
+Technical
+=========
+
+You wrote a string parsing and XML reading program
+like this, in 2008, in C ???! Are you mad?
+--------------------------------------------------
+
+Yes, a sane person would probably not do such a thing. The FAUST XML
+output is so simple, however, and generally predictable, that I didn't
+feel it was necessary to bring in a lot of external dependencies for
+such a small application. So I ended up basically writing a small,
+inadequate macro replacement parser, which was actually kind of fun.
+Of course, if it ever called for more a complex solution I'd probably
+re-do it in Perl or Python. But this'll do for now, and it means the
+program is tiny and easy to execute on any computer without installing
+huge libraries.
+
+Of course, it does depend on 'sed' to generate the template for
+inclusion in the final program. I wanted to include it right in the
+executable instead of having faust2ck load an external file that would
+always be exactly the same. Unfortunately the C preprocessor doesn't
+make it easy, so sed is just used to wrap lines of the template file
+in double-quotes ("") and backslash-escape a few special characters.
+
+faust2ck is distributed with the template already generated so that it
+can be compiled without needing to have sed around.
+
+
+Why generate the C++ wrapper on demand instead of just writing a
+better wrapper that doesn't need to change?
+----------------------------------------------------------------
+
+If you look at the FAUST wrappers for PureData and Max/MSP, for
+example, they are just a single file where FAUST replaces a certain
+line with the DSP code class.
+
+Unfortunately FAUST doesn't provide much for dynamically generating
+code from the wrapper, other than a single replacement within the file
+where it provides the DSP class. Specifically, for parameters
+(declared in FAUST with "UI" elements like hslider and vslider), it
+calls a function at run-time to inform the UI code about each
+parameter. In the case of PureData and Max/MSP, it's possible to
+instantiate parameters (inlets) at run-time, so this works well. In
+ChucK however, each parameter needs a getter and setting function,
+called "cget" and "ctrl", which must be made available statically at
+compile time. (This isn't strictly true, these functions are "linked
+in" to the rest of ChucK at run-time, but ChucK doesn't provide the
+function with enough information to figure out which parameter it's
+modifying, so each parameter needs its own function.)
+
+Now, before writing faust2ck, I tried very hard to come up with some
+kind of combination of preprocessor macros or C++ templates that would
+do the job of instantiating a cget and ctrl function for each
+parameter, but I just couldn't figure out a way to do it. If anyone
+wants to give it a try, it's a nice challenging problem. In any case,
+I realized I was wasting my time when a quick little program could
+generate the appropriate wrapper easily enough, hence faust2ck.
projects / Faustine.git / blobdiff