HOWTO-externals-pt_br.tex

% format latexg -*- latex -*-

\documentclass[12pt, a4paper,english,titlepage]{article}  

%% HOWTO write an external for pd
%% Copyright (c) 2001-2006 by IOhannes m zmölnig
%%
%%  Permission is granted to copy, distribute and/or modify this document
%%  under the terms of the GNU Free Documentation License, Version 1.2
%%  or any later version published by the Free Software Foundation;
%%  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
%%  Texts.  A copy of the license is included in the LICENSE.txt file.

% \usepackage[latin1]{inputenc}
\usepackage[utf8]{inputenc}
% \usepackage[T1]{fontenc}
\usepackage[brazil]{babel}

\title{
Como escrever  \\
um External \\
para {\em Pure Data}
}

\author{
johannes m zmölnig \\
\\
{\em institute of electronic music and acoustics\footnote{http://iem.at}}
\\
{\em Traduzido por Anderson Goulart - global at codekab.com}
}

\date{}

\begin{document}
\maketitle

\begin{abstract}
Pd é um sistema gráfico de composição musical por computador em tempo real que segue
os tradicionais IRCAMs {\em ISPW-max}

Embora muitas funcionalidades são construídas dentro do Pd,
algumas vezes é difícil ou impossível criar um patch com uma certa funcionalidade
fora das primitivas e suas combinações.

Entretanto, Pd pode ser expandido com primitivas (``objetos'')
escritos em linguagens de programação complexas, como {\tt C/C++}. 

Este documento tenta explicar como construir tais primitivas em  {\tt C},
a linguagem popular utilizada para criar o Pd.
\end{abstract}


\vfill
\newpage

\tableofcontents

\vfill
\newpage

\section{definições e pré-requisitos}
Pd ({\em Pure Data}) refere-se ao ambiente gráfico de tempo real para composição musical pelo computador
criado por Miller~S.~Puckette.

Para compreender este documento é necessário saber usar o Pd e 
conhecer técnicas de programação especialmente em {\tt C}.

Para você escrever externals, um compilador que suporta o 
{\tt ANSI-C}-Standard como o {\em Gnu C-compiler} (gcc) nos sistemas Linux ou 
{\em Visual-C++} em plataformas Windows será necessário.

\subsection{classes, instâncias, objetos}
Pd está escrito na linguagem {\tt C}.
Devido a sua natureza gráfica, Pd é um novo sistema {\em orientado a objetos}.
Infelizmente {\tt C} não suporta muito bem o uso de classes.
Então, o código resultante não é tão elegante como em {\tt C++} seria, por exemplo.

Neste documento, a expressão {\em classe} refere-se à realização de um conceito 
combinando dados e manipuladores destes.

{\em Instâncias de uma classe} concretas são chamadas de {\em objetos}.

\subsection{internals, externals e bibliotecas}

Para evitar confusões de idéias, as expressões {\em internal}, {\em external} e
{\em biblioteca (library)} serão explicadas aqui.

\paragraph{Internal}
Um {\em internal} é uma classe construída dentro do Pd.
Várias primitivas como ``+'', ``pack'' ou ``sig\~\/'' são {\em internals}.

\paragraph{External}
Um {\em external} é uma classe não construída dentro do Pd, mas carregada em tempo de execução.
Uma vez carregada na memória do Pd, {\em externals} não se distinguem dos {\em internals}.

\paragraph{Biblioteca (Library)}
Uma {\em biblioteca (library)} é uma coleção de {\em externals} compilados dentro de um único arquivo binário. 

Arquivos-{\em biblioteca} seguem a seguinte convenção de nomes: 

\begin{tabular}{c||c|c|c}
biblioteca & linux&irix&Win32 \\
\hline
{\tt minha\_lib}&{\tt  minha\_lib.pd\_linux}&{\tt  minha\_lib.pd\_irix}&
{\tt  minha\_lib.dll}\\
\end{tabular}

A forma mais simples de uma {\em biblioteca} inclui exatamente um {\em external}
contendo o mesmo nome da {\em biblioteca}.

Diferente dos {\em externals}, {\em bibliotecas} podem ser importadas pelo Pd com operações especiais.
Depois de uma {\em biblioteca} ser importada,
todos os {\em externals} são carregados na memória e estão disponíveis como objetos.

Pd suporta alguns modos para importar as {\em bibliotecas}:

\begin{itemize}
\item via opção em linha de comando ``{\tt -lib minha\_lib}''
\item criando um objeto chamado ``{\tt minha\_lib}''
\item criando o arquivo .pd dentro do mesmo diretório da biblioteca
\end{itemize}

O primeiro e último métodos carregam a {\em biblioteca} na memória quando o Pd é iniciado.
O primeiro método é mais usado para {\em bibliotecas} que contém muitos {\em externals}.

O outro método deve ser utilizado em {\em bibliotecas} que contém exatamente 
um {\em external} com o mesmo nome.

Pd checa primeiro se a classe nomeada ``minha\_lib'' está carregada.
Se não é o caso \footnote{
Se a classe ``minha\_lib'' já existe, um objeto ``minha\_lib'' será instanciado e o procedimento
termina. 
Assim, nenhuma {\em biblioteca} foi carregada. 
Contudo, nenhuma {\em biblioteca} com um nome já utilizado em alguma outra classe, como por exemplo ``abs'',
pode ser carregada.}, é feita uma busca em todos os caminhos pelo arquivo 
``{\tt my\_lib.pd\_linux}''\footnote{ou outra extensão de arquivo dependente no sistema (s.a.)}.
Se tal arquivo é encontrado, todos os {\em externals} incluídos são carregados na memória chamando
a rotina \verb+minha_lib_setup()+.

Após carregar, a classe ``my\_lib'' é (de novo) procurada como (recentemente carregado) {\em external}.
Se encontrada, uma instância da classe é criada, caso contrário, a instanciação falha e um erro é impresso.
Todas as {\em external}-classes declaradas na {\em biblioteca} são carregadas a partir de agora.

\section{meu primeiro external: {\tt helloworld}}
Geralmente a primeira tentativa de se aprender uma linguagem de programação é através de uma aplicação ``hello world'' (olá mundo);

No nosso caso, uma classe de objeto deve ser criada e erá imprimir a linha ``hello world!!'' na saída
de erro a cada tentativa de habilitar com um ``bang''.

\subsection{a interface do Pd}
Para escrever um external, um interface bem definida é necessário. Ela é disponibilizada
pelo cabeçalho ``m\_pd.h''.

\begin{verbatim}
#include "m_pd.h"
\end{verbatim}

\subsection{uma classe e seu espaço de dados}
Primeiro, uma nova classe tem que ser preparada e seus dados definidos.

\begin{verbatim}
static t_class *helloworld_class;

typedef struct _helloworld {
  t_object  x_obj;
} t_helloworld;
\end{verbatim}

\verb+hello_worldclass+ será um ponteiro para a nova classe.

A estrutura \verb+t_helloworld+ (do tipo \verb+_helloworld+) é o espaço de
dados da classe.

Um elemento obrigatório dessa estrutura é a variável do tipo 
\verb+t_object+, a qual é utilizada para armazenar propriedades internas do objeto como
a representação gráfica do objeto ou dados sobre inlets e outlets.

\verb+t_object+ deve ser a primeira entrada da estrutura!

Por ser uma aplicação simples, o ``hello world'' não terá nenhuma variável
a mais na estrutura além do \verb+t_object+.

\subsection{espaço de métodos}
Além do espaço de dados, uma classe necessita de manipuladores (métodos) para
manipular os dados. 

Se uma mensagem é enviada para uma instância de nossa classe, um método é chamado.
Estes métodos são interfaces para o sistema de mensagens do Pd. 
Eles não retornam nada e, por isso, são do tipo \verb+void+.

\begin{verbatim}
void helloworld_bang(t_helloworld *x)
{
  post("Hello world !!");
}
\end{verbatim}

Este método tem o argumento do tipo \verb+t_helloworld+,
o qual nos permite manipular o espaço de dados.

Como queremos apenas imprimir ``Hello world!''
(e nosso espaço de dados é um pouco vazio), não iremos fazer qualquer tipo
de manipulação. 

O comando \verb+post(char *c,...)+ envia uma string para a saída de erro padrão. 
Um ENTER é adicionado automaticamente. 
O comando \verb+post+- funciona como o comando {\tt C} \verb+printf()+.

\subsection{geração de uma nova classe}
Para gerar uma nova classe, informações do espaço de dados e do espaço de métodos dessa classe
devem ser passadas ao Pd quandoa biblioteca é carregada.

Ao carregar a biblioteca ``my\_lib'',
Pd tenta carregar a função ``my\_lib\_setup()''.
Esta função (ou funções chamadas por ela) declara uma nova classe e suas propriedades.
É chamada apenas uma vez, quando a biblioteca é carregada.
Se a função falha (por exemplo, se o nome da função não estiver presente),
nenhum external da biblioteca será carregado. 

\begin{verbatim}
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);
}
\end{verbatim}

