flext - C++ layer for Max/MSP and pd (pure data) externals Copyright (c) 2001,2002 Thomas Grill (xovo@gmx.net) For information on usage and redistribution, and for a DISCLAIMER OF ALL WARRANTIES, see the file, "license.txt," in this distribution. This package seeks to encourage the development of open source software for the pd and Max/MSP platforms. Donations for further development of the package are highly appreciated. ---------------------------------------------------------------------------- Package files: - readme.txt: this one - gpl.txt,license.txt: GPL license stuff - flext.h: main include file - flstdc.h: Basic definitions in classic C - some common vocabulary for the different platforms - flbase.h,flbase.cpp: C++ interface - flclass.h,flext.cpp: actual base classes for message (flext_base) and dsp (flext_dsp) processing - fldsp.h,fldsp.cpp: code for signal externals - flthr.h,flthr.cpp: code for threaded methods - flsupport.h,flsupport.cpp: various flext support functions and classes - flatom.cpp flatom_pr.cpp: code for functions dealing with lists of atoms - flutil.cpp: additional utility functions - flxlet.cpp: code for variable inlet/outlet stuff - flattr.cpp: code for attribute stuff - flinternals.h: internal definitions for flext library - flbuf.cpp: buffer object handling for base classes - fllib.cpp: code for handling external libraries in MaxMSP - fldefs.h: definitions for internal flext use - flcwmax.h: trivial prefix header file for Max/MSP CodeWarrior projects - flmspbuffer.h: MaxMSP's inofficial buffer.h included here for conveniance > for PD you need the pd source code (which is most likely part of the distribution) > for Max/MSP you will also need the Max/MSP SDK (and for threading the GUSI library) ---------------------------------------------------------------------------- The package should at least compile (and is tested) with the following compilers: pd - Windows: ------------- For any of these compilers define "PD" and "NT". o Microsoft Visual C++ 6: edit "config-pd-msvc.txt" & run "build-pd-msvc.bat" o Borland C++ 5.5 (free): edit "config-pd-bcc.txt" & run "build-pd-bcc.bat" o Cygwin: edit "config-pd-cygwin.txt" & run "sh build-pd-cygwin.sh" pd - linux: ----------- Be sure to define "PD". o GCC: edit "config-pd-linux.txt" & run "sh build-pd-linux.sh" pd - MacOSX: ----------- Be sure to define "PD". o GCC: edit "config-pd-darwin.txt" & run "sh build-pd-darwin.sh" Max/MSP - MacOS 9: ------------------ Be sure to define "MAXMSP". o Metrowerks CodeWarrior V6: edit & use the "flext.cw" project file Max/MSP - MacOSX: ------------------ ... sorry, not yet... would someone please donate me a CodeWarrior V8 ? ---------------------------------------------------------------------------- Goals/features of the package: pros: - better readability of code compared to straight C externals - faster development, more robust coding - sharing of common methods and data by using base classes - any input to any inlet (with the exception of signal streams) - transparent use of threads for methods - libraries of externals in MaxMSP - more than 3 typed creation arguments possible for MaxMSP cons: - introduces a small overhead to speed of message handling - overhead in object size (due to possibly unneeded code) see flext.h, fldefs.h and flclass.h for the documented base definitions and classes ---------------------------------------------------------------------------- Version history: 0.4.1: - fixed crash issue in flext_dsp when there are NO signal inlets or outlets defined (this is possibly only a problem for the signal2 tutorial example) - added flext::GetType(t_atom &) - added flext::ZeroMem 0.4.0: - the use of the const keyword is enforced (e.g. the preferred type for symbols is now "const t_symbol *") - there _might_ be some problems with sensitive compilers - introduced Max/Jitter-like attribute functionality ("@value" command line, "getvalue" get and "value" set functions) - introduced a flext static class for general flext functions (to clean up the flext_base class) - creation argument handling is now done by flext no more weird PD re-ordering of arguments - no more support for the Apple MPW compiler - MacOS9 is dying anyway... - calling SetupInOut() has become obsolete - flext creates all inlets/outlets by itself after the constructor has finished - this implies that CntIn(),CntOut() and the outlet pointers are not valid in the constructor - there is a virtual bool Init() function that may be used for such initialization - completely redesigned FLEXT_NEW macros, usage of dynamic classes (in fllib.cpp) - added ToQueue* functions - like ToOut* but messages or not directly sent (well suited for deadlock situations) - introduced additional per-class methods and attributes (just like it ever was in Max and PD) - fixed potentially dangerous typo in flext.cpp - (was: FLEXT_THREAD instead of FLEXT_THREADS) - added OSX/darwin support (originally done by Adam T. Lindsay) - SndObj interface now also available for cygwin and BCC - added prepend and append functions to AtomList class - added IsNothing, SetNothing, CanbeBool and GetABool functions - eliminated the remaining Get*Flint and Set*Flint functions - added/completed Is/Canbe/Get/Set for pointer atoms - added print/scan functions for atoms - fixed anything outlets for Max/MSP... for some strange reason this severe bug has not had severe consequences.... 0.3.3: - PD: fixed bug for DSP objects having no signal inlets this also enables floats into a non-signal leftmost inlet - revisited priority stuff for detached threads - Bind/unbind functions for flext classes (in MaxMSP only one object can be bound) - made "t_symtype" another synonym for "t_symbol *" - added forgotten dsp_free function for MaxMSP - fixed forgotten __class__ member for MaxMSP libraries - changed basic MaxMSP object to t_pxbox (ok, a bit more memory is used....) - MaxMSP library can now be loaded from startup folder (but can't use aliases) - if no handler is found for pure anything (just symbol, no args...) try list handler - added interface for SndObj (http://www.may.ie/academic/music/musictec/SndObj/ ) 0.3.2: - Doxygen generated inline documentation / functional reference - added some more functionality to the AtomAnything class - bugfix for threaded methods with var list or anything arguments - added threaded method for arbitrary (void *) data structs - ThrMutex: added lock count functions Push() and Pop() - eliminated potentially dangerous SetThing,GetThing and introduced DoBind,DoUnbind,GetBound instead - fixed severe bug with the current threads list - add path specification possibility for help symbols (in FLEXT_NEW*) - use pthread_attr and DETACHED flag 0.3.1: - added some more functionality to the AtomList class - fixed forgotten Sleep implementation in pd@unix - reorganized file structure and config/make procedures 0.3.0: - added CYGWIN support - added threaded methods along with a message queue for ToOut* functions (very unstable for MaxMSP!) to use threads compile flext with FLEXT_THREADS definition - check/update function for buffer change (resize etc.) - description text for inlets/outlets (e.g. for MaxMSPs assist function) - not fully implemented - added buffer resize functions flext_base::buffer::Frames(int,bool) - added some utility functions: Sleep, CopyAtom, CopyList - added List manipulation classes: AtomList, AtomAnything - Alias object names (simply specify with FLEXT_NEW*, separated by whitespace) - float messages - int method is called if there is no float method - MaxMSP: int messages - float method is called if there is no int method - fixed type warning for class constructors with int arguments in PD - fixed severe bug concerning symbol methods - MaxMSP: use critical sections for message output (for more safety in overdrive mode) - PD: default/manual definition of help file by flext_base::DefineHelp - added GetThing/SetThing to access t_symbol's s_thing data member - introduced FLEXT_NEW_DSP* and FLEXT_LIB_DSP* for FLEXT_NEW_TILDE* and FLEXT_LIB_TILDE* (the latter become deprecated) - all variable argument defs (aka gimme) now have a V instead of G (e.g. FLEXT_NEW_V) 0.2.3: - restructured files and started usable inline documentation - found that there was no method to output a bang?! Ugh! -> corrected - finally eliminated awful t_flint type and all other schizophrenic flint functions (float and int exist now equally) - now (finally) using type t_sample for sample values (should just be identical to float) - added AddInBang/AddOutBang (same as Add*Symbol - unchecked) - buffer class: added "bool Ok()" check function - switched on error posting for unhandled messages - added XletCode and AddInlets/AddOutlets for multiple Inlet/Outlet addition (max. 9 inlets/outlets) - if float or int message is not handled explicitly then [list float/int( is tried 0.2.2: - added xgimme argument type (supplies method handlers with symbol+gimme) - more information on DSP system with flext_dsp object (block size,number of audio inputs and outputs) - cleaner gcc makefile - made NewAligned/FreeAligned static functions - introduced FLEXT(_TILDE)_SETUP for class setup in a library setup function - introduced external libraries for MaxMSP, changed library setup behavior (now via FLEXT_LIB_SETUP) - included MaxMsp's inofficial buffer.h with consent by David Zicarelli - changed dynamic casts in callback functions to static as gcc 3.0.4 has obvious bugs 0.2.1: - fixed bug in message parsing code (anything messages were not correctly mapped to inlets) - changed t_symtype to t_symptr (= t_symbol *), needed for method argument lists - eliminated flint type (t_flint remains) 0.2.0: - internal proxy objects for any non-leftmost inlets - Max/MSP: all signal inlets can receive messages - method/argument parsing is done by flext - float/int are not distinguished, the first handler wins - integrated more system functions into flext_base & eliminated superfluous #defines - distribute list (into inlet 0) elements over inlets (right to left) - added outlets for anythings - defines for callback-to-method functions and method setup (FLEXT_CALLBACK*, FLEXT_ADD*) - uses PD's or Max's memory allocation functions (for safety in Max's overdrive) - no support for default arguments (A_DEFFLOAT and A_DEFSYMBOL).. use GIMME instead! - better graphics update behavior for PD - improved behavior for invalid/undefined buffers/arrays - use MaxMSP internal z_disabled flag with flext_dsp for pausing/resuming dsp processing - included CHECK_TILDE, a test whether a tilde object (defined as FLEXT_TILDE_*) has a trailing ~. (debug mode only) - changed notation of flext functions from to_out_float like to ToOutFloat like - eliminated trivial shortcuts (F,I,V,...) for built-in types - MaxMSP is only capable of 3 creation arguments... that should be sufficient - otherwise use GIMME - Methods for aligned memory (NewAligned, FreeAligned) 0.1.1: - documentation for flext.h - more emancipation from GEM code - virtually everything renamed - abstraction for dsp processing - makefile for BCC - manual call of extern_setup or main unnecessary for single objects - only in pd libraries - delayed buffer init (only name is set beforehand) - loadbang also in PD - introduced "compatibility mode" which denies platform-specific features - fixed severe dsp bug (symptom: "float method overwritten" warning in pd) - fixed bug: wrong return code from buffer::Set 0.1.0: - max-pd 0.2 becomes flext 0.1.0 - heavy usage of unchanged GEM code ---------------------------------------------------------------------------- Notes: - no support for default object arguments (A_DEFFLOAT, A_DEFSYMBOL) -> use variable argument lists instead Platform specific: - PD does not allow signal and message to go into the same inlet Restrictions in compatibility mode: - Max allows only 9 float/int inlets Porting to new compilers/platforms: - enums must be int-sized - compiler must support bool type - no need of C++ exceptions or RTTI (RTTI only for GUI objects) ---------------------------------------------------------------------------- TODO list: general: - documentation - add log messages for debugging version - where to put flext source/lib in linux: /usr/local/lib,/usr/local/include ? - clean up headers (eliminate flstdc.h?) - check that SetupInOut is only called once - feed assist function with in/outlet description - MaxMSP: how to call separate help files for objects in a library? - MaxMSP for OSX: add support bugs: - PD: problems with timed buffer redrawing (takes a lot of cpu time) - hard thread termination upon object destruction doesn't seem to work properly -> crash - Max rounding bug ... buffer resize could be one sample less! - flext_dsp: Max/MSP doesn't correctly report in/out channel counts tests: - PD: figure out what "pointer" messages do and where they occur - some more mutexes needed for thread safety? - buffer resize: flext_base::buffer::Frames(): should we use buffer or system sample rate? - what about FLEXT_ADDMETHOD_V (for var arg lists) and FLEXT_ADDMETHOD_A (anythings)... nonsense? - queued messages... triggering timer should not be necessary for MaxMSP qmsg features: - abstraction for clock functions - manage running threads individually (stop, isrunning?, priority etc.) premature thoughts: - GUI objects