GridFlow 0.9.3 - Reference Manual: Format Classes

From 089475041fe26964d72cb2ebc3559a36ba89a2f2 Mon Sep 17 00:00:00 2001 From: "N.N." Date: Tue, 8 Jul 2008 05:56:10 +0000 Subject: trying to import gridflow 0.9.4 svn path=/trunk/; revision=10148 --- externals/gridflow/doc/format.html | 511 +++++++++++++++++++++++++++++++++++++ 1 file changed, 511 insertions(+) create mode 100644 externals/gridflow/doc/format.html (limited to 'externals/gridflow/doc/format.html') diff --git a/externals/gridflow/doc/format.html b/externals/gridflow/doc/format.html new file mode 100644 index 00000000..3dd3a830 --- /dev/null +++ b/externals/gridflow/doc/format.html @@ -0,0 +1,511 @@ + + + + +GridFlow 0.9.3 - Reference Manual: Format Classes + + + + + +

+ + + + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ +
GridFlow 0.9.3 - Reference Manual: Format Classes
+

Objects for Input/Output
+
#in +
+
#out +
+
#peephole +
+
#mouse +
+
#camera +
+
+
Picture/Movie Formats
+
format ppm #in/#out +
+
format targa #in/#out +
+
format jpeg #in/#out +
+
format png #in +
+
format quicktime #in/#out +
+
format mpeg #in +
+
format grid #in/#out +
+
+
Acquisition Devices
+
format videodev #in +
+
+
Window Output
+
format x11 #in/#out +
+
format quartz #out +
+
format sdl #out +
+
format aalib #out +
+
format window #out +
+
+

+

+
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.9.3 Documentation
+Copyright © 2001-2007 by Mathieu Bouchard +matju@artengine.ca +
+
-- cgit v1.2.1