\paragraph{class\_new}

A função \verb+class_new+ cria uma nova classe e retorna um ponteiro para seu protótipo. 

O primeiro argumento é o nome simbólico da classe.

Os próximos 2 argumentos definem o construtor e o destrutor da classe. 

Sempre que um objeto da classe é criado em um patch do Pd, 
o construtor da classe \verb+(t_newmethod)helloworld_new+ instancia o objeto e 
inicializa o seu espaço de dados. 

Sempre que o objeto é destruído (seja por fechar o patch ou por deletar o objeto do patch), 
o destrutor libera a memória dinamicamente alocada. 
A memória alocada para os dados estáticos são automaticamente reservados e liberados.

Como não temos que prover um destrutor para este exemplo, o argumento é passado como ``0''.

Para habilitar o Pd reservar e liberar memória suficiente para o espaço de dados estático,
o tamanho da estrutura é passada no quarto argumento.

O quinto argumento tem influência na representação gráfica dos objetos da classe. 
O valor padrão é \verb+CLASS_DEFAULT+ ou simplesmente ``0''.

O restante dos argumentos definem os argumentos do objeto e seus tipos. 

Até 6 argumentos númericos e simbólicos podem ser definidos via 
\verb+A_DEFFLOAT+ e \verb+A_DEFSYMBOL+.
Se mais argumentos são necessários para o objeto, ou se a ordem dos tipos 
de átomos devem ser mais flexíveis,\verb+A_GIMME+ pode ser utilizada 
para passar uma lista arbitrária de átomos.

