running PF inside Pure Data.
----------------------------

there are 5 pd objects

[pf <class>]		run a PF script inside PD

[dsp2pf~ <size>]	convert dsp blocks to PF matrix events..
[pf2dsp~]		.. and back

[array2pf <array>]	read contents of PD array into PF matrix packet ..
[pf2array <array>]	.. and write back

the last 2 are really straightforward: they simply convert data. the
first one is what you need to do proper embedding.

* a class is implemented as a PF file. for example, see the
  "puredata/extra/pf_console.pd" abstraction, which uses the PD object
  [pf pd-console], implemented by "script/pd-console.pf".  (or
  anything in the PF load path called "pd-console.pf")

* all selectors sent to a [pf] object are prepended with "pd-". this
  is to avoid most 'random exection' since method handles are
  implemented as plain forth words.

* the class implementation in PF uses the following words:

  class <name>    define a new class. name refers to constructor.
  method <name>   declare a word as method (probably starts with "pd-") 
  handles <name>  set the behaviour of a method

* to interface scripts you usually would run at the command line or
  inside emacs, use the objects

  [pf_console]    to get a the PF console where you can type commands
  [pf_tick]       to create the time base of animations


pd words
--------

make-outlet    # --
make-inlet     # fromsymbol tosymbol --
send	       # atom symbol --
outlet	       # atom index --
done	       # ... --


message protocol
----------------

sending messages from PF -> PD uses the 'send' and 'outlet' words. the
list (boo 1 2 3) corresponds to the message |boo 1 2 3<

message reception works like this: suppose the [pf <blabla>] object
gets a PD message

		    |blabla 1 2 3<

this will result in the execution of the 'pd-blabla' word, which is
passed the remaining aruments in a list, so the sending is equivalent
to the forth code "(1 2 3) pd-blabla".

the 'done' word clears the data stack, (back to a predictable state),
and signals PD to continue execution.

(implementation detail: it does so by using a low-level message
protocol implemented in puredata/src/pdobj.c which interprets the
empty list as return. you can use this protocol to do a bit more fancy
stuff, for example implementing pd objects as proper tasks for
sequencing without using state machines. see script/puredata.pf for
more info)


remarks
-------

it's probably not a good idea to create lots of small objects: it's
probably easier to create some PF words and glue them together in a
larger object. this is how i use it, but who am i to judge usage.. i
am not going to implement a 'PD wrapper around PF', as i once planned
(a new version of PDP/3DP). anyone who wants to do so, please go
ahead.

one piece of advice though: if you do want to create a set of
wrappers, don't create a bunch of text files in the style of
script/pd-console.pf since wrappers are probably a lot easier to
generate automaticly.