[Gridflowcvs] [svn] commit: r3224  /trunk/doc/architecture.html
gridflowcvs at artengine.ca
gridflowcvs at artengine.ca
Thu Mar 13 23:23:01 EDT 2008
Author: matju
Date: Thu Mar 13 23:23:01 2008
New Revision: 3224
Log:
more cleanup
Modified:
trunk/doc/architecture.html
Modified: trunk/doc/architecture.html

 trunk/doc/architecture.html (original)
+++ trunk/doc/architecture.html Thu Mar 13 23:23:01 2008
@@ 14,13 +14,10 @@
</td></tr></table>
<blockquote>
=
<table bgcolor=3D"white" border=3D"2" cellspacing=3D"2" width=3D"100%">
<tr><td bgcolor=3D"black">
<img src=3D"images/black.png" height=3D"2" width=3D"1"></td></tr>

<tr><td height=3D"16">
 <h4>GridFlow 0.9.1  Reference Manual: Architecture</h4>

+<table bgcolor=3D"white" border=3D"0" cellspacing=3D"2" width=3D"100%">
+<tr><td bgcolor=3D"black"><img src=3D"images/black.png" height=3D"2" width=
=3D"1"></td></tr>
+
+<tr><td height=3D"16"><h4>GridFlow 0.9.1  Reference Manual: Architecture<=
/h4>
<ul>
<li><a href=3D"#Numbers">Numbers</a>
<li><a href=3D"#Grid_Literals">Grid Literals</a>
@@ 31,52 +28,32 @@
<li><a href=3D"#Bridges">Bridges</a>
</ul>
<br></td></tr>
<tr><td bgcolor=3D"black">
<img src=3D"images/black.png" height=3D"2" width=3D"1"></td></tr>

<tr><td><h4><a name=3D"Numbers">Numbers</a></h4></td></tr>
<tr><td> </td></tr>

<tr><td><p>Highperformance computation requires precise and quite peculia=
r =
 definitions of numbers and their representation.</p></td></tr>

<tr><td> </td></tr>

<tr><td><p>Inside most programs, numbers are written down as strings of =
+<tr><td bgcolor=3D"black"><img src=3D"images/black.png" height=3D"2" width=
=3D"1"></td></tr>
+
+<tr><td><h4><a name=3D"Numbers">Numbers</a></h4>
+<p>Highperformance computation requires precise and quite peculiar =
+ definitions of numbers and their representation.</p>
+<p>Inside most programs, numbers are written down as strings of =
bits. A bit is either zero or one. Just like the decimal system =
uses units, tens, hundreds, the binary system uses units, twos, =
 fours, eights, sixteens, and so on, doubling every time.</p></td></tr>

<tr><td> </td></tr>

<tr><td><p>One notation, called integer allows for only integer values to =
be =
+ fours, eights, sixteens, and so on, doubling every time.</p>
+<p>One notation, called integer allows for only integer values to be =
written (no fractions). when it is unsigned, no negative values may =
be written. when it is signed, one bit indicates whether the number =
is positive or negative. Integer storage is usually fixedsize, so you ha=
ve =
bounds on the size of numbers, and if a result is too big it "wraps aroun=
d", truncating the biggest =
 bits.</p></td></tr>

<tr><td> </td></tr>

<tr><td><p>Another notation, called floating point (or float) stores numbe=
rs using =
+ bits.</p>
+<p>Another notation, called floating point (or float) stores numbers using =
a fixed number of significant digits, and a scale factor that allows for =
huge numbers =
and tiny fractions at once. Note that 1/3 has periodic digits, but even 0=
.1 has periodic digits, =
in binary coding; so expect some slight roundings; the precision offered =
should be =
 sufficient for most purposes. Make sure the errors of rounding don't accu=
mulate, though.</p></td></tr>

<tr><td> </td></tr>

