SETFLOAT(atom, f)This macro sets the type of
atom to A_FLOAT
and stores the numerical value f in this atom.
SETSYMBOL(atom, s)This macro sets the type of
atom to A_SYMBOL
and stores the symbolic pointer s in this atom.
SETPOINTER(atom, pt)This macro sets the type of
atom to A_POINTER
and stores the pointer pt in this atom.
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.
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.
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.
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.
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 different type, are ``reasonably'' converted into a string. This string is - on demand - inserted into the symbol-table. A pointer to this symbol is returned.
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-Buffer has to be reserved manually and
its length has to be declared in bufsize.
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.
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.
size is the static size of the class-dataspace,
that is returned by sizeof(t_mydata).
flags define the presentation of the graphical object.
A (more or less arbitrary) combination of following objects is possible:
| flag | 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,... define the
types of object-arguments passed at the creation of a class-object.
A maximum of six typechecked arguments 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.
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,... define 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 |
void class_addbang(t_class *c, t_method fn);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);
void class_addfloat(t_class *c, t_method fn);Adds a method
fn for ``float''-messages to the class c.
The arguments of the ``float''-method is a pointer to the class-dataspace and a floatingpoint-argument:
void my_float_method(t_mydata *x, t_floatarg f);
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);
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);
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);
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);
void class_addcreator(t_newmethod newmethod, t_symbol *s,
t_atomtype type1, ...);
Adds a creator-symbol s, alternative to the symbolic classname,
to the constructor newmethod.
Thus, objects can be created either by their ``real'' classname or
an alias-name (p.e. an abbreviation, like the internal ``float'' resp. ``f'').
The ``0''-terminated list of types corresponds to that of class_new.
void class_sethelpsymbol(t_class *c, t_symbol *s);
If a pd-object is right-clicked, a help-patch for the corresponding objectclass 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/.
t_pd *pd_new(t_class *cls);Generates a new instance of the class
cls and
returns a pointer to this instance.
t_object-type is initialized.
This variable has to be passed as the owner-object to the
various inlet- and outlet-routines.
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
class_addmethod
in the setup-routine.
Using an empty symbol (gensym("")) as selector
makes it impossible to address a right inlet via the leftmost one.
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.
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.
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.
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) |
| ``float'' | &s_float |
message (float) |
| ``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 differences 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.
Whenever 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.
void outlet_bang(t_outlet *x);Outputs a ``bang''-message at the outlet specified by
x.
void outlet_float(t_outlet *x, t_float f);Outputs a ``float''-message with the numeric value
f
at the outlet specified by x.
void outlet_symbol(t_outlet *x, t_symbol *s);Outputs a ``symbol''-message with the symbolic value
s
at the outlet specified by x.
void outlet_pointer(t_outlet *x, t_gpointer *gp);Outputs a ``pointer''-message with the pointer
gp
at the outlet specified by x.
void outlet_list(t_outlet *x,
t_symbol *s, int argc, t_atom *argv);
Outputs a ``list''-message at the outlet specified by x.
The list contains argc atoms.
argv points to the first 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)
void outlet_anything(t_outlet *x,
t_symbol *s, int argc, t_atom *argv);
Outputs a message at the outlet specified by x.
The message-selector is specified with s.
It is followed by argc atoms.
argv points to the first element of the atom-list.
Whenever pd's audioengine is started, all objects that provide a ``dsp''-method are identified as instances of signalclasses.
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.
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 first pointer is stored at w[1] !!!
The perform-routine has to return a pointer to integer,
that points directly 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 defined in the second argument of dsp_add) plus one.
CLASS_MAINSIGNALIN(<class_name>, <class_data>, <f>);The macro
CLASS_MAINSIGNALIN declares,
that the class will use signal-inlets.
The first macro-argument is a pointer to the signal-class. The second argument is the type of the class-dataspace. The third argument is a (dummy-)floatingpoint-variable of the dataspace, that is needed to automatically convert ``float''-messages into signals if no signal is present at the signal-inlet.
No ``float''-methods can be used for signal-inlets, that are created this way.
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 defines the number of following pointer-arguments
Which pointers to which data are passes is not limited. Generally, pointers 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 effectively.
float sys_getsr(void);Returns the samplerate of the system.
void *getbytes(size_t nbytes);Reserves
nbytes bytes and returns a pointer to the allocated memory.
void *copybytes(void *src, size_t nbytes);Copies
nbytes bytes from *src into a newly allocated memory.
The address of this memory is returned.
void freebytes(void *x, size_t nbytes);Frees
nbytes bytes at address *x.
void post(char *fmt, ...);
Writes a C-string to the standarderror (shell).
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 identified via the pd-menu Find->Find last error.