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