A lista de argumentos do objeto deve terminar com o valor ``0''.
Neste exemplo não temos argumentos para a classe.

\paragraph{class\_addbang}
Nós ainda temos que adicionar o espaço de métodos para a classe.

\verb+class_addbang+ adiciona o método para uma mensagem de ``bang'' para a classe
definida no primeiro argumento. 
O método adicionado é definido no segundo argumento.


\subsection{construtor: instanciação de um objeto}
A cada vez que um objeto é criado dentro de um patch no Pd, o construtor
definido no comando \verb+class_new+ gera uma nova instância da classe.

O construtor deve ser do tipo \verb+void *+.

\begin{verbatim}
void *helloworld_new(void)
{
  t_helloworld *x = (t_helloworld *)pd_new(helloworld_class);

  return (void *)x;
}
\end{verbatim}

Os argumentos do construtor dependem dos argumentos do objeto definidos com \verb+class_new+.

\begin{tabular}{l|l}
Argumentos do \verb+class_new+-&Argumentos do construtor\\
\hline
\verb+A_DEFFLOAT+&\verb+t_floatarg f+ \\
\verb+A_DEFSYMBOL+&\verb+t_symbol *s+ \\
\verb+A_GIMME+&\verb+t_symbol *s, int argc, t_atom *argv+
\end{tabular}

Como não há argumentos para a nossa classe ``hello world'', o construtor também não possui.

A função \verb+pd_new+ reserva a memória para o espaço de dados, inicializa as variáveis
que são internas do objeto e retorna um ponteiro para o espaço de dados.

A conversão (cast) do espaço de dados é necessária.

Geralmente, o construtor iria iniciar as variáveis do objeto. 
Entretanto, como não temos nenhuma, nada mais é necessário.

O construtor deve retornar um ponteiro para o espaço de dados instanciado.

\subsection{o código: \tt helloworld}

\begin{verbatim}
#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);
}
\end{verbatim}


\subsection{como compilar}

\begin{verbatim}
cc -DPD -O2 -funroll-loops -fomit-frame-pointer -fPIC -m64 -Wall -W -Wshadow -Wstrict-prototypes -Wno-unused -Wno-parentheses -Wno-switch -c helloworld.c
cc -m64 -export_dynamic -shared -o hello.pd_linux hello.o
\end{verbatim}

\subsection{como testar}

Para testar o objeto criado, crie um patch .pd dentro do diretório que contém
a biblioteca .pd\_linux gerada na seção anterior. Caso você queira salvar o patch
em outro diretório, lembre-se de alterar o PATH ()



\section{um simples external: {\tt contador}}

Agora queremos construir um contador como um external.
Um ``bang'' irá imprimir o valor do contador em um outlet e depois incrementá-lo em 1.

Esta classe é similar à primeira, 
mas o espaço de dados é expandido pela variável ``counter`` e o
resultado é escrito como uma mensagem para um outlet ao invés de
uma string na saída de erro padrão.

\subsection{variáveis objeto}
É claro, um contador precisa de uma variável de estado para armazenar seu valor atual.

Uma variável de estado que pertence à uma instância da classe, pertence ao espaço de dados.
\footnote{NT: Perceba que mudamos o nome da estrutura que pode ser salva em um arquivo
denominado counter.c}

\begin{verbatim}
typedef struct _counter {
  t_object  x_obj;
  t_int i_count;
} t_counter;
\end{verbatim}

A variável inteira \verb+i_count+ armazena o valor do contador.

\subsection{Argumentos do objeto}

É muito útil para um contador que um valor inicial possa ser definido pelo usuário.
Assim, este valor deve ser passado para o objeto no ato de sua criação.

\begin{verbatim}
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);
}
\end{verbatim}

Então nós temos um argumento adicional na função \verb+class_new+:
\verb+A_DEFFLOAT+ diz ao Pd que o objeto necessita de 1 argumento do tipo 
\verb+t_floatarg+.
Se nenhum argumento for passado, o padrão será ``0''.

\subsection{construtor}
O construtor tem algumas tarefas.
De um lado, uma variável deve ser inicializada. Do outro,
um outlet para o objeto deve ser criado.

\begin{verbatim}
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;
}
\end{verbatim}

O método construtor tem 1 argumento do tipo \verb+t_floatarg+ declarado na função ``setup''
do \verb+class_new+.
Este argumento é utilizado para inicializar o contador.

