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

NAME

6       PPDIPO - generates and returns the boundary of the "difference"
7       polygon, which consists of all points that are inside the subject
8       polygon but not inside the clip polygon.
9

SYNOPSIS

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

C-BINDING SYNOPSIS

14       #include <ncarg/ncargC.h>
15
16       void c_ppdipo(
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 (*urpp_)( float *xcra, float *ycra, int *ncra),
27            int *ierr)
28

DESCRIPTION

30       XCCP        (an input array of type REAL) is the X coordinate array for
31                   the clip polygon.
32
33       YCCP        (an input array of type REAL) is the Y coordinate array for
34                   the clip polygon.
35
36       NCCP        (an input expression of type INTEGER) is the number of
37                   points defining the clip polygon.
38
39       XCSP        (an input array of type REAL) is the X coordinate array for
40                   the subject polygon.
41
42       YCSP        (an input array of type REAL) is the Y coordinate array for
43                   the subject polygon.
44
45       NCSP        (an input expression of type INTEGER) is the number of
46                   points defining the subject polygon.
47
48       RWRK        (a scratch array, dimensioned NWRK, of type REAL) is a real
49                   workspace array.  Because of the way in which they are
50                   used, RWRK and IWRK may be EQUIVALENCEd (and, to save
51                   space, they should be).
52
53       IWRK        (a scratch array, dimensioned NWRK, of type INTEGER) is an
54                   integer workspace array.  Because of the way in which they
55                   are used, RWRK and IWRK may be EQUIVALENCEd (and, to save
56                   space, they should be).
57
58       NWRK        (an input expression of type INTEGER) is the length of the
59                   workspace array(s).  It is a bit difficult to describe how
60                   much space might be required. At the moment, I would
61                   recommend using NWRK equal to about ten times the total of
62                   the number of points in the input polygons and the number
63                   of intersection points. This situation will change with
64                   time; at the very least, I would like to put in an internal
65                   parameter that will tell one how much space was actually
66                   used on a given call, but I have not yet done so.
67
68       URPP        is the name of a user-provided routine to process the
69                   polygon-boundary pieces.  This name must appear in an
70                   EXTERNAL statement in the routine that calls PPDIPO and the
71                   routine itself must have the following form:
72
73                        SUBROUTINE URPP (XCRA,YCRA,NCRA)
74                          DIMENSION XCRA(NCRA),YCRA(NCRA)
75                          ...(code to process a polygon boundary piece)...
76                          RETURN
77                        END
78
79                   Each of the arguments XCRA and YCRA is a real array,
80                   dimensioned NCRA; the former holds the X coordinates, and
81                   the latter the Y coordinates, of a piece of the polygon
82                   boundary. It will be the case that XCRA(NCRA)=XCRA(1) and
83                   YCRA(NCRA)=YCRA(1).
84
85       IERR        (an output variable of type INTEGER) is returned with the
86                   value zero if no errors occurred in the execution of PPDIPO
87                   or with a small positive value if an error did occur.  The
88                   value 1 indicates that a degenerate clip polygon was
89                   detected, the value 2 that a degenerate subject polygon was
90                   detected, and the value 3 that the workspace provided was
91                   too small; values greater than 3 should be reported to the
92                   author, as they indicate some problem with the algorithm.
93                   Currently, if IERR is returned non-zero, one can be sure
94                   that no calls to URPP were executed; in the future, this
95                   could change, but, in that case, there will be an internal
96                   parameter allowing one to request the current behavior.
97

C-BINDING DESCRIPTION

99       The C-binding argument descriptions are the same as the FORTRAN
100       argument descriptions.
101

USAGE

103       The FORTRAN statement
104
105       CALL PPDIPO (XCCP,YCCP,NCCP,XCSP,YCSP,NCSP,RWRK,IWRK,NWRK,URPP,IERR)
106
107       causes the formation of a difference polygon (the subject polygon minus
108       the clip polygon) and the delivery of that polygon's boundary, piece by
109       piece, to the user-specified polygon-processing routine URPP.
110

EXAMPLES

112       Use the ncargex command to see the following relevant examples: ppex01,
113       tppack, c_ppex01.
114

ACCESS

116       To use PPDIPO or c_ppdipo, load the NCAR Graphics libraries ncarg,
117       ncarg_gks, and ncarg_c, preferably in that order.
118

SEE ALSO

120       Online: polypack, ppditr, ppinpo, ppintr, ppplcl, ppppap, ppunpo,
121       ppuntr, ncarg_cbind.
122
123       Hardcopy: None.
124

COPYRIGHT

126       Copyright (C) 1987-2009
127       University Corporation for Atmospheric Research
128       The use of this Software is governed by a License Agreement.
129
130
131
132UNIX                              March 1995                    PPDIPO(3NCARG)