HOWTO

write an External
for puredata

johannes m zmölnig

institut for electronic music and acoustics

 Zusammenfassung

pd is a graphical realtime-computermusicsystem that follows the tradition of

IRCAMs ISPW-max.
Although plenty of functions are built into pd, it is sometimes a pain or
simply impossible to create a patch with a certain functionality out of the
given primitives and combinations of these.
Therefore, pd can be extended with selfmade primitives (objects) that
are written in complex programming-languages, like C/C++.
This document aims to explain, how to write such primitives in C, the
popular language that was used to realize pd.
Inhaltsverzeichnis

1 denitions and prerequisites 2

1.1 classes, instances, objects . . . . . . . . . . . . . . . . . . . . . 2
1.2 internals, externals und libraries . . . . . . . . . . . . . . . . . 2

2 my rst external: helloworld 3

2.1 the interface to pd . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 a class and its dataspace . . . . . . . . . . . . . . . . . . . . . 4
2.3 methodspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4 generation of a new class . . . . . . . . . . . . . . . . . . . . . 5
2.5 constructor: instantiation of an object . . . . . . . . . . . . . 6
2.6 the code: helloworld . . . . . . . . . . . . . . . . . . . . . . 7

3 a simple external: counter 7

3.1 object-variables . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2 object-arguments . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.3 constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.4 the countermethod . . . . . . . . . . . . . . . . . . . . . . . . 9
3.5 the code: counter . . . . . . . . . . . . . . . . . . . . . . . . 10

4 a complex external: counter 11

4.1 extended dataspace . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2 extension of the class . . . . . . . . . . . . . . . . . . . . . . . 11
4.3 construction of in- and outlets . . . . . . . . . . . . . . . . . . 12
4.4 extended methodspace . . . . . . . . . . . . . . . . . . . . . . 14
4.5 the code: counter . . . . . . . . . . . . . . . . . . . . . . . . 15

5 a signal-external: pan 18
5.1 variables of a signalclass . . . . . . . . . . . . . . . . . . . . . 18
5.2 signal-classes . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.3 construction of signal-inlets and -outlets . . . . . . . . . . . . 19
5.4 DSP-methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.5 perform-routine . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.6 the code: pan . . . . . . . . . . . . . . . . . . . . . . . . . . 21

A pd's message-system 23
A.1 atoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
A.2 selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

B pd-types 24

1
C important functions in m_pd.h 25
C.1 functions: atoms . . . . . . . . . . . . . . . . . . . . . . . . . 25
C.1.1 SETFLOAT . . . . . . . . . . . . . . . . . . . . . . . . 25
C.1.2 SETSYMBOL . . . . . . . . . . . . . . . . . . . . . . . 25
C.1.3 SETPOINTER . . . . . . . . . . . . . . . . . . . . . . 25
C.1.4 atom_getoat . . . . . . . . . . . . . . . . . . . . . . . 25
C.1.5 atom_getoatarg . . . . . . . . . . . . . . . . . . . . . 25
C.1.6 atom_getint . . . . . . . . . . . . . . . . . . . . . . . . 25
C.1.7 atom_getsymbol . . . . . . . . . . . . . . . . . . . . . 26
C.1.8 atom_gensym . . . . . . . . . . . . . . . . . . . . . . . 26
C.1.9 atom_string . . . . . . . . . . . . . . . . . . . . . . . . 26
C.1.10 gensym . . . . . . . . . . . . . . . . . . . . . . . . . . 26
C.2 functions: classes . . . . . . . . . . . . . . . . . . . . . . . . . 26
C.2.1 class_new . . . . . . . . . . . . . . . . . . . . . . . . . 26
C.2.2 class_addmethod . . . . . . . . . . . . . . . . . . . . . 27
C.2.3 class_addbang . . . . . . . . . . . . . . . . . . . . . . 27
C.2.4 class_addoat . . . . . . . . . . . . . . . . . . . . . . . 28
C.2.5 class_addsymbol . . . . . . . . . . . . . . . . . . . . . 28
C.2.6 class_addpointer . . . . . . . . . . . . . . . . . . . . . 28
C.2.7 class_addlist . . . . . . . . . . . . . . . . . . . . . . . 28
C.2.8 class_addanything . . . . . . . . . . . . . . . . . . . . 29
C.2.9 class_addcreator . . . . . . . . . . . . . . . . . . . . . 29
C.2.10 class_sethelpsymbol . . . . . . . . . . . . . . . . . . . 29
C.2.11 pd_new . . . . . . . . . . . . . . . . . . . . . . . . . . 29
C.3 functions: inlets and outlets . . . . . . . . . . . . . . . . . . . 30
C.3.1 inlet_new . . . . . . . . . . . . . . . . . . . . . . . . . 30
C.3.2 oatinlet_new . . . . . . . . . . . . . . . . . . . . . . . 30
C.3.3 symbolinlet_new . . . . . . . . . . . . . . . . . . . . . 31
C.3.4 pointerinlet_new . . . . . . . . . . . . . . . . . . . . . 31
C.3.5 outlet_new . . . . . . . . . . . . . . . . . . . . . . . . 31
C.3.6 outlet_bang . . . . . . . . . . . . . . . . . . . . . . . . 32
C.3.7 outlet_oat . . . . . . . . . . . . . . . . . . . . . . . . 32
C.3.8 outlet_symbol . . . . . . . . . . . . . . . . . . . . . . 32
C.3.9 outlet_pointer . . . . . . . . . . . . . . . . . . . . . . 32
C.3.10 outlet_list . . . . . . . . . . . . . . . . . . . . . . . . . 32
C.3.11 outlet_anything . . . . . . . . . . . . . . . . . . . . . . 32
C.4 functions: DSP . . . . . . . . . . . . . . . . . . . . . . . . . . 33
C.4.1 CLASS_MAINSIGNALIN . . . . . . . . . . . . . . . . 34
C.4.2 dsp_add . . . . . . . . . . . . . . . . . . . . . . . . . . 34
C.4.3 sys_getsr . . . . . . . . . . . . . . . . . . . . . . . . . 34
C.5 functions: memory . . . . . . . . . . . . . . . . . . . . . . . . 34

2
 C.5.1 getbytes . . . . . . . . . . . . . . . . . . . . . . . . . . 34
C.5.2 copybytes . . . . . . . . . . . . . . . . . . . . . . . . . 34
C.5.3 freebytes . . . . . . . . . . . . . . . . . . . . . . . . . . 35
C.6 functions: output . . . . . . . . . . . . . . . . . . . . . . . . . 35
C.6.1 post . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
C.6.2 error . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

