1PPDIPO(3NCARG) NCAR GRAPHICS PPDIPO(3NCARG)
2
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
11 CALL PPDIPO (XCCP,YCCP,NCCP,XCSP,YCSP,NCSP,RWRK,IWRK,NWRK,URPP,IERR)
12
14 #include <ncarg/ncargC.h>
15 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
30 XCCP (an input array of type REAL) is the X coordinate array for
31 the clip polygon.
32 YCCP (an input array of type REAL) is the Y coordinate array for
34 the clip polygon.
35 NCCP (an input expression of type INTEGER) is the number of
37 points defining the clip polygon.
38 XCSP (an input array of type REAL) is the X coordinate array for
40 the subject polygon.
41 YCSP (an input array of type REAL) is the Y coordinate array for
43 the subject polygon.
44 NCSP (an input expression of type INTEGER) is the number of
46 points defining the subject polygon.
47 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 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 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 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 SUBROUTINE URPP (XCRA,YCRA,NCRA)
74 DIMENSION XCRA(NCRA),YCRA(NCRA)
75 ...(code to process a polygon boundary piece)...
76 RETURN
77 END
78 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 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
99 The C-binding argument descriptions are the same as the FORTRAN
100 argument descriptions.
101
103 The FORTRAN statement
104 CALL PPDIPO (XCCP,YCCP,NCCP,XCSP,YCSP,NCSP,RWRK,IWRK,NWRK,URPP,IERR)
106 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
112 Use the ncargex command to see the following relevant examples: ppex01,
113 tppack, c_ppex01.
114
116 To use PPDIPO or c_ppdipo, load the NCAR Graphics libraries ncarg,
117 ncarg_gks, and ncarg_c, preferably in that order.
118
120 Online: polypack, ppditr, ppinpo, ppintr, ppplcl, ppppap, ppunpo,
121 ppuntr, ncarg_cbind.
122 Hardcopy: None.
124
126 Copyright (C) 1987-2007
127 University Corporation for Atmospheric Research
128 This documentation is free software; you can redistribute it and/or
130 modify it under the terms of the GNU General Public License as
131 published by the Free Software Foundation; either version 2 of the
132 License, or (at your option) any later version.
133 This software is distributed in the hope that it will be useful, but
135 WITHOUT ANY WARRANTY; without even the implied warranty of
136 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
137 General Public License for more details.
138 You should have received a copy of the GNU General Public License along
140 with this software; if not, write to the Free Software Foundation,
141 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
142UNIX March 1995 PPDIPO(3NCARG)