diff options
author | N.N. <matju@users.sourceforge.net> | 2009-10-18 20:01:19 +0000 |
---|---|---|
committer | N.N. <matju@users.sourceforge.net> | 2009-10-18 20:01:19 +0000 |
commit | ccddec68116fc6403858ebfa13d4a7b1aa3d5278 (patch) | |
tree | 6b90e41b15bbf2440afa76d53cc436debf5b5c5b /externals/gridflow/doc/format.xml | |
parent | a1fb215b39535805aa19608185d5e52c0f524b42 (diff) |
hi gridflow 0.9.5
svn path=/trunk/; revision=12611
Diffstat (limited to 'externals/gridflow/doc/format.xml')
-rw-r--r-- | externals/gridflow/doc/format.xml | 714 |
1 files changed, 714 insertions, 0 deletions
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 @@ +<?xml version="1.0" standalone="no" ?> +<documentation title="Reference Manual: Format Classes"> +<!-- $Id: format.xml 3559 2008-04-16 20:29:00Z matju $ --> +<!-- + GridFlow Reference Manual: Format Handler Reference + Copyright (c) 2001,2002,2003,2004,2005 by Mathieu Bouchard +--> + +<section name="Objects for Input/Output"> + <class name="#in"> + <method name="init" min="0"> + <arg name="format"/> + <rest name="format_specific_part"/> + + If no arguments given, creates an input object for an unspecified + format. You then need to use the <k>"open"</k> command to link + a format handler to it. + + If arguments given, the <k>"open"</k> command is immediately called + with those arguments. + + Remember that most formats produce Dim[rows,columns,3] grids with + 0-255 values. (Most.) + </method> + + <inlet id="0"> + <method name="open" min="1"> + <arg name="format"/> + <rest name="format_specific_part"/> + This is the command that gives a particular resource + to a <k>[#out]</k> 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. + </method> + <method name="open"> + <arg name="filename"/> + This is a shortcut for <k>"open file"</k> followed by a filename. + The filename must contain a dot, else it will be seen as a handler name. + </method> + <method name="close"> + close may be necessary if you operate on <k>"/dev/video"</k>, + which can only be read by one at a time. otherwise it's + usually not necessary. + </method> + <method name="int"> + <arg name="frame_number"/> + selects one picture from a multi-picture format + and then does the same as a bang. + </method> + <method name="set"> + <arg name="frame_number"/> + selects one picture from a multi-picture format, + to be displayed by the next bang. + </method> + <method name="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". + + </method> + <method name="option"> + <arg name="selector" type="symbol"/> + <rest name="stuff"/> + Obsolete. the word "option" is optional now. + </method> + <method name="rewind"> + rewinds to beginning of file if applicable. + </method> + <method name="loop"> + <arg name="flag" type="bool"/> + controls the automatic looping of movies. + </method> + + </inlet> + + <outlet id="1"> + <method name="int"> + frame number of frame just sent, + for formats that have frame numbers. + </method> + + <method name="bang"> + tried to read a frame that does not exist + (signals end of file) + </method> + </outlet> + </class> + <class name="#out"> + <method name="init" min="0"> + <arg name="format"/> + <rest name="format_specific_part"/> + + If no arguments given, creates an output object for an unspecified + format. You then need to use the <k>"open"</k> command to link + a format handler to it. + + If arguments given, the <k>"open"</k> command is immediately called + with those arguments. + + Remember that most formats expect dim(rows,columns,3) grids with + 0-255 values. (Most.) + </method> + <method name="init"> + <arg name="rows" type="integer"/> + <arg name="columns" type="integer"/> + + This alternate way to create an <k>[#out]</k> automatically calls + <k>"open window"</k> and <k>"out_size <i>rows columns</i>"</k>. + </method> + <inlet id="0"> + <method name="open" min="1"> + <arg name="format"/> + <rest name="format_specific_part"/> + This is the command that gives a particular resource + to a <k>[#out]</k> 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. + </method> + <method name="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. + </method> + <method name="open"> + <arg name="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. + </method> + <method name="grid"><arg name="grid" type="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". + </method> + <method name="close"> + closes the file. usually not necessary. + </method> + <method name="option"> + <arg name="selector" type="symbol"/> + <rest name="stuff"/> + Obsolete. Omit the word "option" now. + </method> + <method name="timelog"> + <arg name="status" type="0,1"/> + 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. + </method> + <method name="rewind"> + rewinds to beginning of file if applicable. + will overwrite the previous data. + </method> + <method name="autoclose"> + ... + </method> + </inlet> + <outlet id="0"> + <method name="bang"> + sent when a complete grid has been received. + </method> + </outlet> + </class> + + <class name="#peephole"> + <p> + This object class only works with a X11-based version of Pd. + (e.g. on Linux, BSD, but not MacOS X). + </p> + <p>Similar to <k>[#out window]</k>, 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 <k>[#out window]</k> and automatically scales cursor position according to the current scale factor. + The scale factor is decided automatically. + </p> + <method name="init"> + <arg name="height" type="int"/> + <arg name="width" type="int"/> + </method> + <p>All other methods are as in <k>[#out window]</k>.</p> + </class> + <class name="#mouse"> + This will process the "position" messages emitted by <k>[#out]</k> or <k>[#peephole]</k> in + useful ways. + <outlet id="0"><method name="list"> + y,x coords of a click + </method></outlet> + <outlet id="1"><method name="list"> + y,x coords of a drag (any button is kept pressed) + </method></outlet> + <outlet id="2"><method name="list"> + y,x coords of an unclick + </method></outlet> + <outlet id="3"><method name="list"> + y,x coords of a move (no button is pressed) + </method></outlet> + <outlet id="4"><method name="float" type="0,1">button 1 status</method></outlet> + <outlet id="5"><method name="float" type="0,1">button 2 status</method></outlet> + <outlet id="6"><method name="float" type="0,1">button 3 status</method></outlet> + <outlet id="7"><method name="float" type="-1,1"> + wheel difference: -1 = roll up; 1 = roll down. + </method></outlet> + </class> + <class name="#camera"> + Works about like <k>[#in videodev]</k> except you can right-click-open it to access all of the + camera settings visually. + </class> +</section> + +<section name="Picture/Movie Formats"> + + <class name="format ppm #in/#out"> + <p>Subformat P6 only. + Max-number can only be 255 (24-bit RGB). + </p> + + <method name="open ppm file"> + <arg name="filename" type="symbol"/> + opens the specified file, taken from the current + directory. + </method> + + <method name="open ppm gzfile"> + <arg name="filename" type="symbol"/> + same but for .ppm.gz files + </method> + + <method name="grid"> + <arg name="grid" type="grid(rows columns {r g b})"/> + values 0-255 + </method> + </class> + + <class name="format jpeg #in/#out"> + <p>Support for RGB non-progressive</p> + + <method name="open jpeg file"> + <arg name="filename" type="symbol"/> + opens the specified file, taken from the current + directory. + </method> + + <method name="grid"> + <arg name="grid" type="grid(rows columns 3)"/>RGB-24 + </method> + </class> + + <class name="format png #in"> + <p>Support for RGB non-progressive</p> + + <method name="open png file"> + <arg name="filename" type="symbol"/> + opens the specified file, taken from the current + directory. + </method> + + <method name="grid"><arg name="grid" type="grid(rows columns 1)"/>Y-8 (greyscale)</method> + <method name="grid"><arg name="grid" type="grid(rows columns 2)"/>YA-16 (greyscale and transparency)</method> + <method name="grid"><arg name="grid" type="grid(rows columns 3)"/>RGB-24 (colour)</method> + <method name="grid"><arg name="grid" type="grid(rows columns 4)"/>RGBA-32 (colour and transparency)</method> + </class> + + <class name="format quicktime #in/#out"> + <p>Support for .mov files.</p> + <p>This format supports frame-seek and frame-tell.</p> + <p>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.</p> + <p>Some versions of those libraries may include support for different codecs, + and some also may support entirely different wrapper formats such as AVI.</p> + <p>On Macintosh, Apple QuickTime is used instead, but several of the following + messages may not be available.</p> + + <method name="open quicktime file"> + <arg name="filename" type="symbol" /> + </method> + <method name="codec"> + <arg name="codec" type="symbol"/> + 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 <k>[#out]</k>. 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> + <method name="parameter"> + <arg name="key" type="symbol"/> + <arg name="value" type="int"/> + Sets special codec-specific settings. + For example: <k>"parameter jpeg_quality 75"</k> + </method> + <method name="framerate"> + <arg name="fps" type="int"/> + Sets the framerate of the file. + This is not used by GridFlow when reading a file, but other + programs usually care. + </method> + + <method name="colorspace"> + <arg name="colorspace" type="symbol"/> + Allowed values are rgb, rgba, bgr, bgra, yuv, yuva. + Normally you don't need this. + </method> + <method name="size"> + <arg name="height" type="int"/> + <arg name="width" type="int"/> + Forces a window size when writing. Usually this has to be used <u>after</u> + setting the framerate and codec and <u>before</u> setting the codec-parameters. + (Strange. Sorry.) + </method> + <method name="force_size"> + <arg name="height" type="int"/> + <arg name="width" type="int"/> + forces a window size when reading. + this is a workaround for a problem in HW-QuickTime. + </method> + </class> + + <class name="format mpeg #in"> + <p>support for .mpeg files</p> + <p>this format supports frame-seek and frame-tell.</p> + <p>Two different libraries are available for dealing with + MPEG files. Those have different details, capabilities and quirks.</p> + <p>In any case, GridFlow does not support importing audio from + those files.</p> + <p>If you use the HeroineWarrior library, you may open several + mpeg files at once, but not with the GregWard library.</p> + <p>Libraries may scream error messages in a rude way.</p> + <p>By opposition to PPM and TARGA, this format driver only + allows a single MPEG stream per file (you cannot "cat" + several MPEG files together). + </p> + <p>Supports Rewind and Frame Select.</p> + <method name="open mpeg file"> + <arg name="filename" type="symbol"/> + opens the specified file, taken from the current + directory. + </method> + </class> + + <class name="format grid #in/#out"> + <p> + This is GridFlow's special file format. This is the only I/O + format that can hold anything that the <k>[#store]</k> object can. + </p> + <p> + This is the picture format that would support TCP connections + if that feature actually worked. More on this later. + </p> + + <method name="open grid file"> + <arg name="filename" type="symbol"/> + opens the specified file, taken from the current + directory. + </method> + <method name="open grid gzfile"> + <arg name="filename" type="symbol"/> + same but for .grid.gz files + </method> + <method name="type int32"> + output will be as 32 bit signed integers. + </method> + <method name="type uint8"> + output will be as 8 bit unsigned integers. + </method> + <method name="headerful"> + cancels "headerless" (and back to reading .grid) + </method> + <method name="headerless"> + <rest name="dimensions" type="integer"/> + 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: + <k>type</k> and <k>endian</k>. + </method> + + <p>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 name="endian" type="symbol(big|endian|same)"> + <list><li>big: + A number will be written starting with the biggest digit. + This is the natural way on the Macintosh, Sun, Amiga, and so on. + </li> + <li>little: + A number will be written starting with the smallest digit. + This is the natural way on the Intel 386/Pentium. + </li> + <li>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. + </li> + </list> + </method> + </p> + </class> +</section> + +<section name="Acquisition Devices"> + <class name="format videodev #in"> + <method name="open"> + <arg name="device"/> + </method> + + <p>Video4Linux-1 devices, RGB-24 only. Variable picture size.</p> + + <p>We have been testing it using cards of the BT-848 family, + such as Miro DC10plus and Hauppauge WinTV, using the <k>bttv.o</k> linux driver. + Also we have been testing using Logitech QuickCam (and similar Labtec hardware), + but don't use the <k>qce-ga</k> driver, which is buggy and obsolete: the <k>qc-usb</k> + works better.</p> + + <p>Some hardware doesn't support RGB, so you may have to select a YUV colorspace + (see below) and then use <k>[#yuv_to_rgb]</k>. Don't forget to also do + <k>[# min 255]</k> and <k>[# max 0]</k>. + </p> + + <p>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 <k>[#inner * + 0 {3 3 # 0 0 1 0 1 0 1 0 0}]</k>.</p> + + <p>color adjustments: + <method name="brightness"><arg name="level" type="0-65535"/></method> + <method name="hue" ><arg name="level" type="0-65535"/></method> + <method name="colour" ><arg name="level" type="0-65535"/></method> + <method name="contrast" ><arg name="level" type="0-65535"/></method> + <method name="whiteness" ><arg name="level" type="0-65535"/></method> + </p> + <method name="get"> + <arg name="attr" type="symbol"/> + gets a specific attribute. a message is sent through right outlet. + valid attributes are: brightness, hue, colour, contrast, whiteness. + </method> + <method name="get"> + gets all attributes. + </method> + + <p>other options: + <method name="channel" ><arg type="integer"/></method> + <method name="tuner" ><arg type="integer"/></method> + <method name="norm" ><arg type="integer"/></method> + <method name="frequency" ><arg type="integer"/></method> + <method name="transfer" > + <arg type="symbol(read|mmap)"/> + <arg type="integer" default="2"/> + <list> + <li>mmap: + This is the normal (and fast) way of transferring pictures + from the camera. + </li> + <li>read: + Some cameras/drivers only support this instead of mmap. + </li></list> + 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> + + <method name="colorspace"> + <arg name="colorspace" type="symbol"/> + Allowed values are: RGB24, YUV420P. + Use this if your driver doesn't support RGB24. + </method> + + <method name="size"> + <arg name="height"/> + <arg name="width"/> + sets the input size, especially when using a video digitalizer + device. + </method> + </p> + </class> +</section> + +<section name="Window Output"> + + <class name="format x11 #in/#out"> + <p>supports 15,16,24,32-bit truecolor displays</p> + + <p>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.</p> + + <p>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.</p> + + <method name="open x11"> + synonym of "open x11 here". + </method> + + <method name="open x11 here"> + connects to the default X11 server, + according to your environment variable "DISPLAY". + </method> + + <method name="open x11 local"> + <arg name="display_number" type="integer"/> + connects to a display server on this machine. + </method> + + <method name="open x11 remote"> + <arg name="host_name" type="symbol"/> + <arg name="display_number" type="integer"/> + 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> + + <method name="grid"> + <arg name="grid" type="grid(rows columns {red green blue})"/> + 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". + </method> + + <p> + Destroying the object (or sending "close") should close the window. + </p> + + <p>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.</p> + + <p>only one window may be used per connection (to simplify matters; + this doesn't reduce flexibility).</p> + + <p>there is an additional argument that may be added to every + <k>"open"</k> 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. <k>0x28003ff</k>, you may connect to + an existing window; you can find out the number of a window by using + a tool like <k>xwininfo</k>, part of X11 standard tools.</p> + + <method name="out_size"> + <arg name="height" type="integer"/> + <arg name="width" type="integer"/> + changes the window's size, just like sending a grid + dim(height,width,3) would. + + this affects the size of screen captures too. + </method> + + <method name="setcursor"> + <arg name="cursor" type="0..63"/> + 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> + + <method name="hidecursor"> + This makes the cursor invisible. + </method> + + <outlet id="0"> + <method name="position"> + <arg name="y" type="integer"/> + <arg name="x" type="integer"/> + <arg name="buttons" type="integer"/> + + <p>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.</p> + + <p>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: + <list start="0"> + <li>Shift</li> + <li>CapsLock</li> + <li>Control</li> + <li>Alternate</li> + <li>NumLock</li> + <li>???</li> + <li>Meta</li> + <li>ScrollLock</li> + <li>Left Button</li> + <li>Middle Button</li> + <li>Right Button</li> + <li>Wheel Up</li> + <li>Wheel Down</li> + </list></p> + <p>NOTE: This message form may become longer in the future, but the already defined parts will stay the same.</p> + </method> + <method name="keypress"> + <arg name="y" type="integer"/> + <arg name="x" type="integer"/> + <arg name="buttons" type="integer"/> + <arg name="keyname" type="symbol"/> + <p>Similar to <k>position</k> 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.</p> + <p>NOTE: This message form may become longer in the future, but the already defined parts will stay the same.</p> + </method> + <method name="keyrelease"> + <arg name="y" type="integer"/> + <arg name="x" type="integer"/> + <arg name="buttons" type="integer"/> + <arg name="keyname" type="symbol"/> + Same as keypress but when a key gets released instead. + <p>NOTE: This message form may become longer in the future, but the already defined parts will stay the same.</p> + </method> + </outlet> + </class> + + <class name="format quartz #out"> + The equivalent of format x11 on MacOS 10.x, but with less features (sorry). + <method name="open"> + opens a dim(240,320,3) rgb window (default). + </method> + <method name="grid"> + <arg name="grid" type="grid(rows columns {red green blue})"/> + Sends image to screen. Window will be resized to fit the image exactly. + </method> + </class> + + <class name="format sdl #out"> + <method name="open"> + Opens a dim(240,320,3) rgb window (default). + </method> + <method name="grid"> + <arg name="grid" type="grid(rows columns {red green blue})"/> + Sends image to screen. Window will be resized to fit the image exactly. + </method> + </class> + + <class name="format aalib #out"> + <method name="open aalib"> + <arg name="driver"> + Normally "X11" with uppercase X; else consult + the AALib manual. + </arg> + <rest name="args"> + You can pass "commandline options" of AALib here. + </rest> + </method> + <method name="grid"> + <arg name="grid" type="grid(rows columns {white})"/> + 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> + <method name="grid"> + <arg name="grid" type="grid(rows columns {ascii attr})"/> + the inverse of "dump". Both together in a loop allow to + post-process aalib's buffer before displaying. Goes well + with "draw", "autodraw". + </method> + <method name="print"> + <arg name="y" type="int"/> + <arg name="x" type="int"/> + <arg name="attr" type="int"/> + <arg name="text" type="symbol"/> + </method> + <method name="autodraw"> + like X11's autodraw. + </method> + <method name="draw"> + like X11's draw. + </method> + <method name="dump"> + produces a Dim[y,x,2] grid whose two channels are + ascii character codes and character attributes. + </method> + </class> + + <class name="format window #out"> + <method name="open window"> + Equivalent to "open x11", but this can be set by putting a line like + this in the config file: <k>GridFlow.formats[:window] = GridFlow.formats[:x11]</k> + (and similarly other aliases can be created too) + </method> + </class> +</section> + +</documentation> |