NAME
write_pix - display pixel image
PROTOTYPE
unitptr write_pix( int dx, int dy, char *wdw, char *fmt, unitptr dest)
ARGUMENTS
- int dx
- width in pixels of image region
- int dy
- height in pixels of image region
- char *wdw
- title, location and zoom factor for display window
- char *fmt
- string to specify options (see below)
- unitptr dest
- host unit for newly created instance
RETURN VALUE:
- unitptr u:
- pointer to newly created unit
INTERFACE OF CREATED UNIT:
In monochrome or colormap mode (set by option fmt, see below):
- X_in[dx*dy]:
- (packed input field 0) single color or graylevel
- CTL_in[1]
- control input. A value of 0 disables execution.
image to be displayed in window.
In RGB-mode (set by option fmt, see below):
- in_0[dx*dy]:
- (packed input field 0) red channel of image
- in_1[dx*dy]:
- (packed input field 1) green channel of image
- in_2[dx*dy]:
- (packed input field 2) blue channel of image
- CTL_in[1]
- control input. A value of 0 disables execution.
In single-pin RGB-mode (set by option fmt, see below):
- in_0[3*dx*dy]:
- (packed input field 0) rgb tripes for image
- CTL_in[1]
- control input. A value of 0 disables execution.
When a dynamic input pin is requested:
- in_0[n*dx*dy]:
- (dynamic input field 0) mono values (n=1) or
rgb tripes (n=3) for image.
- in_1[1]:
- scalar input for image width (if 0, unit will try
to guess image shape by attempting to factor pixel dimension
such that widht >= height and shape is as close as possible to
a square).
- CTL_in[1]
- control input. A value of 0 disables execution.
OPTIONS:
The option string fmt can be used to specify various options.
Each option starts with a % - character, followed by a command
letter. The following options are recognized:
- %M:
- set color map mode; this mode displays positive input values
in the range 0 (=black) to 255 (=white) into gray levels;
Negative inputs are sign-reversed and then used as indices into
a color map to display colors.
- %R,%G,%B:
- set mono-color mode and interprete input values
as intensities for a red, green or blue image. In mono-color
mode, the unit is created with a single packed input field
for the specified color channel.
- %C:
- set RGB-color mode. In this case, the unit will have
three packed input fields that are interpreted as intensity values
for the red, green and blue channel.
- %1C:
- set single-input RGB-color mode. In this case, the unit will have
one packed input field expecting for each pixel a red/green/blue
triple.
- %D:
- request dynamic input pin for image data. Additionally, the unit
will have a scalar pin for specifying an image width. If the input to
this pin is zero, the unit will try to guess the image shape by looking
for a factorization of the pixel number that is as close as possible
to a square and that has the larger factor as the image width.
Note: this option entails %1C, i.e., for RGB images the dyn input
pin has always to be filled with RGB-triples.
- %s:
- show restriction(s) at input(s) as bounding box(es)
- %H:
- Hide mode: defer opening of window until unit is
executed.
If fmt=NULL or none of the options %R, %G, %B, %M or %C is
specified, the window will be in monochrome mode.
The presence of %C or %1C overrides any other color option.
DESCRIPTION:
Creates a unit execution of which displays the values at its input
fields as gray levels or pixel colors in a window of width dx
and height dy pixels. The string win specifies the window title,
the screen position (x,y) of the lower left corner pixel (the pixel at
coordinates (0,0) in the displayed image rectangle) and an optional
zoom factor z in the following format:
win = "title x y z"
After return from the constructor function, the current window is
the set to the newly opened window. If the %H option was
specified, no window is opened and the current window is not changed.
EXECUTION:
Updates the displayed image with the data at the input fields,
unless CTL_in[0]==0, in which case no action is performed
(in all cases, execution does not change the current window).
Pin x+y*dx,
x=0..dx-1, y=0..dy-1 is mapped to a pixel block with an
edge length of z pixels with lower left corner at pixel coordinates
(x*z,y*z). The origin (0,0) is the lower left inner corner
of the newly created window. To add further graphics to the window,
use the draw_sym, draw_str or draw_pix units.
CONTROL MODES:
The following control modes are recognized:
- NST_W_CLOSE
- store the current position and close the window,
if it is open and not subwindow of
another window host.
- NST_W_OPEN
- if closed, open the window at the stored position.
- NST_W_REDRAW
- redraw the window contents.
- NST_W_SETPOS
- move the window to the position read with
a previous load_unit - call and make this
the currently stored position.
- NST_W_GETPOS
- store the window's current position.
- NST_W_GET_ID
- return the window id (a value of -1 indicates
the window is closed).
- NST_W_CLEAR
- clear the window contents
SEE ALSO:
write_pix8, color_code, mouse_xy,
draw_sym, draw_str
FILE
/homes/jontrup/nst5/man/../o.sol2//../foldersrc/nst_pixel.c