'\"!  tbl | mmdoc
.if n .pH ref.drawing @(#)drawing	40.2
.ig
imagen 8/31/89
docformat -c -s4 -dqm4 -p1 drawing
..
.SO mstr.hdr
.SO BP.HEADER
.ds Lb Shapes
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.BK "Shapes Reference Manual"
.CH "Drawing Macros" "6"
.H 1 "Drawing Macros" 
.H 2 "Introduction"
.P
.nh
.IX "draw macros"
Drawing macros provide the information for
creating images and are composed of three parts:
.BL
.LI
Drawing operation.
Specifies move and draw operations.
It is as though you are saying,
``Move pen in absolute coordinates''
or ``draw a line relative to the previous pen position.''
.LI
Coordinate type.
Specifies the type of coordinates that are to be used,
such as float or fixed-point binary.
.LI
Coordinate data.
Specifies the locations for the operations.
.LE
.P
Non-positional drawing macros specify color,
curve characteristics, and area closure.
This section describes all the types of drawing macros.
.H 4 "NAME"
.P
Close \- Closes current bound and begins a new area.
.IX "Close"
.tm .CE U 3 "Close" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Close\f2(ctx)\f1
.br
CONTEXT ctx;
.H 4 "DESCRIPTION"
.P
Closes the current bound,
applies the current fill rule to the preceding geometry,
and begins a new area.
Use the Close() macro to mark explicitly the end
of a polygon;
to do so implicitly and avoid the use of this macro,
set the context attribute CTX_AREA_STYLE to
CTX_CLOSE_MOVE.
Using Close() allows multiple bounds to be stored
in the same path but provides that each bound is
considered by the fill rule separately.
.P
When closing the current bound,
the CTX_PATH_PEN prior to the Close() command is
joined to the first point of the bound.
.P
This macro is useful for creating complex
descriptions of filled regions.
For example,
imagine two squares that overlap
(they have a non-empty area of both
intersection and difference).
If you draw each square followed by a Close,
the displayed area will be the union of the two squares.
However, if you draw the first square,
followed by CloseSubpath,
followed by the second square and Close,
the filled area will be the two squares minus
their intersection.
.FG "Close vs. CloseSubpath"
.DS
.BP PSART/ps.cl_sbpth
.DE
.P
\f2ctx\f1
Specifies the context describing the area to be closed.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
CTX_AREA_STYLE
.br
CTX_PATH_PEN
.br
CTX_PATH
.br
RAS_AREA_STYLE
.H 4 "NAME"
.P
CloseSubpath \- Closes the current boundary without starting a new area.
.IX "Close_SubPath"
.tm .CE U 3 "Close_SubPath" \n(PN
.H 4 "SYNOPSIS"
.P
\f3CloseSubPath\f2(ctx)\f1
.br
CONTEXT ctx;
.H 4 "DESCRIPTION"
.P
Closes the current bound by defining an edge from
the current draw position to the previous PT_MOVE
operation.
It does not, however, start a new area,
nor does it apply the current fill rule.
.P
This macro is useful for creating complex
descriptions of filled regions.
For example, imagine two squares that overlap
(they have a non-empty area of both
intersection and difference).
If you draw each square followed by a Close,
the displayed area will be the union of the two squares.
However, if you draw the first square,
followed by CloseSubpath,
followed by the second square and Close,
the filled area will be the two squares minus
their intersection.
.FG "Close vs. CloseSubpath"
.DS
.BP PSART/ps.cl_sbpth
.DE
\f2ctx\f1
Specifies the context associated with the path defining the polygon to be
closed.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
CTX_PATH_PEN
.br
CTX_AREA_STYLE
.br
RAS_AREA_STYLE
.br
CTX_PATH
.H 4 "NAME"
.P
Color \- Sets the current color.
.IX "Color"
.tm .CE U 3 "Color" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Color\f2(ctx, c)\f1
.br
CONTEXT  ctx;
.br
COLOR * c;
.H 4 "DESCRIPTION"
.P
Embeds color changes inside the path.
This is the only way to specify different line
colors for each vector or specify different fill
colors for each filled polygon within a path.
The Color macro updates the CTX_COLOR attribute
when it is encountered as paths are rendered.
.P
If you are using CTX_SHADE_SOLID to draw filled areas,
it is the last color command encountered before
closing the area that determines the fill color.
Nonetheless, CTX_COLOR should be set between area
or outline definitions.
When an area is filled or an outline defined,
the current value of CTX_COLOR determines the color used.
If you change the color in the middle,
the results will be inconsistent.
.P
\f2ctx\f1
Specifies the context for which the color is set.
.P
\f2c\f1
Specifies a pointer to the color.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
CTX_PATH
.br
CTX_SHADE
.br
COLOR Structure
.H 4 "NAME"
.P
Curve \- Sets the curve form and order.
.IX "Curve"
.tm .CE U 3 "Curve" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Curve\f2(ctx, form, order)\f1
.br
CONTEXT ctx;
.br
PATH_curve_form form;
.br
int order;
.H 4 "DESCRIPTION"
.P
Specifies the curve form and the order for curves
in the path object.
All ensuing PT_CURVE points placed in the path
will be interpreted as being of that form and
order.
.P
\f2ctx\f1
Specifies the context for which the path's
ensuing curve points are to be interpreted.
.P
\f2form\f1
Specifies the curve form.
.P
PATH_CURVE_BEZIER specifies Bezier that which
have the following unique properties:
.BL
.LI
Pass through of start and end control points.
.LI
Line formation between the start and first middle
point is equal to the tangent vector at the first
control point,
and the line between the end and second middle
point is equal to the tangent vector at the
ending control point
(for order 3 Beziers,
consider both middle points as a single middle point).
.LI
Convex hull property,
wherein a closed polygon with the control points
as successive vertices encloses the curve
completely.
.P
Order 3 Bezier curves require an initial pen
position and two extra control points for the curve.
The middle point of a conic Bezier must be
specified with homogeneous coordinates that
indicate the \f2w\fP for the conic curve.
For more information,
see Vaughn Pratt's paper:\ \&
\f2Techniques for Conic Splines\fP,
SIGGRAPH 1985 Conference proceedings,
Vol. 19, No. 3, pp.\&
151\(en159.
.P
Order 4 Beziers require an initial pen position
and three copntrol points.
For more information,
see Foley and Van Dam's book:\ \&
\f2Fundamentals of Interactive Computer Graphics\fP,
Addison-Wesley Publishing Company,
Reading, Massachusetts, 1985.
.P
.\" BEGIN Paint------------------------------------------------
.if "\*(Lb"Paint" \{\
.br
PATH_CURVE_BSPLINE specifies b-spline curves
which are implemented for order 4 only.
You must specify at least 3 control points in
addition to the pen position.
For more information,
see Bartels, Richard H., et al, 1987:\ \&
\f2An Introduction to Splines for use in Computer
Graphics & Geometric Modeling\fP,
Morgan Kaufmann Publishers,
95 First Street, Los Altos, CA 94022
.br \}
.\"  ENDIF Paint------------------------------------------------
.P
\f2order\f1
Specifies the curve order.
Order 3 are conic curves,
and order 4 are cubic curves.
.LE
.H 4 "EXAMPLE
.SS
/*
 * Draw a circle out of four quarter circles.
 */

#define cos_45  0.707106781
Curve(ctx, PATH_CURVE_BEZIER, 3);

Draw_F2D(ctx, PT_MOVE,   x+rad, y );
Draw_F2H(ctx, PT_CURVE,  x+rad, y-rad, cos_45);
Draw_F2D(ctx, PT_CURVE,  x,     y-rad);

Draw_F2H(ctx, PT_CURVE,  x-rad, y-rad, cos_45);
Draw_F2D(ctx, PT_CURVE,  x-rad, y);

Draw_F2H(ctx, PT_CURVE,  x-rad, y+rad, cos_45);
Draw_F2D(ctx, PT_CURVE,  x,     y+rad);

Draw_F2H(ctx, PT_CURVE,  x+rad, y+rad, cos_45);
Draw_F2D(ctx, PT_CURVE,  x+rad, y);
.ft1
.SE
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Draw_B2H
.br
Draw_F2H
.br
PT_CURVE
.H 4 "NAME"
.P
Draw \- Moves the current pen position.
.IX "Draw"
.tm .CE U 3 "Draw" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Draw\f2(ctx, pi)\f1
.br
CONTEXT ctx;
.br
POINT * pi;
.H 4 "DESCRIPTION"
.P
The Draw macro moves the position of the current pen.
This macro provides one of the two methods for
specifying geometric data.
It is the most efficient way of moving data from
arrays already filled with Shapes data types into
Shapes for processing.
See the chapter on points for a description of
how to form valid point structures with the
appropriately set point types.
.P
If the context has a path defined,
Shapes appends the specified geometric data to the path.
If it does not,
Shapes is in immediate mode and draws the data
immediately,
subject to how the Shapes implementation buffers output.
.P
\f2ctx\f1
Specifies the context to receive the data.
In path mode,
the data accumulates in the associated path.
.P
\f2pi\f1
Establishes a pointer to the point data.
The type of the point determines how Shapes
interprets the geometry.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
CONTEXT
.br
CTX_PATH
.br
Draw_XXX
.br
POINT Data Structure
.H 4 "NAME"
.P
Draw_XXX \- Moves the current pen position.
.IX "Draw_XXX"
.tm .CE U 3 "Draw" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Draw_XXX\f2(ctx, type, x, y, ...)\f1
.br
CONTEXT ctx;
.br
PT_type type;
.br
<float or fract> x, y, ...
.H 4 "DRAW MACROS"
.TB "Draw MMacros"
.TS
box, tab(/);
cf4I | cf4I
l | l.
Macro/Description
=
Draw_B2D(ctx,t,x,y)/T{
2-dimensional signed fixed-point binary (32 bits).
T}
_
Draw_B2H(ctx,t,x,y,w)/T{
2-dimensional fixed-point binary homogeneous (32 bits).
Use only with type PT_CURVE.
T}
_
Draw_F2D(ctx,t,x,y)/T{
2-dimensional signed floating
(IEEE 32 bits single-precision).
T}
_
Draw_F2H(ctx,t,x,y,w)/T{
2-dimensional signed floating
(IEEE 32 bits single-precision).
Use only with type PT_CURVE.
T}
_
Draw_I2D(ctx,t,x,y)/T{
2-dimensional short integer (16 bits).
T}
_
Draw_I2H(ctx,t,x,y,w)/T{
2-dimensional homogeneous integer (16 bits).
Use only with type PT_CURVE.
T}
.TE
.TT
.H 4 "DESCRIPTION"
.P
The Draw_XXX macro moves the position of the
current pen.
This macro is one of the two methods for
specifying geometric data.
.P
If the context has a path defined,
Shapes appends the specified geometric data to the
path.
If it does not,
Shapes is in immediate mode and draws the data immediately,
subject to how the Shapes implementation buffers output.
.P
\f2ctx\f1
Specifies the context to receive the data.
In path mode,
the data accumulates in the associated path.
.P
\f2type\f1
.TB "Drawing Types"
.TS
box, tab(/);
cf4I | cf4I
l | l.
Type/Description
=
PT_CURVE/T{
Sets down a curve control point in absolute
coordinates.
The current point moves to end of the curve
drawn\(emnot necessarily to the control point
from the Draw macro.
See the Curve() command for more details.
T}
_
PT_LINE/T{
Draws a line from the current point to the
specified absolute point and updates the current
point to the point in the Draw macro.
T}
_
PT_LINEREL/T{
Draws a line from the current point to the
current point offset by the relative coordinates
from the Draw macro and sets the current point to
the line's endpoint.
T}
_
PT_MOVE/T{
Moves the current point to the position specified
in the Draw macro.
T}
_
PT_MOVEREL/T{
Moves the current point relative to the previous
current point.
T}
.TE
.TT
\f2x, y, ...\fP
Coordinate data,
which may be a fract or a float.
The coordinate may include coordinates \f2x, y,\fP or \f2w\fP,
depending on the particular macro.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
CONTEXT
.br
CTX_PATH
.br
Draw
.br
POINT Data Structure
