'\"!  eqn | tbl | mmdoc
.if n .pH ref.point @(#)point	40.1

.ig
imagen 8/31/89
docformat -c -s4 -dqm4 -p1 point
..
.SO mstr.hdr
.ds Lb Shapes
.BK "Shapes Reference Manual"
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.EQ
delim $$
.EN
.CH "Point Data Structure" "13"
.H 1 "Point Data Structure" 
.H 2 "Coordinate Representation Types"
.IX "coordinate" "floating-point" "" "" "" PAGE START
.IX "coordinate" "fixed-point binary" "" "" "" PAGE START
.IX "floating-point coordinate" "" "" "" PAGE START
.IX "fixed-point binary coordinate" "" "" "" PAGE START
.P
.nh
.IX "point" "structures"
Shapes point data comes in varying types:\ \&
float or fract, moves versus draws,
two-dimensional versus three-dimensional,
homogeneous or non-homogeneous.
The POINT data structure provides an abstraction for
encompassing these various kinds of points by using a
C union of all the various subclasses of points
(e.g., fract 2D).
However, this union must encompass up to a 3D
homogeneous point as the largest subclass.
Each subclass of point is structured the same way.
The first field of each POINT_XXX structure
contains a type that determines how the coordinate
data is interpreted:\ \&
as fract or float,
as 2D or 3D, as a regular or homogeneous point.
The POINT_XXX structures also define vectors
(e.g., x, y) that designate a direction or position.
.P
NOTE: Three-dimensional coordinates are maintained for
future expansion.
.P
.PC
typedef struct { unsigned int t; int   x, y; }
     POINT_B2D;
typedef struct { unsigned int t; int   x, y, z; }
     POINT_B3D;
typedef struct { unsigned int t; int   x, y, z, w; }
     POINT_B2H;
typedef struct { unsigned int t; int   x, y, z, w; }
     POINT_B3H;
typedef struct { unsigned int t; float x, y; }
     POINT_F2D;
typedef struct { unsigned int t; float x, y, z; }
     POINT_F3D;
typedef struct { unsigned int t; float x, y, z, w; }
     POINT_F2H;
typedef struct { unsigned int t; float x, y, z, w; }
    POINT_F3H;

typedef union
  {
   POINT_F3H f;
   POINT_B3H b;
  } POINT;
.ft1
.SF
.H 2 "Coordinate Types"
.IX "coordinate" "types"
.P
The type field of a coordinate structure specifies the
kind of coordinate represented.
Many Shapes macros, such as the Draw_XXX
(e.g., Draw_F2D) macros and Point_XXX
(e.g., Point_B2D) macros,
construct the type for you automatically.
Nonetheless, at times it may be necessary for you to
construct the type field.
Passing data points to the Draw() macro is typically
one such time.
.P
The following table shows which POINT types are valid
for initializing a point structure directly.
To formulate a legal name, combine the prefix
indicating the nature of the drawing operation
(e.g., PT_MOVE_, PT_LINEREL) with a suffix indicating
the type of the coordinate
(e.g., B2D, F2H) wherever the tables indicates the
name exists.
For example, PT_MOVE_B2D is a legitimate type;
PT_MOVE_F2H is not.
.TB "Legal Point Types"
.TS
box tab(|);
cf4I | cf4I | cf4I
l | c | c .
|B2D or F2D|B2H or F2H
=
PT_|X|X
PT_CURVE_|X|X
PT_LINE_|X
PT_LINEREL_|X
PT_MOVE_|X
PT_MOVEREL_|X|
.TE
.TT
.IX "point" "passing to Shapes"
.P
The Point macros initialize the components of POINT structure;
the type is set to type PT_XXX (e.g., PT_B2D),
and the vector components of the point are set in
accordance with the values passed to the point macro.
Because these macros do not allocate memory,
be sure you have already allocated a POINT
\- typically by static allocation \- before using them.
.P
Pointers to initialized points are required as
arguments to many operators \-
when specifying how to scale or translate a transform,
when setting clipping dimensions, etc.
Since the Point macros return their first argument,
which is a pointer to a POINT structure,
these macros can be used wherever a pointer to an as
yet uninitialized point is called for.
.P
.TB "Point Structure Initialization"
.TS
box tab(|);
cf4I | cf4I
l | l  .
Call |  Returns Type
=
Point_B2D(p,x,y)|POINT_B2D *
Point_F2D(p,x,y)|POINT_F2D *
Point_I2D(p,x,y)|POINT_B2D *
_
Point_B2H(p,x,y,w)|POINT_B2H *
Point_F2H(p,x,y,w)|POINT_F2H *
Point_I2GH(p,x,y,w)|POINT_B2H *
.TE
.TT
.H 4 "SEE ALSO"
.P
Draw Primitives
.br
Read_Path
.br
Next_Path
.br
Path_Item_Type
.IX "coordinate" "floating-point" "" "" "" PAGE END
.IX "coordinate" "fixed-point binary" "" "" "" PAGE END
.IX "floating-point coordinate" "" "" "" PAGE END
.IX "fixed-point binary coordinate" "" "" "" PAGE END
