[PD] templates, data, scalars etc.

[Orm Finnendahl]

Hi Miller,

I'm currently trying to understand the concepts behind PD's notion of
data, scalars, templates, pointers and such. I have to admit it is
quite cryptic to me as I couldn't find any documentation besides the
help patches.

My questions:

1. Is there any documentation anywhere, which explains, what exactly a
scalar means in pd's terminology? It seems, a scalar can be a list or
some reference to a subwindow with graphic capabilities.

2. How does the template/data mechanism work? 

If there isn't any documentation, I would volunteer to write one, once
I've fully understood the concept. For that purpose I attached my
understanding of it below (please correct me where I'm wrong, I'm just
trying to get grips with this and am thinking aloud (sorry for the
noise but maybe its helpful for somebody in the list)).

Three more things:

1. In version 0.35test16 a message is printed that the use of
   "template" is deprecated (while still working) and the use of
   "struct" is recommended (I couldn't find any documentation for that
   yet).

2. In my version an object named "scalar" doesn't exist anymore
   (therefore some of the help patches are broken).

3. In addition I couldn't find any documentation about the "show on
   parent" feature of canvases. Is there anything documented
   somewhere?

Yours,
Orm

---------------------------------------------------------

My understanding of the template/data concept in PD:

- any window in pd can contain one and only one template object. This
  object defines fields much like a struct declaration in C.  In order
  to allocate memory and data space for instances of the template you
  have to use a pd subpatch called pd <some-name>-data (does the name
  have to end in -data? Does it have to be a subpatch or could any pd
  window be used as data space and how would the top window be
  referenced?)
  
- In order to access the data you have to use pointers. To store the
  data, the "append" and "traverse" objects are needed: The append
  object appends values given in the left inlet to instances of a
  template of the form given as first argument. Which fields are
  accessed by the values in the inlets are specified in the remaining
  arguments of the append object. The instance (actual place), where
  to store the data has to be given in form of a pointer to the
  rightmost inlet of append (and it has nothing to do with the
  location of the template). As said above, the instance is given in
  form of a subpatch of pd. To set the pointer, you send its leftmost
  inlet a message "traverse pd-<name-of-subpatch>, bang".

  (Question: could any subpatch window name be used here and are there
  other ways to create instances for data storage apart from pd
  subpatches?).

- To clear the data you have to send a "clear" message to
  pd-<name-of-subpatch>. That clears any contents in the subpatch
  window. (Question: Are all the objects and patchcords gone forever?)

- To retrieve the values, you can use the get object (with template
  name and values to retrieve as arguments) and send it the pointer of
  the instance where to get it (again with traverse). Subsequent
  "next" messages to the pointer object will access the following
  fields.

  (Question: Is there a way to access, say the 5th element in this
  data structure directly, or is the data stored as linked list? How
  can I access the last element in the list?)

- This mechanism can be used for graphics by the use of
  "filledpolygon" and such. These objects take arguments about the
  size and colors. These arguments can also contain references to
  template fields in the same window. If graphics are used, the first
  two fields of the template in this window have to be floats. They
  specify the local x and y coordinates of the graphic to be
  drawn. (Question: Do the first fields have to be called x and y?)
  Any storage of an instance of the data to its subpatch window
  results in a drawing of all graphic-drawing objects in the same
  window as the referenced template object (What about the subwindows
  of the window, the template object is in?)