video4jmax - reference

Grid classes

There are seven of them and they are named with a "@" prefix because they all have at least one inlet and/or outlet that can handle streamed Grids.

@video_out

Each @video_out object creates a window when it is created. It is constructed with two parameters. If you want to create a window that is 240 pixels high and 320 pixels wide: @video_out 240 320. @video_out will use three channels in RGB by default.

Grid of size (rows, columns, 3)

send it a picture as a 3D grid in which dimension 0 is the rows, dimension 1 is for the columns, and dimension 2 is for the channels; and in which channel 0 is red, channel 1 is green, channel 2 is blue. The picture's height and width must be of the same size as specified in the constructor.

bang
asks for a repaint of the window. When part of a window gets hidden and then exposed, it is not redrawn automatically. Use bang for this purpose.

autodraw
sets the drawing mode. Send a message called "autodraw" along with an integer argument.
0 makes all drawing manually activated (by bang).
1 displays when a whole picture has been received.
2 displays every line as it comes.

@video_out sends a bang on its outlet when it has finished receiving a picture. Destroying the object should close the window. Because of how jMax works, this may be delayed until you do something else. Closing the window yourself will make jMax crash.

@video_out_file

This class is similar to the preceding one, but instead writes a PPM file.

open
you must open a file first. You do this by sending the message "open" with a filename parameter.

close
you can send a "close" to close the file, but it's usually not necessary. Sending a 2nd picture overwrites the first, like what happens to the video buffer inside a @video_out object.

* there are no "autodraw" nor "bang" commands in this class.

@video_in_file

This class is similar to @video_out_file in that it operates on files. However some aspects of it are backwards because it's reading, not writing. Objects of this class don't have a grid inlet, they have a grid outlet instead.

bang
causes the object to send the picture from an open file through its outlet. Several bangs reread the same picture over and over.

* You can send a "close" to close the file, but it's usually not necessary.

@import

Objects of this class have an inlet that can receive integers and reset as well as Grid outlet. You specify the dimensions (all of them) in the constructor. For a 240-row 320-column picture you'd say: @import 240 320 3

An import object accumulates the integers you send to it. They should be
in the 0-255 range. When you send 3 of them, they represent the red,
green and blue values of one pixel. Successive pixels are ordered left
to right and when there are enough of them they form a line. Successive
lines are ordered top to bottom and when there are enough of them they
form a frame. After a frame is completed a new frame begins replacing
the previous one.

@export

not implemented yet

Objects of this class have a Grid inlet and a 0.1-compatible outlet. They do the opposite of @import and take no parameters.

@

This object computes a Grid by combining each of its elements with an integer in its right inlet. This is not unlike built-in arithmetic objects, except that the left inlet, and the outlet, work with Grids. This runs up to 10 times faster than equivalent built-ins (but still probably slower than equivalent DSP built-ins. Construction takes 2 parameters: a first one is the operation's symbol, and a second optional one is the default value for the right inlet. Operations provided are listed below in the "binary operations" section. The latter two have no equivalent that I know of in plain jMax. They return respectively the smallest and the highest of two values.

@store

A @store object can store exactly one Grid. You store it via its right inlet. You fetch it by sending a bang through its left inlet, which sends the Grid on the outlet. You may also perform all kinds of coordinate transforms with @store. You send in the left inlet a Grid whose two channels are Y and X coordinates of pixels of the stored grid. Values too large or too small are wrapped around (using uniform modulo). @store is even more flexible than that: you can address whole lines and pixel parts too, by sending appropriately-sized grids (non-3D). Advanced users can figure it out; beginners should simply ignore it.

If you send to @store a grid of 2 dimensions consisting of rows (y) and channels, in which the channel ... see the example

TODO @store takes one argument specifying its size, int32 (default) or uint8 (native format for ppm or tga formats)

Grid Protocol Basics

No matter how shapeful we can think Grids are, they are usually stored and transmitted in a quite flat sequential way. In an N-dimensional Grid, dimension 0 is called "outer" and dimension N-1 is called "inner" or "last". This inner/outer thing can be thought of this way: a Grid is an array of array of array of...; for example, a picture is an array of lines; a line is an array of pixels; a pixel is an array of integers. At each such level, elements are sent/stored in their numeric order, and are numbered using natural numbers starting at 0. This explains why you can see the picture result appear line by line (and not column by column, or channel by channel)

Video4jmax Picture Format

Most of what you should know about this topic is in the @video_out documentation. A small additional note: pictures are handled in 96 bpp and have to be downscaled to 24 bpp for display. That huge amount of slack is to improve speed and because if you create your own effects you often have intermediate results that need to be of higher precision. In the final conversion, high bits are just truncated. The black value is 0 and the maximum intensity value is 255; negative values are wrapped and values above 255 are wrapped too. If you want to clip them, you may use "@ max 0" and "@ min 255" objects.

Binary Operations

where A is the left value, and B is the right value.

External Picture Formats

PPM: Read+Write. Subformat P6 only. RGB-24 only.

Targa: Read Only. BGR-24 and ABGR-32 (channels are in reverse order). Experimental.

VideoDev: Video4Linux-1 devices, RGB-24 only. Variable picture size. Compatibility problems.