3
1 denitions and prerequisites

pd refers to the graphical realtime-computermusicprogramme puredata by

Miller S. Puckette.
To fully understand this document, it is necessary to be acquainted with
pd and to have a general understanding of programming techniques especially
in C.
To write externals yourself, a C-compiler that supports the ANSI-C-Standard,
like the Gnu C-compiler (gcc) on linux-systems or Visual-C++ 6.0 (vc6) on
windos-plattforms, will be necessary.

1.1 classes, instances, objects

pd is written in the programming-language C. Due to its graphical nature, pd

ist a object-oriented system. Unfortunately C does not support very well the
use of classes. Thus the resulting source-code is not as elegant as C++-code
would be, for instance.
In this document, the expression class refers to the realisation of a concept
combining data and manipulators on this data.
Concrete instances of a class are called objects.

1.2 internals, externals und libraries

To avoid confusion of ideas, the expressions internal, external and library

should be explained here.

Internal An internal is a class that is built into pd. Plenty of primitives,

such as +, pack or sig are internals.

External An external is a class that is not built into pd but is loaded at

runtime. Once loaded into pd's memory, externals cannot be distinguished
from internals any more.

Library A library is a collection of externals that are compiled into a single

binary-le.
Library-les have to follow a systemdependent naming convention:
library linux irix Win32
my_lib my_lib.pd_linux my_lib.pd_irix my_lib.dll
The simplest form of a library includes exactly one external bearing the
same name as the library.

4
 Unlike externals, libraries can be imported by pd with special operations.
After a library has been imported, all included externals have been loaded
into memory and are available as objects.
pd supports to modes to import libraries:

• via the commandline-option  -lib my_lib

• by creating an object  my_lib

The rst method loads a library when pd is started. This method is

preferably used for libraries that contain several externals.
The other method should be used for libraries that contain exactly one
external bearing the same name. pd checks rst, whether a class named
my_lib is already loaded. If this is not the case1 , all paths are searched for
a le called  my_lib.pd_linux 2 . If such le is found, all included externals
are loaded into memory by calling a routine my_lib_setup(). After loading,
a class my_lib is (again) looked for as a (newly loaded) external. If so, an
instance of this class is created, else the instantiation fails and an error is
printed. Anyhow, all external-classes declared in the library are loaded by
now.

2 my rst external: helloworld

Usually the rst attempt learning a programming-language is a hello world-
application.
In our case, an objectclass should be created, that prints the line hello
world!! to the standarderror everytime it is triggered witha bang-message.

2.1 the interface to pd

To write a pd-external a well-dened interface is needed. This is provided in

the header-le m_pd.h.

#include "m_pd.h"
1 If a class my_lib is already existent, an object my_lib will be instantiated and the
procedure is done. Thus, no library has been loaded. Therefore no library that is named
like an already used class-name like, say, abs, can be loaded.
2 or another system-dependent lename-extensions (s.a.)

5
2.2 a class and its dataspace

First a new class has to be prepared and the dataspace for this class has to
be dened.

static t_class *helloworld_class;

typedef struct _helloworld {

t_object x_obj;
} t_helloworld;

hello_worldclass is going to be a pointer to the new class.

The structure t_helloworld (of the type _helloworld) is the dataspace
of the class.
An absolutely necessary element of the dataspace is a variable of the type
t_object, which is used to store internal object-properties like the graphical
presentation of the object or data about inlets and outlets.
t_object has to be the rst entry in the structure !
Because a simple hello world-application needs no variables, the struc-
ture is empty apart from the t_object.

2.3 methodspace

Apart from the dataspace, a class needs a set of manipulators (methods) to

manipulate the data with.
If a message is sent to an instance of our class, a method is called. These
methods are the interfaces to the messagesystem of pd. On principal they
have no return argument and are therefore are of the type void.

void helloworld_bang(t_helloworld *x)

{
post("Hello world !!");
}

This method has an argument of the type t_helloworld, which would

enable us to manipulate the dataspace.
Since we only want to output Hello world! (and, by the way, our datas-
pace is quite sparse), we renounce a manipulation.
The command post(char *c,...) sends a string to the standarderror. A
carriage return is added automatically. Apart from this, the post-command
works like the C-command printf().

6
2.4 generation of a new class

To generate a new class, information of the dataspace and the methodspace

of this class, have to be passed to pd when a library is loaded.
On loading a new library my_lib, pd tries to call a function my_lib_setup().
This function (or functions called by it) declares the new classes and their
properties. It is only called once, when the library is loaded. If the function-
call fails (e.g., because no functionn of the specied name is present) no
external of the library will be loaded.

void helloworld_setup(void)
{
helloworld_class = class_new(gensym("helloworld"),
(t_newmethod)helloworld_new,
0, sizeof(t_helloworld),
CLASS_DEFAULT, 0);

class_addbang(helloworld_class, helloworld_bang);
}

class_new The function class_new creates a new class and returns a poin-
ter to this prototype.
The rst argument is the symbolic name of the class.
Das erste Argument ist der symbolische Name der Klasse.
The next two arguments dene the constructor and dstructor of the class.
Whenever a classobject is created in a pd-patch, the class-constructor
(t_newmethod)helloworld_new instantiates the object and initializes the
dataspace.
Whenever an object is destroyed (either by closing the containing patch
or by deleting the object from the patch) the destructor frees the dynami-
cally reserved memory. The allocated memory for the static dataspace is
automatically reserved and freed.
Therefore we do not have to provide a destructor in this example, the
argument is set to 0.
To enable pd to reserve and free enough memory for the static dataspace,
the size of the datastructure has to be passed as the fourth argument.
The fth argument has inuence on the graphical representaion of the
classobjects. The default-value is CLASS_DEFAULT or simply 0.
The remaining arguments dene the arguments of an object and its type.
Up to six numeric and symbolic object-arguments can be dened via
A_DEFFLOAT and A_DEFSYMBOL. If more arguments are to be passed to the

7
object or if the order of atomtypes should by more exible, A_GIMME can be
used for passing an arbitrary list of atoms.
The list of object-arguments is terminated by 0. In this example we
have no object-arguments at all for the class.

class_addbang We still have to add a methodspace to the class.

class_addbang adds a method for a bang-message to the class that is
dened in the rst argument. The added method is dened in the second
argument.

2.5 constructor: instantiation of an object

