Update of /cvsroot/pure-data/doc/additional In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv21715
Added Files: pd-fileformat.html Log Message: added HTML file from puredata.org since the creators don't seem to be maintaining this
--- NEW FILE: pd-fileformat.html --- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<html>
<head> <title>Unofficial PD v0.37 fileformat specification</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><style type="text/css"><!--.Title { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 18px; font-style: normal; line-height: normal; font-weight: bold; font-variant: normal; text-transform: none; color: #000000; text-decoration: none; text-align: center;}.subTitle { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 12px; font-style: normal; line-height: normal; font-weight: normal; font-variant: normal; text-transform: none; color: #000000; text-decoration: none; text-align: center;}a:link { color: #0000FF; text-decoration: none;}a:visited { text-decoration: none; color: #0000FF;}a:hover { text-decoration: underline; color: #0000FF;}a:active { text-decoration: none; color: #0000FF;}body,td,th { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 12px; color: #000000;}body { background-color: #FFFFFF;}.code { font-family: "Courier New", Courier, mono; font-size: 12px; font-style: normal; line-height: normal; font-weight: normal; font-variant: normal; text-transform: none; color: #000000; text-decoration: none;}.Head { font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 16px; font-style: normal; line-height: normal; font-weight: normal; font-variant: normal; text-decoration: underline;}--></style></head><body><div align="center"> <p align="center"><span class="Title"><a name="0"></a>Unofficial PD v0.37 fileformat specification</span><br> <span class="subTitle">by <a href="mailto:simon3@student-kmt.hku.nl">Simon Asselbergs</a> and <a href="mailto:tjeerd@student-kmt.hku.nl">Tjeerd Sietsma</a><br> Hogeschool voor de Kunsten Utrecht<br> Faculty of Art Media and Technology <br> October 23rd 2004<br><br> Copyright (c) 2005 Free Software Foundation. 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 online at <a href="http://www.gnu.org/licenses/fdl.html">http://www.gnu.org/licenses/fdl.html</a>. Initial authors: Simon Asselbergs and Tjeerd Sietsma. </span></p></div><hr width="100%" size="2" noshade><div align="center"><a href="#1">introduction</a> | <a href="#2">records</a> | <a href="#3">wiring</a> | <a href="#4">elements and objects</a> | <a href="#5">common parameters</a> | <strong><a href="#6">reference</a></strong> | <a href="pd_fileformat.ebnf">EBNF version</a></div><hr width="100%" size="2" noshade><P class="Head"><a name="1"></a>Introduction</P><blockquote> <p>This file describes the fileformat of patchfiles (*.pd) of Miller Puckette's PureData.</p> <p> It is released because:</p></blockquote><ul> <li>PureData's patchfile format is officially undocumented.</li> <li>It may serve as a partial tutorial to help readers understand PureData better.</li></ul><blockquote> <p>This documents is currently unofficial, beware that there is no warranty whatsoever.<br> If you find this document incorrect or incomplete please send us an e-mail using the links at the top of this document.<br> There are a few things still unknown, we don't exclude the possibility those things are used for compatibility with Max.</p> <p><a href="#0">back to top</a> </p></blockquote><P class="Head"><br> <a name="2"></a>Records</P><blockquote> <p>The PD fileformat is a genuine custom textfile format, not to be confused with XML.<br> It consists of one ore more records.<br> Each record may cover multiply lines but they all have thesame syntax:</p> <p> <span class="code"><strong>#</strong>[data]<strong>;</strong>\r\n</span></p> <p>where[data] holds the record data, \r represents an ASCII code 13 carriage return character, and \n represents an ASCII code 10 line-feed character.<br> Let us take a closer look on the records contents.</p> <p>Each record consists of a chunk type, element type and optional parameters like this:</p> <p class="code"><strong>#</strong>[chunk_type] [element_type] [p1] [p2] [p3] [...]<strong>;\r\n</strong></p> <p>[chunk_type] is a sinlge character with only three possible values: "X" for an object, "N" for a new window, and finally "A" for array data.</p> <p>[element_type] is a predefined PD element. This declaration is also used for wires. <em>Object </em>elements are numbered in order of appearance in the file, all other elements are excluded from numbering. These numbers are pure virtual and can not be seen directly in the file.</p> <p>[p1] [p2] [p3] [...] are the required parameters for each element, this differences per element.</p> <p><a href="#0">back to top</a> </p></blockquote><P class="style13"><br> <span class="Head"><a name="3"></a>Wiring</span></P><blockquote> <p>Almost all objects can be interconnected with wires in PureData. Each wire is stored in the file using the following syntax: </p> <p class="code"><strong>#X connect</strong> [source] [outlet_number] [sink] [inlet_number]<strong>;\r\n</strong></p> <p>[source] Is the number of the object the data is coming from. [outlet-number] Represents the number of the outlet of the source object where the wire starts. Sequentially, [sink] is the number of the target object, and finally [inlet_number] specifies inlet of the target object to which the wired is connected.<br> Logically, the objects (again, <strong>connect</strong>s excluded) are numbered from 0 to the total number of objects in the file using the integer format. The inlets and outlets are numbered likewise.<br> Please keep this in mind, to prevent making often made off-by-one errors.</p> <p><a href="#0">back to top</a> </p></blockquote><P class="style13"><br> <span class="Head"><a name="4"></a>Elements and objects </span></P><blockquote> <p>There's a difference between elements and objects. Elements are the parts that together make up the entire layout of a patch, including windowsizes and position. Objects are the building blocks of PureData that contain functionality, gui-related or not. </p> <p>All other <strong>elements</strong> are used to build actual PureData objects:</p></blockquote><ul> <li>array - visual two dimensional array</li> <li>canvas - specifications for the windowsizes and position </li> <li>coords - used for graphs </li> <li>floatatom - number</li> <li>msg - message</li> <li>obj - object, empty, subpatch or gui: <ul> <li>bang</li> <li>toggle</li> <li>nbx</li> <li>vslider</li> <li>hslider</li> <li>vu</li> <li>canvas - gui element</li> <li>pd [name]</li> <li>[name]</li> </ul> </li> <li>restore - for exiting subwindows and graphs </li> <li>symbolatom - symbol</li> <li>text - comment</li></ul><blockquote> <p><a href="#0">back to top</a></p></blockquote><p><br> <span class="Head"><a name="5"></a>Common parameters</span></p><ul> <li><em>Positions and size</em>: As PureData uses a graphical interface every gui-related element (object, message, number, symbol, comment, bang, toggle, number2, vslider, hslider, vradio, hradio, vu, canvas, graph, array) have a horizontal and vertical position in the window that holds the (sub)patch.<br> Records of gui elements that have adjustable sizes also contain the horizontal and/or vertical size.<br> Positions and sizes are stored in pixels.<br> Note that in graphs (element: coords) the pixel sizes of its canvas are relative of the coordinates of the graph, when the option "graph on parent" is selected.</li> <li><em>Color</em>: Some graphical elements have color attributes. Per color only one signed integer value is stored that contains the three 8-bit color components (RGB).<br> Formula to calculate color attribute values:<br> <br> <strong>color = ( </strong>[red]<strong> * -65536) + ( </strong>[green]<strong> * -256) + ( </strong>[blue]<strong> * -1)<br> <br> </strong>Where [red], [green], [blue] obviously represent the three color components, their values range from 0 to 255.<br> They apply to the attributes [background color], [front color], [label color] of various elements.</li> <li><em>Fonts</em>: elements that have a unsigned integer [font] attribute (e.g. the element <strong>text</strong>) have a choice out of three different fonts:<br> 0 = Courier, 1 = Helvetica, 2 = Times. Courier is the only available fixed width font.<br> The [fontsize] attribute contains the font size in pixels.</li> <li><em>Labels</em>: the many GUI-elements that have a [label] attribute can be named. In its label string no spaces ASCII code 32 is allowed. It will generally be recognized as a seperator character for the next parameter/attribute.</li> <li><em>Other parameters</em>: Because of the difference between element parameters there is no default syntax for all elements. They may or may not look much like other elements, depending on their visual and functional similarities.</li></ul><blockquote> <p><a href="#0">back to top</a></p> </blockquote><br><hr width="100%" size="2" noshade><p> <span class="Head"><a name="6"></a>Reference</span></p><ul> <li><a href="#r1">A</a></li> <li><a href="#r2">N</a><ul> <li><a href="#r21">canvas</a></li> </ul> </li> <li><a href="#r3">X</a><ul> <li><a href="#r31">array</a></li> <li><a href="#r32">connect</a></li> <li><a href="#r33">coords</a></li> <li><a href="#r34">floatatom</a></li> <li><a href="#r35">msg</a></li> <li><a href="#r36">obj</a> <ul> <li><a href="#r361">bng</a></li> <li><a href="#r362">tgl</a></li> <li><a href="#r363">nbx</a></li> <li><a href="#r364">vsl</a></li> <li><a href="#r365">hsl</a></li> <li><a href="#r366">vradio</a></li> <li><a href="#r367">hradio</a></li> <li><a href="#r368">vu</a></li> <li><a href="#r369">cnv</a></li> </ul> </li> <li><a href="#r37">[name]</a></li> <li><a href="#r38">pd [name]</a></li> <li><a href="#r39">restore</a></li> <li><a href="#r3A">symbolatom</a></li> <li><a href="#r3B">text</a></li> </ul> </li></ul><blockquote><p><a href="#0">back to top</a></p></blockquote><br><hr width="100%" size="2" noshade><br><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r1"></a>A</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Announces array data </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td><span class="code"><strong>#A </strong>[p1] [p2] [p3] [...]<strong>;\r\n</strong></span></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[p1] [p2] [p3] [...] floating point variables representing array elements</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td>See Array</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td>Used only in combination of an array definition </td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r2"></a>N</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Announces a frameset</td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td><span class="code"><strong>#N </strong>[new_frame]<strong>;\r\n</strong></span></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[new_frame] new frameset, currently only a new patchwindow can be defined</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td>see canvas</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td>Currently used only for new canvas definitions</td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r21" id="r21"></a>canvas</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines window properties</td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td><span class="code"><strong>#N canvas </strong>[x_pos] [y_pos] [x_size] [y_size] [name] [open_on_load]<strong>;\r\n</strong></span></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position offset of frameset (window)<br> [y_pos] - vertical position offset of frameset (window)<br> [x_size] - horizontal size of frameset (window)<br> [y_size] - vertical size of frameset (window)<br> [name] - name / handle of frameset <br> [open_on_load] - when flag is set the canvas is opened when the patch is loaded</td> </tr> <tr> <td valign="top"><div align="right">Example:</div></td> <td class="code">#N canvas 0 0 452 302 12;</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code"> #N canvas 0 0 452 302 thiscanvas 0;<br> #X restore 41 136 pd thiscanvas;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td>In this example patch there are two canvas definitions.<br> The first example has a special syntax, the attributes [name] and [open_on_load] have been replaced by a [font_size] attribute. This is only the case when the canvas definition is the first record in the patchfile, to define the position and size of the main patcher window, and set the default font size. When a first canvas definition is absent the default values of PureData are used. Note that in this case you can alter the default font size with a command line parameter.<br> The second example shows a regular internal subpatch definition. Normally a canvas defintion is always postceeded with a restore element to define the position within the canvas, and the name of the subpatch.<br> Presumably, the canvas name in the canvas defintion and restore definition should be thesame.</td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r3"></a>X</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Announces regular elements </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X </strong>[element]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[element] - element definition</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X obj 50 36;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td>Used with <em>every</em> element definition except canvas definitions</td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r31"></a>array</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Array</td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X array </strong>[array_name] [array_size] <strong>float </strong>[save_flag]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[array_name] - name / handle of the array <br> [array_size] - total number of elements of an array<br> [save_flag] - with this flag set the array data is stored in the patch</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#N canvas 0 0 450 300 graph4 0;<br> #X array array3 10 float 1;<br> #A 0 0 0 0 0 0 0 0 0 0;<br> #X coords 0 1 99 -1 200 140 1;<br> #X restore 270 193 graph;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td>An array is a gui-form of a table, always visualised using a graph. Optionally the array data can be saved in the patch - which can be <strong>very</strong> space-consuming and CPU intensive when you want to store a large number of floating point values typed out in a textfile.</td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r32"></a>connect</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Wires GUI-elements</td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X connect </strong> [source] [outlet] [target] [inlet]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[source]<br> [outlet]<br> [target]<br> [inlet]</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X obj 30 27 midiin;<br> #X obj 26 59 midiout;<br> #X connect 0 0 1 0;<br> #X connect 0 1 1 1;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p><strong>Obj</strong>ects are virtually numbered in order of appearance in the file, starting from zero. Inlets and outlets of the objects are numbered likewise. <strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r33"></a>coords</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Visual ranges of a frameset (window) </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X coords</strong> [x_from] [y_to] [x_to] [y_from] [width] [heigth] [graph_on_parent]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_from] - first index to display <br> [y_to] - dynamic range of graph upper border<br> [x_to] - last index to display<br> [y_from] - dynamic range of graph lower border <br> [width] - relative horizontal size of graph <br> [heigth] - relative vertical size of graph <br> [graph_on_parent] - when set displayes child path, when unset graph is displayed like an object</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#N canvas 0 0 452 302 graph1 0;<br> #X coords 0 1 100 -1 200 140 1;<br> #X restore 58 26 graph;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>A coords statement must always be preceded with a canvas statement which also holds the graph name. <br> A coords statement must always be terminated with a restore statement that has the reserved handle <strong>graph<br> </strong>Off limit values will be displayed outside the graph in the PureData GUI.<strong><br> </strong></p> </td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r34"></a>floatatom</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines a number box </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X floatatom </strong> [x_pos] [y_pos] [width] [lower_limit] [upper_limit] [label_pos] [label] [receive] [send]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within window <br> [y_pos] - vertical position within window<br> [width] - number of digits <br> [lower_limit] - minimal value<br> [upper_limit] - maximum value <br> [label_pos] - label position relative to floatatom position. 0 = left, 1 = right, 2 = top, 3 = bottom <br> [label] - floatatom label/name<br> [receive] - receive symbol name <br> [send] - send symbol name</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X floatatom 32 26 5 0 0 0 - - -;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>When the value of [upper_limit] minus the value of [lower_limit] is less than one, or the [width] attribute is set to one, PureData resets these values both to zero.<br> Floatatom and symbolatom are the only elements that uses "-" characters to indicate that no value has been assigned to its attributes [label], [receive] and [send].<strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r35"></a>msg</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines a message </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X msg </strong> [x_pos] [y_pos] [p1] [p2] [p3] [...]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window <br> [y_pos] - vertical position within the window<br> [p1] [p2] [p3] [...] the content of the message</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X msg 61 48 read audio.wav;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>-<strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r36"></a>obj</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines an object </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X obj </strong> [x_pos] [y_pos] [object_name] [p1] [p2] [p3] [...]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window <br> [y_pos] - vertical position within the window<br> [object_name] - name of the object (optional) <br> [p1] [p2] [p3] [...] the parameters of the object (optional)</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X obj 55 50;<br> #X obj 132 72 trigger bang float;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>The first line is an example of an empty object. The second line describes a trigger object with its parameters<strong>.<br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r361"></a>bng</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines a bang </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X obj </strong> [x_pos] [y_pos] <strong>bng</strong> [size] [hold] [interrupt] [init] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] <strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window<br> [y_pos] - vertical position within the window <br> [size] - square size of the gui element<br> [hold] - hold time in milliseconds, ranges from 50 to 1000000000<br> [interrupt] - interrupt time in milliseconds, ranges from 10 to 250<br> [init] - bang on load <br> [send] - send symbol name <br> [receive] - receive symbol name <br> [label] - label<br> [x_off] - horizontal position of the label text relative to the upperleft corner of the object <br> [y_off] - vertical position of the label text relative to the upperleft corner of the object <br> [font] - font type <br> [fontsize] - font size<br> [bg_color] - background color <br> [fg_color] - foreground color <br> [label_color] - label color</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X obj 27 32 bng 15 10000 100 1 empty empty empty 0 -6 0 8 -262144 -1 -1;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>Hold time is for how long you see a flash when you click on the bang, interrupt time is for how long you don't see it flash when you click on this object while it's flashing.<strong><br> </strong>[send], [receive] and [label] cannot be named "empty", this is a reserved name for when no value is assigned. <strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r362"></a>tgl</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines a toggle </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X obj </strong> [x_pos] [y_pos] <strong>tgl</strong> [size] [init] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] [init_value] [default_value] <strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window<br> [y_pos] - vertical position within the window <br> [size] - square size of the gui element<br> [init] - set on load <br> [send] - send symbol name <br> [receive] - receive symbol name <br> [label] - label<br> [x_off] - horizontal position of the label text relative to the upperleft corner of the object <br> [y_off] - vertical position of the label text relative to the upperleft corner of the object <br> [font] - font type <br> [fontsize] - font size<br> [bg_color] - background color <br> [fg_color] - foreground color <br> [label_color] - label color<br> [init_value] - value sent when the [init] attribute is set<br> [default_value] - default value when the [init] attribute is not set</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X obj 29 44 tgl 15 1 empty empty empty 0 -6 192 8 -262144 -1 -1 234 234;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>[send], [receive] and [label] cannot be named "empty", this is a reserved name for when no value is assigned.<br> The [default_value] attribute can be changed in a patch and saved, this is why there are different values for [init_value] and [default_value]<strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r363"></a>nbx</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines a Number2 number box </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X obj </strong> [x_pos] [y_pos] <strong>nbx</strong> [size] [height] [min] [max] [log] [init] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] [log_height]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window<br> [y_pos] - vertical position within the window <br> [size] - number of digits the element displays <br> [height] - vertical size of element in pixels<br> [min] - minimum value, typically -1e+037<br> [max] - maximum value, typically 1e+037<br> [log] - linear when unset, logarithmic when set<br> [init] - when set outputs <br> [send] - send symbol name <br> [receive] - receive symbol name<br> [label] - label <br> [x_off] - horizontal position of the label text relative to the upperleft corner of the object<br> [y_off] - vertical position of the label text relative to the upperleft corner of the object<br> [font] - font type <br> [fontsize] - font size in pixels<br> [bg_color] - background color<br> [fg_color] - foreground color<br> [label_color] - label color <br> [log_height] - logarithmic steps, accepts values from 10 to 2000, default is 256</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X obj 39 48 nbx 5 14 -1e+037 1e+037 0 0 empty empty empty 0 -6 0 10 -262144 -1 -1 0 256;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>This element resembles the floatatom element, but is extended with gui and logarithmic parameters and (probably) more accurate.<br> The attributes [font], [font_size] and [fg_color] also apply to the digits.<strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r364"></a>vsl</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines a vertical slider </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X obj </strong> [x_pos] [y_pos] <strong>vsl</strong> [width] [height] [bottom] [top] [log] [init] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] [default_value] [steady_on_click]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window<br> [y_pos] - vertical position within the window <br> [width] - horizontal size of gui element <br> [height] - vertical size of gui element <br> [bottom] - minimum value <br> [top] - maximum value<br> [log] - when set the slider range is outputted logarithmically, otherwise it's output is linair<br> [init] - sends default value on patch load <br> [send] - send symbol name <br> [receive] - receive symbol name <br> [label] - label <br> [x_off] - horizontal position of the label text relative to the upperleft corner of the object<br>[y_off] - vertical position of the label text relative to the upperleft corner of the object<br> [font] - font type <br> [fontsize] - font size <br> [bg_color] - background color <br> [fg_color] - foreground color<br> [label_color] - label color <br> [default_value] - default value times hundred<br> [steady_on_click] - when set, fader is steady on click, otherwise it jumps on click</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X obj 50 38 vsl 15 128 0 127 0 0 empty empty empty 0 -8 0 8 -262144 -1 -1 0 1;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>The vertical slider object and the horizontal slider are the only objects which have a default value multiplied by hundred. This purpose is unknown.<strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r365"></a>hsl</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines a horizontal slider </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X obj </strong> [x_pos] [y_pos] <strong>hsl</strong> [width] [height] [bottom] [top] [log] [init] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] [default_value] [steady_on_click]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window<br> [y_pos] - vertical position within the window <br> [width] - horizontal size of gui element <br> [height] - vertical size of gui element <br> [bottom] - minimum value <br> [top] - maximum value<br> [log] - when set the slider range is outputted logarithmically, otherwise it's output is linair<br> [init] - sends default value on patch load <br> [send] - send symbol name <br> [receive] - receive symbol name <br> [label] - label <br> [x_off] - horizontal position of the label text relative to the upperleft corner of the object<br> [y_off] - vertical position of the label text relative to the upperleft corner of the object<br> [font] - font type <br> [fontsize] - font size <br> [bg_color] - background color <br> [fg_color] - foreground color<br> [label_color] - label color <br> [default_value] - default value times hundred<br> [steady_on_click] - when set, fader is steady on click, otherwise it jumps on click</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X obj 53 44 hsl 128 15 0 127 0 0 empty empty empty -2 -6 0 8 -262144 -1 -1 0 1;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>The horizontal slider object and the vertical slider are the only objects which have a default value multiplied by hundred. This purpose is unknown.<br> </p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r366"></a>vradio</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines a vertical radio button selector</td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X obj </strong> [x_pos] [y_pos] <strong>vradio</strong> [size] [new_old] [init] [number] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] [default_value]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window<br> [y_pos] - vertical position within the window <br> [size] - horizontal size and vertical size, depending on the number of radio buttons <br> [new_old] - send new and old value, or only the new value<br> [init] - send default value on init <br> [number] - amount of radio buttons <br> [send] - send symbol name <br> [receive] - receive symbol name <br> [label] - label <br> [x_off] - horizontal position of the label text relative to the upperleft corner of the object<br>[y_off] - vertical position of the label text relative to the upperleft corner of the object<br>[font] - font type <br>[fontsize] - font size <br>[bg_color] - background color <br>[fg_color] - foreground color<br>[label_color] - label color<br> [default_value] - default value to be sent on patch load when the [init] attribute has been set.</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X obj 48 42 vradio 15 1 0 8 empty empty empty 0 -6 0 8 -262144 -1 -1 0;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>The purpose of the [new_old] switch is unknown.<strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r367"></a>hradio</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines a horizontal radio button selector</td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X obj </strong> [x_pos] [y_pos] <strong>hradio</strong> [size] [new_old] [init] [number] [send] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [fg_color] [label_color] [default_value]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window<br> [y_pos] - vertical position within the window <br> [size] - vertical size and horizontal size, depending on the number of radio buttons <br> [new_old] - send new and old value, or only the new value<br> [init] - send default value on init <br> [number] - amount of radio buttons <br> [send] - send symbol name <br> [receive] - receive symbol name <br> [label] - label <br> [x_off] - horizontal position of the label text relative to the upperleft corner of the object<br> [y_off] - vertical position of the label text relative to the upperleft corner of the object<br> [font] - font type <br> [fontsize] - font size <br> [bg_color] - background color <br> [fg_color] - foreground color<br> [label_color] - label color<br> [default_value] - default value to be sent on patch load when the [init] attribute has been set.</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X obj -50 54 hradio 15 1 0 8 empty empty empty 0 -6 0 8 -262144 -1 -1 0;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>The purpose of the [new_old] switch is unknown.<strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r368"></a>vu</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines a VU-meter </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X obj </strong> [x_pos] [y_pos] <strong>vu</strong> [width] [height] [receive] [label] [x_off] [y_off] [font] [fontsize] [bg_color] [label_color] [scale] [?]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window<br> [y_pos] - vertical position within the window <br> [width] - horizontal size of element <br> [height] - vertical size of element <br> [receive] - receive symbol name <br> [label] - label<br> [x_off] - horizontal position of the label text relative to the upperleft corner of the object<br>[y_off] - vertical position of the label text relative to the upperleft corner of the object<br>[font] - font type <br>[fontsize] - font size <br>[bg_color] - background color <br> [label_color] - label color <br> [scale] - when set the logarithmic scale is displayed <br> [?] - unknown value, default is zero</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td>#X obj 40 44 vu 15 120 empty empty -1 -8 0 8 -66577 -1 1 0;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>We looked inside the source code but still couldn't see the purpose of the final value.<strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r369"></a>cnv</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines a canvas, a gui component </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X obj </strong> [x_pos] [y_pos] <strong>cnv</strong> [size] [width] [height] [send] [receive] [label] [x_off] [y_off] [font] [font_size] [bg_color] [label_color] [?]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window<br>[y_pos] - vertical position within the window<br> [size] - size of selectable square<br>[width] - horizontal size of the GUI-element<br>[height] - vertical size of the GUI-element<br>[send] - send symbol name <br>[receive] - receive symbol name <br>[label] - label <br>[x_off] - horizontal position of the label text relative to the upperleft corner of the object<br>[y_off] - vertical position of the label text relative to the upperleft corner of the object<br>[font] - font type <br>[fontsize] - font size <br>[bg_color] - background color<br>[label_color] - foreground color <br>[?] - unknown value, default is zero</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X obj 27 40 cnv 15 100 60 empty empty empty 20 12 0 14 -233017 -66577 0;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>We couldn't find the purpose of the final value.<strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r37"></a>[name]</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines an external subpatch or library patch </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X obj </strong> [x_pos] [y_pos] [name] [p1] [p2] [p3] [...] <strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window<br>[y_pos] - vertical position within the window<br> [name] - name of the subpatch / library patch<br> [p1] [p2] [p3] [...] - optional parameters</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#X obj 121 102 subpatch; </td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>If the external object isn't in the loaded libraries PureData searches in the folder of the main frame (window) to locate the object. <strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r38"></a>pd</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines an internal subpatch </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X restore </strong> [x_pos] [y_pos] <strong>pd</strong> [name]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window<br>[y_pos] - vertical position within the window<br> [size] - size of selectable square<br> [width] - horizontal size of the GUI-element<br> [name] - name of the subpatch</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#N canvas 0 0 454 304 inc 0;<br> #X obj 34 40 inlet;<br> #X obj 34 95 outlet;<br> #X obj 34 67 + 1;<br> #X connect 0 0 2 0;<br> #X connect 2 0 1 0;<br> #X restore 90 124 pd inc;<br> #X floatatom 90 99 5 0 0 0 - - -;<br> #X floatatom 90 151 5 0 0 0 - - -;<br> #X connect 0 0 2 0;<br> #X connect 1 0 0 0;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>Naturally the restore element which invokes a subpatch is preceded with a canvas element and the subpatch elements. <br> Objects within a subpatch are counted seperately from a parent frame (window).<strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r39"></a>restore</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Ends a canvas definition</td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X restore </strong> [x_pos] [y_pos] [type] [name]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td>[x_pos] - horizontal position within the window<br> [y_pos] - vertical position within the window<br> [type] - type of canvas, values are either "graph" or "pd"<br> [name] - name of the subpatch, only used when the [type] attribute is set to "pd"</td> </tr> <tr> <td valign="top"><div align="right">Example:</div></td> <td class="code">#N canvas 0 0 450 300 graph2 0;<br> #X coords 0 1 100 -1 200 140 1;<br> #X restore 27 30 graph;</td> </tr> <tr> <td width="85" valign="top"><div align="right">Example:</div></td> <td class="code">#N canvas 0 0 452 302 subpatch 0;<br> #X restore 64 69 pd subpatch;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>The restore element is used only in combination with canvas elements. There are two uses:<br> In the first example it defines a graph, in this case a coords element is required.<br> In the second example it defines a subpatch. In this case only the canvas attribute [name] and the restore attribute [name] should correlate.<strong><br> </strong></p> </td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r3A"></a>symbolatom</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines an symbol box </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X symbolatom </strong> [x_pos] [y_pos] [width] [lower_limit] [upper_limit] [label_pos] [label] [receive] [send]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td><p>[x_pos] - horizontal position within the window<br> [y_pos] - vertical position within the window<br> [width] - amount of digits/characters<br>[lower_limit] - minimum value <br> [upper_limit] - maximum value <br> [label_pos] - label position relative to floatatom position. 0 = left, 1 = right, 2 = top, 3 = bottom <br> [label] - label <br> [receive] - receive symbol value <br> [send] - send symbol value</p> </td> </tr> <tr> <td valign="top"><div align="right">Example:</div></td> <td class="code">#X symbolatom 36 37 10 0 0 0 - - -;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>When the value of [upper_limit] minus the value of [lower_limit] is less than one, PureData resets these values both to zero.<br> Symbolatom and floatatom are the only elements that uses "-" characters to indicate that no value has been assigned to its attributes [label], [receive] and [send].<strong></strong><strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p> <p> </p></blockquote><table width="100%" border="0"> <tr bgcolor="#CCCCCC"> <td colspan="2"><a name="r3B"></a>text</td> </tr> <tr> <td valign="top"><div align="right">Description:</div></td> <td>Defines a comment </td> </tr> <tr> <td width="85" valign="top"><div align="right">Syntax:</div></td> <td class="code"><strong>#X text </strong> [x_pos] [y_pos] [comment]<strong>;\r\n</strong></td> </tr> <tr> <td width="85" valign="top"><div align="right">Parameters:</div></td> <td><p>[x_pos] - horizontal position within the window<br> [y_pos] - vertical position within the window<br> [comment] - custom string, spaces allowed<br> </p></td> </tr> <tr> <td valign="top"><div align="right">Example:</div></td> <td class="code">#X text 28 25 comment;</td> </tr> <tr> <td valign="top"><div align="right">Remarks:</div></td> <td><p>ASCII return codes 13 and 10 are not stored, a semicolon character is preceded with the escape character backslash. <strong><br> </strong></p></td> </tr></table><blockquote> <p><a href="#6">back to reference index</a></p></blockquote><p> <br> <hr width="100%" size="2" noshade> <p> <a href="http://validator.w3.org/check?uri=referer"><img border="0" src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" height="31" width="88"></a> </p> </body> </html>
-
Hans-Christoph Steiner