GridFlow 0.8.0 - Reference Manual: Architecture

From 31beef22c1f976ee0d0b7d10157e726f234cff4e Mon Sep 17 00:00:00 2001 From: "N.N." Date: Tue, 4 Oct 2005 02:09:43 +0000 Subject: adding documentation in xml and html svn path=/trunk/; revision=3650 --- externals/gridflow/doc/architecture.html | 217 ++++ externals/gridflow/doc/architecture.xml | 395 +++++++ externals/gridflow/doc/format.html | 485 +++++++++ externals/gridflow/doc/format.xml | 780 ++++++++++++++ externals/gridflow/doc/index.html | 149 +++ externals/gridflow/doc/install.html | 122 +++ externals/gridflow/doc/install.xml | 140 +++ externals/gridflow/doc/internals.html | 206 ++++ externals/gridflow/doc/internals.xml | 228 ++++ externals/gridflow/doc/introduction.html | 125 +++ externals/gridflow/doc/license.html | 75 ++ externals/gridflow/doc/profiling.html | 151 +++ externals/gridflow/doc/project_policy.html | 98 ++ externals/gridflow/doc/project_policy.xml | 99 ++ externals/gridflow/doc/reference.html | 1070 +++++++++++++++++++ externals/gridflow/doc/reference.xml | 1591 ++++++++++++++++++++++++++++ 16 files changed, 5931 insertions(+) create mode 100644 externals/gridflow/doc/architecture.html create mode 100644 externals/gridflow/doc/architecture.xml create mode 100644 externals/gridflow/doc/format.html create mode 100644 externals/gridflow/doc/format.xml create mode 100644 externals/gridflow/doc/index.html create mode 100644 externals/gridflow/doc/install.html create mode 100644 externals/gridflow/doc/install.xml create mode 100644 externals/gridflow/doc/internals.html create mode 100644 externals/gridflow/doc/internals.xml create mode 100644 externals/gridflow/doc/introduction.html create mode 100644 externals/gridflow/doc/license.html create mode 100644 externals/gridflow/doc/profiling.html create mode 100644 externals/gridflow/doc/project_policy.html create mode 100644 externals/gridflow/doc/project_policy.xml create mode 100644 externals/gridflow/doc/reference.html create mode 100644 externals/gridflow/doc/reference.xml diff --git a/externals/gridflow/doc/architecture.html b/externals/gridflow/doc/architecture.html new file mode 100644 index 00000000..3009be34 --- /dev/null +++ b/externals/gridflow/doc/architecture.html @@ -0,0 +1,217 @@ + + +GridFlow 0.8.0 - Reference Manual: Architecture + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

GridFlow 0.8.0 - Reference Manual: Architecture

Numbers

+ +

Grid Literals

+ +

Grid Protocol

+ +

Picture Protocol

+ +

Numeric Operators

+ +

Synchronisation

+ +

Bridges

+ +

+

Numbers

High-performance computation requires precise and quite peculiar + definitions of numbers and their representation.

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.

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 fixed-size, so you have + bounds on the size of numbers, and if a result is too big it "wraps around", truncating the biggest + bits.

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 accumulate, though.

This little program of mine prints 1/3 in base 2 (only digits after the period): ruby -e 'x=1/3.0;for i in 0..52 do x*=2;y=x.floor;print y;x-=y end;puts'

In GridFlow, there are six kinds of numbers:

name	aliases	range	size (bytes)	precision	description
uint8	u8 b	0..255	1	1	+ unsigned 8-bit integer. + this is the usual size of numbers taken from files and cameras, and + written to files and to windows. (however this gets converted to `int32` + unless otherwise specified.)
int16	i16 s	±2¹⁵ = -32768..32767	2	1	...
int32	i32 i	±2³¹ = -2147483648..2147483647	4	1	+ signed 32-bit integer. + this is used for most computations.
int64	i64 l	±2⁶³	8	1	...
float32	f32 f	±10^±38	4	23 bits = 0.000012% (about 7 digits)	...
float64	f64 d	±10^±308	8	52 bits (about 15 digits)	...

Grid Literals

