diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 248 |
1 files changed, 248 insertions, 0 deletions
@@ -0,0 +1,248 @@ + + + +k_cext PD external + + + +INTRODUCTION + + The k_cext PD external makes you able to program + the programming language "C" directly within + the PD objects. + + +-------------------------------------------------------+ + | Which means: You don't need an external text-editor. | + +-------------------------------------------------------+ + + + +WHY USE K_CEXT + + First, the reason for using "C", and not some other programming + or scripting language, was simply because it is + so easy to compile and link c code inside externals in pd. + Because C is probably not the best suited language for this + task, except when extreme cpu-efficiency is needed. + + Still, I personally think making small k_cext objects + is a lot more comfortable than making large pd sub-patches + doing the same things. And thats probably the main reason + to use k_cext. + + + + +A SMALL EXAMPLE IN K_CEXT + + The following k_cext object have one inlet and one outlet. + What it does, when receiving a value on the inlet, is to + send the _previously_ received inlet value to the outlet. + + + [ k_cext 1 1; + static t_float prev=0; + O(0,prev); + prev=V(0); ] + + + The "k_cext 1 1" line is the k_cext header. The first "1" + means that it has one inlet, and the second "1" means that + it has one outlet. + + The "static t_float prev=0;" line declares a variable for the + object called "prev". "t_float" means that the type of the variable is + a floating-point number. "static" means here that the value + for the variable is remembered the next time the object + is runned, which is necesarry if we want to send out the + previous value sent to the inlet. + + "O(0,prev);" sends the value of "prev" to outlet number 0. + "O" is a function. + + "prev=V(0);" stores the value of the current inlet to the + variable "prev" for the next time the object is run. + + + + +THE SAME EXAMPLE AS A PD SUB-PATCH + + + The following PD-patch does the same: + + [inlet] + | + [t f b] + \ / + \ / + X + / \ + / \ + [float] + | + [outlet] + + + I guess its a matter of personal taste, but I really don't + find the PD-way of sending out a previous value very intuitive. + + And the advantage of using k_cext instead of making + PD sub-patches becomes more appearent the larger the tasks are. + Look at the help-file, and try to do the same things directly in PD. + + + +K_CEXT OBJECT + + A k_cext object can be divided into three parts: + + 1. Header. + 2. Variables + 3. Body. + + + +K_CEXT HEADER + + The first line in a k_cext header is built up like this: + + "k_cext <num_inlets> <num_outlets> <default inlet values>". + + "k_cext 4 5 1 2 3 4" means that the object has 4 inlets, + 5 outlets, and the value of V(0) is by default 1, the + value of V(1) is by default 2, the value of V(2) is by + default 3, and the value of V(3) is by default 4. + + Its optional whether you want to set "default inlet values" + or not. If not set, they get the value 0. + + + +K_CEXT VARIABLES + + There are four types of variables that makes sense using + in a k_cext object. These are: + + "int" - integer number. + "t_float" - floating point numbers. + "INTARRAY" - An array of integer numbers. + "FLOATARRAY" - An array of floating point numbers. + + See the help patch for examples of use. + + + +MACROS / USING THE PD OBJECT AS A TEXT-EDITOR + + Using the pd object as a text-editor is unfortunately + a bit limited. But by using some pre-defined macros + spesified in the "k_cext.h" file, its not that bad. + + begin/end - + The most noticable limitation is probably that you are + not able to write { or }. This is solved by + using the BEGIN and END macros. Or better; the "DO" + symbol which makes k_cext automaticly insert BEGIN and + END for you. Look at the help-do.pd patch. + + lineshift - + The pd object text editor doesn't understand lineshift + directly. Instead you have to use ";" at the end + of each line. + + semicolon - + If you need to write ";", but dont want the line to end + right there, use the "SC" macro instead. + + indentation - + The pd object text editor automaticly removes spaces and + tabs from the beginning of lines. You can work around this by + writing ". " instead. The k_cext external removes all + ". "'s at the beginning of lines before compiling the code. + + + More macros are defined in the k_cext.h header file. + + + +OS + k_cext runs fine in linux using gcc and in windows using visual C. + The macosx code was made by looking at code inside PD, and has never + been tested (at least not that I know if). It might work, but probably + not. Check out the k_cext_macosx.c file. + + +FAQ + Q: I can not get k_cext to work in windows, and I dont have Visual C. + A: You need Visual C. + + Q: Where can I get a windows .dll file? + A: Since you allready need to have some basic knowledge about C, in + addition to a C compiler, it should not be that hard for you to + compile the .dll file yourself, if you know how to use the k_cext + external. So you have to make it yourself. + + +CHANGES + 0.3.0 -> 0.3.1: + -Works with VisualC. (0.3.0 didn't): + -Workaround for missing variable number of argument macros in VisualC, (which is not a gcc + extension, by the way, but a part of the iso99 c-standard). + -Workaround for missing stdbool.h file in VisualC. (also a part of the iso99 c-standard) + (code by Thomas Grill) + -Workaround for missing static <something> <something>[] in VisualC. + -Fixed a variable which was not defined at the beginning of the function. (Thomas Grill) + + 0.2.5 -> 0.3.0: + -Added the k_cfunc object. k_cfunc is very similar to k_cext, but instead of being triggered + by getting a bang or value on the first inlet, the k_cfunc-code is run + when being called from another k_cfunc object or a k_cext object. In other words, + its a c function object available for k_cext. + + 0.2.4 -> 0.2.5: + -Fixed the problem that integer numbers sometimes was converted to + floats before compiling. + -Fixed ENDSWITCH macro. + -Small internal changes. + -Changed the PD subpatch example in the README file to use the trigger + object. The information that was written earlier that you had to + make connections in a certain order, was misinformation. The behaviour + is unspesified according to the spesification. The trigger object fix + such situations. (But if you need to use the trigger-object, its a good + sign that you should rather use k_cext for the operation anyway. My + opinion.) + -Removed the windows .dll file. If you are not able to compile up k_cext + yourself, you most probably aren't able to use k_cext either. + -Added a "print" message, which prints out the generated c-code with + line-numbers to the terminal. + -Prints out the generated c-code with linenumbers if compilation fails. + Makes debugging a lot faster. + -Added a SEND macro that takes a symbol string and a number, and sends + a pd message. + -Added "DO", which can (and should) be used instead of the BEGIN macro. + DO is not a macro, but a special symbol used by the k_cext + preprocessor to know when to automaticly insert BEGIN and + END based on indentation. Just like Python. :) + -Changed the main example patch to use DO instead of BEGIN/END. + -Added some more example patches. + -Fixed nearly correct indentation for the generated C code. + + 0.2.3 -> 0.2.4: + -Added a lot of new macros to k_cext.h. + -Fixed the help file a bit. + -Wrote the README file. + -Changed the license for k_cext.h from GPL to LGPL. + (Note, the k_cext external is still GPL) + -Some windows code was for some strange reason put + in the macosx file. Fixed. + -Added Mac OSX to the Makefile. (Not tested.) + + +CREDITS + k_cext is made by Kjetil S. Matheussen 2002/2003. + k.s.matheussen@notam02.no + + The windows-port is made by Olaf Matthes. + olaf.matthes@gmx.de + |