Um novo outlet é criado com ao função \verb+outlet_new+.
O primeiro argumento é um ponteiro para o objeto interno (t\_obj) para o qual
o outlet é criado. 

O segundo argumento é uma descrição simbólica do tipo de outlet.
Sabendo que o contador deve gerar na saída um valor numérico, seu tipo é ``float''.

\verb+outlet_new+ retorna um ponteiro para o novo outlet e salva este ponteiro na
variável \verb+t_object+ chamada \verb+x_obj.ob_outlet+.

Se somente um outlet é utilizado, o ponteiro não precisa ser adicionado no espaço de dados. 
Se mais de um outlet é utilizado, os ponteiros devem ser armazenados no espaço de dados, pois
a variável \verb+t_object+ pode armazenar somente um ponteiro de outlet. 

\subsection{o método contador}
Quando acionado, o valor do contador deve ser enviado para o outlet e
em seguida incrementado por 1.

\begin{verbatim}
void counter_bang(t_counter *x)
{
  t_float f=x->i_count;
  x->i_count++;
  outlet_float(x->x_obj.ob_outlet, f);
}
\end{verbatim}

A função \verb+outlet_float+ envia um valor de ponto flutuante (segundo argumento) para o outlet
especificado no primeiro argumento. 

Nós primeiro armazenamos o contador em um buffer (variável temporária) de ponto flutuante.
Assim o outlet enviará o valor antes do incremento. Depois o contador é incrementado. 

O que parece ser desnecessário a primeira vista, faz sentido depois de uma inspeção:
O buffer é criado como um \verb+t_float+, desde que o \verb+outlet_float+ 
espera um valor em ponto flutuante e uma conversão é inevitável.

Se o valor do contador for enviado para um outlet antes de ser incrementado,
isso pode gerar um indesejado (mas definido) comportamento:
Se o outlet do contador acionar seu próprio inlet diretamente, 
o método contador pode ser chamado embora o valor do contador ainda não esteja incrementado.
Normalmente não é isso que desejamos.

O mesmo (correto) resultado pode ser obtido com uma única linha, mas isso
iria obscurecer o problema de reentrância.

\subsection{o código: \tt contador}

\begin{verbatim}
#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);
}
\end{verbatim}


\section{a complex external: \tt counter}

The simple counter of the previous chapter can easily be extended to more complexity.
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 data space}

\begin{verbatim}
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;
\end{verbatim}

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 class objects should have methods for different messages,
like ``set'' and ``reset''.
Therefore the method space has to be extended too.

\begin{verbatim}
  counter_class = class_new(gensym("counter"),
        (t_newmethod)counter_new,
        0, sizeof(t_counter),
        CLASS_DEFAULT, 
        A_GIMME, 0);
\end{verbatim}

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}
  class_addmethod(counter_class,
        (t_method)counter_reset,
        gensym("reset"), 0);
\end{verbatim}

\verb+class_addmethod+ adds a method for an arbitrary selector to an class.

The first 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.

\begin{verbatim}
  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);
\end{verbatim}

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.

\begin{verbatim}
  class_sethelpsymbol(counter_class, gensym("help-counter"));
\end{verbatim}

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 class name.

An alternative help-patch can be defined with the 
\verb+class_sethelpsymbol+-command.

\subsection{construction of in- and outlets}

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

\begin{verbatim}
void *counter_new(t_symbol *s, int argc, t_atom *argv)
\end{verbatim}
Because of the declaration of arguments in the \verb+class_new+-function
with \verb+A_GIMME+,
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 number of arguments passed to the object\\
\verb+t_atom *argv+ & a pointer to a list of {\tt argc} atoms
\end{tabular}

\begin{verbatim}
  t_float f1=0, f2=0;

  x->step=1;
  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:
    break;
  }
  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;
\end{verbatim}

If three arguments are passed, these should be the {\em lower boundary},
the {\em upper boundary} and the {\em step width}.

If only two arguments are passed, the step-width defaults to ``1''.
If only one argument is passed, this should be the {\em initial value} of the counter with
step-width of ``1''.

\begin{verbatim}
  inlet_new(&x->x_obj, &x->x_obj.ob_pd,
        gensym("list"), gensym("bound"));
\end{verbatim}

The function \verb+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 first inlet is always ``active''.

The first two arguments of the \verb+inlet_new+-function are
pointers to the interna of the object and to the graphical presentation of the object.

The symbolic selector that is specified 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:
\begin{itemize}
\item The substituting selector has to be declared by \verb+class_addmethod+
in the setup-routine.
\item It is possible to simulate a certain right inlet, by sending a message with
this inlet's selector to the leftmost inlet.
\item 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.
\end{itemize}

\begin{verbatim}
  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 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 data space-memory,
where other objects can write too.

