fldoxygen.h 6.72 KB
Newer Older
thomas's avatar
thomas committed
1
2
3
#ifndef __FLEXT_DOXYGEN_H
#define __FLEXT_DOXYGEN_H

thomas's avatar
thomas committed
4
5
6
7
8
/*! \file fldoxygen.h
	\brief Doxygen definitions
	\remark There is no code in here, just documentation stuff.
*/

thomas's avatar
thomas committed
9
/*! 
thomas's avatar
thomas committed
10

thomas's avatar
thomas committed
11
\mainpage flext - a C++ layer for cross-platform development of PD and Max/MSP objects
thomas's avatar
thomas committed
12

thomas's avatar
thomas committed
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
\section INTRO Introduction

Currently there exist two widely used modular systems for real-time audio that can be
extended by self-written objects (so called "externals"):<br>
Max/MSP (http://www.cycling74.com) and Pure Data (http://www.pure-data.org).

Both come with APIs that are not very different, but as well not quite the same.
Flext seeks to provide a unifying interface for the APIs of those real-time systems while also
concentrating on making use of the advantages of the object orientation of the C++ language.

Consequently, flext allows to write externals (or libraries of a number of these), that can
be compiled for both systems (with various compilers on a few platforms) without changes to the
source code.

The advantages of flext are:
<ul>
<li>Identical source code for PD and Max/MSP objects on a number of platforms
<li>Better readability of code compared to straight C externals
<li>Faster development, more robust coding
<li>Sharing of common methods and data by using base classes
<li>Transparent use of threads for methods
<li>Libraries of externals in Max/MSP
<li>More than 3 typed creation arguments possible for Max/MSP
<li>Any input to any object's inlet (with the exception of signal streams)
</ul>

Naturally there are some cons, too:
<ul>
<li>Introduces a small overhead to speed of message handling 
<li>Overhead in object size (due to possibly unneeded library code)
</ul>

Currently, flext supports 
<ul>
<li>PD on Windows with Microsoft Visual C++, Borland C++ and gcc(cygwin) compilers
<li>PD on Linux with gcc
<li>PD on Mac OSX with gcc (Project Builder to follow soon)
thomas's avatar
thomas committed
50
<li>Max/MSP on Mac OS9 with Metrowerks CodeWarrior
thomas's avatar
thomas committed
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
</ul>

\section LICENSE License

Flext is covered by the GPL.

flext - C++ layer for Max/MSP and pd (pure data) externals<BR>
Copyright (C) 2001,2002 Thomas Grill

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.<BR>
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.<BR>
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

In the official flext distribution, the GNU General Public License is
in the file gpl.txt<BR> Also see the file license.txt for notes on 
referenced works and their license texts.

\section DOWNLOAD Download 

Download the latest flext version from http://www.parasitaere-kapazitaeten.net/ext/flext .<br>
Alternatively, you can check out the cvs version from http://sourceforge.net/projects/pure-data .

\section USAGE Usage

As a developer, you should know the C++ language, how to use a makefile 
and how to steer your compiler.<br>
So let's come to the point... how does a typical flext object look like?

This is the object "attr1", one of the flext tutorial examples:

\verbatim
// enable attribute processing
#define FLEXT_ATTRIBUTES 1

// include flext header
#include <flext.h>

// check for appropriate flext version
#if !defined(FLEXT_VERSION) || (FLEXT_VERSION < 400)
#error You need at least flext version 0.4.0
#endif
\endverbatim

With these lines, all the necessary definitions from the flext package have been included.

\verbatim
class attr1:
	public flext_base
{
	FLEXT_HEADER(attr1,flext_base)
\endverbatim

A flext class is simply defined by inheriting from the flext_base (see also \ref FLEXT_CLASS) 
or flext_dsp (see also \ref FLEXT_DSP) classes.
Additionally some information has to be added using FLEXT_HEADER (see \ref FLEXT_D_HEADER)

\verbatim
public:
	// constructor 
	attr1();
\endverbatim

Normally the constructor takes the creation arguments of an object. Here there are none.

\verbatim
protected:
	void m_trigger(float f);   
	
	// stored argument
	float arg; 
\endverbatim

These are methods and data elements for internal class usage. Flext doesn't know about them
as long as they are not registered.

\verbatim
private:
	// callback for method "m_trigger" (with one float argument)
	FLEXT_CALLBACK_F(m_trigger);  

	// define attribute callbacks for variable "arg" (with GET and SET properties)
	FLEXT_ATTRVAR_F(arg);  
};
\endverbatim

For each method that shall be exposed to the realtime-system (for receiving messages) and 
every attribute (for setting and getting values) callbacks have to be set up.
The functions in the groups "\ref FLEXT_D_CALLBACK" and "\ref FLEXT_D_ATTRIB" allow for their 
convenient definition.

\verbatim
// instantiate the class 
FLEXT_NEW("attr1",attr1)
\endverbatim

With FLEXT_NEW the class is instantiated and registered for the real-time system.
The number of creation arguments and their types must be taken into account here.
There are several variants depending on whether a message oriented (see \ref FLEXT_D_NEW)
or a DSP object (see \ref FLEXT_D_NEW_DSP) is created and whether it resides in a object library
(see \ref FLEXT_D_LIB and \ref FLEXT_D_LIB_DSP).<BR>

\verbatim
attr1::attr1():
	arg(0)  // initialize argument 
{ 
	// define inlets
	AddInAnything();  // first inlet of type anything (index 0)
	
	// define outlets
	AddOutFloat();  // one float outlet (has index 0)
\endverbatim
	
Every inlet and outlet that the object shall have has to be registered.
This is done with the functions in \ref FLEXT_C_IO_ADD.

\verbatim
	// register methods
	FLEXT_ADDMETHOD(0,m_trigger);  // register method (for floats) "m_trigger" for inlet 0

	FLEXT_ADDATTR_VAR1("arg",arg);  // register attribute "arg" with variable arg
} 
\endverbatim

Likewise, every method (called by a message) (see \ref FLEXT_D_ADDMETHOD) and every
attribute (see \ref FLEXT_D_ADDATTR) exposed to the system has to be registered.

\verbatim
void attr1::m_trigger(float f)
{
	float res = arg+f;
	
	// output value to outlet
	ToOutFloat(0,res); // (0 stands for the outlet index 0)
}
\endverbatim

This is a method that is triggered with a message. It does some calculation and then outputs
a value to an outlet. There are numerous functions (see \ref FLEXT_C_IO_OUT) supporting 
that functionality. 

Be sure to work through the examples provided with the flext tutorial. These should give you
an overview about the possibilities of flext.
The "\ref modules" link at the top of the page leads to a complete reference
of flext functions and classes.
thomas's avatar
thomas committed
203
204
205
206

*/

#endif