[PD] templates, data, scalars etc.

[Miller Puckette]

Hi Orm,

Well, documenting "scalars" or "data structures" is the main thing I have to
do before 0.35 can be considered "finished".  It looks like you've understood
what's going on pretty well, and if you don't mind, I'll borrow some of your 
text below for the documentation...

There's no more "scalar" "box" (text object), but rather, the word "scalar"
refers to the "data" objects themselves.  It's meant to be an oposite of
"array" and "list" -- arrays and lists have scalars as elements and scalars
may have arrays and lists as "slots" defined in "struct" objects.

THere's no way to get teh nth element of a list, nor its length; I'll add
that later but it will be by linear search, so not as efficient as looking
them up in arrays.

"show on parent" is the coolest new thing in 0.35, but isn't documented yet
either...

cheers
Miller

On Wed, Apr 03, 2002 at 05:39:07PM +0200, Orm Finnendahl wrote:
> 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?)
> 
> 
> 
>