``Passive'' inlets can be created for pointers, symbolic or
numerical (floating point\footnote{
That's why the {\tt step}-width of the class\/data space is realized as {\tt t\_float}.})
values.


\begin{verbatim}
  x->f_out = outlet_new(&x->x_obj, &s_float);
  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\/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 method space}

The method for the ``bang''-message has to full fill the more complex tasks.

\begin{verbatim}
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);
    }
  }
  outlet_float(x->f_out, f);
}
\end{verbatim}

Each outlet is identified by the \verb+outlet_...+-functions via the
pointer to this outlets.

The remaining methods still have to be implemented:

\begin{verbatim}
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;
}
\end{verbatim}

\subsection{the code: \tt counter}

\begin{verbatim}
#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)
{
  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:
  case 3:
    x->step=atom_getfloat(argv+2);
  case 2:
    f2=atom_getfloat(argv+1);
  case 1:
    f1=atom_getfloat(argv);
    break;
  case 0:
    break;
  }
  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"),
        A_DEFFLOAT, A_DEFFLOAT, 0);

  class_sethelpsymbol(counter_class, gensym("help-counter"));
}
\end{verbatim}


\section{a signal-external: {\tt pan\~\/}}
Signal classes are normal Pd-classes, that offer additional methods for signals.


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 signal classes end with a tilde \~\/.

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.
The mixing-factor between 0 and 1 is defined via a \verb+t_float+-message
on a third inlet.

\subsection{variables of a signal class}
Since a signal-class is only an extended normal class,
there are no principal differences between the data spaces.

\begin{verbatim}
typedef struct _pan_tilde {
  t_object x_obj;

  t_sample f_pan;
  t_float  f;
} t_pan_tilde;
\end{verbatim}

Only one variable \verb+f_pan+ for the {\em mixing-factor} of the panning-function is needed.

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

\subsection{signal-classes}

\begin{verbatim}
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);
}
\end{verbatim}

A method for signal-processing has to be provided by each signal class.

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 recognised as signal class.

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
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 signal class.
The second argument is the type of the class's data space.

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}

\begin{verbatim}
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;
}
\end{verbatim}

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

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

\subsection{DSP-methods}
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-data space, 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.\footnote{
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, finally there comes the leftmost out-signal.}

\begin{verbatim}
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);
}
\end{verbatim}

\verb+dsp_add+ adds a {\em perform}-routine (as declared in the first 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 first in-signal, sp[1] represents the second in-signal and
sp[3] points to the out-signal.

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 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 signal class.

A pointer to an integer-array is passed to it.
This array contains the pointers, that were passed via \verb+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 return argument equals the
argument of the perform-routine plus
the number of pointer variables (as declared as the second argument
of \verb+dsp_add+) plus one.

\begin{verbatim}
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);
}
\end{verbatim}

Each sample of the signal vectors is read and manipulated in the \verb+while+-loop.


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
before having read the in-signal to avoid overwriting data that is not yet saved.

\subsection{the code: \tt pan\~\/}

\begin{verbatim}
#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]);
  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);
}
\end{verbatim}

\vfill
\newpage
\begin{appendix}

\section{Pd's message-system}
Non-audio-data are distributed via a message-system.
Each message consists of a ``selector'' and a list of atoms.

\subsection{atoms}

There are three kinds of atoms:
\begin{itemize}
\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 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.
The command \verb+gensym+ looks up a string in the lookup-table and
returns the address of the symbol.
If the string is not yet to be found in the table,
a new symbol is added.

Atoms of type {\em A\_POINTER} are not very important (for simple externals). 

The type of an atom \verb+a+ is stored in the structure-element \verb+a.a_type+.

\subsection{selectors}
The selector is a symbol that defines the type of a message.
There are five predefined selectors:
\begin{itemize}
\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}
\item ``{\tt symbol}'' labels a symbolic value.
The list of a ``symbol''-Message contains one single atom of type {\em A\_SYMBOL}
\item ``{\tt pointer}'' labels a pointer value.
The list of a ``pointer''-Message contains one single atom of type {\em A\_POINTER}
\item ``{\tt list}'' labels a list of one or more atoms of arbitrary type.
\end{itemize}

Since the symbols for these selectors are used quite often,
their address in the lookup-table can be queried directly,
without having to use \verb+gensym+:

\begin{tabular}{l||l|l}
selector&lookup-routine&lookup-address\\
\hline
\tt bang &\verb+gensym("bang")+ & \verb+&s_bang+ \\
\tt float &\verb+gensym("float")+ & \verb+&s_float+ \\
\tt symbol &\verb+gensym("symbol")+ & \verb+&s_symbol+ \\
\tt pointer &\verb+gensym("pointer")+ & \verb+&s_pointer+ \\
\tt list &\verb+gensym("list")+ & \verb+&s_list+ \\
--- (signal) &\verb+gensym("signal")+&\verb+&s_symbol+
\end{tabular}

Other selectors can be used as well.
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 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 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.

Apart from this there are many predefined types,
that should make the life of the programmer simpler.

Generally, Pd-types start with \verb|t_|.

