aboutsummaryrefslogtreecommitdiff
path: root/externals/grill/flext/readme.txt
blob: 3bd1594e5f478b9249e687fb8c8259be8522db95 (plain)
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
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
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 &), flext::ZeroMem
- put the clock_delay for the message queue inside the thread-locked area
	Ok for the actual object, but PD has to be thread-safe here as well
- BACKWARDS-INCOMPATIBLE CHANGE: flext_base::m_methodmain and flext_base::m_method_ have got 
	const modifiers.... these virtual methods are used rarely (except for example in py/pyext)
- now MUCH cleaner platform identification... FLEXT_SYS,FLEXT_OS,FLEXT_CPU definitions
- also FLEXT_DEBUG for debug build
- SndObjs: virtual FreeObject routine is now called at destruction (by parent class), derived class doesn't need to call it!
- SndObjs: fixed typo (numbers of output slots was wrong) and init bug

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