NAME

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

SYNOPSIS

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

C-BINDING SYNOPSIS

       #include <ncarg/ncargC.h>

       void c_ppdipo(
            float *xccp,
            float *yccp,
            int nccp,
            float *xcsp,
            float *ycsp,
            int ncsp,
            float *rwrk,
            int *iwrk,
            int nwrk,
            int (*urpp_)( float *xcra, float *ycra, int *ncra),
            int *ierr)

DESCRIPTION

       XCCP        (an input array of type REAL) is the X coordinate array for the clip polygon.

       YCCP        (an input array of type REAL) is the Y coordinate array for the clip polygon.

       NCCP        (an input expression of type INTEGER) is the number of points defining the
                   clip polygon.

       XCSP        (an input array of type REAL) is the X coordinate array for the subject
                   polygon.

       YCSP        (an input array of type REAL) is the Y coordinate array for the subject
                   polygon.

       NCSP        (an input expression of type INTEGER) is the number of points defining the
                   subject polygon.

       RWRK        (a scratch array, dimensioned NWRK, of type REAL) is a real workspace array.
                   Because of the way in which they are used, RWRK and IWRK may be EQUIVALENCEd
                   (and, to save space, they should be).

       IWRK        (a scratch array, dimensioned NWRK, of type INTEGER) is an integer workspace
                   array.  Because of the way in which they are used, RWRK and IWRK may be
                   EQUIVALENCEd (and, to save space, they should be).

       NWRK        (an input expression of type INTEGER) is the length of the workspace array(s).
                   It is a bit difficult to describe how much space might be required. At the
                   moment, I would recommend using NWRK equal to about ten times the total of the
                   number of points in the input polygons and the number of intersection points.
                   This situation will change with time; at the very least, I would like to put
                   in an internal parameter that will tell one how much space was actually used
                   on a given call, but I have not yet done so.

       URPP        is the name of a user-provided routine to process the polygon-boundary pieces.
                   This name must appear in an EXTERNAL statement in the routine that calls
                   PPDIPO and the routine itself must have the following form:

                        SUBROUTINE URPP (XCRA,YCRA,NCRA)
                          DIMENSION XCRA(NCRA),YCRA(NCRA)
                          ...(code to process a polygon boundary piece)...
                          RETURN
                        END

                   Each of the arguments XCRA and YCRA is a real array, dimensioned NCRA; the
                   former holds the X coordinates, and the latter the Y coordinates, of a piece
                   of the polygon boundary. It will be the case that XCRA(NCRA)=XCRA(1) and
                   YCRA(NCRA)=YCRA(1).

       IERR        (an output variable of type INTEGER) is returned with the value zero if no
                   errors occurred in the execution of PPDIPO or with a small positive value if
                   an error did occur.  The value 1 indicates that a degenerate clip polygon was
                   detected, the value 2 that a degenerate subject polygon was detected, and the
                   value 3 that the workspace provided was too small; values greater than 3
                   should be reported to the author, as they indicate some problem with the
                   algorithm. Currently, if IERR is returned non-zero, one can be sure that no
                   calls to URPP were executed; in the future, this could change, but, in that
                   case, there will be an internal parameter allowing one to request the current
                   behavior.

C-BINDING DESCRIPTION

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

USAGE

       The FORTRAN statement

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

       causes the formation of a difference polygon (the subject polygon minus the clip polygon)
       and the delivery of that polygon's boundary, piece by piece, to the user-specified
       polygon-processing routine URPP.

EXAMPLES

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

ACCESS

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

SEE ALSO

       Online: polypack, ppditr, ppinpo, ppintr, ppplcl, ppppap, ppunpo, ppuntr, ncarg_cbind.

       Hardcopy: None.

COPYRIGHT

       Copyright (C) 1987-2009
       University Corporation for Atmospheric Research
       The use of this Software is governed by a License Agreement.