From ccddec68116fc6403858ebfa13d4a7b1aa3d5278 Mon Sep 17 00:00:00 2001 From: "N.N." Date: Sun, 18 Oct 2009 20:01:19 +0000 Subject: hi gridflow 0.9.5 svn path=/trunk/; revision=12611 --- externals/gridflow/doc/format.xml | 714 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 714 insertions(+) create mode 100644 externals/gridflow/doc/format.xml (limited to 'externals/gridflow/doc/format.xml') diff --git a/externals/gridflow/doc/format.xml b/externals/gridflow/doc/format.xml new file mode 100644 index 00000000..78a398e1 --- /dev/null +++ b/externals/gridflow/doc/format.xml @@ -0,0 +1,714 @@ + + + + + +
+ + + + + + 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 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 + + + 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. + + + + + 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
    • +
  • ???
    • +
  • Meta
    • +
  • ScrollLock
    • +
  • Left Button
    • +
  • Middle Button
    • +
  • Right Button
    • +
  • Wheel Up
    • +
  • Wheel Down
    • +

    +

    NOTE: This message form may become longer in the future, but the already defined parts will stay the same.

    +     + + + + + +

    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.

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

    +     +     +     + + + The equivalent of format x11 on MacOS 10.x, but with less features (sorry). + + opens a dim(240,320,3) rgb window (default). + + + + Sends image to screen. Window will be resized to fit the image exactly. + + + + + + Opens a dim(240,320,3) rgb window (default). + + + + Sends image to screen. Window will be resized to fit the image exactly. + + + + + + + Normally "X11" with uppercase X; else consult + the AALib manual. + + + You can pass "commandline options" of AALib here. + + + + + 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. + + + + the inverse of "dump". Both together in a loop allow to + post-process aalib's buffer before displaying. Goes well + with "draw", "autodraw". + + + + + + + + + like X11's autodraw. + + + like X11's draw. + + + produces a Dim[y,x,2] grid whose two channels are + ascii character codes and character attributes. + + + + + + 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) + + +
    + +     -- cgit v1.2.1