Each time, an object is created in a pd-patch, the constructor that is dened

with the class_new-command, generates a new instance of the class.
The constructor has to be of type void *.

void *helloworld_new(void)
{
t_helloworld *x = (t_helloworld *)pd_new(helloworld_class);

return (void *)x;

}

The arguments of the constructor-method depend on the object-arguments

dened with class_new.
class_new-argument constructor-argument
A_DEFFLOAT t_floatarg f
A_DEFSYMBOL t_symbol *s
A_GIMME t_symbol *s, int argc, t_atom *argv
Because there are no object-arguments for our hello world-class, the
constructor has anon too.
The function pd_new reserves memory for the dataspace, initializes the
variables that are internal to the object and returns a pointer to the datas-
pace.
The type-cast to the dataspace is necessary.
Normally, the constructor would initialize the object-variables. However,
since we have none, this is not necessary.
The constructor has to return a pointer to the instantiated dataspace.

8
2.6 the code: helloworld
#include "m_pd.h"

static t_class *helloworld_class;

typedef struct _helloworld {

t_object x_obj;
} t_helloworld;

void helloworld_bang(t_helloworld *x)

{
post("Hello world !!");
}

void *helloworld_new(void)
{
t_helloworld *x = (t_helloworld *)pd_new(helloworld_class);

return (void *)x;

}

void helloworld_setup(void) {
helloworld_class = class_new(gensym("helloworld"),
(t_newmethod)helloworld_new,
0, sizeof(t_helloworld),
CLASS_DEFAULT, 0);
class_addbang(helloworld_class, helloworld_bang);
}

3 a simple external: counter

Now we want to realize a simple counter as an external. A bang-trigger
outputs the counter-value on the outlet and afterwards increases the counter-
value by 1.
This class is similar to the previous one, but the dataspace is extended
by a variable counter and the result is written as a message to an outlet
instead of a string to the standarderror.

9
3.1 object-variables

Of course, a counter needs a state-variable to store the actual counter-value.

State-variables that belong to classinstances belong to the dataspace.

typedef struct _counter {

t_object x_obj;
t_int i_count;
} t_counter;

The integer variable i_count stores the counter-value.

3.2 object-arguments

It is quite usefull for a counter, if a initial value can be dened by the user.
Therefore this initial value should be passed to the object at creation-time.

void counter_setup(void) {
counter_class = class_new(gensym("counter"),
(t_newmethod)counter_new,
0, sizeof(t_counter),
CLASS_DEFAULT,
A_DEFFLOAT, 0);

class_addbang(counter_class, counter_bang);
}

So we have an additional argument in the function class_new: A_DEFFLOAT

tells pd, that the object needs one argument of the type t_floatarg. If no
argument is passed, this will default to 0.

3.3 constructor

The constructor has some new tasks. On the one hand, a variable value has
to be initialized, on the other hand, an outlet for the object has to be created.

void *counter_new(t_floatarg f)
{
t_counter *x = (t_counter *)pd_new(counter_class);

x->i_count=f;
outlet_new(&x->x_obj, &s_float);

10
 return (void *)x;
}
The constructor-method has one argument of type t_floatarg as decla-
red in the setup-routine by class_new. This argument is used to initialize
the counter.
A new outlet is created with the function outlet_new. The rst argument
is a pointer to the interna of the object the new outlet is created for.
The second argument is a symbolic description of the outlet-type. Since
out counter should output numeric values it is of type oat.
outlet_new returns a pointer to the new outlet and saves this very pointer
in the t_object-variable x_obj.ob_outlet. If only one outlet is used, the
pointer need not additionally be stored in the dataspace. If more than one
outlets are used, the pointers have to be stored in the dataspace, because the
t_object-variable can only hold one outletpointer.

3.4 the countermethod

When triggered, the countervalue should be sent to the outlet and afterwards
be incremented by 1.
void counter_bang(t_counter *x)
{
t_float f=x->i_count;
x->i_count++;
outlet_float(x->x_obj.ob_outlet, f);
}
The function outlet_float sends a oating-point-value (second argu-
ment) to the outlet that is specied by the rst argument.
We rst store the counter in a oatingpoint-buer. Afterwards the coun-
ter is incremented and not before that the buervariable is sent to the outlet.
What appears to be unnecessary on the rst glance, makes sense after
further inspection: The buervariable has been realized as t_float, since
outlet_float expects a oatingpoint-value and a typecast is inevitable.
If the countervalue was sent to the outlet before being incremented, this
could result in an unwanted (though welldened) behaviour: If the counter-
outlet directly triggered its own inlet, the counter-method would be called
although the countervalue was not yet incremented. Normally this is not
what we want.
The same (correct) result could of course be obtained with a single line,
but this would obscure the reentrant-problem.

11
3.5 the code: counter
#include "m_pd.h"

static t_class *counter_class;

typedef struct _counter {

t_object x_obj;
t_int i_count;
} t_counter;

void counter_bang(t_counter *x)

{
t_float f=x->i_count;
x->i_count++;
outlet_float(x->x_obj.ob_outlet, f);
}

void *counter_new(t_floatarg f)
{
t_counter *x = (t_counter *)pd_new(counter_class);

x->i_count=f;
outlet_new(&x->x_obj, &s_float);

return (void *)x;

}

void counter_setup(void) {
counter_class = class_new(gensym("counter"),
(t_newmethod)counter_new,
0, sizeof(t_counter),
CLASS_DEFAULT,
A_DEFFLOAT, 0);

class_addbang(counter_class, counter_bang);
}

12
4 a complex external: counter
The simple counter of the previous chapter can easily be extended to more
complexity. It might be quite usefull to be able to reset the counter to an
initial value, to set upper and lower boudaries and to control the step-width.
Each overrun should send a bang-Message to a second outlet and reset the
counter to the initial value.

4.1 extended dataspace

typedef struct _counter {

t_object x_obj;
t_int i_count;
t_float step;
t_int i_down, i_up;
t_outlet *f_out, *b_out;
} t_counter;

The dataspace has been extended to hold variables for stepwidth and
upper and lower boundaries. Furthermore pointers for two outlets have been
added.

4.2 extension of the class

The new classobjects should have methods for dierent messages, like set
and reset. Therefore the methodspace has to be extended too.

counter_class = class_new(gensym("counter"),
(t_newmethod)counter_new,
0, sizeof(t_counter),
CLASS_DEFAULT,
A_GIMME, 0);

