NAME

draw_sym -- draw symbol into window

PROTOTYPE

unitptr draw_sym( char *pcWdw, int iNumPts, char *pcFmt, unitptr uHost)

ARGUMENTS

char *pcWdw
specifies which window to draw into: if this string can be interpreted as an integer number iPos, the iPos -th successor window (if iPos>0 ) or the -iPos -th predecessor window (if iPos<0 ) is used; otherwise, a window that has pcWdw as its title is sought.
int iNumPts
number of points drawn per exec call (specify iNumPts<0 for packed input field 0)
char *pcFmt
string to specify options
unitptr uHost
host unit

RETURN VALUE:

A pointer to the created unit or NULL in the case of an error.

INTERFACE OF CREATED UNIT:

X_in[2*iNumPts]:
positions for iNumPts points at which to center symbol (packed field, if iNumPts<0).
Y_in[3]:
(input field 1) Three pins to specify drawn symbol/text (see below)
CTL_in[1]:
(control field) linewidth. A value of 0 supresses any drawing.
SPECIFICATION OF DRAWN SYMBOL/TEXT: The pins of Y_in[3] specify the following attributes: For the draw_sym - unit: all three pins are of type float and specify color, marker type and size:
Pin 0
values 1-7 specify colors (order is white, red, green, blue, yellow, magenta, cyan).
Pin 1
abs value specifies marker type: values 1-9 yield point, square, diamond, triangle, cross, plus, star, circle, histobox. If these values are chosen negative, the same markers are selected, but each marker will be connected with its subsequently drawn marker by a line if either (i) the subsequent marker is in the same group or (ii) the marker belongs to a group of size 1 (a group is the collection of markers specified by X_in[] and drawn by a single exec call).
Pin 2
positive value specifies size in pixels, neg value: abs value specifies size in units of 1/1000 window width.
For the draw_str unit: pins 0 and 2 are of type float and specify color and alignment. Pin 1 is of type text and specifies text to be drawn:
Pin 0
values 1-7 specify colors (order is white, red, green, blue, yellow, magenta, cyan).
Pin 1
text string to be drawn
Pin 2
alignment. Values 0-8 specify the location of a `hot spot'' relative to the text, according to the following scheme:

        7 6 5
        0TheTextToBeDrawn4
        1 2 3

A value of 8 specifies the hot spot at the center of the string.

EXECUTION OF CREATED UNIT:

Draws designated symbol/string into designated predecessor window. If the %nB option is specified in pcFmt, each drawn symbol/string will be added to an internal buffer whose size is set with parameter n (see below). Subsequent redraw operations of the associated window unit then will also redraw the buffered objects. If n is not specified, a default size of n=30000 will be used (i.e., the buffer will grow to this size unless regularly intervening NST_W_CLEAR calls keep it from growing to its maximal extent [see below]). If no %B option is specified (the default), the internal buffer will only hold the object of the most recent draw operation. The stored object(s) can be cleared with a NST_W_CLEAR control call, but applied to the associated window unit (the draw unit itself has no clear or redraw operation, i.e., any redraw/clear must always be done via the associated window unit).

DESCRIPTION:

String pcFmt may be used to initialize various parameters and to specify options for this routine. Each option is started by a %-character and is of the form %f1:f2:f3c, where f1..f3 are floating point numbers (which need not all be present) and .c is a control character. Currently, the following options are recognized:
%nB
activate buffering mode and set buffer size to n. In this mode, the unit will store the objects that it has drawn since the most recent ctrl_unit(NST_W_CLEAR,u) call to its window host unit u (this is the unit that manages the window into which the draw unit draws).
The stored objects can be redrawn with a ctrl_unit(NST_W_REDRAW,u) (again to be applied to the window host unit u ) and the buffer can be cleared (with the buffer memory released) with a ctrl_unit(NST_W_CLEAR,u) call to the window host unit u.

REMARKS ON BUFFERING OPERATION:

The buffer will operate as a ring-buffer that grows to a maximal size. When (due to the absence of intervening NST_W_CLEAR calls) this size has been reached, newly arriving objects will start to shift out the oldest ones from the buffer. To accomodate num points in a draw_sym unit (or num strings in a draw_str unit), the minimal required value of n is num+numcalls (just num in case of strings for the draw_str unit), where numcalls is the number of exec calls to deliver the num points (with dynamic input fields, each exec draw_sym call may deliver a variable number of points, called a group below). If the shifted-out objects are groups of several points each, they are not considered 'atomic' and just enough of the oldest group is shifted out in order to make room for the new one (if the partially shifted-out group consists of points connected by lines, this may result in the appearance of partial structures). In the extreme case of a small buffer and a very large single new group, only the part of the new group that fits into the buffer will be accommodated. NOTE: %B mode is incompatible with %I mode.
%I
use inverse color to draw symbols or text. After the first exec call, each subsequent exec call selectively undraws the previously drawn symbols/text (keeping any other drawn objects intact) and then draws the new symbols/text. NOTE: %I mode is incompatible with %B mode.
text:
any text before the first % character is interpreted by the draw_str unit as initializer for the to-be-drawn text in input pin 1 of input field 1. It is ignored by the draw_sym unit.
%a:
automatic scaling (currently for xyplot and write_pix-units.). If this option is specified, the routine checks, whether any special coordinate system is defined for the specified window w and if so, automatically interpretes the specified location as given in these coordinates. This is, for instance, useful for windows created by units xyplot and write_pix. The presence of this option overrides any other scaling option.
%3D:
use 3D-mode (only for draw_sym unit)
%F:
draw into frontbuffer
%G:
draw into backbuffer
%iC:
use initial color i. Default is %1C, i.e. white. -.%c:t:sm (only draw_sym unit) set initial color c, marker type t and size s
%f1:f2s:
specify that a window pixel has a size of f1 screen pixels along the horizontal direction, and of f2 screen pixels along the vertical direction (i.e. the horizontal and vertical mouse coordinates will be scaled by factors 1/f1 and 1/f2).
%f1:f2o:
add an offset vector (f1,f2) to the scaled coordinates. The offset vector (f1,f2) is subtracted from the input vector X_in
In the case of conflicting options, the rightmost option of a set of conflicting options will prevail.

SEE ALSO:

draw_mesh, draw_pix, mouse_xy

FILE

/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../nstsrc/nst_draw.c