\begin{tabular}{c|l}
Pd-type & description \\
\hline\hline
\verb+t_atom+& atom \\
\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+ & 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
\verb+t_class+ & a Pd-class \\
\verb+t_method+ & class-method \\
\verb+t_newmethod+ & pointer to a constructor (new-routine) \\
\end{tabular}


\section{important functions in ``m\_pd.h''}

\subsection{functions: atoms}

\subsubsection{SETFLOAT}
\begin{verbatim}
SETFLOAT(atom, f)
\end{verbatim}
This macro sets the type of \verb+atom+ to \verb+A_FLOAT+
and stores the numerical value \verb+f+ in this atom.

\subsubsection{SETSYMBOL}
\begin{verbatim}
SETSYMBOL(atom, s)
\end{verbatim}
This macro sets the type of \verb+atom+ to \verb+A_SYMBOL+
and stores the symbolic pointer \verb+s+ in this atom.

\subsubsection{SETPOINTER}
\begin{verbatim}
SETPOINTER(atom, pt)
\end{verbatim}
This macro sets the type of \verb+atom+ to \verb+A_POINTER+
and stores the pointer \verb+pt+ in this atom.

\subsubsection{atom\_getfloat}
\begin{verbatim}
t_float atom_getfloat(t_atom *a);
\end{verbatim}
If the type of the atom \verb+a+ is \verb+A_FLOAT+,
the numerical value of this atom else ``0.0'' is returned.

\subsubsection{atom\_getfloatarg}
\begin{verbatim}
t_float atom_getfloatarg(int which, int argc, t_atom *argv)
\end{verbatim}
If the type of the atom -- that is found at in the atom-list
\verb+argv+ with the length \verb+argc+ at the place \verb+which+ --
is \verb+A_FLOAT+, the numerical value of this atom else ``0.0'' is returned.

\subsubsection{atom\_getint}
\begin{verbatim}
t_int atom_getint(t_atom *a);
\end{verbatim}
If the type of the atom \verb+a+ is \verb+A_FLOAT+,
its numerical value is returned as integer else ``0'' is returned.

\subsubsection{atom\_getsymbol}
\begin{verbatim}
t_symbol atom_getsymbol(t_atom *a);
\end{verbatim}
If the type of the atom \verb+a+ is \verb+A_SYMBOL+,
a pointer to this symbol is returned, else a null-pointer ``0'' is returned.

\subsubsection{atom\_gensym}
\begin{verbatim}
t_symbol *atom_gensym(t_atom *a);
\end{verbatim}
If the type of the atom \verb+a+ is \verb+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.

\subsubsection{atom\_string}
\begin{verbatim}
void atom_string(t_atom *a, char *buf, unsigned int bufsize);
\end{verbatim}
Converts an atom \verb+a+ into a {\tt C}-string \verb+buf+.
The memory to this char-Buffer has to be reserved manually and
its length has to be declared in \verb+bufsize+.

\subsubsection{gensym}
\begin{verbatim}
t_symbol *gensym(char *s);
\end{verbatim}
Checks, whether the C-string \verb+*s+ has already been inserted into the symbol-table.
If no entry exists, it is created.
A pointer to the symbol is returned.

\subsection{functions: classes}
\subsubsection{class\_new}
\begin{verbatim}
t_class *class_new(t_symbol *name,
        t_newmethod newmethod, t_method freemethod,
        size_t size, int flags,
        t_atomtype arg1, ...);
\end{verbatim}
Generates a class with the symbolic name \verb+name+.
\verb+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 \verb+freemethod+ (without any return argument),
when the object is destroyed.

\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.
A (more or less arbitrary) combination of following objects is possible:

\begin{tabular}{l|l}
flag&description\\
\hline
\verb+CLASS_DEFAULT+ & a normal object with one inlet \\
\verb+CLASS_PD+ & \em object (without graphical presentation) \\
\verb+CLASS_GOBJ+ & \em pure graphical object (like arrays, graphs,...)\\
\verb+CLASS_PATCHABLE+ & \em a normal object (with one inlet) \\
\verb+CLASS_NOINLET+ & the default inlet is suppressed \\
\end{tabular}

Flags the description of which is printed in {\em italic}
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 type checked arguments can be passed to an object.
The list of argument-types are terminated by ``0''.

Possible types of arguments are:

\begin{tabular}{l|l}
\verb+A_DEFFLOAT+ & a numerical value \\
\verb+A_DEFSYMBOL+ & a symbolical value \\
\verb+A_GIMME+ & a list of atoms of arbitrary length and types \\
\end{tabular}

If more than six arguments are to be passed,
\verb+A_GIMME+ has to be used and a manual type-check has to be made.

\subsubsection{class\_addmethod}
\begin{verbatim}
void class_addmethod(t_class *c, t_method fn, t_symbol *sel,
    t_atomtype arg1, ...);
\end{verbatim}
Adds a method \verb+fn+ for a selector \verb+sel+ to a class \verb+c+.

The remaining arguments \verb+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,
\verb+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:

\begin{tabular}{l|l}
\verb+A_DEFFLOAT+ & a numerical value \\
\verb+A_DEFSYMBOL+ & a symbolical value \\
\verb+A_POINTER+ & a pointer \\
\verb+A_GIMME+ & a list of atoms of arbitrary length and types \\
\end{tabular}

\subsubsection{class\_addbang}
\begin{verbatim}
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-data space:

\verb+void my_bang_method(t_mydata *x);+

\subsubsection{class\_addfloat}
\begin{verbatim}
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-data space and
a floating point-argument:

\verb+void my_float_method(t_mydata *x, t_floatarg f);+

\subsubsection{class\_addsymbol}
\begin{verbatim}
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-data space and
a pointer to the passed symbol:

\verb+void my_symbol_method(t_mydata *x, t_symbol *s);+

\subsubsection{class\_addpointer}
\begin{verbatim}
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-data space and
a pointer to a pointer:

\verb+void my_pointer_method(t_mydata *x, t_gpointer *pt);+

\subsubsection{class\_addlist}
\begin{verbatim}
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-data space --
a pointer to the selector-symbol (always \verb+&s_list+),
the number of atoms and a pointer to the list of atoms:

\verb+void my_list_method(t_mydata *x,+

\verb+   t_symbol *s, int argc, t_atom *argv);+

\subsubsection{class\_addanything}
\begin{verbatim}
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-data space --
a pointer to the selector-symbol,
the number of atoms and a pointer to the list of atoms:

\verb+void my_any_method(t_mydata *x,+

\verb+   t_symbol *s, int argc, t_atom *argv);+

\subsubsection{class\_addcreator}
\begin{verbatim}
 void class_addcreator(t_newmethod newmethod, t_symbol *s, 
    t_atomtype type1, ...);
\end{verbatim}
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'' 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+.

\subsubsection{class\_sethelpsymbol}
\begin{verbatim}
void class_sethelpsymbol(t_class *c, t_symbol *s);
\end{verbatim}

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 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+
is changed to the symbol \verb+s+.

Therefore, several similar classes can share a single help-patch.

Path-information is relative to the default help path {\em doc/5.reference/}.

\subsubsection{pd\_new}
\begin{verbatim}
t_pd *pd_new(t_class *cls);
\end{verbatim}
Generates a new instance of the class \verb+cls+ and
returns a pointer to this instance.