+ In every grid-accepting inlet, a list may be sent instead; if + it consists only of integers, it will be converted to a + one-dimensional 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 [#redim] object and the one to the + right of it are fed through that [#redim].

+ In every grid-accepting inlet, an integer or float may also be sent; + it will be converted to a zero-dimensional grid (a scalar).

Grid Protocol

+ a grid has an associated number type that defines what are the possible values for its elements + (and how much space it takes). the default is int32.

+ a single-dimensional grid of 3 elements (a triplet) is called dim(3). a + three-dimensional grid of 240 rows of 320 columns of triplets is called + dim(240,320,3).

+ There is a sequence in which elements of a Grid are stored and + transmitted. Dimension 0 is called "first" and dimension N-1 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 same + 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 select + a subpart two more times you get to a single number.

+ At each such level, elements are sent/stored in their numeric order, + and are numbered using natural numbers starting at 0. This ordering usually + does not matter, but sometimes it does. Most notably, [#import], [#export] and [#redim] care about it.

+ 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.

+ 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.

+ Zero-dimensional grids exist. They are called dim(). They can only contain + a single number.

Picture Protocol

This section is useful if you want to know what a picture is + in terms of a grid.

A picture is a three-dimensional Grid:

0 : rows
1 : columns
2 : channels

Channels for the RGB color model are:

0 : red
1 : green
2 : blue

+ Because Grids are made of 32-bit integers, a three-channel picture uses + 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 multiplications + 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.

+ In the final conversion, high bits are just ignored. This means: black is + 0, maximum is 255, and values wrap like with % 256. If you want to + clip them, you may use [# max 0] and [# min 255] objects.

Numeric Operators

In the following table, A is the value entered to the + left, and B is the value entered to the right.

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.

Hyperbolic functions (tanh) work with our angles too, so the + same conversions apply.

name	description	meaning in pixel context (pictures, palettes)	meaning in spatial context (indexmaps, polygons)
	A	no effect	no effect
	B	replace by	replace by
	A + B	brightness, crossfade	move, morph
	A - B	brightness, motion detection	move, motion detection
	B - A	negate then contrast	180 degree rotate then move
	A * B	contrast	zoom out
	A / B, rounded towards zero	contrast	zoom in
	A / B, rounded downwards	contrast	zoom in
	B / A, rounded towards zero	--	--
	B / A, rounded downwards	--	--
	A % B, modulo (goes with div)	--	tile
	B % A, modulo (goes with div)	--	--
	A % B, remainder (goes with /)	--	--
	B % A, remainder (goes with /)	--	--
	+ greatest common divisor	--	--
	+ least common multiple	--	--
	A or B, bitwise	bright munchies	bottomright munchies
	A xor B, bitwise	symmetric munchies (fractal checkers)	symmetric munchies (fractal checkers)
	A and B, bitwise	dark munchies	topleft munchies
	A * (2**(B % 32)), which is left-shifting	like *	like *
	A / (2**(B % 32)), which is right-shifting	like /,div	like /,div
	if A is zero then B else A	--	--
	if A is zero then zero else B	--	--
	the lowest value in A,B	clipping	clipping (of individual points)
	the highest value in A,B	clipping	clipping (of individual points)
	-1 when A<B; 0 when A=B; 1 when A>B.	--	--
	is A equal to B ? 1=true, 0=false	--	--
	is A not equal to B ?	--	--
	is A greater than B ?	--	--
	is A not greater than B ?	--	--
	is A less than B ?	--	--
	is A not less than B ?	--	--
	B * sin(A)	--	waves, rotations
	B * cos(A)	--	waves, rotations
	arctan(A/B)	--	find angle to origin (part of polar transform)
	B * tanh(A)	smooth clipping	smooth clipping (of individual points), neural sigmoid, fuzzy logic
	B * log(A) (in base e)	--	--
	floor(pow(a/256.0,256.0/b)*256.0)	gamma correction	--
	A**B, that is, A raised to power B	gamma correction	--
	absolute value of (A-B)	--	--
	randomly produces a non-negative number below A	--	--
	square root of A, rounded downwards	--	--
	(A-B) times (A-B)	--	--
	like A+B but overflow causes clipping instead of wrapping around (coming soon)	--	--
	like A-B but overflow causes clipping instead of wrapping around (coming soon)	--	--
	(A+B)/2	--	--
	square root of (AA+BB)	--	--
	integral of e^(-x*x) dx ... (coming soon; what ought to be the scaling factor?)	--	--

Synchronisation

In GridFlow you cannot send two grids in different inlets at the +same time. You have to use [#finished] together with (possibly) [fork] and [#store], +which can be cumbersome. If you don't do this, the result is undefined +behaviour (or crash!).

In GridFlow 0.7.1 this is beginning to change. [#store] and # now allow +right-inlet grids to be buffered if an operation is occuring on left inlet. This +should make many circuits simpler.

(more to come)

Bridges

Starting with version 0.6, GridFlow is Ruby-centric instead of jMax-centric. +jMax support has been added back as a Bridge.

Bridges, for the most part, plug into the FObject class, which is the common +root of most of GridFlow's classes. Under the current design, the bridge is +compiled separately, and is directly loaded by the host software; then the +bridge starts Ruby and makes it load the main GridFlow; then the bridge hooks +with the main part.

+GridFlow 0.8.0 Documentation
+Copyright © 2001,2002,2003,2004,2005 by Mathieu Bouchard +matju@artengine.ca +

+ + diff --git a/externals/gridflow/doc/architecture.xml b/externals/gridflow/doc/architecture.xml new file mode 100644 index 00000000..ec0c5a14 --- /dev/null +++ b/externals/gridflow/doc/architecture.xml @@ -0,0 +1,395 @@ + + + + + + + + + + + + +

+ +

High-performance computation requires precise and quite peculiar + definitions of numbers and their representation.

+ +

This little program of mine prints 1/3 in base 2 (only digits after the period): + ruby -e 'x=1/3.0;for i in 0..52 do x*=2;y=x.floor;print y;x-=y end;puts'

+ + +

In GridFlow, there are six kinds of numbers:

+ + + name + aliases + range + size (bytes) + precision + description + + unsigned 8-bit integer. + this is the usual size of numbers taken from files and cameras, and + written to files and to windows. (however this gets converted to int32 + unless otherwise specified.) + + ... + + signed 32-bit integer. + this is used for most computations. + + ... + ... + ... +

+ +

+ In every grid-accepting inlet, a list may be sent instead; if + it consists only of integers, it will be converted to a + one-dimensional 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 [#redim] object and the one to the + right of it are fed through that [#redim]. +

+ In every grid-accepting inlet, an integer or float may also be sent; + it will be converted to a zero-dimensional grid (a scalar). +

+ +

+ a grid has an associated number type that defines what are the possible values for its elements + (and how much space it takes). the default is int32. +

+ a single-dimensional grid of 3 elements (a triplet) is called dim(3). a + three-dimensional grid of 240 rows of 320 columns of triplets is called + dim(240,320,3). +

+ At each such level, elements are sent/stored in their numeric order, + and are numbered using natural numbers starting at 0. This ordering usually + does not matter, but sometimes it does. Most notably, [#import], + [#export] and [#redim] care about it. +

+ 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. +

+ 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. +

+ Zero-dimensional grids exist. They are called dim(). They can only contain + a single number. +

+ +

This section is useful if you want to know what a picture is + in terms of a grid. +

+ +

A picture is a three-dimensional Grid: + +

rows

columns

channels

+ +

Channels for the RGB color model are: + +

red

green

blue

+ +

+ In the final conversion, high bits are just ignored. This means: black is + 0, maximum is 255, and values wrap like with % 256. If you want to + clip them, you may use [# max 0] and [# min 255] objects. +

+ +

In the following table, A is the value entered to the + left, and B is the value entered to the right.

+ +

Hyperbolic functions (tanh) work with our angles too, so the + same conversions apply.

+ + + name + description + meaning in pixel context (pictures, palettes) + meaning in spatial context (indexmaps, polygons) + + + A + B + + + A + B + A - B + B - A + + + A * B + A / B, rounded towards zero + A / B, rounded downwards + B / A, rounded towards zero + B / A, rounded downwards + A % B, modulo (goes with div) + B % A, modulo (goes with div) + A % B, remainder (goes with /) + B % A, remainder (goes with /) + + + greatest common divisor + + + least common multiple + + + A or B, bitwise + A xor B, bitwise + A and B, bitwise + A * (2**(B % 32)), which is left-shifting + A / (2**(B % 32)), which is right-shifting + + + if A is zero then B else A + if A is zero then zero else B + the lowest value in A,B + the highest value in A,B + + + -1 when A<B; 0 when A=B; 1 when A>B. + is A equal to B ? 1=true, 0=false + is A not equal to B ? + is A greater than B ? + is A not greater than B ? + is A less than B ? + is A not less than B ? + + + B * sin(A) + B * cos(A) + arctan(A/B) + B * tanh(A) + B * log(A) (in base e) + floor(pow(a/256.0,256.0/b)*256.0) + A**B, that is, A raised to power B + + + absolute value of (A-B) + randomly produces a non-negative number below A + square root of A, rounded downwards + (A-B) times (A-B) + + + like A+B but overflow causes clipping instead of wrapping around (coming soon) + like A-B but overflow causes clipping instead of wrapping around (coming soon) + (A+B)/2 + square root of (A*A+B*B) + integral of e^(-x*x) dx ... (coming soon; what ought to be the scaling factor?) +

+ + + +

In GridFlow you cannot send two grids in different inlets at the +same time. You have to use [#finished] together with (possibly) [fork] and [#store], +which can be cumbersome. If you don't do this, the result is undefined +behaviour (or crash!).

+ +

In GridFlow 0.7.1 this is beginning to change. [#store] and # now allow +right-inlet grids to be buffered if an operation is occuring on left inlet. This +should make many circuits simpler. +

+ +

(more to come)

+ +

Starting with version 0.6, GridFlow is Ruby-centric instead of jMax-centric. +jMax support has been added back as a Bridge.

+ +

+ + diff --git a/externals/gridflow/doc/format.html b/externals/gridflow/doc/format.html new file mode 100644 index 00000000..325a6409 --- /dev/null +++ b/externals/gridflow/doc/format.html @@ -0,0 +1,485 @@ + + +GridFlow 0.8.0 - Reference Manual: Format Classes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +

+
+ GridFlow 0.8.0 - Reference Manual: Format Classes +

	Objects for Input/Output + + + + + + + Picture/Movie Formats + + + + + + + + + Acquisition Devices + + + Window Output + + + + + + + +
+
Objects for Input/Output

class #in
	+	+ method init (format, format_specific_part...) + If no arguments given, creates an input object for an unspecified + format. You then need to use the `"open"` command to link + a format handler to it. + If arguments given, the `"open"` command is immediately called + with those arguments. + Remember that most formats produce Dim[rows,columns,3] grids with + 0-255 values. (Most.) + inlet 0 method open (format, format_specific_part...) + This is the command that gives a particular resource + to a `[#out]` object. This is done through a "format" + (there is a list of formats in this manual). The other + arguments depend on the chosen format. The format may + be a file format or a protocol or a hardware device, etc. + The format called "file" is a special shortcut that autodetects the + type of file (by name suffix) and picks up the appropriate handler. + inlet 0 method open (filename) + This is a shortcut for `"open file"` followed by a filename. + The filename must contain a dot, else it will be seen as a handler name. + inlet 0 method close () + close may be necessary if you operate on `"/dev/video"`, + which can only be read by one at a time. otherwise it's + usually not necessary. + inlet 0 method int (frame_number) + selects one picture from a multi-picture format + and then does the same as a bang. + inlet 0 method set (frame_number) + selects one picture from a multi-picture format, + to be displayed by the next bang. + inlet 0 method bang () + sends a grid through the outlet. the grid may be the + result of reading from a file, acquiring from a device, + capturing from the screen etc. + this is format-specific. most formats + produce grid(rows columns {red green blue}). + In formats that read from a file, reading another picture + will continue if there are several pictures in the + same file, but if the end of file is reached instead, + it will rewind and send the first picture again. + see section "External Picture Formats". + inlet 0 method option (symbol selector, stuff...) + Obsolete. the word "option" is optional now. + inlet 0 method rewind () + rewinds to beginning of file if applicable. + inlet 0 method loop (bool flag) + controls the automatic looping of movies. + outlet 1 method int () + frame number of frame just sent, + for formats that have frame numbers. + outlet 1 method bang () + tried to read a frame that does not exist + (signals end of file) +

class #out
	+	+ method init (format, format_specific_part...) + If no arguments given, creates an output object for an unspecified + format. You then need to use the `"open"` command to link + a format handler to it. + If arguments given, the `"open"` command is immediately called + with those arguments. + Remember that most formats expect dim(rows,columns,3) grids with + 0-255 values. (Most.) + method init (integer rows, integer columns) + This alternate way to create an `[#out]` automatically calls `"open window"` and `"out_size rows columns"`. + inlet 0 method open (format, format_specific_part...) + This is the command that gives a particular resource + to a `[#out]` object. This is done through a "format" + (there is a list of formats in this manual). The other + arguments depend on the chosen format. The format may + be a file format or a protocol or a hardware device, etc. + inlet 0 method open file () + The format called "file" is a special shortcut that autodetects the + type of file (by name suffix) and picks up the appropriate handler. + inlet 0 method open (filename) + This is a shortcut for "open file" followed by a filename. + The filename must contain a dot, else it will be seen as a handler name. + inlet 0 method grid (grid grid) + this is format-specific. most formats + expect grid(rows columns {red green blue}). + In formats that write to a file, sending a 2nd picture + overwrites the first. + see section "External Picture Formats". + inlet 0 method close () + closes the file. usually not necessary. + inlet 0 method option (symbol selector, stuff...) + Obsolete. Omit the word "option" now. + inlet 0 method timelog (0,1 status) + when status=1, current time (unix clock) and time since last + frame-end are printed in the console. when status=0, it is off. + default is 0. + inlet 0 method rewind () + rewinds to beginning of file if applicable. + will overwrite the previous data. + outlet 0 method bang () + sent when a complete grid has been received. +

class #peephole
	+	+ + This object class only works with a X11-based version of Pd. + (e.g. on Linux, BSD, but not MacOS X). Similar to `[#out window]`, except it creates an inset in the patch you put it + in, and a scaled version of the picture appears in the inset. It also emits the same messages + as `[#out window]` and automatically scales cursor position according to the current scale factor. + The scale factor is decided automatically. method init (int height, int width) + All other methods are as in `[#out window]`.

class #mouse
	+	+ + This will process the "position" messages emitted by `[#out]` or `[#peephole]` in + useful ways. outlet 0 method list () + y,x coords of a click + outlet 1 method list () + y,x coords of a drag (any button is kept pressed) + outlet 2 method list () + y,x coords of an unclick + outlet 3 method list () + y,x coords of a move (no button is pressed) + outlet 4 method float () button 1 status + outlet 5 method float () button 2 status + outlet 6 method float () button 3 status + outlet 7 method float () + wheel difference: -1 = roll up; 1 = roll down. +

class #camera
	+	+ + Works about like `[#in videodev]` except you can right-click-open it to access all of the + camera settings visually.


+
Picture/Movie Formats

class format ppm #in/#out
	+	+ Subformat P6 only. + Max-number can only be 255 (24-bit RGB). method open ppm file (symbol filename) + opens the specified file, taken from the current + directory. + method open ppm gzfile (symbol filename) + same but for .ppm.gz files + method grid (grid(rows columns {r g b}) grid) + values 0-255 +

class format targa #in/#out
	+	+ Support for RGB-24 (3 channels) and RGBA-32 (4 channels) method open targa file (symbol filename) + opens the specified file, taken from the current + directory. + method open targa gzfile (symbol filename) + same but for .tga.gz files + method grid (grid(rows columns 3) grid) RGB-24 + method grid (grid(rows columns 4) grid) RGBA-32 +

class format jpeg #in/#out
	+	+ Support for RGB non-progressive method open jpeg file (symbol filename) + opens the specified file, taken from the current + directory. + method grid (grid(rows columns 3) grid) RGB-24 +

class format png #in
	+	+ Support for RGB non-progressive method open png file (symbol filename) + opens the specified file, taken from the current + directory. + method grid (grid(rows columns 1) grid) Y-8 (greyscale) + method grid (grid(rows columns 2) grid) YA-16 (greyscale and transparency) + method grid (grid(rows columns 3) grid) RGB-24 (colour) + method grid (grid(rows columns 4) grid) RGBA-32 (colour and transparency) +

class format quicktime #in/#out
	+	+ Support for .mov files. This format supports frame-seek and frame-tell. Uses the HW-QuickTime library aka QuickTime4Linux + (libquicktime.so). There is also a variant on the same library and that project + is just called LibQuickTime. Some versions of those libraries may include support for different codecs, + and some also may support entirely different wrapper formats such as AVI. On Macintosh, Apple QuickTime is used instead, but several of the following + messages may not be available. method open quicktime file (symbol filename) + method codec (symbol codec) + Allowed values are at least: raw, jpeg, png, mjpa, yuv2, yuv4. + Some other values may allowed, depending on the version of the library + and which codec plugins are installed. + Must be set before the first frame is written. + only applies to `[#out]`. Choosing a codec is important + because codecs influence greatly the speed of + encoding, the speed of decoding, + the size of the written file, and its fidelity to the + original content. Note that there exist other Apple-QuickTime + codecs that are not supported by HW-QuickTime. + method parameter (symbol key, int value) + Sets special codec-specific settings. + For example: `"parameter jpeg_quality 75"` + method framerate (int fps) + Sets the framerate of the file. + This is not used by GridFlow when reading a file, but other + programs usually care. + method colorspace (symbol colorspace) + Allowed values are rgb, rgba, bgr, bgra, yuv, yuva. + Normally you don't need this. + method size (int height, int width) + Forces a window size when writing. Usually this has to be used after + setting the framerate and codec and before setting the codec-parameters. + (Strange. Sorry.) + method force_size (int height, int width) + forces a window size when reading. + this is a workaround for a problem in HW-QuickTime. +

class format mpeg #in
	+	+ support for .mpeg files this format supports frame-seek and frame-tell. Two different libraries are available for dealing with + MPEG files. Those have different details, capabilities and quirks. In any case, GridFlow does not support importing audio from + those files. If you use the HeroineWarrior library, you may open several + mpeg files at once, but not with the GregWard library. Libraries may scream error messages in a rude way. By opposition to PPM and TARGA, this format driver only + allows a single MPEG stream per file (you cannot "cat" + several MPEG files together). Supports Rewind and Frame Select. method open mpeg file (symbol filename) + opens the specified file, taken from the current + directory. +

class format grid #in/#out
	+	+ + This is GridFlow's special file format. This is the only I/O + format that can hold anything that the `[#store]` object can. + This is the picture format that would support TCP connections + if that feature actually worked. More on this later. method open grid file (symbol filename) + opens the specified file, taken from the current + directory. + method open grid gzfile (symbol filename) + same but for .grid.gz files + method open grid tcp (symbol hostname, integer port) + dials an specified hostname/port on the InterNet or + compatible network. the TCP protocol is used. + method open grid tcpserver (integer port) + waits for a call (and answers) for this port on the + local machine via InterNet or compatible network. + Answers the call. + method type int32 () + output will be as 32 bit signed integers. + method type uint8 () + output will be as 8 bit unsigned integers. + method headerful () + cancels "headerless" (and back to reading .grid) + method headerless (dimensions...) + instead of reading .grid files with header, will read raw data, + faking a .grid header to itself. It will use the hereby specified + dimension list, as well as two other settings: `type` and `endian`. + When writing "raw" data, a file may be considered a long string of + base 256 digits (called bytes), but different computers have different + conventions for dealing with them: method endian () 1 : big: + A number will be written starting with the biggest digit. + This is the natural way on the Macintosh, Sun, Amiga, and so on. 2 : little: + A number will be written starting with the smallest digit. + This is the natural way on the Intel 386/Pentium. 3 : same: + A number will be written in whichever way is more natural + on this computer. The natural way is slightly faster to handle. + This is the default setting. +


+
Acquisition Devices

class format videodev #in
	+	+ method open (device) + Video4Linux-1 devices, RGB-24 only. Variable picture size. We have been testing it using cards of the BT-848 family, + such as Miro DC10plus and Hauppauge WinTV, using the `bttv.o` linux driver. + Also we have been testing using Logitech QuickCam (and similar Labtec hardware), + but don't use the `qce-ga` driver, which is buggy and obsolete: the `qc-usb` + works better. Some hardware doesn't support RGB, so you may have to select a YUV colorspace + (see below) and then use `[#yuv_to_rgb]`. Don't forget to also do `[# min 255]` and `[# max 0]`. If for some reason there's a bug that causes a driver to produce BGR instead of RGB, + so that red and blue are swapped, you can swap them back by filtering through a RGB-BGR + converter, such as `[#inner * + 0 {3 3 # 0 0 1 0 1 0 1 0 0}]`. color adjustments: method brightness (0-65535 level) + method hue (0-65535 level) + method colour (0-65535 level) + method contrast (0-65535 level) + method whiteness (0-65535 level) + method get (symbol attr) + gets a specific attribute. a message is sent through right outlet. + valid attributes are: brightness, hue, colour, contrast, whiteness. + method get () + gets all attributes. + other options: method channel (integer ) + method tuner (integer ) + method norm (integer ) + method frequency (integer ) + method transfer (symbol(read\|mmap) , integer ) 1 : mmap: + This is the normal (and fast) way of transferring pictures + from the camera. 2 : read: + Some cameras/drivers only support this instead of mmap. + In case of mmap, the extra numeric argument sets the + queue length in number of frames, so you can select an + appropriate tradeoff between efficiency and latency. + method colorspace (symbol colorspace) + Allowed values are: RGB24, YUV420P. + Use this if your driver doesn't support RGB24. + method size (height, width) + sets the input size, especially when using a video digitalizer + device. +


+
Window Output

class format x11 #in/#out
	+	+ supports 15,16,24,32-bit truecolor displays now also support 8-bit indexed displays, using a private colormap + configured as 3:3:2 RGB. When using 8-bit you can specify the + "use_stripes" option to use a completely different color scheme + involving R,G,B diagonal stripes, a kind of 6:6:6 RGB spread over three + pixels. If you are using Windows or MacOS 10: you will have to install + a X11 server. This will emulate Unix display on your OS. (note: + Unix systems also need a X11 server, but it's built-in and handles + the video driver directly). In the case of MacOS 10 and QNX that both + use non-X11 display technology on top of a basically Unix OS, the + OS comes with a X11 server, but it may be on a "bundled software" + CD. method open x11 () + synonym of "open x11 here". + method open x11 here () + connects to the default X11 server, + according to your environment variable "DISPLAY". + method open x11 local (integer display_number) + connects to a display server on this machine. + method open x11 remote (symbol host_name, integer display_number) + connects to a remote X11 display server using TCP. + Sorry, IP addresses are not supported. + Port number will be 6000 plus the display number, because + of the X11 standard. + method grid (grid(rows columns {red green blue}) grid) + resizes the window to the size of the grid; + encodes that grid in the display's pixel format; + also displays it if autodraw > 0 + the values must be in range 0-255, + or else they will be "wrapped". + + Destroying the object (or sending "close") should close the window. because of the design of Xlib, or if any of the connections + involved crashes, then the whole program has to be terminated. + (don't you love xlib). Something similar happens if you close any + of the windows yourself, but IIRC this could be fixed. only one window may be used per connection (to simplify matters; + this doesn't reduce flexibility). there is an additional argument that may be added to every `"open"` message; if you don't put it, a new toplevel window is created. + if you put "root" then the screen's wallpaper will be used instead + (it may fail to work with some popular window managers). You can also + put a window number, e.g. `0x28003ff`, you may connect to + an existing window; you can find out the number of a window by using + a tool like `xwininfo`, part of X11 standard tools. method out_size (integer height, integer width) + changes the window's size, just like sending a grid + dim(height,width,3) would. + this affects the size of screen captures too. + method draw () + forces a redraw of the window's contents. + method autodraw (0,1,2 level) 0 : draw() is never automatically invoked 1 : draw() is invoked after each grid is finished 2 : draw() is invoked incrementally after each row is + received. (but buffering may cause lines to come in groups + anyway) + method setcursor (0..63 cursor) + Selects one of the 64 predefined cursors of X11. (Note that if + your cursor table has them numbered from 0 to 126 using only even + numbers, then those cursor numbers are all doubled compared to + the ones GridFlow uses.) + method hidecursor () + This makes the cursor invisible. + outlet 0 method position (integer y, integer x, integer buttons) This is emitted every time the cursor moves inside + the window connected to this format handler. This is also + emitted when the cursor is dragging from inside to outside + the window. This is also emitted when a mouse button is pressed. The y and x coordinates are relative to the upper + right corner of the window. Specific button states may be + extracted from the button value by applying [>> + buttonnumber] and then checking whether the result is odd. + Button numbers normally are: 0 : Shift 1 : CapsLock 2 : Control 3 : Alternate 4 : NumLock 5 : ??? 6 : Meta 7 : ScrollLock 8 : Left Button 9 : Middle Button 10 : Right Button 11 : Wheel Up 12 : Wheel Down NOTE: This message form may become longer in the future, but the already defined parts will stay the same. + outlet 0 method keypress (integer y, integer x, integer buttons, symbol keyname) Similar to `position` above, but this is emitted when a + keyboard key is pressed while this format handler's window + is active. Keynames follow the X11 standard, similarly to PureData's [keyname] object. + The only exception is that keynames that are digits get prefixed by a capital D so that + they don't get mistaken for actual numbers. NOTE: This message form may become longer in the future, but the already defined parts will stay the same. + outlet 0 method keyrelease (integer y, integer x, integer buttons, symbol keyname) + Same as keypress but when a key gets released instead. NOTE: This message form may become longer in the future, but the already defined parts will stay the same. +

class format quartz #out
	+	+ + The equivalent of format x11 on MacOS 10.x, but with less features (sorry). method open () + opens a dim(240,320,3) rgb window (default). + method grid (grid(rows columns {red green blue}) grid) + Sends image to screen. Window will be resized to fit the image exactly. +

class format sdl #out
	+	+ method open () + Opens a dim(240,320,3) rgb window (default). + method grid (grid(rows columns {red green blue}) grid) + Sends image to screen. Window will be resized to fit the image exactly. +

class format aalib #out
	+	+ method open aalib (driver, args...) + method grid (grid(rows columns {white}) grid) + converts a greyscale image to an ascii image and possibly + displays it. note that the image is typically downscaled by + a factor of 2 by aalib itself. + method grid (grid(rows columns {ascii attr}) grid) + the inverse of "dump". Both together in a loop allow to + post-process aalib's buffer before displaying. Goes well + with "draw", "autodraw". + method print (int y, int x, int attr, symbol text) + method autodraw () + like X11's autodraw. + method draw () + like X11's draw. + method dump () + produces a Dim[y,x,2] grid whose two channels are + ascii character codes and character attributes. +

class format window #out
	+	+ method open window () + Equivalent to "open x11", but this can be set by putting a line like + this in the config file: `GridFlow.formats[:window] = GridFlow.formats[:x11]` + (and similarly other aliases can be created too) +


+
+ +GridFlow 0.8.0 Documentation +Copyright © 2001,2002,2003,2004,2005 by Mathieu Bouchard +matju@artengine.ca + +

+ + diff --git a/externals/gridflow/doc/format.xml b/externals/gridflow/doc/format.xml new file mode 100644 index 00000000..39f17cf3 --- /dev/null +++ b/externals/gridflow/doc/format.xml @@ -0,0 +1,780 @@ + + + + + + +

+ + + + + + + + + + If no arguments given, creates an input object for an unspecified + format. You then need to use the "open" command to link + a format handler to it. + + If arguments given, the "open" command is immediately called + with those arguments. + + Remember that most formats produce Dim[rows,columns,3] grids with + 0-255 values. (Most.) + + + + + + + This is the command that gives a particular resource + to a [#out] object. This is done through a "format" + (there is a list of formats in this manual). The other + arguments depend on the chosen format. The format may + be a file format or a protocol or a hardware device, etc. + + The format called "file" is a special shortcut that autodetects the + type of file (by name suffix) and picks up the appropriate handler. + + + + This is a shortcut for "open file" followed by a filename. + The filename must contain a dot, else it will be seen as a handler name. + + + close may be necessary if you operate on "/dev/video", + which can only be read by one at a time. otherwise it's + usually not necessary. + + + + selects one picture from a multi-picture format + and then does the same as a bang. + + + + selects one picture from a multi-picture format, + to be displayed by the next bang. + + + sends a grid through the outlet. the grid may be the + result of reading from a file, acquiring from a device, + capturing from the screen etc. + + this is format-specific. most formats + produce grid(rows columns {red green blue}). + + In formats that read from a file, reading another picture + will continue if there are several pictures in the + same file, but if the end of file is reached instead, + it will rewind and send the first picture again. + + see section "External Picture Formats". + + + + + + Obsolete. the word "option" is optional now. + + + rewinds to beginning of file if applicable. + + + + controls the automatic looping of movies. + + + + + + frame number of frame just sent, + for formats that have frame numbers. + + + + tried to read a frame that does not exist + (signals end of file) + + + + + + + + + + + + + If no arguments given, creates an output object for an unspecified + format. You then need to use the "open" command to link + a format handler to it. + + If arguments given, the "open" command is immediately called + with those arguments. + + Remember that most formats expect dim(rows,columns,3) grids with + 0-255 values. (Most.) + + + + + + This alternate way to create an [#out] automatically calls + "open window" and "out_size rows columns". + + + + + + This is the command that gives a particular resource + to a [#out] object. This is done through a "format" + (there is a list of formats in this manual). The other + arguments depend on the chosen format. The format may + be a file format or a protocol or a hardware device, etc. + + + The format called "file" is a special shortcut that autodetects the + type of file (by name suffix) and picks up the appropriate handler. + + + + This is a shortcut for "open file" followed by a filename. + The filename must contain a dot, else it will be seen as a handler name. + + + this is format-specific. most formats + expect grid(rows columns {red green blue}). + + In formats that write to a file, sending a 2nd picture + overwrites the first. + + see section "External Picture Formats". + + + closes the file. usually not necessary. + + + + + Obsolete. Omit the word "option" now. + + + + when status=1, current time (unix clock) and time since last + frame-end are printed in the console. when status=0, it is off. + default is 0. + + + rewinds to beginning of file if applicable. + will overwrite the previous data. + + + + + sent when a complete grid has been received. + + + + + +

+ This object class only works with a X11-based version of Pd. + (e.g. on Linux, BSD, but not MacOS X). +

Similar to [#out window], except it creates an inset in the patch you put it + in, and a scaled version of the picture appears in the inset. It also emits the same messages + as [#out window] and automatically scales cursor position according to the current scale factor. + The scale factor is decided automatically. +

+ + + + +

All other methods are as in [#out window].

+ + + This will process the "position" messages emitted by [#out] or [#peephole] in + useful ways. + + y,x coords of a click + + + y,x coords of a drag (any button is kept pressed) + + + y,x coords of an unclick + + + y,x coords of a move (no button is pressed) + + button 1 status + button 2 status + button 3 status + + wheel difference: -1 = roll up; 1 = roll down. + + + + Works about like [#in videodev] except you can right-click-open it to access all of the + camera settings visually. + +

+ +

+ + + + +

Subformat P6 only. + Max-number can only be 255 (24-bit RGB). +

+ + + + opens the specified file, taken from the current + directory. + + + + + same but for .ppm.gz files + + + + + values 0-255 + + + + + +

Support for RGB-24 (3 channels) and RGBA-32 (4 channels)

+ + + + opens the specified file, taken from the current + directory. + + + + + same but for .tga.gz files + + + RGB-24 + RGBA-32 + + + + +

Support for RGB non-progressive

+ + + + opens the specified file, taken from the current + directory. + + + + RGB-24 + + + + + +

Support for RGB non-progressive

+ + + + opens the specified file, taken from the current + directory. + + + Y-8 (greyscale) + YA-16 (greyscale and transparency) + RGB-24 (colour) + RGBA-32 (colour and transparency) + + + +

Support for .mov files.

This format supports frame-seek and frame-tell.

Uses the HW-QuickTime library aka QuickTime4Linux + (libquicktime.so). There is also a variant on the same library and that project + is just called LibQuickTime.

Some versions of those libraries may include support for different codecs, + and some also may support entirely different wrapper formats such as AVI.

On Macintosh, Apple QuickTime is used instead, but several of the following + messages may not be available.

+ + + + + + + Allowed values are at least: raw, jpeg, png, mjpa, yuv2, yuv4. + Some other values may allowed, depending on the version of the library + and which codec plugins are installed. + Must be set before the first frame is written. + only applies to [#out]. Choosing a codec is important + because codecs influence greatly the speed of + encoding, the speed of decoding, + the size of the written file, and its fidelity to the + original content. Note that there exist other Apple-QuickTime + codecs that are not supported by HW-QuickTime. + + + + + Sets special codec-specific settings. + For example: "parameter jpeg_quality 75" + + + + Sets the framerate of the file. + This is not used by GridFlow when reading a file, but other + programs usually care. + + + + + Allowed values are rgb, rgba, bgr, bgra, yuv, yuva. + Normally you don't need this. + + + + + Forces a window size when writing. Usually this has to be used after + setting the framerate and codec and before setting the codec-parameters. + (Strange. Sorry.) + + + + + forces a window size when reading. + this is a workaround for a problem in HW-QuickTime. + + + + + +

support for .mpeg files

this format supports frame-seek and frame-tell.

Two different libraries are available for dealing with + MPEG files. Those have different details, capabilities and quirks.

In any case, GridFlow does not support importing audio from + those files.

If you use the HeroineWarrior library, you may open several + mpeg files at once, but not with the GregWard library.

Libraries may scream error messages in a rude way.

By opposition to PPM and TARGA, this format driver only + allows a single MPEG stream per file (you cannot "cat" + several MPEG files together). +

Supports Rewind and Frame Select.

+ + + opens the specified file, taken from the current + directory. + + + + + + + + +

+ This is GridFlow's special file format. This is the only I/O + format that can hold anything that the [#store] object can. +

+ This is the picture format that would support TCP connections + if that feature actually worked. More on this later. +

+ + + + opens the specified file, taken from the current + directory. + + + + same but for .grid.gz files + + + + + dials an specified hostname/port on the InterNet or + compatible network. the TCP protocol is used. + + + + waits for a call (and answers) for this port on the + local machine via InterNet or compatible network. + Answers the call. + + + output will be as 32 bit signed integers. + + + output will be as 8 bit unsigned integers. + + + cancels "headerless" (and back to reading .grid) + + + + instead of reading .grid files with header, will read raw data, + faking a .grid header to itself. It will use the hereby specified + dimension list, as well as two other settings: + type and endian. + + +

When writing "raw" data, a file may be considered a long string of + base 256 digits (called bytes), but different computers have different + conventions for dealing with them: + + +

big: + A number will be written starting with the biggest digit. + This is the natural way on the Macintosh, Sun, Amiga, and so on. +

little: + A number will be written starting with the smallest digit. + This is the natural way on the Intel 386/Pentium. +

same: + A number will be written in whichever way is more natural + on this computer. The natural way is slightly faster to handle. + This is the default setting. +

+ + +

+ +

+ + + + + + + + +

Video4Linux-1 devices, RGB-24 only. Variable picture size.

+ +

We have been testing it using cards of the BT-848 family, + such as Miro DC10plus and Hauppauge WinTV, using the bttv.o linux driver. + Also we have been testing using Logitech QuickCam (and similar Labtec hardware), + but don't use the qce-ga driver, which is buggy and obsolete: the qc-usb + works better.

+ +

Some hardware doesn't support RGB, so you may have to select a YUV colorspace + (see below) and then use [#yuv_to_rgb]. Don't forget to also do + [# min 255] and [# max 0]. +

+ +

If for some reason there's a bug that causes a driver to produce BGR instead of RGB, + so that red and blue are swapped, you can swap them back by filtering through a RGB-BGR + converter, such as [#inner * + 0 {3 3 # 0 0 1 0 1 0 1 0 0}].

+ +

color adjustments: + + + + + +

+ + + gets a specific attribute. a message is sent through right outlet. + valid attributes are: brightness, hue, colour, contrast, whiteness. + + + gets all attributes. + + +

other options: + + + + + + + + +

mmap: + This is the normal (and fast) way of transferring pictures + from the camera. +

read: + Some cameras/drivers only support this instead of mmap. +

+ In case of mmap, the extra numeric argument sets the + queue length in number of frames, so you can select an + appropriate tradeoff between efficiency and latency. + + + + + Allowed values are: RGB24, YUV420P. + Use this if your driver doesn't support RGB24. + + + + + + sets the input size, especially when using a video digitalizer + device. + +

+ +

+ + + + + +

supports 15,16,24,32-bit truecolor displays

+ +

now also support 8-bit indexed displays, using a private colormap + configured as 3:3:2 RGB. When using 8-bit you can specify the + "use_stripes" option to use a completely different color scheme + involving R,G,B diagonal stripes, a kind of 6:6:6 RGB spread over three + pixels.

+ +

If you are using Windows or MacOS 10: you will have to install + a X11 server. This will emulate Unix display on your OS. (note: + Unix systems also need a X11 server, but it's built-in and handles + the video driver directly). In the case of MacOS 10 and QNX that both + use non-X11 display technology on top of a basically Unix OS, the + OS comes with a X11 server, but it may be on a "bundled software" + CD.

+ + + synonym of "open x11 here". + + + + connects to the default X11 server, + according to your environment variable "DISPLAY". + + + + + connects to a display server on this machine. + + + + + + connects to a remote X11 display server using TCP. + Sorry, IP addresses are not supported. + Port number will be 6000 plus the display number, because + of the X11 standard. + + + + + resizes the window to the size of the grid; + encodes that grid in the display's pixel format; + also displays it if autodraw > 0 + the values must be in range 0-255, + or else they will be "wrapped". + + +

+ Destroying the object (or sending "close") should close the window. +

+ +

because of the design of Xlib, or if any of the connections + involved crashes, then the whole program has to be terminated. + (don't you love xlib). Something similar happens if you close any + of the windows yourself, but IIRC this could be fixed.

+ +

only one window may be used per connection (to simplify matters; + this doesn't reduce flexibility).

+ +

there is an additional argument that may be added to every + "open" message; if you don't put it, a new toplevel window is created. + if you put "root" then the screen's wallpaper will be used instead + (it may fail to work with some popular window managers). You can also + put a window number, e.g. 0x28003ff, you may connect to + an existing window; you can find out the number of a window by using + a tool like xwininfo, part of X11 standard tools.

+ + + + + changes the window's size, just like sending a grid + dim(height,width,3) would. + + this affects the size of screen captures too. + + + + forces a redraw of the window's contents. + + + + + +

draw() is never automatically invoked

draw() is invoked after each grid is finished

draw() is invoked incrementally after each row is + received. (but buffering may cause lines to come in groups + anyway)

+ + + + + + Selects one of the 64 predefined cursors of X11. (Note that if + your cursor table has them numbered from 0 to 126 using only even + numbers, then those cursor numbers are all doubled compared to + the ones GridFlow uses.) + + + + This makes the cursor invisible. + + + + + + + + +

This is emitted every time the cursor moves inside + the window connected to this format handler. This is also + emitted when the cursor is dragging from inside to outside + the window. This is also emitted when a mouse button is pressed.

+ +

The y and x coordinates are relative to the upper + right corner of the window. Specific button states may be + extracted from the button value by applying [>> + buttonnumber] and then checking whether the result is odd. + Button numbers normally are: + +

Shift

CapsLock

Control

Alternate

NumLock

???

GridFlow 0.8.0 - documentation index

GridFlow On The Net

+ Browse GridFlow documentation and source code on the web +
+ Download GridFlow and related files +
Or checkout using the CVS protocol (no password): + cvs -d :pserver:anonymous@artengine.ca:/home/cvs/gridflow checkout . +
+ Browse GridFlow CVS on the Web +
+ GridFlow Frequently Asked Questions (on wiki) +
Mailing Lists (Subscription and Archives):
+
PureData Community Site
Ruby Home Page
+ Join us on IRC at +
+ + + + +
host irc.freenode.net
port 6667
channel #dataflow
+
+
See also : +
- Danks/Geiger/Zmölnig's GEM (video plugin for PureData) +
- Tom Schouten's PDP (video plugin for PureData)
- OpenDragon (externals collection for Max)
- NATO (QuickTime library wrapper for Max)
- David Rokeby's SoftVNS (for Max)
- JKClayton/Cycling74's + Jitter (for Max)
- APL (Array Programming Language)
- J (modern APL)
- PDL (APL for Perl)
- Ruby NArray: + japanese page; + english page
- gstreamer (video for Gnome/Kde)
- aRts (audio for Kde)
- + Image Processing Operator Worksheets
- FreeJ
+ +

Credits

+ + C++/Ruby Programming : Mathieu Bouchard
+ Pd Examples : Mathieu Bouchard, Alexandre Castonguay
+ MacOS 10 version : Mathieu Bouchard, James Tittle, Adam Lindsay
+ Windows version (upcoming) : Carmen Rocco
+ +

GridFlow 0.7.7 - License

+ This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + +

+ See file LICENSE for further informations on licensing terms. + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A + PARTICULAR PURPOSE. See the GNU General Public + License for more details. + +

+ You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, + MA 02111-1307, USA. + +

GridFlow 0.7.7 Documentation
+ by Mathieu Bouchard matju@sympatico.ca + and
+ Alexandre Castonguay acastonguay@artengine.ca

+ + diff --git a/externals/gridflow/doc/profiling.html b/externals/gridflow/doc/profiling.html new file mode 100644 index 00000000..aac2ea1f --- /dev/null +++ b/externals/gridflow/doc/profiling.html @@ -0,0 +1,151 @@ + + + + +GridFlow 0.7.7 - Profiling Execution Speed + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + +

+


+ GridFlow 0.7.7 - Profiling Execution Speed +

	+ + What is profiling? + + It is about getting empiric metrics about the execution of a program. + For example, find out which parts of a program consume the most time + and/or memory. Usually it's about the time, and this is what GridFlow + allows you to measure. + + + How to get those stats from GridFlow ? + + create a "@global" object and connect two + messageboxes to it, "profiler_reset" and "profiler_dump". The first + one resets all counters to zero. The second one gives a top of + the busiest objects, with percentages. + note that those results are global to a process. That is, if you load + several patches in the same process (program instance), then all those patches + will be monitored at once. But if you open jMax (or PD) several times at once, then + the profiler will not see everything happening on that machine. + + How do i interpret those stats? + Note that some operations may not be monitored, and some of the + monitoring may be buggy. I think it's not buggy as it is now, but I may be wrong. + + + The current profiler uses a thing called RDTSC (Pentium only). This is a very high + precision clock that is very fast to use. However, major imprecisions + may come from the fact that an ordinary multitasking OS will run other + tasks without stopping/resuming the clock. This may happen randomly; + however, it has a much bigger chance of happening in [@in] or [@out], because that's + where all the communication with other stuff is (files, sockets, windows, etc). + + + If you make sure that only the bare minimum is actively running on your + computer, then [@out] (using x11) would still include the time spent in the x11 + server, except in some conditions. This applies to every kind of window output too, + because however the data trickles through libraries (sdl, aalib), it has to reach the x11 server + and the display driver. + + + The profiler has an impact on the results of the profiler. The profiler + includes half of its own influence in its own results, and disregards the + other half (or so). Profiling shouldn't add more than 100-300 ticks per + message (of which half is counted). + + + Message-passing time is not counted at all. Only time actually spent + inside GridFlow objects is counted. This may skew results. + Transmission of a grid requires one message, thus we may speak of "grid messages". + However, when the message is received, one or several packets may get transmitted, which + is done outside of the message system. Each packet contains at most 2048 numbers + (adjustable limit), and normally a packet should be at least one quarter of that size unless it is the last one. + On RGB grids of widths 640,320,160, the packet size will usually be 1920. + + + + + Getting a frames-per-second measure + This section formerly was describing what can now be obtained using the [fps] object class. + + acceleration tricks + + try the profiler and see what it says. + i mean really. + you can lose a lot of your time accelerating something + that isn't really taking execution time. + it's faster to work on big grids than on small grids, + for the amount of number-crunching you can do. + + about numbertypes: uint8 is the fastest, followed by int16, int32, float32. + (and the first two are faster when MMX is enabled). However it + may be difficult to make some effects use int16 + or smaller without overflow happening. + [@ <<] is a very fast multiplication by powers of two (1, 2, 4, 8, 16, ...). + [@ >>] is a very fast division by powers of two. + + from my little experience, normal integer multiplication and division are + rather slow, especially on Intel brand. The gap between ,/ and + <<,>> is smaller on Cyrix/AMD brand CPUs, but still, try it + yourself. (my experience has been on specific models and may not reflect currently common models) + + + [@ & 255] is a very fast [@ % 256], and likewise for other + powers of two. + for do-nothing operations, "ignore" and "put" are faster than + "+ 0" and such... + remember that an image twice smaller in height and twice + smaller in height will be processed four times as fast (for + most effects) so you can get four times more frames per second. + It's the "rowscolumns*channels" value that makes the biggest + difference (usually). + + If all fails you may recode a jMax/PD/Ruby abstraction into + plain Ruby code or C++ code. If your new class is of generic + usefulness then maybe it should be added to the releases of + GridFlow. Contact me if you need help extending GridFlow. + + Put often-used files on fast drives. This means don't use NFS + (networked file system) for that. The file-to-ram cache can compensate for + that up to a certain amount, but the larger the file is, and the most used + the file is, the more important it is to put it on a local drive. + +


+ GridFlow 0.7.7 Documentation + by Mathieu Bouchard matju@sympatico.ca + +

+ + diff --git a/externals/gridflow/doc/project_policy.html b/externals/gridflow/doc/project_policy.html new file mode 100644 index 00000000..38790844 --- /dev/null +++ b/externals/gridflow/doc/project_policy.html @@ -0,0 +1,98 @@ + + +GridFlow 0.8.0 - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +

+
+ GridFlow 0.8.0 - +

	Note + + Release + + Documentation + + CVS + + +
+
Note
		+ first consult the file ../README for a vague idea on the meaning of + subdirectories.

+
Release
		+Compatibility:
		1 : + Should work with Ruby 1.6.6 and PureData 0.36, 0.37, 0.38
		+Release steps (
		OPERATE WITH CAUTION
		):
		1 : make vvtest # leak detection 2 : ruby base/test.rb formats 3 : cvs tag gridflow_0_7_7 . 4 : mkdir gridflow 5 : cvs -d :pserver:anonymous@cvs.gridflow.ca:/home/cvs/gridflow + export -r gridflow_0_7_7 -d gridflow . 6 : cd gridflow 7 : rm -rf CVS CVSROOT 8 : chmod -R go=u-w . 9 : cd .. 10 : tar cfzvv gridflow-0.7.7.tar.gz gridflow 11 : rm -rf gridflow # caution!!! 12 : scp gridflowgz gridflow@artengine.ca:download 13 : mv gridflowgz /home/matju/net/GridFlow 14 : ssh gridflow@artengine.ca : expand tarball into public_html/latest 15 : download somewhere else and try to compile 16 : update main page 17 : jmax/pd/ruby-talk mlists : post release (note: prefix subject with [ANN] !!!!) 18 : freshmeat.net : post release 19 : RAA : post release


+
Documentation

		1 : + Pictures identified as "<help>" should be screenshots of the + help files. They shouldn't be screenshots of the template. 2 : + A Help file is a visual summary of what an object does. It should be + interactive and allow the user to understand what the object does. + Sample inputs are provided and sample results can be seen. 3 : + All modifications to the documentation must be done in the XML. The + HTML must be kept up-to-date by rerunning "make" in the "doc/" directory. 4 : + Help-wise, Formats are considered objects. + Operators are to be documented as part of [@] and [@!]. 5 : + Images grabbed directly from a jMax window should be encoded in PNG. + This includes "icons" (object boxes, message boxes, etc). If they are + in JPEG, only change to PNG when the image has to change anyway. + Distinguish "icons" from "thumbnails", the latter of which are scaled-down grabs, which should be encoded in JPEG. 6 : + There are not help-thumbnails anymore in the reference manual + because they were not helpful. 7 : + Large images should be kept out of the release. The release itself must + be small enough not to discourage us from doing releases and keeping + them all. It also should be downloadable on a bad modem. =) + Let's keep it under 500k please.
		+in doc do: +for z in images/. images//.; do fgrep -q $z .html \|\| echo "$z"; done

+
CVS
		+ environment variables + CVSEDITOR=pico + CVS_RSH=ssh2

+
+ +GridFlow 0.8.0 Documentation +Copyright © 2001,2002,2003,2004,2005 by Mathieu Bouchard +matju@artengine.ca + +

+ + diff --git a/externals/gridflow/doc/project_policy.xml b/externals/gridflow/doc/project_policy.xml new file mode 100644 index 00000000..3bf7368e --- /dev/null +++ b/externals/gridflow/doc/project_policy.xml @@ -0,0 +1,99 @@ + + + + + + +

+ first consult the file ../README for a vague idea on the meaning of + subdirectories. +

+ +

+ +Compatibility: + +

+ Should work with Ruby 1.6.6 and PureData 0.36, 0.37, 0.38 +

+ +Release steps (OPERATE WITH CAUTION): + + +

make vvtest # leak detection +

ruby base/test.rb formats +

cvs tag gridflow_0_7_7 . +

mkdir gridflow +

cvs -d :pserver:anonymous@cvs.gridflow.ca:/home/cvs/gridflow + export -r gridflow_0_7_7 -d gridflow . +

cd gridflow +

rm -rf CVS CVSROOT +

chmod -R go=u-w . +

cd .. +

tar cfzvv gridflow-0.7.7.tar.gz gridflow +

rm -rf gridflow # caution!!! +

scp gridflow*gz gridflow@artengine.ca:download +

mv gridflow*gz /home/matju/net/GridFlow +

ssh gridflow@artengine.ca : expand tarball into public_html/latest +

download somewhere else and try to compile +

update main page +

jmax/pd/ruby-talk mlists : post release (note: prefix subject with [ANN] !!!!) +

freshmeat.net : post release +

RAA : post release +

+ +

+ Pictures identified as "<help>" should be screenshots of the + help files. They shouldn't be screenshots of the template. +

+ A Help file is a visual summary of what an object does. It should be + interactive and allow the user to understand what the object does. + Sample inputs are provided and sample results can be seen. +

+ All modifications to the documentation must be done in the XML. The + HTML must be kept up-to-date by rerunning "make" in the "doc/" directory. +

+ Help-wise, Formats are considered objects. + Operators are to be documented as part of [@] and [@!]. +

+ Images grabbed directly from a jMax window should be encoded in PNG. + This includes "icons" (object boxes, message boxes, etc). If they are + in JPEG, only change to PNG when the image has to change anyway. + Distinguish "icons" from "thumbnails", the latter of which are + scaled-down grabs, which should be encoded in JPEG. +

+ There are not help-thumbnails anymore in the reference manual + because they were not helpful. +

+ Large images should be kept out of the release. The release itself must + be small enough not to discourage us from doing releases and keeping + them all. It also should be downloadable on a bad modem. =) + Let's keep it under 500k please. +

+ + +in doc do: +for z in images/*.* images/*/*.*; do fgrep -q $z *.html || echo "$z"; done + +

+ +

+ environment variables + CVSEDITOR=pico + CVS_RSH=ssh2 +

+ + diff --git a/externals/gridflow/doc/reference.html b/externals/gridflow/doc/reference.html new file mode 100644 index 00000000..ac1f4373 --- /dev/null +++ b/externals/gridflow/doc/reference.html @@ -0,0 +1,1070 @@ + + +GridFlow 0.8.0 - Reference Manual: Flow Classes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ +

+
+ GridFlow 0.8.0 - Reference Manual: Flow Classes +

	Objects for making grids and breaking them down + + + + + + + + + + + + Objects for Computing + + + + + + + + + + + + + + + + + + Objects for Coordinate Transforms + + + + + + + + + + Objects for Reporting + + + + + + + + Objects for Color Conversion + + + + + + + Objects for Miscellaneous Picture Processing + + + + + + + + + + + + Other Objects + + + + + + + + + + + + + jMax emulation + + + + + + + + + + + + + + + + + + + + + + + PureData emulation + + + + +
+
Objects for making grids and breaking them down

class #import
	+	+ This object allows you to produce grids from non-grid data, such as + integers and lists of integers. This object also reframes/resyncs + grids so that multiple grids may be joined together, or + single grids may be split. That kind of operation is already done implicitly in many + cases (e.g. sending an integer or list to a grid-receiving inlet), + but using this object you have greater flexibility on the conversion. attr shape (GridShape\|symbol(per_message) shape) attr cast (NumberType cast) method init (shape, cast) + inlet 0 method int () + begins a new grid if there is no current grid. + puts that integer in the current grid. + ends the grid if it is full. + the constructed grid is not stored: it is streamed. + the stream is buffered, so the output is in packets + of about a thousand numbers. + inlet 0 method list () + just like a sequence of ints sent one after another, + except in a single message. + inlet 0 method symbol () + considered as a list of ascii characters. + inlet 0 method reset () + aborts the current grid if there is one. + inlet 0 method grid (grid(dims...) grid) + this is the equivalent of filtering this grid through + an `[#export]` object and sending the resulting integers + to this `[#import]` object, except that it's over + 10 times faster. + inlet 1 method per_message () + old synonym for "shape per_message" + outlet 0 method grid (grid grid) + the grid produced from incoming integers and/or grids. +

class #export
	+	+ this object is the opposite of #import. method init () + this object is not configurable because there isn't + anything that could possibly be configured here. + inlet 0 method grid (grid(dims...) grid) + transforms this grid into a sequence of integer messages. + outlet 0 method int () + elements of the incoming grid. +

class #export_list
	+	+ this object is another opposite of `[#import]`, which puts + all of its values in a list. method init () + inlet 0 method grid (grid(dims...) grid) + transforms this grid into a single message containing + a list of integers. + outlet 0 method list () + elements of the incoming grid. +

class #export_symbol
	+	+ this object is another opposite of #import, which constructs a symbol + from its input. The values are expected to be valid ASCII codes, but no check + will be performed for that, and additionally, no check will be made that the generated + symbol only contains characters that can be put in a symbol. method init () + inlet 0 method grid (grid(dims...) grid) + transforms this grid into a single message containing + a list of integers. + outlet 0 method symbol () generated symbol +

class #pack
	+	+ Similar to `[#join]`, but takes individual integers, and builds a Dim(N) vector out of it. attr trigger_by (TriggerBy trigger_by) method init (integer inputs) + inlet * method int () + outlet 0 method grid () + combination of inputs given in all inlets. + this is produced according to the value of the trigger attribute. +

class #color
	+	+ Triple slider for the selection of RGB values. method init (float min, float max, 0,1 hidepreview) + inlet 0 method grid () + Produces a Dim(3) grid of RGB values. +

class #unpack
	+	+ method init (integer outputs) + inlet 0 method grid(N) () + the input vector is split in N parts containing one number each. + numbers are sent left-to-right, that is, outlet 0 is triggered first, then outlet 1, etc. + outlet * method int () +

class #centroid
	+	+ method init () + inlet 0 method grid(rows,columns,1) () + will compute the centroid of the given grid, which + is a weighted average, namely, the average position weighted + by the pixel values. + outlet 0 method grid(2) () + result +

class #centroid2
	+	+ + a new experimental and faster version of #centroid. method init () + inlet 0 method grid(rows,columns,1) () + will compute the centroid of the given grid, which + is a weighted average, namely, the average position weighted + by the pixel values. + outlet 0 method grid(2) () + result +

class #for
	+	+ when given scalar bounds, works like a regular `[for]` object plugged + to a `[#import]` tuned for a Dim(size) where size is the number of values + produced by a bang to that `[for]`. when given vector bounds, will work like any number of [for] objects + producing all possible combinations of their values in the proper order. + This replaces the old `[#identity_transform]` object. method init (integer from, integer to, integer step) + inlet 0 method grid (grid(index) grid) + replaces the "from" value and produces output. + inlet 1 method grid (grid(index) grid) + replaces the "to" value. + inlet 2 method grid (grid(index_steps) grid) + replaces the "step" value. + outlet 0 method grid (grid(size) grid) + where size is floor((to-from+1)/step) + [for scalar bounds] + outlet 0 method grid (grid(size,dimension)* grid) + where *size is floor((to-from+1)/step) + [for vector bounds] +


+
Objects for Computing

class #
	+	+ attr op (grid op) attr right_hand (grid right_hand) This object outputs a grid by computing "in parallel" a same + operation on each left-hand element with its corresponding right-hand + element. method init (op, right_hand) + inlet 0 method grid (grid(dims...) grid) + on each element of this grid, perform the operation + together with the corresponding element of inlet 1. + in the table of operators (at the top of this document) + elements of inlet 0 are called "A" and elements of inlet 1 + are called "B". the resulting grid is the same size as the + one in inlet 0. + inlet 1 method grid (grid(dims...) grid) + any grid, preferably shaped like the one that will be put + in the left inlet, or like a subpart of it (anyway the contents + will be redim'ed on-the-fly to fit the grid of inlet-0, + but the stored grid will not be modified itself) + inlet 1 method int () + stores a single int in the right inlet; the same int will + be applied in all computations; this is like sending a + Dim(1) or Dim() grid with that number in it. + outlet 0 method grid (grid grid) +

class @complex_sq
	+	+ this object computes the square of complex numbers. + If seeing imaginary as Y and real as X, then this operation squares + the distance of a point from origin and doubles the angle between it + and the +X half-axis clockwise. (fun, eh?) used on an indexmap, this makes each thing appear twice, + each apparition spanning half of the original angle. inlet 0 method grid (grid(dims... {imaginary real}) grid) + outlet 0 method grid (grid(dims... {imaginary real}) grid) +

class #fold
	+	+ 1 : `[#fold +]` computes totals 2 : `[#fold inv+]` is an alternated sum (+/-) 3 : `[#fold * 1]` can compute the size of a grid using its dimension list 4 : `[#fold & 1]` can mean "for all" 5 : `[#fold \| 0]` can mean "there exists (at least one)" 6 : `[#fold ^ 0]` can mean "there exists an odd number of..." 7 : `[#fold ^ 1]` can mean "there exists an even number of...". method init (numop2 operator, grid seed, grid right_hand) + inlet 0 method grid (grid(dims..., last) grid) + replaces every Dim(last) subgrid by the result of a cascade on that subgrid. + Doing that + with seed value 0 and operation + on grid "2 3 5 7" will compute + ((((0+2)+3)+5)+7) find the total "17". + produces a Dim(dims) grid. +

class #scan
	+	+ `[#scan +]` computes subtotals; this can be used, for example, + to convert a regular probability distribution into a cumulative one. + (or in general, discrete integration) method init (numop2 operator, grid seed) + inlet 0 method grid (grid(dims..., last) grid) + replaces every Dim(last) subgrid by all the results of + cascading the operator on that subgrid, + producing a Dim(dims,last) grid. + For example, with base value 0 and operation + on grid "2 3 5 + 7" will compute 0+2=2, 2+3=5, 5+5=10, 10+7=17, and give the + subtotals "2 5 10 17". +

class #outer
	+	+ method init (numop2 operator, grid value) + the operator must be picked from the table of two-input operators. + the grid is optional and corresponds to inlet 1. + inlet 0 method grid (grid(anyA...) grid) + + produces a grid of size Dim(anyA..., anyB...), where numbers + are the results of the operation on every element of A and + every element of B. the resulting array can be very big. Don't + try this on two pictures (the result will have 6 dimensions) inlet 1 method grid (grid(anyB...) grid) + + stores the specified grid, to be used when inlet 0 is activated. When given a grid of Dim(3) and a grid of Dim(5) `[#outer]` will + produce a grid of Dim(3,5) with the selected two-input operation + applied on each of the possible pairs combinations between numbers + from the left grid and the ones from the right. for example : + (10,20,30) [#outer +] (1,2,3) will give : + ((11,12,13),(21,22,23),(31,32,33))

class #inner
	+	+ think of this one as a special combination of `[#outer]`, `[#]` and `[#fold]`. this is one of the most complex operations. It is very useful + for performing linear transforms like rotations, scalings, shearings, + and some kinds of color remappings. A linear transform is done by + something called matrix multiplication, which happens to be `[#inner * + + 0]`. `[#inner]` also does dot product and other funny operations. method init (numop2 op_para, numop2 op_fold, integer base, grid right_hand) + op_para and op_fold are two operators picked from the table + of two-input operators. + the base value has to be specified (has no default value yet). + inlet 0 method grid (grid(anyA..., lastA) grid) + Splits the Dim(anyA...,lastA) left-hand grid into Dim(anyA...) + pieces of Dim(lastA) size. + Splits the Dim(firstB,anyB...) right-hand grid into + Dim(anyB...) pieces of Dim(firstB) size. + On every piece pair, does `[#]` using the specified + op_para operation, followed by a `[#fold]` using + the specified op_fold operator and base value. + creates a Dim(anyA...,anyB...) grid by assembling all + the results together. + (note: lastA must be equal to firstB.) + inlet 1 method int () + changes the base value to that. + inlet 2 method grid (grid(anyB..., lastB) grid) + changes the right-hand side grid to that. +

class @join
	+	+ method init (which_dim) + Which_dim is the number of the dimension by which the join will + occur. For N-dimensional grids, the dimensions are numbered from 0 + to N-1. In addition, negative numbers from -N to -1 may be used, to + which N will be added. + inlet 0 method grid (grid grid) + The left grid and right grid must have the same number + of elements in all dimensions except the one specified. + The result will have the same number of elements in all + dimensions except the one specified, which will be the + sum of the two corresponding one. For example, joining a RGB picture Dim[y,x,3] and a + greyscale picture Dim[y,x,1] on dimension 2 (or -1) could + make a RGBA picture Dim[y,x,4] in which the greyscale image + becomes the opacity channel. + inlet 1 method grid (grid grid) +

class #finished
	+	+ inlet 0 method grid (grid grid) any grid + + a bang is emitted every time a grid transmission ends.

class #cast
	+	+ method init (numbertype numbertype) + inlet 0 method grid (grid grid) any grid + outlet 0 method grid (grid grid) a grid of the same shape containing all the same + values after type conversion. note that while casting to + a smaller type, values that are overflowing will be truncated. +

class #ravel
	+	+ inlet 0 method grid (grid grid) any grid + outlet 0 method grid (grid grid) + like `[#redim]` but always produce a 1-D grid + with the same total number of elements. +

class #grade
	+	+ inlet 0 method grid (grid grid) any grid + outlet 0 method grid (grid grid) splits a Dim[A...,B] grid into Dim[B] vectors, + producing new Dim[B] vectors that each contain numbers from + 0 to B-1 indicating the ordering of the values. The result is + a Dim[A...,B] grid. for example, connecting a [#grade] to a `[#outer ignore {0}]` + to a `[#store]` object, storing a single vector into `[#store]`, and + sending the same vector to `[#grade]`, will sort the values of the + vector. however for higher-dimensional grids, what should go + between `[#store]` and `[#grade]` to achieve the same result would + be more complex. you may achieve different kinds of sorting by applying various + filters before `[#grade]`. the possibilities are unlimited. if you plug `[#grade]` directly into another `[#grade]`, you will + get the inverse arrangement, which allows to take the sorted values + and make them unsorted in the original way. note that this is really + not the same as just listing the values backwards. +

class #perspective
	+	+ method init (integer depth) + inlet 0 method grid (grid grid) any grid + outlet 0 method grid (grid grid) transforms a Dim[A...,B] grid into a Dim[A...,B-1] grid. + There is a projection plane perpendicular to the last axis and + whose position is given by the "depth" parameter. Each vector's + length is adjusted so that it lies onto that plane. Then the + last dimension of each vector is dropped. useful for converting from 3-D geometry to 2-D geometry. Also + useful for converting homogeneous 3-D into regular 3-D, as + homogeneous 3-D is really just regular 4-D...(!) +

class #transpose
	+	+ method init (integer dim1, integer dim2) + inlet 0 method grid (grid grid) + swaps the two specified dimensions; dimension numbers are as in `[#join]`. +

class #fade
	+	+ method init (integer rate) + inlet 0 method grid (grid grid) + produces on outlet 0 a linear recurrent fading according to the flow of + incoming messages. For example, if rate=5, then 20% (one fifth) + of each new message will be blended with 80% of the previous output. +

class #fade_lin
	+	+ method init (integer maxraise, integer maxdrop) + inlet 0 method grid (grid grid) + produces on outlet 0 a piecewise-linear nonrecurrent fading according to the flow of + incoming messages. For example, if maxraise=2 and maxdrop=4, then with each + new message an output is produced that is at most 2 more or 4 less than the + previous output. +

class #reverse
	+	+ method init (whichdim) + Whichdim is the number of the dimension by which the reverse will + occur. For N-dimensional grids, the dimensions are numbered from 0 + to N-1. In addition, negative numbers from -N to -1 may be used, to + which N will be added. +


+
Objects for Coordinate Transforms

class #redim
	+	+ method init (dim_list dims) + a list specifying a grid shape that the numbers + will fit into. + (same as with `[#import]`) + inlet 0 method grid (grid(dims...) grid) + the elements of this grid are serialized. if the resulting grid + must be larger, the sequence is repeated as much as necessary. + if the resulting grid must be smaller, the sequence is truncated. + then the elements are deserialized to form the resulting grid. + inlet 1 method grid (grid(rank) grid) + this grid is a dimension list that replaces the one + specified in the constructor. + (same as with `[#import]`) + outlet 0 method grid (grid grid) + redimensioned grid potentially containing repeating data. + example: with a 240 320 RGB image, `[#redim 120 640 3]` will visually + separate the even lines (left) from the odd lines (right). contrary + to this, `[#redim 640 120 3]` will split every line and put its left half + on a even line and the right half on the following odd line. `[#redim]` + 480 320 3 will repeat the input image twice in the output image. `[#redim]` 240 50 3 will only keep the 50 top lines.

class #store
	+	+ A `[#store]` object can store exactly one grid, using the right + inlet. You fetch it back, or selected subparts thereof, using the left + inlet. method init (grid contents) + inlet 0 method bang () + the stored grid is fully sent to the outlet. + inlet 0 method grid (grid(dims..., indices) grid) + in this grid, the last dimension refers to subparts of + the stored grid. sending a Dim(200,200,2) on a `[#store]` + that holds a Dim(240,320,3) will cause the `[#store]` to handle + the incoming grid as a Dim(200,200) of Dim(2)'s, where each + Dim(2) represents a position in a Dim(240,320) of Dim(3)'s. + therefore the resulting grid will be a Dim(200,200) of + Dim(3) which is a Dim(200,200,3). in practice this example + would be used for generating a 200200 RGB picture from a + 200200 XY map and a 240320 RGB picture. this object can + be logically used in the same way for many purposes + including color palettes, tables of probabilities, tables + of statistics, whole animations, etc. + inlet 1* method grid (grid(dims...) grid) + replace the whole grid, or a subpart of it (see other options on inlet 1) + inlet 1 method reassign () (Future Use): + makes it so that sending a grid to inlet 1 detaches the old buffer from [#store] + and attaches a new one instead. This is the default. + inlet 1 method put_at (indices...) (Future Use): + makes it so that sending a grid to inlet 1 writes into the existing buffer of [#store]. + example: suppose you have `[#store {10 240 320 3}]`. then "put_at 3" + will allow to write a Dim[240,320,3] grid in indices (3,y,x,c) where y,x,c are indices of the incoming grid; + in other words, if that's a buffer of 10 RGB frames, you'd be replacing frame #3. Furthermore, + it also allows you to write a Dim[n,240,320,3] grid at (3+f,y,x,c) where f,y,x,c are indices of the incoming grid, + replacing frame #3, #4, ... up to #3+n-1. Here n is at most 7 because the last frame in the buffer is #9. that way of working extends to other kinds of data you'd put in Grids, in any numbers of dimensions; + because, as usual, [#store] wouldn't know the difference. + + grids as stored, as indexed, or as assembled from multiple + indexings.

class #scale_to
	+	+ method init (size) + inlet 0 method grid (grid grid) a 3-channel picture to be scaled. + inlet 1 method int () a {height width} pair. + outlet 0 method grid (grid grid) a scaled 3-channel picture. +

class #scale_by
	+	+ method init (grid dim() or dim(2) factor) + factor is optional (default is 2). + if it's a single value, then that factor is to be used + for both rows and columns. + inlet 0 method grid (grid(y x channels) grid) + duplicates each pixel several times in width and several times in height, + where the number of times is determined by the factor described above. + twice those of the incoming grid. It is several times faster. + inlet 1 method grid (grid(1 or 2) grid) sets factor + outlet 0 method grid (grid((factory) (factorx) channels) grid) +

class #downscale_by
	+	+ method init (+integer factor, optional symbol(smoothly) how) + factor is optional (default is 2). + if it's a single value, then that factor is to be used + for both rows and columns. + inlet 0 method grid (grid(y x channels) grid) + Scales down picture by specified amount. (See scale factor above) + inlet 1 method grid (grid(1 or 2) grid) sets scale factor + outlet 0 method grid (grid((factor/y) (factor/x) channels) grid) +

class #spread
	+	+ typically you plug a `[#for]` into this object, + and you plug this object into the left side of a `[#store]`. it will + scatter pixels around, giving an "unpolished glass" effect. if you put a picture in it, however, it will add noise. The + resulting values may be out of range, so you may need to clip them + using min/max. method init (factor) + inlet 0 method grid (grid grid) a coordinate map. + inlet 1 method int () a spread factor. + outlet 0 method grid (grid grid) a coordinate map. + `[#spread]` scatters the pixels in an image. Not all original pixels + will appear, and some may get duplicated (triplicated, etc) + randomly. Some wrap-around effect will occur close to the edges. Sending an integer to inlet 1 sets the amount of spreading in + maximum number of pixels + 1. even values translate the whole image + by half a pixel due to rounding.

class #rotate
	+	+ performs rotations on indexmaps and polygons and such. method init (0...35999 angle) + inlet 0 method grid (grid(anyA 2) grid) + inlet 1 method int () rotation angle; 0...36000 + outlet 0 method grid (grid(anyA 2) grid) +

class #remap_image
	+	+ if you chain indexmap (coordinate) transformations from outlet 1 + to inlet 1, then sending an image in inlet 0 will emit its + deformation out of outlet 0.


+
Objects for Reporting

class #dim
	+	+ Returns list of dimensions as a grid. Given a grid sized like Dim(240,320,4), `[#dim]` will return a grid like Dim(3), whose values are 240, 320, 4. method init () + no arguments. + inlet 0 method grid (grid(dims...) grid) + ignores any data contained within. + sends a grid dim(length of dims) containing dims. + outlet 0 method grid (grid(rank) grid) + the list of dimensions of the incoming grid. +

class #type
	+	+ gives a symbol representing the numeric type of the grid received. outlet 0 method <numeric type symbol> () +

class #print
	+	+ method init () + inlet 0 method grid (grid(dims...) grid) + prints the dimensions of the grid. + prints all the grid data if there are 2 dimensions or less. +

class rubyprint
	+	+ + This is only for testing the translation from PD to Ruby. method init () + inlet 0 method (any) () + prints the message to the console. +

class printargs
	+	+ + This is only for testing the translation from PD to Ruby. method init (any...) + prints everything. +

class display
	+	+ + GUI object equivalent to [print] and [#print]. method (any) () + Displays the received message in the box, resizing the box so that the message fits exactly. +


+
Objects for Color Conversion

class #apply_colormap_channelwise
	+	+ This object is useful for color correction. For each pixel + it takes it apart, looks up each part separately in the colormap, + and constructs a new pixel from that. You may also color-correct + colormaps themselves. Only works for things that have 3 channels. Note: if you just need to apply a palette on an indexed-color + picture, you don't need this. Just use #store instead. inlet 0 method grid (grid(rows columns channels) grid) + picture + inlet 1 method grid (grid(intensities channels) grid) + colormap ("palette") + outlet 0 method grid (grid(rows columns channels) grid) + picture +

class #rgb_to_greyscale
	+	+ inlet 0 method grid (grid(rows columns {red green blue}) grid) + outlet 0 method grid (grid(rows columns {white}) grid) +

class #greyscale_to_rgb
	+	+ inlet 0 method grid (grid(rows columns {white}) grid) + outlet 0 method grid (grid(rows columns {red green blue}) grid) +

class #yuv_to_rgb
	+	+ note: may change slightly to adapt to actual video standards. inlet 0 method grid (grid(rows columns {y u v}) grid) + outlet 0 method grid (grid(rows columns {red green blue}) grid) +

class #rgb_to_yuv
	+	+ note: may change slightly to adapt to actual video standards. inlet 0 method grid (grid(rows columns {red green blue}) grid) + outlet 0 method grid (grid(rows columns {y u v}) grid) +


+
Objects for Miscellaneous Picture Processing

class #convolve
	+	+ this is the object for blurring, sharpening, finding edges, + embossing, cellular automata, and many other uses. method init (numop2 op_para, numop2 op_fold, grid seed, grid right_hand) + inlet 0 method grid (grid(rows columns rest...) grid) + splits the incoming grid into dim(rest...) parts. + for each of those parts at (y,x), a rectangle of such + parts, centered around (y,x), is combined with the + convolution grid like a `[#]` of operation op_para. Then + each such result is folded like `[#fold]` of operation + op_fold and specified base. the results are assembled + into a grid that is sent to the outlet. near the borders of + the grid, coordinates wrap around. this means the whole grid + has to be received before production of the next grid + starts. + inlet 1 method grid (grid(rows2 columns2) grid) + this is the convolution grid and it gets stored in + the object. if rows2 and/or columns2 are odd numbers, + then the centre of convolution is the middle of the convolution + grid. if they are even numbers, then the chosen centre will + be slightly more to the left and/or to the top, because the + actual middle is between cells of the grid. + outlet 0 method grid (grid(rows columns rest...) grid) +

class #contrast
	+	+ method init (iwhiteness, contrast) + inlet 0 method grid (grid(rows columns channels) grid) + produces a grid like the incoming grid but with + different constrast. + `[#contrast]` adjusts the intensity in an image. + resulting values outside 0-255 are automatically clipped. inlet 1 method int () + this is the secondary contrast (inverse whiteness). + it makes the incoming black + correspond to a certain fraction between output black and the + master contrast value. no effect is 256. default value is 256. + inlet 2 method int () + this is the master contrast. it makes the incoming white + correspond to a certain fraction between output black and output + white. no effect is 256. default value is 256. + outlet method grid (grid(rows columns channels) grid) +

class #posterize
	+	+ `[#posterize]` reduces the number of possible intensities in an image; + it rounds the color values.The effect is mostly apparent with a low + number of levels. method init (levels) + inlet 0 method grid (grid(rows columns channels) grid) + produces a posterized picture from the input picture. + inlet 1 method int () + this is the number of possible levels per channel. the + levels are equally spaced, with the lowest at 0 and the + highest at 255. the minimum number of levels is 2, and the + default value is 2. + example: simulate the 216-color "web" palette using 6 levels. + simulate a 15-bit display using 32 levels.

class #solarize
	+	+ makes medium intensities brightest; formerly brightest colours + become darkest; formerly darkest stays darkest. This filter is linear: + it's like a 200% contrast except that overflows are mirrored + instead of clipped or wrapped. inlet 0 method grid (grid(rows columns channels) grid) + outlet 0 method grid (grid(rows columns channels) grid) +

class #checkers
	+	+ inlet 0 method grid (grid(y x {y x}) grid) + result from a `[#for {0 0} {height width} {1 1}]` + outlet 0 method grid (grid(y x {r g b}) grid) + checkered pattern of 50%/75% greys + in 8x8 squares +

class #layer
	+	+ inlet 0 method grid (grid(y x {r g b a}) grid) + a picture that has an opacity channel. + will be used as foreground. + inlet 1 method grid (grid(y x {r g b}) grid) + a picture that has NO opacity channel. + will be used as background. + outlet 0 method grid (grid(y x {r g b}) grid) + a picture that has NO opacity channel. + the opacity channel of the foreground is used as + a weighting of how much of either picture is seen + in the result. +

class #draw_image
	+	+ method init (numop2 operator, grid(y,x,channels) picture, grid({y x}) position) + inlet 0 method grid (grid(y x channels) grid) + picture onto which another picture will be superimposed. + inlet 0 method tile (0 or 1 flag) + if enabled, inlet 1 picture will be repeated to cover the inlet 0 picture. + inlet 0 method alpha (0 or 1 flag) + if enabled, inlet 1 picture will be combined with inlet 0 picture using + the selected operator, + and then blended with inlet 0 picture according to transparency of + the inlet 1 picture, and then inserted in the result. + if disabled, the blending doesn't occur, as the transparency level + is considered to be "opaque". note that with alpha enabled, + the last channel of inlet 1 picture is considered to represent transparency. + inlet 1 method grid (grid(y x channels) grid) + picture that will be superimposed onto another picture. + inlet 2 method grid (grid({y x}) grid) + position of the inlet 0 picture corresponding to top-left corner + of inlet 1 picture. + outlet 0 method grid (grid(y x channels) grid) + resulting picture. +

class #draw_polygon
	+	+ method init (numop2 operator, grid(channels) color, grid(vertices,{y x}) vertices) + inlet 0 method grid (grid(y x channels) grid) + picture on which the polygon will be superimposed. + inlet 1 method grid (grid(channels) grid) + color of each pixel + inlet 2 method grid (grid(vertices {y x}) grid) + vertices of the polygon. + outlet 0 method grid (grid(y x channels) grid) + modified picture. + note: starting with 0.7.2, drawing a 1-by-1 + square really generates a 1-by-1 square, and + so on. This is because the right-hand border of a + polygon is excluded, whereas it was included + before, leading to slightly-wider-than-expected polygons. +

class #text_to_image
	+	+ inlet 2 receives a font grid, for example, [#in grid file lucida-typewriter-12.grid.gz] inlet 1 receives a 2 by 3 matrix representing the colours to use (e.g. (2 3 # 0 170 0 255 255 0) means yellow on green) inlet 0 receives a bang, transforming the data into an image suitable for #draw_image.

class #hueshift
	+	+ inlet 1 receives an angle (0..36000) inlet 0 receives a RGB picture that gets hueshifted by a rotation in the colorwheel by the specified angle; it gets sent to outlet 0.


+
Other Objects

class rtmetro
	+	+This class has been removed (0.7.7).

class bindpatcher
	+	+ sets the receive-symbol for the Pd patcher it is in. has no inlets, no outlets. EXPERIMENTAL. method init (symbol symbol) +

class pingpong
	+	+ + Transforms linear counting (0, 1, 2, 3, 4, ...) into a back-and-forth counting (0, 1, 2, 1, 0, ...) + from 0 to a specified upper bound. method init (int top) + inlet 1 method float (float top) + inlet 0 method float () + a value to be transformed. + If, for example, top=10, then values 0 thru 10 are left unchanged, + values 11 thru 19 are mapped to 9 thru 1 respectively, and 20 thru 30 + are mapped to 0 thru 10, and so on. +

class #global
	+	+ + objects of this class do nothing by themselves and are just + an access point to features that don't belong to any object in + particular. method profiler_reset () + resets all the time counters. + method profiler_dump () + displays the time counters in decreasing order, with + the names of the classes those objects are in. this is + an experimental feature. like most statistics, + it could be vaguely relied upon if + only you knew to which extent it is unreliable. more on this + in a future section called "profiling". +

class fps
	+	+ method init (symbol(real\|user\|system\|cpu) clocktype, symbol(detailed) detailed) + method init detailed () + inlet 0 method bang () + Times at which bangs are received are stored until a large + enough sample of those is accumulated. Large enough is defined + to be whenever the timespan exceeds one second. Then a report + is made through the outlet. + inlet 0 method (else) () + messages other than bangs are ignored. + outlet 0 method float () + non-detailed mode only. + this is the messages-per-second rating. + outlet 0 method list(float,6) () + detailed mode only. + this is: messages-per-second, followed by five values of + milliseconds-per-message: minimum, median, maximum, average, + standard deviation. + (the average happens to be simply 1000 divided by the + messages-per-second, but it is convenient to have it anyway) +

class unix_time
	+	+ + This object returns the Unix timestamp. The first + outlet does so with ASCII, the second in seconds and the third outlet + outputs the fractions of seconds up to 1/100 000 th of a second which is useful for creating + filenames. inlet 0 method bang () + outlet 0 method symbol () +Outputs the time and date in ASCII format outlet 1 method float () +Outputs the Unix timestamp in seconds outlet 2 method float () +Outputs the fractions of a second up to 10 microseconds (?) (actual precision is platform-dependent afaik)

class ls
	+	+ + This object is similar to the Unix list command + 'ls'. It returns the names of files in a given + directory. May be used with [listlength] to retrieve the number of files. + Hidden files are displayed. inlet 0 method symbol () +

class exec
	+	+ + This object launches a Unix shell program or script. inlet 0 method symbol () +

class renamefile
	+	+ + This object accepts a list of two elements as arguments. + The current file name being the first and the second is the desired change + in name. inlet 0 method list () +

class plotter_control
	+	+ + This object produces HPGL instructions in ASCII form + that can be sent to the comport object in order to control an HPGL + compatible plotter. inlet 0 method symbol () + outlet 0 method symbol () +Outputs the HPGL commands in ASCII format

class rubyarray
	+	+ inlet 0 float : sends the specified array entry to outlet 0 inlet 1 list: writes that list as an array entry in position last specified by inlet 0. inlet 0 save(symbol filename): writes the array contents to a file of the given filename as a CSV inlet 0 save(symbol filename, symbol format): same thing but using a sprintf string such as %x,%f or whatever inlet 0 load(symbol filename): replace all array contents by the contents of a CSV file


+
jMax emulation

		those classes emulate jMax functionality, + for use within PureData and Ruby.

class fork
	+	+ Every incoming message is sent to inlet 1 and then sent to + inlet 0 as well. Messages remain completely unaltered. Contrast + with PureData's "t a a" objects, which have the same purpose but + transform bangs into zeros and such. inlet 0 method (any) () +

class jmax_udpsend
	+	+ + Sends messages (but not grids nor dspsignals) via UDP (which + does not involve a connection, and may lose packets in case of + network overload or noise or etc). This works with jMax 2.5 and 4.1 but not 4.0. method init (host host, integer port) + inlet 0 method <any> () +

class jmax_udpreceive
	+	+ Counterpart of jmax_udpsend This works with jMax 2.5 and 4.1 but not 4.0. method init (integer port) + outlet 0 method <any> () + outlet 1 method list (protocol_name, sender_port, sender_host, sender_ip_address) +

class foreach
	+	+ inlet 0 method list (...) + Outputs N messages, one per list element, in order. +

class rubysprintf
	+	+ method init (symbol format) + inlet 0 method list () + Outputs the format string with %-codes replaced + by elements of the list formatted as the %-codes say. + To get a list of those codes, consult a Ruby manual + (Equivalently, Perl, Python, Tcl and C all have equivalents of this, + and it's almost always called sprintf, or the % operator, or both) +

class listflatten
	+	+ inlet 0 method list (...) +

class listmake
	+	+ + Emulation of jMax's [list] (but there cannot be a class named [list] in Pd) method init (list...) + inlet 0 method bang () send "list" to outlet 0 + inlet 0 method list () as sending to inlet 1 and then banging; that is, passes thru and remembers. +

class listlength
	+	+ inlet 0 method list () + outputs the number of elements in the incoming list. +

class listelement
	+	+ method init (int index) + inlet 0 method list (...) + Outputs one element of the list, as selected by "index". + Also accepts negative indices (e.g.: -1 means "last"), like Ruby, but unlike jMax. +

class listsublist
	+	+ method init (int index, int length) + inlet 0 method list (...) + Outputs consecutive elements of the list, as selected by "index" and "length". + Also accepts negative indices (e.g.: -1 means "last"), like Ruby, but unlike jMax. +

class listprepend
	+	+ method init (list...) + inlet 0 method list (...) + Outputs the stored list followed by the incoming list, all in one message. +

class listappend
	+	+ method init (list...) + inlet 0 method list (...) + Outputs the incoming list followed by the stored list, all in one message. +

class listreverse
	+	+ inlet 0 method list (...) + Outputs the incoming list, from last element to first element. +

class oneshot
	+	+ + Like [spigot], but turns itself off after each message, so you have to turn it on + again to making it pass another message.

class inv+
	+	+ method init (float b) + inlet 0 method float (float a) + outputs b-a +

class inv*
	+	+ method init (float b) + inlet 0 method float (float a) + outputs b/a +

class messageprepend
	+	+ + (This is not in jMax, but is there to help port $* messageboxes) method init (list...) + inlet 0 method <any> (...) + Like [listprepend], but operates on whole messages, that is, including the selector. +

class messageappend
	+	+ + (This is not in jMax, but is there to help port $* messageboxes) method init (list...) + inlet 0 method <any> (...) + Like [listappend], but operates on whole messages, that is, including the selector. +

class shunt
	+	+ + Compatible with jMax's [demux]. method init (n, i) + inlet 0 method <any> (...) + Routes a message to the active outlet. + inlet 1 method int (int i) + Selects which outlet is active. +

class demux
	+	+ + please use shunt instead (name conflict with another Pd external)

class range
	+	+ method init (separators...) + inlet 0 method float () + a value to be sent to one of the outlets. The first outlet is for values + smaller than the first argument; else the second outlet is for values smaller + than the second argument; and so on; and the last outlet is for values greater + or equal to the last argument. + inlet 1..n method float () + sets the corresponding separator in the separator list. +


+
PureData emulation

class pd_netsend
	+	+ + same as jmax_udpsend but for PureData UDP connections.

class pd_netreceive
	+	+ + same as jmax_udpreceive but for PureData UDP connections.


+
+ +GridFlow 0.8.0 Documentation +Copyright © 2001,2002,2003,2004,2005 by Mathieu Bouchard +matju@artengine.ca + +

+ + diff --git a/externals/gridflow/doc/reference.xml b/externals/gridflow/doc/reference.xml new file mode 100644 index 00000000..8a5f8f7e --- /dev/null +++ b/externals/gridflow/doc/reference.xml @@ -0,0 +1,1591 @@ + + + + + + +

+ + + +

This object allows you to produce grids from non-grid data, such as + integers and lists of integers. This object also reframes/resyncs + grids so that multiple grids may be joined together, or + single grids may be split. That kind of operation is already done implicitly in many + cases (e.g. sending an integer or list to a grid-receiving inlet), + but using this object you have greater flexibility on the conversion.

+ + a list specifying a grid shape that the numbers + will fit into; or "per_message" indicating each incoming message + will be turned into a vector. + + + + + + + + + begins a new grid if there is no current grid. + puts that integer in the current grid. + ends the grid if it is full. + the constructed grid is not stored: it is streamed. + the stream is buffered, so the output is in packets + of about a thousand numbers. + + + just like a sequence of ints sent one after another, + except in a single message. + + + considered as a list of ascii characters. + + + aborts the current grid if there is one. + + + + this is the equivalent of filtering this grid through + an [#export] object and sending the resulting integers + to this [#import] object, except that it's over + 10 times faster. + + + + + old synonym for "shape per_message" + + + + + the grid produced from incoming integers and/or grids. + + + + + + + +

this object is the opposite of #import.

+ + this object is not configurable because there isn't + anything that could possibly be configured here. + + + + transforms this grid into a sequence of integer messages. + + + + + elements of the incoming grid. + + + + + + + +

this object is another opposite of [#import], which puts + all of its values in a list.

+ + + + transforms this grid into a single message containing + a list of integers. + + + + + elements of the incoming grid. + + + + + +

this object is another opposite of #import, which constructs a symbol + from its input. The values are expected to be valid ASCII codes, but no check + will be performed for that, and additionally, no check will be made that the generated + symbol only contains characters that can be put in a symbol.

+ + + + transforms this grid into a single message containing + a list of integers. + + + generated symbol + + + +

Similar to [#join], but takes individual integers, and builds a Dim(N) vector out of it. +

+ + + The value "any" (and the only available value for now) causes an output + to produced when an integer is received thru any inlet, contrary to most + other object classes, that only act upon reception of a value thru inlet 0. + + + + how many inlets the object should have. + + + + combination of inputs given in all inlets. + this is produced according to the value of the trigger attribute. + + + + +

Triple slider for the selection of RGB values.

+ + + + + + + Produces a Dim(3) grid of RGB values. + + + + + + + how many outlets the object should have. + (depending on the version of the software, the number of visible outlets + may have been frozen to 4. If it is so, then the value of this argument + must not exceed 4; and if it is below 4, then don't use the extraneous outlets.) + + + + the input vector is split in N parts containing one number each. + numbers are sent left-to-right, that is, outlet 0 is triggered first, then outlet 1, etc. + + + + + + + + + will compute the centroid of the given grid, which + is a weighted average, namely, the average position weighted + by the pixel values. + + + + result + + + + + a new experimental and faster version of #centroid. + + + will compute the centroid of the given grid, which + is a weighted average, namely, the average position weighted + by the pixel values. + + + + result + + + + + + + + +

when given scalar bounds, works like a regular [for] object plugged + to a [#import] tuned for a Dim(size) where size is the number of values + produced by a bang to that [for].

+ +

when given vector bounds, will work like any number of [for] objects + producing all possible combinations of their values in the proper order. + This replaces the old [#identity_transform] object.

+ + + + + + + + replaces the "from" value and produces output. + + + replaces the "to" value. + + + replaces the "step" value. + + + + where size is floor((to-from+1)/step) + [for scalar bounds] + + + where *size is floor((to-from+1)/step) + [for vector bounds] + + + +

+ +

+ + + + + + + + + +

This object outputs a grid by computing "in parallel" a same + operation on each left-hand element with its corresponding right-hand + element. +

+ + + + + + + + + on each element of this grid, perform the operation + together with the corresponding element of inlet 1. + in the table of operators (at the top of this document) + elements of inlet 0 are called "A" and elements of inlet 1 + are called "B". the resulting grid is the same size as the + one in inlet 0. + + + + + any grid, preferably shaped like the one that will be put + in the left inlet, or like a subpart of it (anyway the contents + will be redim'ed on-the-fly to fit the grid of inlet-0, + but the stored grid will not be modified itself) + + + stores a single int in the right inlet; the same int will + be applied in all computations; this is like sending a + Dim(1) or Dim() grid with that number in it. + + + + + + + + + + +

this object computes the square of complex numbers. + If seeing imaginary as Y and real as X, then this operation squares + the distance of a point from origin and doubles the angle between it + and the +X half-axis clockwise. (fun, eh?) +

used on an indexmap, this makes each thing appear twice, + each apparition spanning half of the original angle.

+ + + + + + + + + + + + +

[#fold +] computes totals

[#fold inv+] is an alternated sum (+/-)

[#fold * 1] can compute the size of a grid using its dimension list

[#fold & 1] can mean "for all"

[#fold | 0] can mean "there exists (at least one)"

[#fold ^ 0] can mean "there exists an odd number of..."

[#fold ^ 1] can mean "there exists an even number of...".

+ + + + + + + + + + replaces every Dim(last) subgrid by the result of a cascade on that subgrid. + Doing that + with seed value 0 and operation + on grid "2 3 5 7" will compute + ((((0+2)+3)+5)+7) find the total "17". + produces a Dim(dims) grid. + + + + + + + + + + +

[#scan +] computes subtotals; this can be used, for example, + to convert a regular probability distribution into a cumulative one. + (or in general, discrete integration) +

+ + + + + + + + + + replaces every Dim(last) subgrid by all the results of + cascading the operator on that subgrid, + producing a Dim(dims,last) grid. + + For example, with base value 0 and operation + on grid "2 3 5 + 7" will compute 0+2=2, 2+3=5, 5+5=10, 10+7=17, and give the + subtotals "2 5 10 17". + + + + + + + + + + + + + + + + + the operator must be picked from the table of two-input operators. + the grid is optional and corresponds to inlet 1. + + + + + produces a grid of size Dim(anyA..., anyB...), where numbers + are the results of the operation on every element of A and + every element of B. the resulting array can be very big. Don't + try this on two pictures (the result will have 6 dimensions) + + + + stores the specified grid, to be used when inlet 0 is activated. + + + + +

When given a grid of Dim(3) and a grid of Dim(5) [#outer] will + produce a grid of Dim(3,5) with the selected two-input operation + applied on each of the possible pairs combinations between numbers + from the left grid and the ones from the right. for example : + (10,20,30) [#outer +] (1,2,3) will give : + ((11,12,13),(21,22,23),(31,32,33))

+ + + + + + +

think of this one as a special combination of [#outer], [#] and + [#fold]. this is one of the most complex operations. It is very useful + for performing linear transforms like rotations, scalings, shearings, + and some kinds of color remappings. A linear transform is done by + something called matrix multiplication, which happens to be [#inner * + + 0]. [#inner] also does dot product and other funny operations.

+ + + + + + + op_para and op_fold are two operators picked from the table + of two-input operators. + the base value has to be specified (has no default value yet). + + + + + Splits the Dim(anyA...,lastA) left-hand grid into Dim(anyA...) + pieces of Dim(lastA) size. + + Splits the Dim(firstB,anyB...) right-hand grid into + Dim(anyB...) pieces of Dim(firstB) size. + + On every piece pair, does [#] using the specified + op_para operation, followed by a [#fold] using + the specified op_fold operator and base value. + + creates a Dim(anyA...,anyB...) grid by assembling all + the results together. + + (note: lastA must be equal to firstB.) + + + + + changes the base value to that. + + + + + changes the right-hand side grid to that. + + + + + + + + + + Which_dim is the number of the dimension by which the join will + occur. For N-dimensional grids, the dimensions are numbered from 0 + to N-1. In addition, negative numbers from -N to -1 may be used, to + which N will be added. + + + + The left grid and right grid must have the same number + of elements in all dimensions except the one specified. + The result will have the same number of elements in all + dimensions except the one specified, which will be the + sum of the two corresponding one. + +

For example, joining a RGB picture Dim[y,x,3] and a + greyscale picture Dim[y,x,1] on dimension 2 (or -1) could + make a RGBA picture Dim[y,x,4] in which the greyscale image + becomes the opacity channel. +

+ + + + + + + + + + any grid + + + a bang is emitted every time a grid transmission ends. + + + + + + + + + any grid + + + a grid of the same shape containing all the same + values after type conversion. note that while casting to + a smaller type, values that are overflowing will be truncated. + + + + + + any grid + + like [#redim] but always produce a 1-D grid + with the same total number of elements. + + + + + any grid + +

splits a Dim[A...,B] grid into Dim[B] vectors, + producing new Dim[B] vectors that each contain numbers from + 0 to B-1 indicating the ordering of the values. The result is + a Dim[A...,B] grid.

for example, connecting a [#grade] to a [#outer ignore {0}] + to a [#store] object, storing a single vector into [#store], and + sending the same vector to [#grade], will sort the values of the + vector. however for higher-dimensional grids, what should go + between [#store] and [#grade] to achieve the same result would + be more complex.

you may achieve different kinds of sorting by applying various + filters before [#grade]. the possibilities are unlimited.

if you plug [#grade] directly into another [#grade], you will + get the inverse arrangement, which allows to take the sorted values + and make them unsorted in the original way. note that this is really + not the same as just listing the values backwards.

+ + + + + + + + any grid + +

transforms a Dim[A...,B] grid into a Dim[A...,B-1] grid. + There is a projection plane perpendicular to the last axis and + whose position is given by the "depth" parameter. Each vector's + length is adjusted so that it lies onto that plane. Then the + last dimension of each vector is dropped.

+ +

useful for converting from 3-D geometry to 2-D geometry. Also + useful for converting homogeneous 3-D into regular 3-D, as + homogeneous 3-D is really just regular 4-D...(!)

+ + + + + + + + + + swaps the two specified dimensions; dimension numbers are as in [#join]. + + + + + + + + + produces on outlet 0 a linear recurrent fading according to the flow of + incoming messages. For example, if rate=5, then 20% (one fifth) + of each new message will be blended with 80% of the previous output. + + + + + + + + + + produces on outlet 0 a piecewise-linear nonrecurrent fading according to the flow of + incoming messages. For example, if maxraise=2 and maxdrop=4, then with each + new message an output is produced that is at most 2 more or 4 less than the + previous output. + + + + + + + Whichdim is the number of the dimension by which the reverse will + occur. For N-dimensional grids, the dimensions are numbered from 0 + to N-1. In addition, negative numbers from -N to -1 may be used, to + which N will be added. + + +

+ +

+ + + + + + + a list specifying a grid shape that the numbers + will fit into. + (same as with [#import]) + + + + the elements of this grid are serialized. if the resulting grid + must be larger, the sequence is repeated as much as necessary. + if the resulting grid must be smaller, the sequence is truncated. + then the elements are deserialized to form the resulting grid. + + + + + this grid is a dimension list that replaces the one + specified in the constructor. + (same as with [#import]) + + + + + redimensioned grid potentially containing repeating data. + + + +

example: with a 240 320 RGB image, [#redim 120 640 3] will visually + separate the even lines (left) from the odd lines (right). contrary + to this, [#redim 640 120 3] will split every line and put its left half + on a even line and the right half on the following odd line. [#redim] + 480 320 3 will repeat the input image twice in the output image. + [#redim] 240 50 3 will only keep the 50 top lines.

+ + + + + +

A [#store] object can store exactly one grid, using the right + inlet. You fetch it back, or selected subparts thereof, using the left + inlet.

+ + + + + + + + the stored grid is fully sent to the outlet. + + + in this grid, the last dimension refers to subparts of + the stored grid. sending a Dim(200,200,2) on a [#store] + that holds a Dim(240,320,3) will cause the [#store] to handle + the incoming grid as a Dim(200,200) of Dim(2)'s, where each + Dim(2) represents a position in a Dim(240,320) of Dim(3)'s. + therefore the resulting grid will be a Dim(200,200) of + Dim(3) which is a Dim(200,200,3). in practice this example + would be used for generating a 200*200 RGB picture from a + 200*200 XY map and a 240*320 RGB picture. this object can + be logically used in the same way for many purposes + including color palettes, tables of probabilities, tables + of statistics, whole animations, etc. + + + + + replace the whole grid, or a subpart of it (see other options on inlet 1) + + + + (Future Use): + makes it so that sending a grid to inlet 1 detaches the old buffer from [#store] + and attaches a new one instead. This is the default. + + (Future Use): + makes it so that sending a grid to inlet 1 writes into the existing buffer of [#store]. +

+ example: suppose you have [#store {10 240 320 3}]. then "put_at 3" + will allow to write a Dim[240,320,3] grid in indices (3,y,x,c) where y,x,c are indices of the incoming grid; + in other words, if that's a buffer of 10 RGB frames, you'd be replacing frame #3. Furthermore, + it also allows you to write a Dim[n,240,320,3] grid at (3+f,y,x,c) where f,y,x,c are indices of the incoming grid, + replacing frame #3, #4, ... up to #3+n-1. Here n is at most 7 because the last frame in the buffer is #9. +

that way of working extends to other kinds of data you'd put in Grids, in any numbers of dimensions; + because, as usual, [#store] wouldn't know the difference. +

+ + + + grids as stored, as indexed, or as assembled from multiple + indexings. + + + + + + + + {height width} pair. + + + + a 3-channel picture to be scaled. + + + a {height width} pair. + + + a scaled 3-channel picture. + + + + + + + + + factor is optional (default is 2). + if it's a single value, then that factor is to be used + for both rows and columns. + + + + duplicates each pixel several times in width and several times in height, + where the number of times is determined by the factor described above. + twice those of the incoming grid. It is several times faster. + + + sets factor + + + + + + + + + + + + factor is optional (default is 2). + if it's a single value, then that factor is to be used + for both rows and columns. + + + + Scales down picture by specified amount. (See scale factor above) + + + + sets scale factor + + + + + + + + + + +

typically you plug a [#for] into this object, + and you plug this object into the left side of a [#store]. it will + scatter pixels around, giving an "unpolished glass" effect.

+ +

if you put a picture in it, however, it will add noise. The + resulting values may be out of range, so you may need to clip them + using min/max.

+ + + same as inlet 1 + + + + a coordinate map. + + + a spread factor. + + + a coordinate map. + + + +

[#spread] scatters the pixels in an image. Not all original pixels + will appear, and some may get duplicated (triplicated, etc) + randomly. Some wrap-around effect will occur close to the edges. +

+ +

Sending an integer to inlet 1 sets the amount of spreading in + maximum number of pixels + 1. even values translate the whole image + by half a pixel due to rounding.

+ + + + +

performs rotations on indexmaps and polygons and such.

+ + + + + + + rotation angle; 0...36000 + + + + + + + +

if you chain indexmap (coordinate) transformations from outlet 1 + to inlet 1, then sending an image in inlet 0 will emit its + deformation out of outlet 0.

+ + + + + + +

+ +

+ + + +

Returns list of dimensions as a grid. Given a grid sized like Dim(240,320,4), + [#dim] will return a grid like Dim(3), whose values are 240, 320, 4.

+ + + no arguments. + + + + ignores any data contained within. + sends a grid dim(length of dims) containing dims. + + + + + the list of dimensions of the incoming grid. + + + + + +

gives a symbol representing the numeric type of the grid received. +

+ + + + + + + + prints the dimensions of the grid. + prints all the grid data if there are 2 dimensions or less. + + + + + + This is only for testing the translation from PD to Ruby. + + + + prints the message to the console. + + + + + + This is only for testing the translation from PD to Ruby. + + + prints everything. + + + + + GUI object equivalent to [print] and [#print]. + + Displays the received message in the box, resizing the box so that the message fits exactly. + + +

+ +

This object is useful for color correction. For each pixel + it takes it apart, looks up each part separately in the colormap, + and constructs a new pixel from that. You may also color-correct + colormaps themselves.

+ +

Only works for things that have 3 channels.

+ +

Note: if you just need to apply a palette on an indexed-color + picture, you don't need this. Just use #store instead.

+ + + + picture + + + + + colormap ("palette") + + + + picture + + + + + + + + + + + + + + + + + + + + + + +

note: may change slightly to adapt to actual video standards.

+ + + + + + + + + +

note: may change slightly to adapt to actual video standards.

+ + + + + + + +

+ +

+ + + +

this is the object for blurring, sharpening, finding edges, + embossing, cellular automata, and many other uses.

+ + + + + + + + + + + splits the incoming grid into dim(rest...) parts. + for each of those parts at (y,x), a rectangle of such + parts, centered around (y,x), is combined with the + convolution grid like a [#] of operation op_para. Then + each such result is folded like [#fold] of operation + op_fold and specified base. the results are assembled + into a grid that is sent to the outlet. near the borders of + the grid, coordinates wrap around. this means the whole grid + has to be received before production of the next grid + starts. + + + + + + this is the convolution grid and it gets stored in + the object. if rows2 and/or columns2 are odd numbers, + then the centre of convolution is the middle of the convolution + grid. if they are even numbers, then the chosen centre will + be slightly more to the left and/or to the top, because the + actual middle is between cells of the grid. + + + + + + + + + + + + + + same as inlet 1. + same as inlet 2. + + + + + + produces a grid like the incoming grid but with + different constrast. + +

[#contrast] adjusts the intensity in an image. + resulting values outside 0-255 are automatically clipped.

+ + + + this is the secondary contrast (inverse whiteness). + it makes the incoming black + correspond to a certain fraction between output black and the + master contrast value. no effect is 256. default value is 256. + + + + + this is the master contrast. it makes the incoming white + correspond to a certain fraction between output black and output + white. no effect is 256. default value is 256. + + + + + + + + + + + + +

[#posterize] reduces the number of possible intensities in an image; + it rounds the color values.The effect is mostly apparent with a low + number of levels.

+ + + same as inlet 1 + + + + + + produces a posterized picture from the input picture. + + + + + + this is the number of possible levels per channel. the + levels are equally spaced, with the lowest at 0 and the + highest at 255. the minimum number of levels is 2, and the + default value is 2. + + + + + + +

example: simulate the 216-color "web" palette using 6 levels. + simulate a 15-bit display using 32 levels.

+ + + +

makes medium intensities brightest; formerly brightest colours + become darkest; formerly darkest stays darkest. This filter is linear: + it's like a 200% contrast except that overflows are mirrored + instead of clipped or wrapped.

+ + + + + + + + + + + + + + + result from a [#for {0 0} {height width} {1 1}] + + + + + + checkered pattern of 50%/75% greys + in 8x8 squares + + + + + + + + + a picture that has an opacity channel. + will be used as foreground. + + + + + + a picture that has NO opacity channel. + will be used as background. + + + + + + a picture that has NO opacity channel. + the opacity channel of the foreground is used as + a weighting of how much of either picture is seen + in the result. + + + + + + + + Normally you would use the "put" operator here; + but abnormally I recommend + and ^ for psychedelic effects. + + + + + + + picture onto which another picture will be superimposed. + + + if enabled, inlet 1 picture will be repeated to cover the inlet 0 picture. + + + if enabled, inlet 1 picture will be combined with inlet 0 picture using + the selected operator, + and then blended with inlet 0 picture according to transparency of + the inlet 1 picture, and then inserted in the result. + if disabled, the blending doesn't occur, as the transparency level + is considered to be "opaque". note that with alpha enabled, + the last channel of inlet 1 picture is considered to represent transparency. + + + + + picture that will be superimposed onto another picture. + + + + + position of the inlet 0 picture corresponding to top-left corner + of inlet 1 picture. + + + + + resulting picture. + + + + + + + + Normally you would use the "put" operator here; + but abnormally I recommend + and ^ for psychedelic effects. + + + + + + + picture on which the polygon will be superimposed. + + + + + color of each pixel + + + + + vertices of the polygon. + + + + + + modified picture. + note: starting with 0.7.2, drawing a 1-by-1 + square really generates a 1-by-1 square, and + so on. This is because the right-hand border of a + polygon is excluded, whereas it was included + before, leading to slightly-wider-than-expected polygons. + + + + + +

inlet 2 receives a font grid, for example, [#in grid file lucida-typewriter-12.grid.gz]

inlet 1 receives a 2 by 3 matrix representing the colours to use (e.g. (2 3 # 0 170 0 255 255 0) means yellow on green)

inlet 0 receives a bang, transforming the data into an image suitable for #draw_image.

+ + +

inlet 1 receives an angle (0..36000)

inlet 0 receives a RGB picture that gets hueshifted by a rotation in the colorwheel by the specified angle; it gets sent to outlet 0.

+ +

+ This class has been removed (0.7.7). + + +

sets the receive-symbol for the Pd patcher it is in.

has no inlets, no outlets.

EXPERIMENTAL.

+ + + + + + + Transforms linear counting (0, 1, 2, 3, 4, ...) into a back-and-forth counting (0, 1, 2, 1, 0, ...) + from 0 to a specified upper bound. + + + + + + + + + a value to be transformed. + If, for example, top=10, then values 0 thru 10 are left unchanged, + values 11 thru 19 are mapped to 9 thru 1 respectively, and 20 thru 30 + are mapped to 0 thru 10, and so on. + + + + + + + +

+ objects of this class do nothing by themselves and are just + an access point to features that don't belong to any object in + particular. +

+ + resets all the time counters. + + + displays the time counters in decreasing order, with + the names of the classes those objects are in. this is + an experimental feature. like most statistics, + it could be vaguely relied upon if + only you knew to which extent it is unreliable. more on this + in a future section called "profiling". + + + + + + + which clock to use. "real" uses wallclock time. "user" uses + the amount of time spent in the process. "system" uses the + amount of time spent in the kernel on behalf of the process. + "cpu" uses the Pentium clock, which is like a more precise + version of "real" if you have a Pentium. + + optional + + + + + + Times at which bangs are received are stored until a large + enough sample of those is accumulated. Large enough is defined + to be whenever the timespan exceeds one second. Then a report + is made through the outlet. + + + messages other than bangs are ignored. + + + + + non-detailed mode only. + this is the messages-per-second rating. + + + detailed mode only. + this is: messages-per-second, followed by five values of + milliseconds-per-message: minimum, median, maximum, average, + standard deviation. + (the average happens to be simply 1000 divided by the + messages-per-second, but it is convenient to have it anyway) + + + + + +

+ This object returns the Unix timestamp. The first + outlet does so with ASCII, the second in seconds and the third outlet + outputs the fractions of seconds up to 1/100 000 th of a second which is useful for creating + filenames. +

+ + Outputs the time and date in ASCII format + Outputs the Unix timestamp in seconds + Outputs the fractions of a second up to 10 microseconds (?) (actual precision is platform-dependent afaik) + + + +

+ This object is similar to the Unix list command + 'ls'. It returns the names of files in a given + directory. May be used with [listlength] to retrieve the number of files. + Hidden files are displayed. +

+ + + + +

+ This object launches a Unix shell program or script. +

+ + + + +

+ This object accepts a list of two elements as arguments. + The current file name being the first and the second is the desired change + in name. +

+ + + + +

+ This object produces HPGL instructions in ASCII form + that can be sent to the comport object in order to control an HPGL + compatible plotter. +

+ + Outputs the HPGL commands in ASCII format + + + +

inlet 0 float : sends the specified array entry to outlet 0

inlet 1 list: writes that list as an array entry in position last specified by inlet 0.

inlet 0 save(symbol filename): writes the array contents to a file of the given filename as a CSV

inlet 0 save(symbol filename, symbol format): same thing but using a sprintf string such as %x,%f or whatever

inlet 0 load(symbol filename): replace all array contents by the contents of a CSV file

+ +

those classes emulate jMax functionality, + for use within PureData and Ruby.

+ + +

Every incoming message is sent to inlet 1 and then sent to + inlet 0 as well. Messages remain completely unaltered. Contrast + with PureData's "t a a" objects, which have the same purpose but + transform bangs into zeros and such.

+ + + + + + + Sends messages (but not grids nor dspsignals) via UDP (which + does not involve a connection, and may lose packets in case of + network overload or noise or etc). + +

This works with jMax 2.5 and 4.1 but not 4.0.

+ + + + + + + + + +

Counterpart of jmax_udpsend

+ +

This works with jMax 2.5 and 4.1 but not 4.0.

+ + + + + + + + + + + + + + + + Outputs N messages, one per list element, in order. + + + + + + + + Outputs the format string with %-codes replaced + by elements of the list formatted as the %-codes say. + To get a list of those codes, consult a Ruby manual + (Equivalently, Perl, Python, Tcl and C all have equivalents of this, + and it's almost always called sprintf, or the % operator, or both) + + + + + + + + + Emulation of jMax's [list] (but there cannot be a class named [list] in Pd) + + + + + send "list" to outlet 0 + as sending to inlet 1 and then banging; that is, passes thru and remembers. + + + + + + outputs the number of elements in the incoming list. + + + + + + + + Outputs one element of the list, as selected by "index". + Also accepts negative indices (e.g.: -1 means "last"), like Ruby, but unlike jMax. + + + + + + + + + + Outputs consecutive elements of the list, as selected by "index" and "length". + Also accepts negative indices (e.g.: -1 means "last"), like Ruby, but unlike jMax. + + + + + + + + + + Outputs the stored list followed by the incoming list, all in one message. + + + + + + + + + Outputs the incoming list followed by the stored list, all in one message. + + + + + + Outputs the incoming list, from last element to first element. + + + + Like [spigot], but turns itself off after each message, so you have to turn it on + again to making it pass another message. + + + + + + + outputs b-a + + + + + + + + + outputs b/a + + + + + (This is not in jMax, but is there to help port $* messageboxes) + + + Like [listprepend], but operates on whole messages, that is, including the selector. + + + + + (This is not in jMax, but is there to help port $* messageboxes) + + + Like [listappend], but operates on whole messages, that is, including the selector. + + + + + + Compatible with jMax's [demux]. + + number of outlets + initial selected outlet + + + Routes a message to the active outlet. + + + Selects which outlet is active. + + + + please use shunt instead (name conflict with another Pd external) + + + + + + + a value to be sent to one of the outlets. The first outlet is for values + smaller than the first argument; else the second outlet is for values smaller + than the second argument; and so on; and the last outlet is for values greater + or equal to the last argument. + + + sets the corresponding separator in the separator list. + + +

+ +

+ + same as jmax_udpsend but for PureData UDP connections. + + + same as jmax_udpreceive but for PureData UDP connections. + +

+ + -- cgit v1.2.1

+ +

+
+ GridFlow 0.8.0 - Installation +

	Hardware and Software you Probably Need + + Downloading from CVS + + Installation instructions (incl. compilation) + + Other Tips + + +
+
Hardware and Software you Probably Need

		Required Computer/Processor (one of...): 1 : PC : AMD K6/K7/K8 or Intel P2/P3/P4 (absolute minimum is 386) 2 : Macintosh : G3/G4/G5 3 : Corel NetWinder : StrongARM V4L 4 : HP iPaq : some processor that works like the NetWinder 5 : could work on SiliconGraphics and SPARCstation with a little nurture.

		Required OS (one of...): 1 : Linux (most any variant) (recommended) 2 : MacOS 10.2 or later (experimental) 3 : Windows with MinGW (very experimental)

		Required Software: 1 : Ruby 1.6.6 or more recent (1.8.0 recommended) (make sure you have the .so and .h files) + (on MacOS you may have to remove or hide the existing one and install a more complete package)

		Dataflow Software : 1 : PureData 0.36 or later (recommended)

		Multimedia Components (optional): 1 : libSDL (Simple Directmedia Layer) 2 : libjpeg 3 : libpng 4 : libmpeg3 (.mpg reader, HeroineWarrior's) 5 : libquicktime (.mov reader/writer, Burkhard Plaum's or HeroineWarrior's) 6 : libmpeg (.mpg reader, Greg Ward's, old) 7 : Apple QuickTime (.mov reader/writer) 8 : Ascii Art Library (aalib) 9 : PCI video digitizer card (and Video4linux 1 driver) 10 : USB camera (and Video4linux 1 driver)

		Developer Tools (roll-your-own): 1 : GNU C++ Compiler (gcc/g++) version 3.x or maybe 2.95 2 : GNU Make (gmake) 3 : CVS (for upgrading/collaboration) 4 : Ruby library "xmlparser" (optional, for editing documentation) 5 : Developer Tools CD dec 2002 (if MacOS 10.2) 6 : XCODE (if MacOS 10.3) 7 : FINK (if MacOS 10)

		NOTE: Apparently GCC 2.x has problems dealing with .a components; if that +affects you, use .so files instead.


+
Downloading from CVS

		The CVS has the absolute latest version of GridFlow, but it's not guaranteed to be working, whereas +the actual releases are more tested.

		However you may have various reasons to use the CVS edition, so here's how:

		Make sure you have the `cvs` program installed.

		`mkdir -p ~/src/gridflow` (make a directory; it could be called otherwise if you like)

		`cd ~/src/gridflow` (go in that directory)

		`cvs -d :pserver:anonymous@cvs.gridflow.ca:/home/cvs/gridflow login` (the password is blank)

		`cvs -d :pserver:anonymous@cvs.gridflow.ca:/home/cvs/gridflow checkout .` (download the first time)

		And the subsequent times, you only do this:

		`cd ~/src/gridflow`

		`cvs update -dP`


+
Installation instructions (incl. compilation)

		1 : Install Ruby. Make sure it contains `ruby.h` and `intern.h` and related files. It's also +recommended to have `libruby.so`. Those extra files may be in a package called `ruby-dev` +if you are using RPM or DEB/FINK. If you are building Ruby yourself, it's better to configure ruby with `--enable-shared`. If you install into a system directory, you may have to run `ldconfig` +after installing Ruby. 2 : Download GridFlow from the website and uncompress it, or get it from the CVS server. 3 : Run `./configure` from the `gridflow` directory. Make sure it detects all the components +you want to use with GridFlow. In MacOS you would normally use FINK to install: `libjpeg libjpeg-shlibs libpng-shlibs libpng3 libpng3-shlibs libmpeg libmpeg-shlibs` 4 : Note: you may have to set `CPLUS_INCLUDE_PATH` to indicate where to find .h files, and you +may have to set both `LIBRARY_PATH` and `LD_LIBRARY_PATH` to indicate where to find +.so or .aor .dylib or .bundle or .dll or *.lib files. 5 : Note: you can do `./configure --help` to get a list of supported +options. You can use them to ignore the presence of troublesome libraries +and select debugging level. With `--use-compiler` you should use a version of `g++`, not +directly a version of `gcc`, else you get `undefined symbol` problems. Some versions of gcc/g++ +are troublesome. 6 : Run `make` to produce the executables `gridflow.so` and `gridflow.pd_linux` or similar 7 : Run `make install` to copy those executables and related files to their final locations. 8 : Run `make test` just to verify that GridFlow isn't working too bad. 9 : With a text editor, create `~/.gridflow_startup` and write something like `GridFlow.data_path << "/home/myself/gridflow/images"` to tell GridFlow where to find the +images used in the examples. You may add more lines like that one if you have folders containing images +or movies you want to use with GridFlow. 10 : Loading GridFlow: 1 : PureData : With a text editor, modify or create `~/.pdrc` and write `-lib gridflow`. 2 : ImpureData : In the ".pdrc editor", add `gridflow` to the list of libraries. 3 : plain Ruby : the command `require "gridflow"` will load gridflow.so. +Note that on MacOS the dot-files are invisible in the Finder but you do `cd ~/Desktop; ln -s ../.pdrc "PureData Configuration"` to make an alias on the Desktop. +Note also that on Windows the dot-files are even more trouble.


+
Other Tips

		1 : you just did a CVS update and now the program does not compile, or +crashes, or changes didn't go through. 1 : Did you forget the "make install" step? 2 : If a new directory is created, you need to do `cvs update -d`. + Many people just add that option to their configuration of the CVS software. 3 : When some kinds of changes have happened, you may have to rerun the `configure` + program before redoing `make`. If you had previously reconfigured with specific options, + don't forget to use them again in this case. 4 : Maybe matju forgot to upload part of an important change. Tell him. 2 : PureData Crashing: 1 : you can start the debugger like gdb `which pd` core.24255 where the latter part + is the name of a RAM dump file. You can enable those dumps using the shell command `ulimit -c unlimited`. To avoid dumping, you can also start Pd from within the debugger + using gdb `which pd` then `run` then cause the crash. 2 : In GDB, after a crash, you can use the `where` to find out what Pd was doing at the moment + of the crash. If instead Pd is frozen, you can force it to crash using Ctrl+C in the terminal. 3 : To quit GDB use the `quit` command. (really.)


+
+ +GridFlow 0.8.0 Documentation +Copyright © 2001,2002,2003,2004,2005 by Mathieu Bouchard +matju@artengine.ca + +

+ +

+
+ GridFlow 0.8.0 - C++/Ruby Internals +

	notes + + Objects for Scripting + + + + + + + + + + + Objects for Internals + + + + + + + + + + +
+
notes

		In Ruby, GridFlow defines a namespace (module) called GridFlow. Most of the +constants it defines are part of that namespace.

		Ruby does not have the same concept of object as PD. In GridFlow, object classes may +inherit features from other object classes, and also there is no concept of inlet nor outlet, which are instead +provided by `GridFlow::FObject`, which also has the purpose of exporting functionality to +PD.

		In this document (and in many others) the phrase "a Potato" will be a shorthand for "an object of the class +called Potato", which is often used in modern software design and is a nice convention borrowed from +biology.

		+A FObject is normally in two or three parts: a (Ruby) GridFlow::FObject +that is the central part; a (C++) FObject; a (C++) BFObject. +The GridFlow::FObject is created as a RData kind of box (T_DATA) +using Ruby-C's Data_Make_Struct on a GridObject. This is +how most Ruby-C programs inherit from Ruby classes. Note that +Ruby's boxed objects have a maximum of five fields, and they're usually +taken, so additional fields have to be outside of it. This is why RData exists.

		+So basically you have a C++ FObject that is "part of" a GridFlow::FObject +and they point to each other using "peer pointers". + The BFObject links back to the RData box through a pointer called peer.


+
Objects for Scripting

class ruby class FObject extending Data
	+	+ + Provides inlets and outlets to Ruby Objects. method init () + method send_in (int inlet, message...) + method send_out (int outlet, message...) +

class ruby class GridObject extending FObject
	+	+ + Provides grid support to FObjects. method inlet_dim (Integer inlet) + gives an array of Integers (dimension list) + method inlet_nt (Integer inlet) + gives a Symbol (number type) + method inlet_set_factor (Integer inlet, Integer factor) + ensures received packets have a size that is + a whole multiple of this size. + must be called from rgrid_begin. + method send_out_grid_begin (Integer outlet, Array of Integer dimensions, number type nt) + establishes grid streams between an outlet and all inlets + connected to it. + method send_out_grid_flow (Integer outlet, String data) + for sending a grid data packet through that outlet. + method send_out_grid_end (Integer outlet) + (isn't this one obsolete?) + inlet 0 method rgrid_begin () + inlet 0 method rgrid_flow (String data) + inlet 0 method rgrid_end () +

class ruby class BitPacking
	+	+ + A BitPacking is a simple two-way converter between different + numeric layouts.

class ruby FPatcher extending FObject
	+	+ This class is much like PureData's abstractions. This is a container for objects. Its proper objects are numbered + starting with zero. The wire list is given in terms of those numbers: + (sourceobject,sourceinlet,destobject,destinlet). There is a + pseudo-object numbered #-1 which map to the container's own inlets + and outlets.

class ruby GridFlow::USB
	+	+ wrapper for struct usb_dev_handle attr .busses (.busses)

class ruby GridFlow::USB::Device
	+	+ wrapper for struct usb_device and struct usb_device_descriptor

class ruby GridFlow::USB::Config
	+	+ wrapper for struct usb_config_descriptor, struct usb_interface

class ruby GridFlow::USB::Interface
	+	+ wrapper for struct usb_interface_descriptor

class ruby GridFlow::USB::Endpoint
	+	+ wrapper for struct usb_endpoint_descriptor


+
Objects for Internals

class C++ class GridInlet
	+	+ + GridInlets represent inlets that accept grids.

class C++ class GridOutlet
	+	+ + GridOutlets represent outlets that send grids.

class C++ class Dim
	+	+ + Dim represents a list of dimensions.

class C++ class Grid
	+	+ + Grid represents a grid that is fully stored in memory.

class C++ class Numop1
	+	+ + This represents a one-input operator. + Such an object contains a map() function that applies the operator + over a memory segment.

class C++ class Numop2
	+	+ + This represents a two-input operator. + Such an object contains four functions for each T, where + T is one of the types uint8, int16, int32, float32. method map (integer n, Pt as, T b) + for i in 0...n, + as[i] := f(as[i],b); + This is like `[#]` with a scalar righthand + method zip (integer n, Pt as, Pt bs) + for i in 0...n, + as[i] := f(as[i],bs[i]); + bs is not modified. + (This is like `[#]` with a nonscalar righthand) + method fold (integer an, integer n, Pt as, Pt bs) + for i in 0...n, + for j in 0...an, + as[j] := f(as[j],bs[ian+j]); + (this is like `[#fold]`) + method* scan (integer an, integer n, Pt as, Pt bs) for j in 0...an: bs[j] := f(as[j],bs[j]); for i in 1...n: for j in 0...an: + bs[j] := f(bs[(i-1)an+j],bs[ian+j]); + (this is like `[#scan]`) +

class C++ class GridClass
	+	+ + This represents a class of GridObjects.

class C++ class GFBridge
	+	+ + This holds linkage information about PureData.


+
+ +GridFlow 0.8.0 Documentation +Copyright © 2001,2002,2003,2004,2005 by Mathieu Bouchard +matju@artengine.ca + +

+


+ GridFlow 0.7.7 - introduction +

	+ + The philosophy that guides PureData is a simple but powerful one: + the software must first provide the user with generic tools + rather than imposing pre-cooked effects. In other words the user + should have total freedom. + + GridFlow follows that philosophy: it first defines elementary + mathematical operations. Those can in turn be used as simple + visual effects or be combined to produce more complex effects. + + The strategy followed by most video plugins for PureData, jMax, and MAX/MSP, is + to provide the user first with constructs for manipulating video + streams at a fairly high level. The strategy put forward by GridFlow + is different. + + It can be said that in all those video plugins there are three layers: + the first, the low level, is not accessible to non-programmers (and fairly + difficult of access even to programmers); the second, mathematical, where + one needs not to be a C++ programmer, but still requires a good + understanding of how numbers and pixels and colours and geometry work; and + a third level that looks more like the software an artist would like to + use. + + In other video plugins there is a fairly low emphasis on the second + layer. In GridFlow that layer is very strong and opens many possibilities. + Even though the third layer in GridFlow is not as developed as it could, + the second layer may be used to produce third-layer object classes much + more quickly. + + GridFlow provides a unifying view of multimedia information. Several + kinds of data -- raster graphics in any number of channels, coordinate + transforms, matrices, vectors -- may all be represented by Grids + (also known as multi-dimensional arrays). Grids exist in several ways: they + are usually streamed from object to object, but they can also be stored in + memory, stored into a file, sent through the network. + + The new GridFlow (0.6) also provides scripting, which inserts itself + between the first and second layer to provide additional functionality. The + language that has been chosen is Ruby, designed by Yukihiro Matsumoto + during the 90's. This new layer is used for portability between host + software (PureData vs jMax), for portability between platforms (Windows/Mac + versions do not exist but would be farther ahead if it wasn't for Ruby), + for independency from host software (GridFlow can be tested and used + independently of PureData/jMax), for quick extensibility (you can create + PureData/jMax object classes directly in GridFlow's configuration file), + and so on. + + In short, GridFlow is a whole new world of possibilities for + the multimedia artist and programmer. + + - matju +


	+ + Here is an example of how things work in GridFlow. (if you want more + information, consult the rest of this manual) + + A picture is a three-dimensional Grid: + 0 : rows + 1 : columns + 2 : channels + + + Pictures come in all sorts of heights and widths. The channels, however, + are more limited in number. Usually it's three: Red, Green, Blue. + + A coordinate transform, when specified pixel by pixel, may be a + three-dimensional Grid in which the two "channels" are Y and X, + representing row-and-column positions in a separate picture. + + Other shapes of grids could be designed to represent various things; + for example, configuration for blur effects. Grids could be useful for + things not directly related to raster pictures (e.g. sound recordings). + Those are all kinds of things you could actually develop within the + PureData / GridFlow framework. You don't need to wait for me. +


+ GridFlow 0.7.7 Documentation + by Mathieu Bouchard matju@sympatico.ca + and + Alexandre Castonguay acastonguay@artengine.ca +

GridFlow 0.8.0 - Reference Manual: Architecture

Numbers

Grid Literals

Grid Protocol

Picture Protocol

Numeric Operators

Synchronisation

Bridges

GridFlow 0.8.0 - Reference Manual: Format Classes

Objects for Input/Output

Picture/Movie Formats

Acquisition Devices

Window Output

GridFlow 0.8.0 - documentation index

GridFlow On The Net

Credits

Sponsors

GridFlow 0.8.0 - Installation

Hardware and Software you Probably Need

Downloading from CVS

Installation instructions (incl. compilation)

Other Tips

GridFlow 0.8.0 - C++/Ruby Internals

notes

Objects for Scripting

Objects for Internals

GridFlow 0.7.7 - introduction

GridFlow 0.7.7 - License

GridFlow 0.7.7 - Profiling Execution Speed

What is profiling?

How to get those stats from GridFlow ?

How do i interpret those stats?

Getting a frames-per-second measure

acceleration tricks

GridFlow 0.8.0 -

Note

Release

Documentation

CVS

GridFlow 0.8.0 - Reference Manual: Flow Classes

Objects for making grids and breaking them down

Objects for Computing

Objects for Coordinate Transforms

Objects for Reporting

Objects for Color Conversion

Objects for Miscellaneous Picture Processing

Other Objects

jMax emulation

PureData emulation