The classgenerator class_new has been extended by the argument A_GIMME.

This enables a dynamic number of arguments to be passed at the instantia-
tion of the object.

class_addmethod(counter_class,
(t_method)counter_reset,
gensym("reset"), 0);

13
 class_addmethod adds a method for an arbitrary selector to an class.
The rst argument is the class the method (second argument) will be
added to.
The third argument is the symbolic selector that should be associated
with the method.
The remaining 0-terminated arguments describe the list of atoms that
follows the selector.

class_addmethod(counter_class,
(t_method)counter_set, gensym("set"),
A_DEFFLOAT, 0);
class_addmethod(counter_class,
(t_method)counter_bound, gensym("bound"),
A_DEFFLOAT, A_DEFFLOAT, 0);

A method for set followed by a numerical value is added, as well as a

method for the selector bound followed by two numerical values.

class_sethelpsymbol(counter_class, gensym("help-counter"));

If a pd-object is right-clicked, a help-patch describing the object-class can

be opened. By default, this patch is located in the directory  doc/5.reference/
and is named like the symbolic classname.
An alternative help-patch can be dened with the class_sethelpsymbol-
command.

4.3 construction of in- and outlets

When creating the object, several arguments should be passed by the user.

void *counter_new(t_symbol *s, int argc, t_atom *argv)

Because of the declaration of arguments in the class_new-function with

A_GIMME, the constructor has following arguments:
t_symbol *s the symbolic name,
that was used for object creation
int argc the numer of arguments passed to the object
t_atom *argv a pointer to a list of argc atoms

t_float f1=0, f2=0;

x->step=1;

14
 switch(argc){
default:
case 3:
x->step=atom_getfloat(argv+2);
case 2:
f2=atom_getfloat(argv+1);
case 1:
f1=atom_getfloat(argv);
break;
case 0:
}
if (argc<2)f2=f1;
x->i_down = (f1<f2)?f1:f2;
x->i_up = (f1>f2)?f1:f2;

x->i_count=x->i_down;

If three arguments are passed, these should be the lower boundary, the
upper boundary and the step width.
If only two arguments are passed, the step-width defaults to 1. If only
one argument is passed, this should be the initial value of the counter with
step-width of 1.

inlet_new(&x->x_obj, &x->x_obj.ob_pd,
gensym("list"), gensym("bound"));

The function inlet_new creates a new active inlet. Active means,

that a class-method is called each time a message is sent to an active inlet.
Due to the software-architecture, the rst inlet is always active.
The rst two arguments of the inlet_new-function are pointers to the
interna of the object and to the graphical presentation of the object.
The symbolic selector that is specied by the third argument is to be
substituted by another symbolic selector (fourth argument) for this inlet.
Because of this substitution of selectors, a message on a certain right inlet
can be treated as a message with a certain selector on the leftmost inlet.
This means:

• The substituting selector has to be declared by class_addmethod in

the setup-routine.

• It is possible to simulate a certain right inlet, by sending a message

with this inlet's selector to the leftmost inlet.

15
 • It is not possible to add methods for more than one selector to a right
inlet. Particularly it is not possible to add a universal method for
arbitrary selectors to a right inlet.

floatinlet_new(&x->x_obj, &x->step);

floatinlet_new generates a new passive inlet for numerical values. Pas-

sive inlets allow parts of the dataspace-memory to be written directly from
outside. Therefore it is not possible to check for illegal inputs.
The rst argument is a pointer to the internal infrastructure of the object.
The second argument is the address in the dataspace-memory, where other
objects can write too.
Passive inlets can be created for pointers, symbolic or numerical (oa-
tingpoint3 ) values.

x->f_out = outlet_new(&x->x_obj, &s_float);

x->b_out = outlet_new(&x->x_obj, &s_bang);

The pointers returned by outlet_new have to be saved in the classdataspace

to be used later by the outlet-routines.
The order of the generation of inlets and outlets is important, since it
corresponds to the order of inlets and outlets in the graphical representation
of the object.

4.4 extended methodspace

The method for the bang-message has to fullll the more complex tasks.

void counter_bang(t_counter *x)

{
t_float f=x->i_count;
t_int step = x->step;
x->i_count+=step;
if (x->i_down-x->i_up) {
if ((step>0) && (x->i_count > x->i_up)) {
x->i_count = x->i_down;
outlet_bang(x->b_out);
} else if (x->i_count < x->i_down) {
x->i_count = x->i_up;
outlet_bang(x->b_out);
3 That's why the step-width of the classdataspace is realized as t_float.

16
 }
}
outlet_float(x->f_out, f);
}

Each outlet is identied by the outlet_...-functions via the pointer to

this outlets.
The remaining methods still have to be implemented:

void counter_reset(t_counter *x)

{
x->i_count = x->i_down;
}

void counter_set(t_counter *x, t_floatarg f)

{
x->i_count = f;
}

void counter_bound(t_counter *x, t_floatarg f1, t_floatarg f2)

{
x->i_down = (f1<f2)?f1:f2;
x->i_up = (f1>f2)?f1:f2;
}

4.5 the code: counter

#include "m_pd.h"

static t_class *counter_class;

typedef struct _counter {

t_object x_obj;
t_int i_count;
t_float step;
t_int i_down, i_up;
t_outlet *f_out, *b_out;
} t_counter;

void counter_bang(t_counter *x)

{

17
 t_float f=x->i_count;
t_int step = x->step;
x->i_count+=step;

if (x->i_down-x->i_up) {
if ((step>0) && (x->i_count > x->i_up)) {
x->i_count = x->i_down;
outlet_bang(x->b_out);
} else if (x->i_count < x->i_down) {
x->i_count = x->i_up;
outlet_bang(x->b_out);
}
}

outlet_float(x->f_out, f);
}

void counter_reset(t_counter *x)

{
x->i_count = x->i_down;
}

void counter_set(t_counter *x, t_floatarg f)

{
x->i_count = f;
}

void counter_bound(t_counter *x, t_floatarg f1, t_floatarg f2)

{
x->i_down = (f1<f2)?f1:f2;
x->i_up = (f1>f2)?f1:f2;
}

void *counter_new(t_symbol *s, int argc, t_atom *argv)

