diff options
| -rw-r--r-- | doc/tutorials/externals-howto/HOWTO-externals-en.tex | 272 |
1 files changed, 134 insertions, 138 deletions
diff --git a/doc/tutorials/externals-howto/HOWTO-externals-en.tex b/doc/tutorials/externals-howto/HOWTO-externals-en.tex index 8c77d3c6..c6ede191 100644 --- a/doc/tutorials/externals-howto/HOWTO-externals-en.tex +++ b/doc/tutorials/externals-howto/HOWTO-externals-en.tex @@ -31,19 +31,15 @@ johannes m zmölnig \\ \begin{document} \maketitle -\hyphenation{Echt-zeit} -\hyphenation{Computer-musik-program-men} -\hyphenation{Echt-zeit-Computer-musik-pro-gramm} - \begin{abstract} -pd is a graphical realtime-computermusicsystem that follows the tradition of +pd is a graphical real-time computer-music system that follows the tradition of IRCAMs {\em 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'') +Therefore, pd can be extended with self made primitives (``objects'') that are written in complex programming-languages, like {\tt C/C++}. This document aims to explain, how to write such primitives in {\tt C}, @@ -60,7 +56,7 @@ the popular language that was used to realize pd. \newpage \section{definitions and prerequisites} -pd refers to the graphical realtime-computermusicprogramme {\em puredata} +pd refers to the graphical real-time computer-music environment {\em pure data} by Miller~S.~Puckette. To fully understand this document, it is necessary to @@ -73,7 +69,7 @@ To write externals yourself, a {\tt C}-compiler that supports the \subsection{classes, instances, objects} pd is written in the programming-language {\tt C}. -Due to its graphical nature, pd ist a {\em object-oriented} system. +Due to its graphical nature, pd is a {\em object-oriented} system. Unfortunately {\tt C} does not support very well the use of classes. Thus the resulting source-code is not as elegant as {\tt C++}-code would be, for instance. @@ -100,7 +96,7 @@ Once loaded into pd's memory, {\em externals} cannot be distinguished from A {\em library} is a collection of {\em externals} that are compiled into a single binary-file. -{\em Library}-files have to follow a systemdependent naming convention: +{\em Library}-files have to follow a system dependent naming convention: \begin{tabular}{c||c|c|c} library & linux&irix&Win32 \\ @@ -119,7 +115,7 @@ all included {\em externals} have been loaded into memory and are available as o pd supports to modes to import {\em libraries}: \begin{itemize} -\item via the commandline-option ``{\tt -lib my\_lib}'' +\item via the command line-option ``{\tt -lib my\_lib}'' \item by creating an object ``{\tt my\_lib}'' \end{itemize} @@ -147,8 +143,8 @@ Anyhow, all {\em external}-classes declared in the {\em library} are loaded by n \section{my first external: {\tt helloworld}} Usually the first 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. +In our case, an object class should be created, that prints the line ``hello world!!'' to +the standard error every time it is triggered with a ``bang''-message. @@ -160,8 +156,8 @@ This is provided in the header-file ``m\_pd.h''. #include "m_pd.h" \end{verbatim} -\subsection{a class and its dataspace} -First a new class has to be prepared and the dataspace for this class has to be defined. +\subsection{a class and its data space} +First a new class has to be prepared and the data space for this class has to be defined. \begin{verbatim} static t_class *helloworld_class; @@ -174,9 +170,9 @@ typedef struct _helloworld { \verb+hello_worldclass+ is going to be a pointer to the new class. The structure \verb+t_helloworld+ (of the type \verb+_helloworld+) is -the dataspace of the class. +the data space of the class. -An absolutely necessary element of the dataspace is a variable of the type +An absolutely necessary element of the data space is a variable of the type \verb+t_object+, which is used to store internal object-properties like the graphical presentation of the object or data about inlets and outlets. @@ -186,12 +182,12 @@ Because a simple ``hello world''-application needs no variables, the structure is empty apart from the \verb+t_object+. -\subsection{methodspace} -Apart from the dataspace, a class needs a set of manipulators (methods) to +\subsection{method space} +Apart from the data space, 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. +These methods are the interfaces to the message system of pd. On principal they have no return argument and are therefore are of the type \verb+void+. @@ -204,18 +200,18 @@ void helloworld_bang(t_helloworld *x) This method has an argument of the type \verb+t_helloworld+, -which would enable us to manipulate the dataspace. +which would enable us to manipulate the data space. Since we only want to output ``Hello world!'' -(and, by the way, our dataspace is quite sparse), +(and, by the way, our data space is quite sparse), we renounce a manipulation. -The command \verb+post(char *c,...)+ sends a string to the standarderror. +The command \verb+post(char *c,...)+ sends a string to the standard error. A carriage return is added automatically. Apart from this, the \verb+post+-command works like the {\tt C}-command \verb+printf()+. \subsection{generation of a new class} -To generate a new class, information of the dataspace and the methodspace of this class, +To generate a new class, information of the data space and the method space of this class, have to be passed to pd when a library is loaded. On loading a new library ``my\_lib'', @@ -223,7 +219,7 @@ 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 specified name is present) +If the function-call fails (e.g., because no function of the specified name is present) no external of the library will be loaded. \begin{verbatim} @@ -244,26 +240,24 @@ The function \verb+class_new+ creates a new class and returns a pointer to this The first argument is the symbolic name of the class. -Das erste Argument ist der symbolische Name der Klasse. - -The next two arguments define the constructor and dstructor of the class. +The next two arguments define the constructor and destructor of the class. -Whenever a classobject is created in a pd-patch, +Whenever a class object is created in a pd-patch, the class-constructor \verb+(t_newmethod)helloworld_new+ instantiates the object -and initializes the dataspace. +and initialises the data space. Whenever an object is destroyed (either by closing the containing patch or by deleting the object from the patch) the destructor frees the dynamically reserved memory. -The allocated memory for the static dataspace is automatically reserved and freed. +The allocated memory for the static data space 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. +To enable pd to reserve and free enough memory for the static data space, +the size of the data structure has to be passed as the fourth argument. -The fifth argument has influence on the graphical representaion of the classobjects. +The fifth argument has influence on the graphical representation of the class objects. The default-value is \verb+CLASS_DEFAULT+ or simply ``0''. The remaining arguments define the arguments of an object and its type. @@ -271,14 +265,14 @@ The remaining arguments define the arguments of an object and its type. Up to six numeric and symbolic object-arguments can be defined via \verb+A_DEFFLOAT+ and \verb+A_DEFSYMBOL+. If more arguments are to be passed to the object -or if the order of atomtypes should by more flexible, +or if the order of atom types should by more flexible, \verb+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. \paragraph{class\_addbang} -We still have to add a methodspace to the class. +We still have to add a method space to the class. \verb+class_addbang+ adds a method for a ``bang''-message to the class that is defined in the first argument. @@ -316,17 +310,17 @@ defined with \verb+class_new+. Because there are no object-arguments for our ``hello world''-class, the constructor has anon too. -The function \verb+pd_new+ reserves memory for the dataspace, -initializes the variables that are internal to the object and -returns a pointer to the dataspace. +The function \verb+pd_new+ reserves memory for the data space, +initialises the variables that are internal to the object and +returns a pointer to the data space. -The type-cast to the dataspace is necessary. +The type-cast to the data space is necessary. -Normally, the constructor would initialize the object-variables. +Normally, the constructor would initialise the object-variables. However, since we have none, this is not necessary. -The constructor has to return a pointer to the instantiated dataspace. +The constructor has to return a pointer to the instantiated data space. \subsection{the code: \tt helloworld} @@ -368,14 +362,14 @@ 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 +but the data space is extended by a variable ``counter'' and the result is written as a message to an outlet instead of -a string to the standarderror. +a string to the standard error. \subsection{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. +State-variables that belong to class instances belong to the data space. \begin{verbatim} typedef struct _counter { @@ -387,7 +381,7 @@ typedef struct _counter { The integer variable \verb+i_count+ stores the counter-value. \subsection{object-arguments} -It is quite usefull for a counter, if a initial value can be defined by the user. +It is quite useful for a counter, if a initial value can be defined by the user. Therefore this initial value should be passed to the object at creation-time. \begin{verbatim} @@ -409,7 +403,7 @@ If no argument is passed, this will default to ``0''. \subsection{constructor} The constructor has some new tasks. -On the one hand, a variable value has to be initialized, +On the one hand, a variable value has to be initialised, on the other hand, an outlet for the object has to be created. \begin{verbatim} @@ -426,7 +420,7 @@ void *counter_new(t_floatarg f) The constructor-method has one argument of type \verb+t_floatarg+ as declared in the setup-routine by \verb+class_new+. -This argument is used to initialize the counter. +This argument is used to initialise the counter. A new outlet is created with the function \verb+outlet_new+. The first argument is a pointer to the interna of the object @@ -437,12 +431,12 @@ Since out counter should output numeric values it is of type ``float''. \verb+outlet_new+ returns a pointer to the new outlet and saves this very pointer in the \verb+t_object+-variable \verb+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 \verb+t_object+-variable can only hold one outletpointer. +If only one outlet is used, the pointer need not additionally be stored in the data space. +If more than one outlets are used, the pointers have to be stored in the data space, +because the \verb+t_object+-variable can only hold one outlet pointer. -\subsection{the countermethod} -When triggered, the countervalue should be sent to the outlet +\subsection{the counter method} +When triggered, the counter value should be sent to the outlet and afterwards be incremented by 1. \begin{verbatim} @@ -457,20 +451,20 @@ void counter_bang(t_counter *x) The function \verb+outlet_float+ sends a floating-point-value (second argument) to the outlet that is specified by the first argument. -We first store the counter in a floatingpoint-buffer. -Afterwards the counter is incremented and not before that the buffervariable is sent +We first store the counter in a floating point-buffer. +Afterwards the counter is incremented and not before that the buffer variable is sent to the outlet. What appears to be unnecessary on the first glance, makes sense after further inspection: -The buffervariable has been realized as \verb+t_float+, -since \verb+outlet_float+ expects a floatingpoint-value and a typecast is +The buffer variable has been realized as \verb+t_float+, +since \verb+outlet_float+ expects a floating point-value and a typecast is inevitable. -If the countervalue was sent to the outlet before being incremented, -this could result in an unwanted (though welldefined) behaviour: +If the counter value was sent to the outlet before being incremented, +this could result in an unwanted (though well defined) behaviour: If the counter-outlet directly triggered its own inlet, -the counter-method would be called although the countervalue was not yet incremented. +the counter-method would be called although the counter value was not yet incremented. Normally this is not what we want. The same (correct) result could of course be obtained with a single line, @@ -520,12 +514,12 @@ void counter_setup(void) { \section{a complex external: \tt 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. +It might be quite useful to be able to reset the counter to an initial value, +to set upper and lower boundaries 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. -\subsection{extended dataspace} +\subsection{extended data space} \begin{verbatim} typedef struct _counter { @@ -537,14 +531,14 @@ typedef struct _counter { } t_counter; \end{verbatim} -The dataspace has been extended to hold variables for stepwidth and +The data space has been extended to hold variables for step width and upper and lower boundaries. Furthermore pointers for two outlets have been added. \subsection{extension of the class} -The new classobjects should have methods for different messages, +The new class objects should have methods for different messages, like ``set'' and ``reset''. -Therefore the methodspace has to be extended too. +Therefore the method space has to be extended too. \begin{verbatim} counter_class = class_new(gensym("counter"), @@ -554,7 +548,7 @@ Therefore the methodspace has to be extended too. A_GIMME, 0); \end{verbatim} -The classgenerator \verb+class_new+ has been extended by the argument \verb+A_GIMME+. +The class generator \verb+class_new+ has been extended by the argument \verb+A_GIMME+. This enables a dynamic number of arguments to be passed at the instantiation of the object. \begin{verbatim} @@ -590,7 +584,7 @@ as well as a method for the selector ``bound'' followed by two numerical values. 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 ``{\em doc/5.reference/}'' and -is named like the symbolic classname. +is named like the symbolic class name. An alternative help-patch can be defined with the \verb+class_sethelpsymbol+-command. @@ -609,7 +603,7 @@ the constructor has following arguments: \begin{tabular}{c|l} \verb+t_symbol *s+ & the symbolic name,\\ & that was used for object creation \\ -\verb+int argc+ & the numer of arguments passed to the object\\ +\verb+int argc+ & the number of arguments passed to the object\\ \verb+t_atom *argv+ & a pointer to a list of {\tt argc} atoms \end{tabular} @@ -627,6 +621,7 @@ the constructor has following arguments: f1=atom_getfloat(argv); break; case 0: + break; } if (argc<2)f2=f1; x->i_down = (f1<f2)?f1:f2; @@ -678,17 +673,17 @@ a right inlet. floatinlet_new(&x->x_obj, &x->step); \end{verbatim} \verb+floatinlet_new+ generates a new ``passive'' inlet for numerical values. -``Passive'' inlets allow parts of the dataspace-memory to be written directly +``Passive'' inlets allow parts of the data space-memory to be written directly from outside. Therefore it is not possible to check for illegal inputs. The first argument is a pointer to the internal infrastructure of the object. -The second argument is the address in the dataspace-memory, +The second argument is the address in the data space-memory, where other objects can write too. ``Passive'' inlets can be created for pointers, symbolic or -numerical (floatingpoint\footnote{ -That's why the {\tt step}-width of the class\/dataspace is realized as {\tt t\_float}.}) +numerical (floating point\footnote{ +That's why the {\tt step}-width of the class\/data space is realized as {\tt t\_float}.}) values. @@ -697,16 +692,16 @@ values. x->b_out = outlet_new(&x->x_obj, &s_bang); \end{verbatim} -The pointers returned by \verb+outlet_new+ have to be saved in the class\/dataspace +The pointers returned by \verb+outlet_new+ have to be saved in the class\/data space 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. -\subsection{extended methodspace} +\subsection{extended method space} -The method for the ``bang''-message has to fullfill the more complex tasks. +The method for the ``bang''-message has to full fill the more complex tasks. \begin{verbatim} void counter_bang(t_counter *x) @@ -816,6 +811,7 @@ void *counter_new(t_symbol *s, int argc, t_atom *argv) f1=atom_getfloat(argv); break; case 0: + break; } if (argc<2)f2=f1; @@ -857,23 +853,23 @@ void counter_setup(void) { \section{a signal-external: {\tt pan\~\/}} -Signalclasses are normal pd-classes, that offer additional methods for signals. +Signal classes are normal pd-classes, that offer additional methods for signals. -All methods and concepts that can be realized with normal objectclasses can -therefore be realized with signalclasses too. +All methods and concepts that can be realized with normal object classes can +therefore be realized with signal classes too. -Per agreement, the symbolic names of signalclasses end with a tilde \~\/. +Per agreement, the symbolic names of signal classes end with a tilde \~\/. -The class ``pan\~\/'' shall demonstrate, how signalclasses are written. +The class ``pan\~\/'' shall demonstrate, how signal classes 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 defined via a \verb+t_float+-message +The mixing-factor between 0 and 1 is defined via a \verb+t_float+-message on a third inlet. -\subsection{variables of a signalclass} +\subsection{variables of a signal class} Since a signal-class is only an extended normal class, -there are no principal differences between the dataspaces. +there are no principal differences between the data spaces. \begin{verbatim} typedef struct _pan_tilde { @@ -906,13 +902,13 @@ void pan_tilde_setup(void) { } \end{verbatim} -A method for signal-processing has to be provided by each signalclass. +A method for signal-processing has to be provided by each signal class. -Whenever pd's audioengine is started, a message with the selector ``dsp'' +Whenever pd's audio engine 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. +Each class that has a method for the ``dsp''-message is recognised as signal class. -Signalclasses that want to provide signal-inlets have to +Signal classes that want to provide signal-inlets have to declare this via the \verb+CLASS_MAINSIGNALIN+-macro. This enables signals at the first (default) inlet. If more than one signal-inlet is needed, they have to be created explicitly @@ -921,10 +917,10 @@ in the constructor-method. Inlets that are declared as signal-inlets cannot provide methods for \verb+t_float+-messages any longer. -The first argument of the macro is a pointer to the signalclass. -The second argument is the type of the class's dataspace. +The first argument of the macro is a pointer to the signal class. +The second argument is the type of the class's data space. -The last argument is a dummy-variable out of the dataspace that is needed +The last argument is a dummy-variable out of the data space that is needed to replace non-existing signal at the signal-inlet(s) with \verb+t_float+-messages. \subsection{construction of signal-inlets and -outlets} @@ -953,10 +949,10 @@ Signal-outlets are also created like normal (message-)outlets, by setting the outlet-selector to ``signal''. \subsection{DSP-methods} -Whenever pd's audioengine is turned on, +Whenever pd's audio engine 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 +The ``dsp''-method has two arguments, the pointer to the class-data space, and a pointer to an array of signals. The signals are arranged in the array in such way, @@ -987,11 +983,11 @@ The structure \verb+t_signal+ contains a pointer to the its signal-vector \verb+().s_vec+ (an array of samples of type \verb+t_sample+), and the length of this signal-vector \verb+().s_n+. -Since all signalvectors of a patch (not including it's sub-patches) are of the same length, +Since all signal vectors of a patch (not including it's sub-patches) are of the same length, it is sufficient to get the length of one of these vectors. \subsection{perform-routine} -The perform-routine is the DSP-heart of each signalclass. +The perform-routine is the DSP-heart of each signal class. A pointer to an integer-array is passed to it. This array contains the pointers, that were passed via \verb+dsp_add+, @@ -1001,7 +997,7 @@ 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 return argument equals the argument of the perform-routine plus -the number of pointervariables (as declared as the second argument +the number of pointer variables (as declared as the second argument of \verb+dsp_add+) plus one. \begin{verbatim} @@ -1021,10 +1017,10 @@ t_int *pan_tilde_perform(t_int *w) } \end{verbatim} -Each sample of the signalvectors is read and manipulated in the \verb+while+-loop. +Each sample of the signal vectors is read and manipulated in the \verb+while+-loop. -Optimization of the DSP-tree tries to avoid unnecessary copy-operations. +Optimisation of the DSP-tree tries to avoid unnecessary copy-operations. Therefore it is possible, that in- and out-signal are located at the same address in the memory. In this case, the programmer has to be careful not to write into the out-signal @@ -1101,12 +1097,12 @@ Each message consists of a ``selector'' and a list of atoms. There are three kinds of atoms: \begin{itemize} -\item {\em A\_FLOAT}: a numerical value (floatingpoint) +\item {\em A\_FLOAT}: a numerical value (floating point) \item {\em A\_SYMBOL}: a symbolic value (string) \item {\em A\_POINTER}: a pointer \end{itemize} -Numerical values are always floatingpoint-values (\verb+t_float+), +Numerical values are always floating point-values (\verb+t_float+), even if they could be displayed as integer values. Each symbol is stored in a lookup-table for reasons of performance. @@ -1123,7 +1119,7 @@ The type of an atom \verb+a+ is stored in the structure-element \verb+a.a_type+. The selector is a symbol that defines the type of a message. There are five predefined selectors: \begin{itemize} -\item ``{\tt bang}'' labels a triggerevent. +\item ``{\tt bang}'' labels a trigger event. A ``bang''-message consists only of the selector and contains no lists of atoms. \item ``{\tt float}'' labels a numerical value. The list of a ``float''-Message contains one single atom of type {\em A\_FLOAT} @@ -1154,14 +1150,14 @@ The receiving class has to provide a method for a specifique 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 ``float''-message (only one atom) or as +are recognised automatically either as ``float''-message (only one atom) or as ``list''-message (several atoms). For example, messages ``\verb+12.429+'' and ``\verb+float 12.429+'' are identical. Likewise, the messages ``\verb+list 1 for you+'' is identical to ``\verb+1 for you+''. \section{pd-types} -Since pd is used on several plattforms, +Since pd is used on several platforms, many ordinary types of variables, like \verb|int|, are re-defined. To write portable code, it is reasonable to use types provided by pd. @@ -1174,14 +1170,14 @@ Generally, pd-types start with \verb|t_|. pd-type & description \\ \hline\hline \verb+t_atom+& atom \\ -\verb+t_float+ & floatingpoint value\\ +\verb+t_float+ & floating point value\\ \verb+t_symbol+ & symbol \\ \verb+t_gpointer+ & pointer (to graphical objects) \\ \hline \verb+t_int+ & integer value \\ \verb+t_signal+ & structure of a signal \\ -\verb+t_sample+ & audiosignal-value (floatingpoint)\\ -\verb+t_outlet+ & outletof an object \\ +\verb+t_sample+ & audio signal-value (floating point)\\ +\verb+t_outlet+ & outlet of an object \\ \verb+t_inlet+ & inlet of an object \\ \verb+t_object+ & object-interna \\ \hline @@ -1288,7 +1284,7 @@ If memory is reserved dynamically, this memory has to be freed by the destructor-method \verb+freemethod+ (without any return argument), when the object is destroyed. -\verb+size+ is the static size of the class-dataspace, +\verb+size+ is the static size of the class-data space, that is returned by \verb+sizeof(t_mydata)+. \verb+flags+ define the presentation of the graphical object. @@ -1309,7 +1305,7 @@ are of small importance for writing externals. The remaining arguments \verb+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. +A maximum of six type checked arguments can be passed to an object. The list of argument-types are terminated by ``0''. Possible types of arguments are: @@ -1354,7 +1350,7 @@ void class_addbang(t_class *c, t_method fn); \end{verbatim} Adds a method \verb+fn+ for ``bang''-messages to the class \verb+c+. -The argument of the ``bang''-method is a pointer to the class-dataspace: +The argument of the ``bang''-method is a pointer to the class-data space: \verb+void my_bang_method(t_mydata *x);+ @@ -1364,8 +1360,8 @@ void class_addfloat(t_class *c, t_method fn); \end{verbatim} Adds a method \verb+fn+ for ``float''-messages to the class \verb+c+. -The arguments of the ``float''-method is a pointer to the class-dataspace and -a floatingpoint-argument: +The arguments of the ``float''-method is a pointer to the class-data space and +a floating point-argument: \verb+void my_float_method(t_mydata *x, t_floatarg f);+ @@ -1375,7 +1371,7 @@ void class_addsymbol(t_class *c, t_method fn); \end{verbatim} Adds a method \verb+fn+ for ``symbol''-messages to the class \verb+c+. -The arguments of the ``symbol''-method is a pointer to the class-dataspace and +The arguments of the ``symbol''-method is a pointer to the class-data space and a pointer to the passed symbol: \verb+void my_symbol_method(t_mydata *x, t_symbol *s);+ @@ -1386,7 +1382,7 @@ void class_addpointer(t_class *c, t_method fn); \end{verbatim} Adds a method \verb+fn+ for ``pointer''-messages to the class \verb+c+. -The arguments of the ``pointer''-method is a pointer to the class-dataspace and +The arguments of the ``pointer''-method is a pointer to the class-data space and a pointer to a pointer: \verb+void my_pointer_method(t_mydata *x, t_gpointer *pt);+ @@ -1397,7 +1393,7 @@ void class_addlist(t_class *c, t_method fn); \end{verbatim} Adds a method \verb+fn+ for ``list''-messages to the class \verb+c+. -The arguments of the ``list''-method are -- apart from a pointer to the class-dataspace -- +The arguments of the ``list''-method are -- apart from a pointer to the class-data space -- a pointer to the selector-symbol (always \verb+&s_list+), the number of atoms and a pointer to the list of atoms: @@ -1411,7 +1407,7 @@ void class_addanything(t_class *c, t_method fn); \end{verbatim} Adds a method \verb+fn+ for an arbitrary message to the class \verb+c+. -The arguments of the anything-method are -- apart from a pointer to the class-dataspace -- +The arguments of the anything-method are -- apart from a pointer to the class-data space -- a pointer to the selector-symbol, the number of atoms and a pointer to the list of atoms: @@ -1424,9 +1420,9 @@ the number of atoms and a pointer to the list of atoms: void class_addcreator(t_newmethod newmethod, t_symbol *s, t_atomtype type1, ...); \end{verbatim} -Adds a creator-symbol \verb+s+, alternative to the symbolic classname, +Adds a creator-symbol \verb+s+, alternative to the symbolic class name, to the constructor \verb+newmethod+. -Thus, objects can be created either by their ``real'' classname or +Thus, objects can be created either by their ``real'' class name or an alias-name (p.e. an abbreviation, like the internal ``float'' resp. ``f''). The ``0''-terminated list of types corresponds to that of \verb+class_new+. @@ -1436,9 +1432,9 @@ The ``0''-terminated list of types corresponds to that of \verb+class_new+. void class_sethelpsymbol(t_class *c, t_symbol *s); \end{verbatim} -If a pd-object is right-clicked, a help-patch for the corresponding objectclass +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 +By default this is a patch with the symbolic class name in the directory ``{\em doc/5.reference/}''. The name of the help-patch for the class that is pointed to by \verb+c+ @@ -1446,7 +1442,7 @@ is changed to the symbol \verb+s+. Therefore, several similar classes can share a single help-patch. -Path-information is relative to the default helppath {\em doc/5.reference/}. +Path-information is relative to the default help path {\em doc/5.reference/}. \subsubsection{pd\_new} \begin{verbatim} @@ -1459,7 +1455,7 @@ returns a pointer to this instance. 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 \verb+t_object+-type is initialized. +the necessary data space-variable of the \verb+t_object+-type is initialised. This variable has to be passed as the \verb+owner+-object to the various inlet- and outlet-routines. @@ -1525,7 +1521,7 @@ Generates a new outlet for the object that is pointed at by \verb+owner+. The Symbol \verb+s+ indicates the type of the outlet. \begin{tabular}{c|l||l} -symbol & symbol-addresse & outlet-type \\ +symbol & symbol-address & outlet-type \\ \hline\hline ``bang'' & \verb+&s_bang+ & message (bang)\\ ``float'' & \verb+&s_float+ & message (float)\\ @@ -1545,11 +1541,11 @@ Signal-outlet must be declared with \verb+&s_signal+. Variables if the type \verb+t_object+ provide pointer to one outlet. Whenever a new outlet is generated, its address is stored in the -objectvariable \verb+(*owner).ob_outlet+. +object variable \verb+(*owner).ob_outlet+. If more than one message-outlet is needed, the outlet-pointers that are returned by \verb+outlet_new+ -have to be stored manually in the dataspace +have to be stored manually in the data space to address the given outlets. \subsubsection{outlet\_bang} @@ -1588,7 +1584,7 @@ Outputs a ``list''-message at the outlet specified by \verb+x+. The list contains \verb+argc+ atoms. \verb+argv+ points to the first element of the atom-list. -Independet of the symbol \verb+s+, the selector ``list'' will precede +Independent of the symbol \verb+s+, the selector ``list'' will precede the list. To make the code more readable, @@ -1611,8 +1607,8 @@ 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 identified as instances of signalclasses. +Whenever pd's audio engine is started, +all objects that provide a ``dsp''-method are identified as instances of signal classes. \paragraph{DSP-method} @@ -1620,10 +1616,10 @@ all objects that provide a ``dsp''-method are identified as instances of signalc void my_dsp_method(t_mydata *x, t_signal **sp) \end{verbatim} -In the ``dsp''-method a classmethod for signal-processing +In the ``dsp''-method a class method for signal-processing is added to the DSP-tree by the function \verb+dsp_add+. -Apart from the dataspace \verb+x+ of the object, +Apart from the data space \verb+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 @@ -1640,16 +1636,16 @@ sp[2] & right out-signal \\ sp[3] & left out-signal \\ \end{tabular} -The signalstructure contains apart from other things: +The signal structure contains apart from other things: \begin{tabular}{c|l} structure-element & description \\ \hline -\verb+s_n+ & length of the signalvector \\ -\verb+s_vec+ & pointer to the signalvector \\ +\verb+s_n+ & length of the signal vector \\ +\verb+s_vec+ & pointer to the signal vector \\ \end{tabular} -The signalvector is an array of samples of type \verb+t_sample+. +The signal vector is an array of samples of type \verb+t_sample+. \paragraph{perform-routine} \begin{verbatim} @@ -1679,8 +1675,8 @@ The macro \verb+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, +The second argument is the type of the class-data space. +The third argument is a (dummy-)floating point-variable of the data space, that is needed to automatically convert ``float''-messages into signals if no signal is present at the signal-inlet. @@ -1696,7 +1692,7 @@ The perform-routine is called at each DSP-cycle. The second argument\verb+n+ 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 +Generally, pointers to the data space of the object and to the signal-vectors are reasonable. The length of the signal-vectors should also be passed to manipulate signals effectively. @@ -1704,7 +1700,7 @@ The length of the signal-vectors should also be passed to manipulate signals eff \begin{verbatim} float sys_getsr(void); \end{verbatim} -Returns the samplerate of the system. +Returns the sampler ate of the system. \subsection{functions: memory} \subsubsection{getbytes} @@ -1732,14 +1728,14 @@ Frees \verb+nbytes+ bytes at address \verb+*x+. void post(char *fmt, ...); \end{verbatim} -Writes a {\tt C}-string to the standarderror (shell). +Writes a {\tt C}-string to the standard error (shell). \subsubsection{error} \begin{verbatim} void error(char *fmt, ...); \end{verbatim} -Writes a {\tt C}-string as an error-message to the standarderror (shell). +Writes a {\tt C}-string as an error-message to the standard error (shell). The object that has output the error-message is marked and can be identified via the pd-menu {\em Find->Find last error}. |