NAME
draw_ellipse -- create unit to draw ellipseoids
PROTOTYPE
unitptr draw_ellipse(char *pcWin, char * fmt, unitptr uHost)
ARGUMENTS
- char *pcWin
- window to access
- char * fmt
- format string
- unitptr uHost
- host unit
RETURN VALUE:
A pointer to the created unit or NULL in the case of an error.
INTERFACE OF CREATED UNIT:
The default interface is
- X_in[6]:
- six parameters that specify location, shape and
orientation of an ellipse. Various ways of
specification can be selected with the option
%p (see below). If nothing is specified,
X_in[6] is taken as the coordinates of three
points (x1,y1), (x2,y2) and (x3,y3) through
which the ellipse will pass such that (x1,y1)
and (x2,y2) are apex points.
- Y_in[1]:
- color of the ellipse.
- CTL_in[1]:
- (control field) resolution and ctrl value
If fmt contains the option %i, the above interface is replaced
by the following interface that allows also to draw elliptic
arcs:
- X_in[2]:
- center coordinates (x,y) of ellipse
- Y_in[1]:
- color (0=black, 1=white, 2=red, 3=green, 4=blue,
5=yellow, 6=magenta, 7=cyan)
- Z_in[2]:
- diameters along principal axes a and b
- inp_3[3]:
- three angles that specify the direction of the
principal axis against the positive x-axis,
the angle of the start of the arc, measured against
the direction of the principal axis, and the
angular extent of the drawn arc.
- CTL_in[1]:
- control pin (0=no operation)
If both %p and %i are present, the rightmost option will
prevail.
OUTPUT FIELDS:
If the %G option has been specified, there are 6 output pins:
- X_out[6]
- center, normal along major axis, and axis lengths
(major/minor).
EXECUTION OF CREATED UNIT:
Draws an ellipse into the window specified with pcWin (which is either
a window title or a window offset).
Option %p allows to choose between different ways to specify the
ellipse. Each possibility requires six parameters that must be
provided at input field X_in[6]. Below, we denote by
p1,p2 and p3 the pairs (X_in[0],X_in[1]), (X_in[2],X_in[3]),
and (X_in[4],X_in[5]).
- %0p
- Put the center of the ellipse at p1 and choose shape and
orientation such that it passes through p2 and p3; again
the major axis will pass through p2, if p2 is farther from the
center than p3, through p3 otherwise.
- %1p
- three point mode I: This will put the center of the ellipse halfway
between points p1 and p2 and to make the ellipse pass through all
three points p1, p2 and p3. Depending on whether p2 or p3 is
farther from the center, the major axis of the ellipse will be chosen
to contain the point p2 or p3. This mode is also chosen when
just %p is specified as option.
- %2p
- three point mode II: This will put the center of the ellipse
at the center (p1+p2+p2)/3 of the three points and choose the remaining
ellipse parameters such that it passes through p1, p2 and p3.
- %3p
- matrix mode: this will center the ellipse at point
p1; the remaining two points will be taken as the two rows of a
2x2-matrix A. The shape of the ellipse will then be determined
by the equation vecr^T A r=1 (if the matrix A is not
positive definite, no ellipse is defined and none will be drawn).
Note that only the symmetric part of A counts and that it does
not matter whether p2 and p3 are considered as rows or as columns
of A.
- %4p
- circle mode: this will draw the circle that passes
through the given three points.
- %5p
- arc mode: this will draw the shortest circular
arc that passes through the given three points.
The further following options will be recognized:
- %G
- provide scalar field with 6 output pins holding the
following geometry parameters of the ellipse:
cx,cy (center), nx,ny (normal along major axis) and
length of major and minor axis, resp.
- %nB
- store up to n most recently drawn ellipses internally,
so that these can be redrawn. The internal buffer will be
cleared by any of NST_INIT, NST_RESET and NST_W_CLEAR.
This mode and the %I mode exclude each other.
If n is not specified, a default value of 1000 is used.
- %I
- if an ellipse was drawn before, undraw it, using inverse color;
then drawn the new ellipse (again in inverse color).
This mode and the %B mode exclude each other.
- %a
- do autoscaling if the corresponding window has a special scale
- %a:bs
- scale according to pixel width a,b
- %a:bo
- substract offset values a,b
- %ac
- set color a for drawing (default white), can be changed by input Y_in
- %ar
- set resolution a; high values result in high resolution
but slower drawing (default 1)
- %p
- use three points for computing parameters.
The default is to use the first two points for a
principal axis. If the form %cp is given, the
three points may be interpreted differently:
c=0: first point is center, remaining two
are on ellipsi.
c=1: same as %p.
- %i
- use an interface analogous to draw_sym:
inp0: 2 pins for x,y
inp1: 1 pin for color
inp2: 2 pins for size [pixel] along principal axes
inp3: 1 pin for orientation
inp4: control pin
only one of the options %i and %p can be given
[the rightmost one will prevail]
- %g
- give angles in degrees (0-360)
FILE
/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../nstsrc/nst_draw.c