{
t_counter *x = (t_counter *)pd_new(counter_class);
t_float f1=0, f2=0;

x->step=1;
switch(argc){
default:

18
 case 3:
x->step=atom_getfloat(argv+2);
case 2:
f2=atom_getfloat(argv+1);
case 1:
f1=atom_getfloat(argv);
break;
case 0:
}
if (argc<2)f2=f1;

x->i_down = (f1<f2)?f1:f2;
x->i_up = (f1>f2)?f1:f2;

x->i_count=x->i_down;

inlet_new(&x->x_obj, &x->x_obj.ob_pd,
gensym("list"), gensym("bound"));
floatinlet_new(&x->x_obj, &x->step);

x->f_out = outlet_new(&x->x_obj, &s_float);

x->b_out = outlet_new(&x->x_obj, &s_bang);

return (void *)x;

}

void counter_setup(void) {
counter_class = class_new(gensym("counter"),
(t_newmethod)counter_new,
0, sizeof(t_counter),
CLASS_DEFAULT,
A_GIMME, 0);

class_addbang (counter_class, counter_bang);

class_addmethod(counter_class,
(t_method)counter_reset, gensym("reset"), 0);
class_addmethod(counter_class,
(t_method)counter_set, gensym("set"),
A_DEFFLOAT, 0);
class_addmethod(counter_class,
(t_method)counter_bound, gensym("bound"),

19
 A_DEFFLOAT, A_DEFFLOAT, 0);

class_sethelpsymbol(counter_class, gensym("help-counter"));
}

5 a signal-external: pan
Signalclasses are normal pd-classes, that oer additional methods for signals.
All methods and concepts that can be realized with normal objectclasses
can therefore be realized with signalclasses too.
Per agreement, the symbolic names of signalclasses end with a tilde .
The class pan shall demonstrate, how signalclasses are written.
A signal on the left inlet is mixed with a signal on the second inlet. Der
mixing-factor between 0 and 1 is dened via a t_float-message on a third
inlet.

5.1 variables of a signalclass

Since a signal-class is only an extended normal class, there are no principal

dierences between the dataspaces.

typedef struct _pan_tilde {

t_object x_obj;

t_sample f_pan;
t_float f;
} t_pan_tilde;

Only one variable f_pan for the mixing-factor of the panning-function is

needed.
The other variable f is needed whenever a signal-inlet is needed too. If
no signal but only a oat-message is present at a signal-inlet, this variable is
used to automatically convert the oat to signal.

5.2 signal-classes

void pan_tilde_setup(void) {
pan_tilde_class = class_new(gensym("pan~"),
(t_newmethod)pan_tilde_new,
0, sizeof(t_pan_tilde),
CLASS_DEFAULT,

20
 A_DEFFLOAT, 0);

class_addmethod(pan_tilde_class,
(t_method)pan_tilde_dsp, gensym("dsp"), 0);
CLASS_MAINSIGNALIN(pan_tilde_class, t_pan_tilde, f);
}
A method for signal-processing has to be provided by each signalclass.
Whenever pd's audioengine is started, a message with the selector dsp
is sent to each object. Each class that has a method for the dsp-message is
recognized as signalclass.
Signalclasses that want to provide signal-inlets have to declare this via the
CLASS_MAINSIGNALIN-macro. This enables signals at the rst (default) inlet.
If more than one signal-inlet is needed, they have to be created explicitly in
the constructor-method.
Inlets that are declared as signal-inlets cannot provide methods for t_float-
messages any longer.
The rst argument of the macro is a pointer to the signalclass. The second
argument is the type of the class's dataspace.
The last argument is a dummy-variable out of the dataspace that is
needed to replace non-existing signal at the signal-inlet(s) with t_float-
messages.

5.3 construction of signal-inlets and -outlets

void *pan_tilde_new(t_floatarg f)
{
t_pan_tilde *x = (t_pan_tilde *)pd_new(pan_tilde_class);

x->f_pan = f;

inlet_new(&x->x_obj, &x->x_obj.ob_pd, &s_signal, &s_signal);

floatinlet_new (&x->x_obj, &x->f_pan);

outlet_new(&x->x_obj, &s_signal);

return (void *)x;

}
Additional signal-inlets are added like other inlets with the routine inlet_new.
The last two arguments are references to the symbolic selector signal in the
lookup-table.

21
 Signal-outlets are also created like normal (message-)outlets, by setting
the outlet-selector to signal.

5.4 DSP-methods

Whenever pd's audioengine is turned on, all signal-objects declare their

perform-routines that are to be added to the DSP-tree.
The dsp-method has two arguments, the pointer to the class-dataspace,
and a pointer to an array of signals.
The signals are arranged in the array in such way, that they are ordered
in a clockwise way in the graphical representation of the object.4

void pan_tilde_dsp(t_pan_tilde *x, t_signal **sp)

{
dsp_add(pan_tilde_perform, 5, x,
sp[0]->s_vec, sp[1]->s_vec, sp[2]->s_vec, sp[0]->s_n);
}

dsp_add adds a perform-routine (as declared in the rst argument) to the