<tr><td><p>This little program of mine prints 1/3 in base 2 (only digits a=
fter the period): <kbd>ruby e 'x=3D1/3.0;for i in 0..52 do x*=3D2;y=3Dx.fl=
oor;print y;x=3Dy end;puts'</kbd></p></td></tr>

<tr><td> </td></tr>

<tr><td><p>In GridFlow, there are six kinds of numbers:</p></td></tr>

<tr><td> </td></tr>

<tr></tr><tr><td><table bgcolor=3D"black" border=3D"0" cellspacing=3D"1">
+ sufficient for most purposes. Make sure the errors of rounding don't accu=
mulate, though.</p>
+<p>This little program of mine prints 1/3 in base 2 (only digits after the=
period): <kbd>ruby e 'x=3D1/3.0;for i in 0..52 do x*=3D2;y=3Dx.floor;prin=
t y;x=3Dy end;puts'</kbd></p>
+<p>In GridFlow, there are six kinds of numbers:</p>
+<table bgcolor=3D"black" border=3D"0" cellspacing=3D"1">
<tr><td align=3D"left" valign=3D"top"><table bgcolor=3D"white" border=3D"0=
" cellpadding=3D"4" cellspacing=3D"1">
<tr><td class=3D"c3"><b>name</b></td>
+<tr>
+<td class=3D"c3"><b>name</b></td>
<td class=3D"c3"><b>aliases</b></td>
<td class=3D"c3"><b>range</b></td>
<td class=3D"c3"><b>size (bytes)</b></td>
@@ 94,156 +71,75 @@
<tr><td class=3D"c2">int64</td><td class=3D"c2">i64 l</td><td class=3D"c2"=
>=C2=B12<sup>63</sup></td><td class=3D"c2">8</td><td class=3D"c2">1</td><td=
class=3D"c2">...</td></tr> =
<tr><td class=3D"c1">float32</td><td class=3D"c1">f32 f</td><td class=3D"c=
1">=C2=B110<sup>=C2=B138</sup></td><td class=3D"c1">4</td><td class=3D"c1">=
23 bits =3D 0.000012% (about 7 digits)</td><td class=3D"c1">...</td></tr> =
<tr><td class=3D"c2">float64</td><td class=3D"c2">f64 d</td><td class=3D"c=
2">=C2=B110<sup>=C2=B1308</sup></td><td class=3D"c2">8</td><td class=3D"c2"=
>52 bits (about 15 digits)</td><td class=3D"c2">...</td></tr> </table></td>=
</tr></table></td></tr>

<tr><td> </td></tr>

<tr><td> </td></tr>
=
<tr><td bgcolor=3D"black">
<img src=3D"images/black.png" height=3D"2" width=3D"1"></td></tr>

<tr><td><h4><a name=3D"Grid_Literals">Grid Literals</a></h4></td></tr>
<tr><td> </td></tr>

<tr><td><p> =
 In every gridaccepting inlet, a list may be sent instead; if =
