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

/local/homes/rhaschke/nst7/man/../o.linx86//../nstsrc/nst_draw.c