DSP-tree.
The second argument is the number of the following pointers to diverse
variables. Which pointers to which variables are passed is not limited.
Here, sp[0] is the rst in-signal, sp[1] represents the second in-signal and
sp[3] points to the out-signal.
The structure t_signal contains a pointer to the its signal-vector ().s_vec
(an array of samples of type t_sample), and the length of this signal-vector
().s_n.
Since all signalvectors of a patch (not including it's sub-patches) are of
the same length, it is sucient to get the length of one of these vectors.

5.5 perform-routine

The perform-routine is the DSP-heart of each signalclass.

A pointer to an integer-array is passed to it. This array contains the
pointers, that were passed via dsp_add, which must be casted back to their
real type.
The perform-routine has to return a pointer to integer, that points to
the address behind the stored pointers of the routine. This means, that the
4 If both left and right in- and out-signals exist, this means: First is the leftmost in-
signal followed by the right in-signals; after the right out-signals, nally there comes the
leftmost out-signal.

22
return argument equals the argument of the perform-routine plus the number
of pointervariables (as declared as the second argument of dsp_add) plus one.

t_int *pan_tilde_perform(t_int *w)

{
t_pan_tilde *x = (t_pan_tilde *)(w[1]);
t_sample *in1 = (t_sample *)(w[2]);
t_sample *in2 = (t_sample *)(w[3]);
t_sample *out = (t_sample *)(w[4]);
int n = (int)(w[5]);

t_sample f_pan = (x->f_pan<0)?0.0:(x->f_pan>1)?1.0:x->f_pan;

while (n--) *out++ = (*in1++)*(1-f_pan)+(*in2++)*f_pan;

return (w+6);
}

Each sample of the signalvectors is read and manipulated in the while-

loop.
Optimization of the DSP-tree tries to avoid unnecessary copy-operations.
Therefore it is possible, that in- and out-signal are located at the same ad-
dress in the memory. In this case, the programmer has to be careful not to
write into the out-signal before having read the in-signal to avoid overwriting
data that is not yet saved.

5.6 the code: pan

#include "m_pd.h"

static t_class *pan_tilde_class;

typedef struct _pan_tilde {

t_object x_obj;
t_sample f_pan;
t_sample f;
} t_pan_tilde;

t_int *pan_tilde_perform(t_int *w)

{
t_pan_tilde *x = (t_pan_tilde *)(w[1]);

23
 t_sample *in1 = (t_sample *)(w[2]);
t_sample *in2 = (t_sample *)(w[3]);
t_sample *out = (t_sample *)(w[4]);
int n = (int)(w[5]);
t_sample f_pan = (x->f_pan<0)?0.0:(x->f_pan>1)?1.0:x->f_pan;

while (n--) *out++ = (*in1++)*(1-f_pan)+(*in2++)*f_pan;

return (w+6);
}

void pan_tilde_dsp(t_pan_tilde *x, t_signal **sp)

{
dsp_add(pan_tilde_perform, 5, x,
sp[0]->s_vec, sp[1]->s_vec, sp[2]->s_vec, sp[0]->s_n);
}

void *pan_tilde_new(t_floatarg f)
{
t_pan_tilde *x = (t_pan_tilde *)pd_new(pan_tilde_class);

x->f_pan = f;

inlet_new(&x->x_obj, &x->x_obj.ob_pd, &s_signal, &s_signal);

floatinlet_new (&x->x_obj, &x->f_pan);
outlet_new(&x->x_obj, &s_signal);

return (void *)x;

}

void pan_tilde_setup(void) {
pan_tilde_class = class_new(gensym("pan~"),
(t_newmethod)pan_tilde_new,
0, sizeof(t_pan_tilde),
CLASS_DEFAULT,
A_DEFFLOAT, 0);

class_addmethod(pan_tilde_class,
(t_method)pan_tilde_dsp, gensym("dsp"), 0);
CLASS_MAINSIGNALIN(pan_tilde_class, t_pan_tilde, f);
}

24
A pd's message-system

Non-audio-data are distributed via a message-system. Each message consists

of a selector and a list of atoms.

A.1 atoms

There are three kinds of atoms:

• A_FLOAT: a numerical value (oatingpoint)

• A_SYMBOL: a symbolic value (string)

• A_POINTER: a pointer

Numerical values are always oatingpoint-values (t_float), even if they

could be displayed as integer values.
Each symbol is stored in a lookup-table for reasons of performance. The
command gensym looks up a string in the lookup-table and returns the ad-
dress of the symbol. If the string is not yet to be found in the table, a new
symbol is added.
Atoms of type A_POINTER are not very important (for simple exter-
nals).
The type of an atom a is stored in the structure-element a.a_type.

A.2 selectors

The selector is a symbol that denes the type of a message. There are ve
predened selectors:

•  bang labels a triggerevent. A bang-message consists only of the

selector and contains no lists of atoms.

•  float labels a numerical value. The list of a oat-Message contains

one single atom of type A_FLOAT

•  symbol labels a symbolic value. The list of a symbol-Message con-

tains one single atom of type A_SYMBOL

•  pointer labels a pointer value. The list of a pointer-Message con-

tains one single atom of type A_POINTER

•  list labels a list of one or more atoms of arbitrary type.

25
 Since the symbols for these selectors are used quite often, their address
in the lookup-table can be queried directly, without having to use gensym:
selector lookup-routine lookup-address
bang gensym("bang") &s_bang
float gensym("float") &s_float
symbol gensym("symbol") &s_symbol
pointer gensym("pointer") &s_pointer
list gensym("list") &s_list
 (signal) gensym("signal") &s_symbol
Other selectors can be used as well. The receiving class has to provide
a method for a specique selector or for anything, which is any arbitrary
selector.
Messages that have no explicit selector and start with a numerical value,
are recognized automatically either as oat-message (only one atom) or as
list-message (several atoms).
For example, messages  12.429 and  float 12.429 are identical. Li-
kewise, the messages  list 1 for you is identical to  1 for you.

B pd-types

Since pd is used on several plattforms, many ordinary types of variables, like

int, are re-dened. To write portable code, it is reasonable to use types
provided by pd.
Apart from this there are many predened types, that should make the
life of the programmer simpler.
Generally, pd-types start with t_.
pd-type description
t_atom atom
t_float oatingpoint value
t_symbol symbol
t_gpointer pointer (to graphical objects)
t_int integer value
t_signal structure of a signal
t_sample audiosignal-value (oatingpoint)
t_outlet outletof an object
t_inlet inlet of an object
t_object object-interna
t_class a pd-class
t_method class-method
t_newmethod pointer to a constructor (new-routine)

26
C important functions in m_pd.h

C.1 functions: atoms

C.1.1 SETFLOAT

SETFLOAT(atom, f)
This macro sets the type of atom to A_FLOAT and stores the numerical value
f in this atom.

C.1.2 SETSYMBOL

SETSYMBOL(atom, s)
This macro sets the type of atom to A_SYMBOL and stores the symbolic pointer
s in this atom.

C.1.3 SETPOINTER

SETPOINTER(atom, pt)
This macro sets the type of atom to A_POINTER and stores the pointer pt in
this atom.

C.1.4 atom_getoat

t_float atom_getfloat(t_atom *a);

If the type of the atom a is A_FLOAT, the numerical value of this atom else
0.0 is returned.

C.1.5 atom_getoatarg

t_float atom_getfloatarg(int which, int argc, t_atom *argv)

If the type of the atom  that is found at in the atom-list argv with the
length argc at the place which  is A_FLOAT, the numerical value of this
atom else 0.0 is returned.

C.1.6 atom_getint

t_int atom_getint(t_atom *a);

If the type of the atom a is A_FLOAT, its numerical value is returned as integer
else 0 is returned.

27
C.1.7 atom_getsymbol

t_symbol atom_getsymbol(t_atom *a);

If the type of the atom a is A_SYMBOL, a pointer to this symbol is returned,

else a null-pointer 0 is returned.

C.1.8 atom_gensym

t_symbol *atom_gensym(t_atom *a);

If the type of the atom a is A_SYMBOL, a pointer to this symbol is returned.

Atoms of a dierent type, are reasonably converted into a string. This
string is  on demand  inserted into the symbol-table. A pointer to this
symbol is returned.

C.1.9 atom_string

void atom_string(t_atom *a, char *buf, unsigned int bufsize);

Converts an atom a into a C-string buf. The memory to this char-Buer has
to be reserved manually and its length has to be declared in bufsize.

C.1.10 gensym

t_symbol *gensym(char *s);

Checks, whether the C-string *s has already been inserted into the symbol-
table. If no entry exists, it is created. A pointer to the symbol is returned.

C.2 functions: classes

C.2.1 class_new

t_class *class_new(t_symbol *name,

t_newmethod newmethod, t_method freemethod,
size_t size, int flags,
t_atomtype arg1, ...);

Generates a class with the symbolic name name. newmethod is the constructor
that creates an instance of the class and returns a pointer to this instance.
If memory is reserved dynamically, this memory has to be freed by the
destructor-method freemethod (without any return argument), when the
object is destroyed.

28
 size is the static size of the class-dataspace, that is returned by sizeof(t_mydata).
flags dene the presentation of the graphical object. A (more or less
arbitrary) combination of following objects is possible:
ag description
CLASS_DEFAULT a normal object with one inlet
CLASS_PD object (without graphical presentation)
CLASS_GOBJ pure graphical object (like arrays, graphs,...)
CLASS_PATCHABLE a normal object (with one inlet)
CLASS_NOINLET the default inlet is suppressed
Flags the description of which is printed in italic are of small importance
for writing externals.
The remaining arguments arg1,... dene the types of object-arguments
passed at the creation of a class-object. A maximum of six typechecked argu-
ments can be passed to an object. The list of argument-types are terminated
by 0.
Possible types of arguments are:
A_DEFFLOAT a numerical value
A_DEFSYMBOL a symbolical value
A_GIMME a list of atoms of arbitrary length and types
If more than six arguments are to be passed, A_GIMME has to be used and
a manual type-check has to be made.

C.2.2 class_addmethod

void class_addmethod(t_class *c, t_method fn, t_symbol *sel,

t_atomtype arg1, ...);

Adds a method fn for a selector sel to a class c.

The remaining arguments arg1,... dene the types of the list of atoms
that follow the selector. A maximum of six type-checked arguments can be
passed. If more than six arguments are to be passed, A_GIMME has to be used
and a manual type-check has to be made.
The list of arguments is terminated by 0.
Possible types of arguments are:
A_DEFFLOAT a numerical value
A_DEFSYMBOL a symbolical value
A_POINTER a pointer
A_GIMME a list of atoms of arbitrary length and types

C.2.3 class_addbang

void class_addbang(t_class *c, t_method fn);

29
Adds a method fn for bang-messages to the class c.
The argument of the bang-method is a pointer to the class-dataspace:
void my_bang_method(t_mydata *x);

C.2.4 class_addoat

void class_addfloat(t_class *c, t_method fn);

Adds a method fn for oat-messages to the class c.

The arguments of the oat-method is a pointer to the class-dataspace
and a oatingpoint-argument:
void my_float_method(t_mydata *x, t_floatarg f);

C.2.5 class_addsymbol

void class_addsymbol(t_class *c, t_method fn);

Adds a method fn for symbol-messages to the class c.

The arguments of the symbol-method is a pointer to the class-dataspace
and a pointer to the passed symbol:
void my_symbol_method(t_mydata *x, t_symbol *s);

C.2.6 class_addpointer

void class_addpointer(t_class *c, t_method fn);

Adds a method fn for pointer-messages to the class c.

The arguments of the pointer-method is a pointer to the class-dataspace
and a pointer to a pointer:
void my_pointer_method(t_mydata *x, t_gpointer *pt);

C.2.7 class_addlist

void class_addlist(t_class *c, t_method fn);

Adds a method fn for list-messages to the class c.

The arguments of the list-method are  apart from a pointer to the class-
dataspace  a pointer to the selector-symbol (always &s_list), the number
of atoms and a pointer to the list of atoms:
void my_list_method(t_mydata *x,
t_symbol *s, int argc, t_atom *argv);

30
C.2.8 class_addanything

void class_addanything(t_class *c, t_method fn);

Adds a method fn for an arbitrary message to the class c.

The arguments of the anything-method are  apart from a pointer to the
class-dataspace  a pointer to the selector-symbol, the number of atoms and
a pointer to the list of atoms:
void my_any_method(t_mydata *x,
t_symbol *s, int argc, t_atom *argv);

C.2.9 class_addcreator

void class_addcreator(t_newmethod newmethod, t_symbol *s,

t_atomtype type1, ...);

Adds a creator-symbol s, alternative to the symbolic classname, to the con-

structor newmethod. Thus, objects can be created either by their real
classname or an alias-name (p.e. an abbreviation, like the internal oat
resp. f).
The 0-terminated list of types corresponds to that of class_new.

C.2.10 class_sethelpsymbol

void class_sethelpsymbol(t_class *c, t_symbol *s);

If a pd-object is right-clicked, a help-patch for the corresponding object-

class can be opened. By default this is a patch with the symbolic classname
in the directory  doc/5.reference/.
The name of the help-patch for the class that is pointed to by c is changed
to the symbol s.
Therefore, several similar classes can share a single help-patch.
Path-information is relative to the default helppath doc/5.reference/.

C.2.11 pd_new

t_pd *pd_new(t_class *cls);

Generates a new instance of the class cls and returns a pointer to this
instance.

31
C.3 functions: inlets and outlets

All routines for inlets and outlets need a reference to the object-interna of the
class-instance. When instantiating a new object, the necessary dataspace-
variable of the t_object-type is initialized. This variable has to be passed
as the owner-object to the various inlet- and outlet-routines.

C.3.1 inlet_new

t_inlet *inlet_new(t_object *owner, t_pd *dest,

t_symbol *s1, t_symbol *s2);

Generates an additional active inlet for the object that is pointed at by

owner. Generally, dest points at  owner.ob_pd.
The selector s1 at the new inlet is substituted by the selector s2.
If a message with selector s1 appears at the new inlet, the class-method
for the selector s2 is called.
This means

• The substituting selector has to be declared by class_addmethod in

the setup-routine.

• It is possible to simulate a certain right inlet, by sending a message

with this inlet's selector to the leftmost inlet.
Using an empty symbol (gensym("")) as selector makes it impossible
to address a right inlet via the leftmost one.

• It is not possible to add methods for more than one selector to a right
inlet. Particularly it is not possible to add a universal method for
arbitrary selectors to a right inlet.

C.3.2 oatinlet_new

t_inlet *floatinlet_new(t_object *owner, t_float *fp);

Generates a new passive inlet for the object that is pointed at by owner.
This inlet enables numerical values to be written directly into the memory
fp, without calling a dedicated method.

32
C.3.3 symbolinlet_new

t_inlet *symbolinlet_new(t_object *owner, t_symbol **sp);

Generates a new passive inlet for the object that is pointed at by owner.
This inlet enables symbolic values to be written directly into the memory
*sp, without calling a dedicated method.

C.3.4 pointerinlet_new

t_inlet *pointerinlet_new(t_object *owner, t_gpointer *gp);

Generates a new passive inlet for the object that is pointed at by owner.
This inlet enables pointer to be written directly into the memory gp, without
calling a dedicated method.

C.3.5 outlet_new

t_outlet *outlet_new(t_object *owner, t_symbol *s);

Generates a new outlet for the object that is pointed at by owner. The
Symbol s indicates the type of the outlet.
symbol symbol-addresse outlet-type
bang &s_bang message (bang)
oat &s_float message (oat)
symbol &s_symbol message (symbol)
pointer &s_gpointer message (pointer)
list &s_list message (list)
 0 message
signal &s_signal signal
There are no real dierences between outlets of the various message-types.
At any rate, it makes code more easily readable, if the use of outlet is shown
at creation-time. For outlets for any messages a null-pointer is used. Signal-
outlet must be declared with &s_signal.
Variables if the type t_object provide pointer to one outlet. Whene-
ver a new outlet is generated, its address is stored in the objectvariable
(*owner).ob_outlet.
If more than one message-outlet is needed, the outlet-pointers that are
returned by outlet_new have to be stored manually in the dataspace to
address the given outlets.

33
C.3.6 outlet_bang

void outlet_bang(t_outlet *x);

Outputs a bang-message at the outlet specied by x.

C.3.7 outlet_oat

void outlet_float(t_outlet *x, t_float f);

Outputs a oat-message with the numeric value f at the outlet specied by
x.

C.3.8 outlet_symbol

void outlet_symbol(t_outlet *x, t_symbol *s);

Outputs a symbol-message with the symbolic value s at the outlet specied
by x.

C.3.9 outlet_pointer

void outlet_pointer(t_outlet *x, t_gpointer *gp);

Outputs a pointer-message with the pointer gp at the outlet specied by x.

C.3.10 outlet_list

void outlet_list(t_outlet *x,

t_symbol *s, int argc, t_atom *argv);
Outputs a list-message at the outlet specied by x. The list contains argc
atoms. argv points to the rst element of the atom-list.
Independet of the symbol s, the selector list will precede the list.
To make the code more readable, s should point to the symbol list (either
via gensym("list") or via &s_list)

C.3.11 outlet_anything

void outlet_anything(t_outlet *x,

t_symbol *s, int argc, t_atom *argv);
Outputs a message at the outlet specied by x.
The message-selector is specied with s. It is followed by argc atoms.
argv points to the rst element of the atom-list.

34
C.4 functions: DSP

If a class should provide methods for digital signal-processing, a method for

the selector dsp (followed by no atoms) has to be added to this class
Whenever pd's audioengine is started, all objects that provide a dsp-
method are identied as instances of signalclasses.

DSP-method

void my_dsp_method(t_mydata *x, t_signal **sp)

In the dsp-method a classmethod for signal-processing is added to the
DSP-tree by the function dsp_add.
Apart from the dataspace x of the object, an array of signals is passed.
The signals in the array are arranged in such a way, that they can be read
in the graphical representation of the object clockwisely.
In case there are both two in- and out-signals, this means:
pointer to signal
sp[0] left in-signal
sp[1] right in-signal
sp[2] right out-signal
sp[3] left out-signal
The signalstructure contains apart from other things:
structure-element description
s_n length of the signalvector
s_vec pointer to the signalvector
The signalvector is an array of samples of type t_sample.

perform-routine

t_int *my_perform_routine(t_int *w)

A pointer w to an array (of integer) is passed to the perform-routine that
is inserted into the DSP-tree by class_add.
In this array the pointers that are passed via dsp_add are stored. These
pointers have to be casted back to their original type.
The rst pointer is stored at w[1] !!!
The perform-routine has to return a pointer to integer, that points di-
rectly behind the memory, where the object's pointers are stored. This
means, that the return-argument equals the routine's argument w plus the
number of used pointers (as dened in the second argument of dsp_add) plus
one.

35
C.4.1 CLASS_MAINSIGNALIN

CLASS_MAINSIGNALIN(<class_name>, <class_data>, <f>);

The macro CLASS_MAINSIGNALIN declares, that the class will use signal-
inlets.
The rst macro-argument is a pointer to the signal-class. The second ar-
gument is the type of the class-dataspace. The third argument is a (dummy-
)oatingpoint-variable of the dataspace, that is needed to automatically con-
vert oat-messages into signals if no signal is present at the signal-inlet.
No oat-methods can be used for signal-inlets, that are created this way.

C.4.2 dsp_add

void dsp_add(t_perfroutine f, int n, ...);

Adds the perform-routine f to the DSP-tree. The perform-routine is called

at each DSP-cycle.
The second argumentn denes the number of following pointer-arguments
Which pointers to which data are passes is not limited. Generally, poin-
ters to the dataspace of the object and to the signal-vectors are reasonable.
The length of the signal-vectors should also be passed to manipulate signals
eectively.

C.4.3 sys_getsr

float sys_getsr(void);

Returns the samplerate of the system.

C.5 functions: memory

C.5.1 getbytes

void *getbytes(size_t nbytes);

Reserves nbytes bytes and returns a pointer to the allocated memory.

C.5.2 copybytes

void *copybytes(void *src, size_t nbytes);

Copies nbytes bytes from *src into a newly allocated memory. The address
of this memory is returned.

36
C.5.3 freebytes

void freebytes(void *x, size_t nbytes);

Frees nbytes bytes at address *x.

C.6 functions: output

C.6.1 post

void post(char *fmt, ...);

Writes a C-string to the standarderror (shell).

C.6.2 error

void error(char *fmt, ...);

Writes a C-string as an error-message to the standarderror (shell).

The object that has output the error-message is marked and can be iden-
tied via the pd-menu Find->Find last error.

37