\subsection{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 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.

\subsubsection{inlet\_new}
\begin{verbatim}
t_inlet *inlet_new(t_object *owner, t_pd *dest,
      t_symbol *s1, t_symbol *s2);
\end{verbatim}
Generates an additional ``active'' inlet for the object
that is pointed at by \verb+owner+.
Generally, \verb+dest+ points at ``\verb+owner.ob_pd+''.

The selector \verb+s1+ at the new inlet is substituted by the selector \verb+s2+.

If a message with selector \verb+s1+ appears at the new inlet,
the class-method for the selector \verb+s2+ is called.

This means
\begin{itemize}
\item The substituting selector has to be declared by \verb+class_addmethod+
in the setup-routine.
\item 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 (\verb+gensym("")+) as selector
makes it impossible to address a right inlet via the leftmost one.

\item 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.
\end{itemize}

\subsubsection{floatinlet\_new}
\begin{verbatim}
t_inlet *floatinlet_new(t_object *owner, t_float *fp);
\end{verbatim}
Generates a new ``passive'' inlet for the object that is pointed at by \verb+owner+.
This inlet enables numerical values to be written directly into the
memory \verb+fp+, without calling a dedicated method.

\subsubsection{symbolinlet\_new}
\begin{verbatim}
t_inlet *symbolinlet_new(t_object *owner, t_symbol **sp);
\end{verbatim}
Generates a new ``passive'' inlet for the object that is pointed at by \verb+owner+.
This inlet enables symbolic values to be written directly into the
memory \verb+*sp+, without calling a dedicated method.


\subsubsection{pointerinlet\_new}
\begin{verbatim}
t_inlet *pointerinlet_new(t_object *owner, t_gpointer *gp);
\end{verbatim}
Generates a new ``passive'' inlet for the object that is pointed at by \verb+owner+.
This inlet enables pointer to be written directly into the
memory \verb+gp+, without calling a dedicated method.

\subsubsection{outlet\_new}
\begin{verbatim}
t_outlet *outlet_new(t_object *owner, t_symbol *s);
\end{verbatim}
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-address & outlet-type \\
\hline\hline
``bang'' & \verb+&s_bang+ & message (bang)\\
``float'' & \verb+&s_float+ & message (float)\\
``symbol'' & \verb+&s_symbol+ & message (symbol) \\
``pointer'' & \verb+&s_gpointer+ & message (pointer)\\
``list'' & \verb+&s_list+ & message (list) \\
--- & 0 & message \\
\hline
``signal'' & \verb+&s_signal+ & signal \\
\end{tabular}

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 \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
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 data space
to address the given outlets.

\subsubsection{outlet\_bang}
\begin{verbatim}
void outlet_bang(t_outlet *x);
\end{verbatim}
Outputs a ``bang''-message at the outlet specified by \verb+x+.

\subsubsection{outlet\_float}
\begin{verbatim}
void outlet_float(t_outlet *x, t_float f);
\end{verbatim}
Outputs a ``float''-message with the numeric value \verb+f+
at the outlet specified by \verb+x+.

\subsubsection{outlet\_symbol}
\begin{verbatim}
void outlet_symbol(t_outlet *x, t_symbol *s);
\end{verbatim}
Outputs a ``symbol''-message with the symbolic value \verb+s+
at the outlet specified by \verb+x+.

\subsubsection{outlet\_pointer}
\begin{verbatim}
void outlet_pointer(t_outlet *x, t_gpointer *gp);
\end{verbatim}
Outputs a ``pointer''-message with the pointer \verb+gp+
at the outlet specified by \verb+x+.

\subsubsection{outlet\_list}
\begin{verbatim}
void outlet_list(t_outlet *x,
                 t_symbol *s, int argc, t_atom *argv);
\end{verbatim}
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.

Independent of the symbol \verb+s+, the selector ``list'' will precede
the list.

To make the code more readable,
\verb+s+ should point to the symbol list
(either via \verb+gensym("list")+ or via \verb+&s_list+)

\subsubsection{outlet\_anything}
\begin{verbatim}
void outlet_anything(t_outlet *x,
                     t_symbol *s, int argc, t_atom *argv);
\end{verbatim}
Outputs a message at the outlet specified by \verb+x+.

The message-selector is specified with \verb+s+.
It is followed by \verb+argc+ atoms.
\verb+argv+ points to the first element of the atom-list.

\subsection{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 audio engine is started,
all objects that provide a ``dsp''-method are identified as instances of signal classes.

\paragraph{DSP-method}

\begin{verbatim}
void my_dsp_method(t_mydata *x, t_signal **sp)
\end{verbatim}

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 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
clockwisely.

In case there are both two in- and out-signals, this means:

\begin{tabular}{c|r}
pointer & to signal \\
\hline\hline
sp[0] & left in-signal \\
sp[1] & right in-signal \\
sp[2] & right out-signal \\
sp[3] & left out-signal \\
\end{tabular}

The signal structure contains apart from other things:

\begin{tabular}{c|l}
structure-element & description \\
\hline
\verb+s_n+ & length of the signal vector \\
\verb+s_vec+ & pointer to the signal vector \\
\end{tabular}

The signal vector is an array of samples of type  \verb+t_sample+.

\paragraph{perform-routine}
\begin{verbatim}
t_int *my_perform_routine(t_int *w)
\end{verbatim}


A pointer \verb+w+ to an array (of integer) is passed to
the perform-routine that is inserted into the DSP-tree by \verb+class_add+.

In this array the pointers that are passed via \verb+dsp_add+ are stored.
These pointers have to be casted back to their original type.

The first pointer is stored at \verb+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 \verb+w+
plus the number of used pointers
(as defined in the second argument of \verb+dsp_add+) plus one.

\subsubsection{CLASS\_MAINSIGNALIN}
\begin{verbatim}
CLASS_MAINSIGNALIN(<class_name>, <class_data>, <f>);
\end{verbatim}
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-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.

No ``float''-methods can be used for signal-inlets, that are created this way.

\subsubsection{dsp\_add}
\begin{verbatim}
void dsp_add(t_perfroutine f, int n, ...);
\end{verbatim}
Adds the perform-routine \verb+f+ to the DSP-tree.
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 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.

\subsubsection{sys\_getsr}
\begin{verbatim}
float sys_getsr(void);
\end{verbatim}
Returns the sampler ate of the system.

\subsection{functions: memory}
\subsubsection{getbytes}
\begin{verbatim}
void *getbytes(size_t nbytes);
\end{verbatim}
Reserves \verb+nbytes+ bytes and returns a pointer to the allocated memory.

\subsubsection{copybytes}
\begin{verbatim}
void *copybytes(void *src, size_t nbytes);
\end{verbatim}
Copies \verb+nbytes+ bytes from \verb+*src+ into a newly allocated memory.
The address of this memory is returned.

\subsubsection{freebytes}
\begin{verbatim}
void freebytes(void *x, size_t nbytes);
\end{verbatim}
Frees \verb+nbytes+ bytes at address \verb+*x+.

\subsection{functions: output}
\subsubsection{post}
\begin{verbatim}
void post(char *fmt, ...);
\end{verbatim}

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 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}.


\section{Glossário das traduções}

A tradução de textos é uma arte que depende da leitura do tradutor, da intenção do autor e das representações semânticas de cada língua.
Neste trabalho algumas decisões sobre traduzir ou não alguns termos foram tomadas e 

external: não houve tradução. É o nome dado ao componente (objeto) escrito na linguagem de programação
que é ligado (carregado) pelo Pd. Funciona como outro objeto primitivo qualquer.

inlets: não houve tradução. Representa as entradas do objeto. 

outlets: não houve tradução. Representa as saídas do objeto.


\end{appendix}


\end{document}