+<tr><td bgcolor=3D"black"><img src=3D"images/black.png" height=3D"2" width=
=3D"1"></td></tr>
+<tr><td><h4><a name=3D"Grid_Literals">Grid Literals</a></h4>
+<p> In every gridaccepting inlet, a list may be sent instead; if =
it consists only of integers, it will be converted to a =
onedimensional grid. Else it may contain a single "#" sign and =
integers on both sides of it, where the ones to the left of it are =
fed as arguments to an imaginary <kbd>[#redim]</kbd> object and the one t=
o the =
 right of it are fed through that <kbd>[#redim]</kbd>. </p></td></tr>

<tr><td> </td></tr>

<tr><td><p> =
 In every gridaccepting inlet, an integer or float may also be sent; =
+ right of it are fed through that <kbd>[#redim]</kbd>. </p>
+<p> In every gridaccepting inlet, an integer or float may also be sent; =
it will be converted to a zerodimensional grid (a <b>scalar</b>). </p></=
td></tr>
=
<tr><td> </td></tr>

<tr><td> </td></tr>
 =
<tr><td bgcolor=3D"black">
<img src=3D"images/black.png" height=3D"2" width=3D"1"></td></tr>

<tr><td><h4><a name=3D"Grid_Protocol">Grid Protocol</a></h4></td></tr>
<tr><td> </td></tr>

<tr><td><p> =
 a grid has an associated number type that defines what are the possible v=
alues for its elements =
 (and how much space it takes). the default is <b>int32</b>. </p></td></tr>

<tr><td> </td></tr>

<tr><td><p> =
 a singledimensional grid of 3 elements (a triplet) is called dim(3). a =
+
+<tr><td bgcolor=3D"black">
+<img src=3D"images/black.png" height=3D"2" width=3D"1"></td></tr>
+
+<tr><td><h4><a name=3D"Grid_Protocol">Grid Protocol</a></h4>
+<p> a grid has an associated number type that defines what are the possibl=
e values for its elements =
+ (and how much space it takes). the default is <b>int32</b>. </p>
+<p> a singledimensional grid of 3 elements (a triplet) is called dim(3). =
a =
threedimensional grid of 240 rows of 320 columns of triplets is called =
 dim(240,320,3). </p></td></tr>

<tr><td> </td></tr>

<tr><td><p> =
 There is a sequence in which elements of a Grid are stored and =
+ dim(240,320,3). </p>
+<p> There is a sequence in which elements of a Grid are stored and =
transmitted. Dimension 0 is called "first" and dimension N1 is =
called "last". They are called so because if you select a =
position in the first dimension of a grid, the selected part is of the sa=
me =
shape minus the first dimension; so in dim(240,320,3) if you select =
row 51 (or whichever valid row number), you get a dim(320,3). if you sele=
ct =
 a subpart two more times you get to a single number. </p></td></tr>

<tr><td> </td></tr>

<tr><td><p> =
 At each such level, elements are sent/stored in their numeric order, =
+ a subpart two more times you get to a single number. </p>
+<p> At each such level, elements are sent/stored in their numeric order, =
and are numbered using natural numbers starting at 0. This ordering usual=
ly =
 does not matter, but sometimes it does. Most notably, <kbd>[#import]</kbd=
>, <kbd>[#export]</kbd> and <kbd>[#redim]</kbd> care about it. </p></td></t=
r>

<tr><td> </td></tr>

<tr><td><p> =
 On the other hand, order of dimensions usually does matter; this is =
+ does not matter, but sometimes it does. Most notably, <kbd>[#import]</kbd=
>, <kbd>[#export]</kbd> and <kbd>[#redim]</kbd> care about it. </p>
+<p> On the other hand, order of dimensions usually does matter; this is =
what distinguishes rows from columns and channels, for example. =
 Most objects care about the distinction. </p></td></tr>

<tr><td> </td></tr>

<tr><td><p> =
 A grid with only 1 element in a given dimension is different from one =
+ Most objects care about the distinction. </p>
+<p> A grid with only 1 element in a given dimension is different from one =
lacking that dimension; it won't have the same meaning. You can use this =
 property to your advantage sometimes. </p></td></tr>

<tr><td> </td></tr>

<tr><td><p> =
 Zerodimensional grids exist. They are called dim(). They can only contai=
n =
 a single number. </p></td></tr>

<tr><td> </td></tr>

<tr><td> </td></tr>
 =
<tr><td bgcolor=3D"black">
<img src=3D"images/black.png" height=3D"2" width=3D"1"></td></tr>

<tr><td><h4><a name=3D"Picture_Protocol">Picture Protocol</a></h4></td></t=
r>
<tr><td> </td></tr>

<tr><td><p><i>This section is useful if you want to know what a picture is =
 in terms of a grid. </i></p></td></tr>

<tr><td> </td></tr>

<tr><td><p>A picture is a threedimensional Grid: </p><ul> <li><b>0</b> : =
rows</li> <li><b>1</b> : columns</li> <li><b>2</b> : channels</li> </ul> <p=
></p></td></tr>

<tr><td> </td></tr>

<tr><td><p>Channels for the RGB color model are: </p><ul> <li><b>0</b> : r=
ed</li> <li><b>1</b> : green</li> <li><b>2</b> : blue</li> </ul> <p></p></t=
d></tr>

<tr><td> </td></tr>

<tr><td><p> =
 Because Grids are made of 32bit integers, a threechannel picture uses =
+ property to your advantage sometimes. </p>
+<p> Zerodimensional grids exist. They are called dim(). They can only con=
tain =
+ a single number. </p>
+<tr><td bgcolor=3D"black">
+<img src=3D"images/black.png" height=3D"2" width=3D"1"></td></tr>
+<tr><td><h4><a name=3D"Picture_Protocol">Picture Protocol</a></h4>
+<p><i>This section is useful if you want to know what a picture is in term=
s of a grid. </i></p>
+<p>A picture is a threedimensional Grid: </p><ul> <li><b>0</b> : rows</li=
> <li><b>1</b> : columns</li> <li><b>2</b> : channels</li> </ul>
+
+<p>Channels for the RGB color model are: </p><ul> <li><b>0</b> : red</li> =
<li><b>1</b> : green</li> <li><b>2</b> : blue</li> </ul>
+<p> Because Grids are made of 32bit integers, a threechannel picture us=
es =
96 bpp (bits per pixel), and have to be downscaled to 24 bpp (or 16 bpp) =
for display. That huge amount of slack is there because when you create =
your own effects you often have intermediate results that need to be of =
higher precision than a normal picture. Especially, results of multiplica=
tions =
are big and should not overflow before you divide them back to normal; =
and similarly, you can have negative values all over, as long as you take =
 care of them before they get to the display. </p></td></tr>

<tr><td> </td></tr>

<tr><td><p> =
 In the final conversion, high bits are just ignored. This means: black is =
+ care of them before they get to the display.
+<p> In the final conversion, high bits are just ignored. This means: blac=
k is =
0, maximum is 255, and values wrap like with <kbd>% 256</kbd>. If you wan=
t to =
 clip them, you may use <kbd>[# max 0]</kbd> and <kbd>[# min 255]</kbd> ob=
jects. </p></td></tr>

<tr><td> </td></tr>

<tr><td> </td></tr>
 =
<tr><td bgcolor=3D"black">
<img src=3D"images/black.png" height=3D"2" width=3D"1"></td></tr>

+ clip them, you may use <kbd>[# max 0]</kbd> and <kbd>[# min 255]</kbd> ob=
jects.
+
+<tr><td bgcolor=3D"black"><img src=3D"images/black.png" height=3D"2" width=
=3D"1"></td></tr>
<tr><td><h4><a name=3D"Numeric_Operators">Numeric Operators</a></h4></td><=
/tr>
<tr><td> </td></tr>

<tr><td><p>In the following table, A is the value entered to the =
left, and B is the value entered to the right.</p></td></tr>

<tr><td> </td></tr>

<tr><td><p>Angles are in hundredths of degrees. This means a full circle =
(two pi radians) is 36000. You convert from degrees to our angles =
by multiplying by 100. You convert from radians to our angles by =
multiplying by 18000/pi.</p></td></tr>

<tr><td> </td></tr>

<tr><td><p>Hyperbolic functions (tanh) work with our angles too, so the =
same conversions apply.</p></td></tr>

<tr><td> </td></tr>
=
<tr></tr><tr><td><table bgcolor=3D"black" border=3D"0" cellspacing=3D"1">
<tr><td align=3D"left" valign=3D"top"><table bgcolor=3D"white" border=3D"0=
" cellpadding=3D"4" cellspacing=3D"1">
@@ 300,58 +196,31 @@
<tr><td class=3D"c1">clip</td><td class=3D"c1"> like AB but overflow cau=
ses clipping instead of wrapping around (coming soon) </td><td class=3D"c1"=
></td><td class=3D"c1"></td></tr> =
<tr><td class=3D"c2">erf*</td><td class=3D"c2"> integral of e^(x*x) dx ..=
. (coming soon; what ought to be the scaling factor?) </td><td class=3D"c2"=
></td><td class=3D"c2"></td></tr> </table></td></tr></table></td></tr>
=
<tr><td> </td></tr>

<tr><td> </td></tr>
 =
<tr><td bgcolor=3D"black">
<img src=3D"images/black.png" height=3D"2" width=3D"1"></td></tr>

<tr><td><h4><a name=3D"Synchronisation">Synchronisation</a></h4></td></tr>
<tr><td> </td></tr>

<tr><td><p>In GridFlow you cannot send two grids in different inlets at th=
e =
+<tr><td bgcolor=3D"black">
+<img src=3D"images/black.png" height=3D"2" width=3D"1"></td></tr>
+
+<tr><td><h4><a name=3D"Synchronisation">Synchronisation</a></h4>
+<p>In GridFlow you cannot send two grids in different inlets at the =
same time. You have to use <kbd>[#finished]</kbd> together with (possibly)=
<kbd>[fork]</kbd> and <kbd>[#store]</kbd>, =
which can be cumbersome. If you don't do this, the result is undefined =
behaviour (or crash!).</p></td></tr>

<tr><td> </td></tr>

<tr><td><p>In GridFlow 0.7.1 this is beginning to change. <kbd>[#store]</k=
bd> and # now allow =
+behaviour (or crash!).</p>
+<p>In GridFlow 0.7.1 this is beginning to change. <kbd>[#store]</kbd> and =
# now allow =
rightinlet grids to be buffered if an operation is occuring on left inlet=
. This =
should make many circuits simpler. </p></td></tr>

<tr><td> </td></tr>

<tr><td><p>(more to come)</p></td></tr>

<tr><td> </td></tr>

<tr><td> </td></tr>
 =
<tr><td bgcolor=3D"black">
<img src=3D"images/black.png" height=3D"2" width=3D"1"></td></tr>

<tr><td><h4><a name=3D"Bridges">Bridges</a></h4></td></tr>
<tr><td> </td></tr>

<tr><td><p>Starting with GridFlow 0.6, GridFlow comes
+should make many circuits simpler. </p>
+<p>(more to come)</p>
+<tr><td bgcolor=3D"black"><img src=3D"images/black.png" height=3D"2" width=
=3D"1"></td></tr>
+
+<tr><td><h4><a name=3D"Bridges">Bridges</a></h4>
+<p>Starting with GridFlow 0.6, GridFlow comes
with a bridge (a converter) between Ruby and Pd. With GridFlow 0.9,
there's an additional converted between Tcl and Pd, and some of the
code of the main library now bypasses the bridge. The goal is to remove
all of the Ruby dependency in 2007. Historically, the bridge has served
the purpose of making GridFlow work on both PureData and jMax.</p></td></t=
r>

<tr><td> </td></tr>

<tr><td><p>Under the current design, the bridge is compiled separately of =
the main library, =
+the purpose of making GridFlow work on both PureData and jMax.</p>
+<p>Under the current design, the bridge is compiled separately of the main=
library, =
and is directly loaded by PureData; then the bridge starts Ruby and makes =
it load the main library; =
then the bridge hooks with the main library. </p></td></tr>
=
<tr><td> </td></tr>

<tr><td> </td></tr>
 =
<tr><td bgcolor=3D"black">
<img src=3D"images/black.png" height=3D"2" width=3D"1"></td></tr>
=
More information about the Gridflowcvs
mailing list