1PPDITR(3NCARG)                   NCAR GRAPHICS                  PPDITR(3NCARG)
2
3
4

NAME

6       PPDITR - generates and returns a set of trapezoids representing the
7       interior of the "difference" polygon, which consists of all points that
8       are inside the subject polygon but not inside the clip polygon.
9

SYNOPSIS

11       CALL PPDITR (XCCP,YCCP,NCCP,XCSP,YCSP,NCSP,RWRK,IWRK,NWRK,URPT,IERR)
12

C-BINDING SYNOPSIS

14       #include <ncarg/ncargC.h>
15
16       void c_ppditr(
17            float *xccp,
18            float *yccp,
19            int nccp,
20            float *xcsp,
21            float *ycsp,
22            int ncsp,
23            float *rwrk,
24            int *iwrk,
25            int nwrk,
26            int (*urpt_)(float *xcbl,
27                         float *xcbr,
28                         float *ycob,
29                         float *dxle,
30                         float *dxre,
31                         float *ycot),
32            int *ierr)
33

DESCRIPTION

35       XCCP        (an input array of type REAL) is the X coordinate array for
36                   the clip polygon.
37
38       YCCP        (an input array of type REAL) is the Y coordinate array for
39                   the clip polygon.
40
41       NCCP        (an input expression of type INTEGER) is the number of
42                   points defining the clip polygon.
43
44       XCSP        (an input array of type REAL) is the X coordinate array for
45                   the subject polygon.
46
47       YCSP        (an input array of type REAL) is the Y coordinate array for
48                   the subject polygon.
49
50       NCSP        (an input expression of type INTEGER) is the number of
51                   points defining the subject polygon.
52
53       RWRK        (a scratch array, dimensioned NWRK, of type REAL) is a real
54                   workspace array.  Because of the way in which they are
55                   used, RWRK and IWRK may be EQUIVALENCEd (and, to save
56                   space, they should be).
57
58       IWRK        (a scratch array, dimensioned NWRK, of type INTEGER) is an
59                   integer workspace array.  Because of the way in which they
60                   are used, RWRK and IWRK may be EQUIVALENCEd (and, to save
61                   space, they should be).
62
63       NWRK        (an input expression of type INTEGER) is the length of the
64                   workspace array(s).  The routines that produce trapezoids
65                   use a lot less workspace than the ones that produce
66                   polygons.  The amount of space used at a particular time
67                   during the execution of one of these routines is roughly
68                   ten or eleven times the number of intersections of a
69                   horizontal "scan line" with the edge segments making up the
70                   input polygons, plus about three times the number of points
71                   above the current scan line that are "local minima".  (A
72                   "local minimum" is a point on one of the polygons that is
73                   connected to two other points on the polygon having larger
74                   Y coordinates than its own).  I have not yet developed a
75                   rule of thumb for setting the value of NWRK.  Ultimately, I
76                   would like to at least put in an internal parameter that
77                   will tell one how much space was actually used on a given
78                   call, but I have not yet done so.
79
80       URPT        is the name of a user-provided routine to process the
81                   trapezoids.  This name must appear in an EXTERNAL statement
82                   in the routine that calls PPDITR and the routine itself
83                   must have the following form:
84
85                        SUBROUTINE URPP (XCBL,XCBR,YCOB,DXLE,DXRE,YCOT)
86                          ...(code to process a trapezoid)...
87                          RETURN
88                        END
89
90                   The bottom and top of the trapezoid are horizontal
91                   (parallel to the X axis); the arguments XCBL and XCBR
92                   define the X coordinates of its bottom left and bottom
93                   right corners, YCOB is the Y coordinate of its bottom edge,
94                   DXLE and DXRE are the inverses (dx/dy) of the slopes of its
95                   left and right edges, and YCOT is the Y coordinate of its
96                   top edge. The corners of the trapezoid are therefore as
97                   follows: (XCBL,YCOB), (XCBR,YCOB), (XCBL+DXLE*(YCOT-
98                   YCOB),YCOT), and (XCBR+DXRE*(YCOT-YCOB),YCOT).
99
100       IERR        (an output variable of type INTEGER) is returned with the
101                   value zero if no errors occurred in the execution of PPDITR
102                   or with a small positive value if an error did occur.  The
103                   value 1 indicates that a degenerate clip polygon was
104                   detected, the value 2 that a degenerate subject polygon was
105                   detected, and the value 3 that the workspace provided was
106                   too small; values greater than 3 should be reported to the
107                   author, as they probably indicate some problem with the
108                   algorithm.  If IERR is returned non-zero, one can be sure
109                   that there have been no calls to URPT only if IERR = 1 or
110                   2; otherwise, some trapezoids probably have been generated
111                   and delivered to URPT.
112

C-BINDING DESCRIPTION

114       The C-binding argument descriptions are the same as the FORTRAN
115       argument descriptions.
116

USAGE

118       The FORTRAN statement
119
120       CALL PPDITR (XCCP,YCCP,NCCP,XCSP,YCSP,NCSP,RWRK,IWRK,NWRK,URPT,IERR)
121
122       causes the formation of a difference polygon (the subject polygon minus
123       the clip polygon) and the delivery of trapezoids representing the
124       interior of that polygon, one at a time, to the user-specified
125       trapezoid-processing routine URPT.
126

EXAMPLES

128       Use the ncargex command to see the following relevant examples: ppex01,
129       tppack, c_ppex01.
130

ACCESS

132       To use PPDITR or c_ppditr, load the NCAR Graphics libraries ncarg,
133       ncarg_gks, and ncarg_c, preferably in that order.
134

SEE ALSO

136       Online: polypack, ppdipo, ppinpo, ppintr, ppplcl, ppppap, ppunpo,
137       ppuntr, ncarg_cbind.
138
139       Hardcopy: None.
140
142       Copyright (C) 1987-2009
143       University Corporation for Atmospheric Research
144       The use of this Software is governed by a License Agreement.
145
146
147
148UNIX                              March 1995                    PPDITR(3NCARG)
Impressum