NAME

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

SYNOPSIS

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

C-BINDING SYNOPSIS

       #include <ncarg/ncargC.h>

       void c_ppditr(
            float *xccp,
            float *yccp,
            int nccp,
            float *xcsp,
            float *ycsp,
            int ncsp,
            float *rwrk,
            int *iwrk,
            int nwrk,
            int (*urpt_)(float *xcbl,
                         float *xcbr,
                         float *ycob,
                         float *dxle,
                         float *dxre,
                         float *ycot),
            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).
                   The routines that produce trapezoids use a lot less workspace than the ones
                   that produce polygons.  The amount of space used at a particular time during
                   the execution of one of these routines is roughly ten or eleven times the
                   number of intersections of a horizontal "scan line" with the edge segments
                   making up the input polygons, plus about three times the number of points
                   above the current scan line that are "local minima".  (A "local minimum" is a
                   point on one of the polygons that is connected to two other points on the
                   polygon having larger Y coordinates than its own).  I have not yet developed a
                   rule of thumb for setting the value of NWRK.  Ultimately, I would like to at
                   least 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.

       URPT        is the name of a user-provided routine to process the trapezoids.  This name
                   must appear in an EXTERNAL statement in the routine that calls PPDITR and the
                   routine itself must have the following form:

                        SUBROUTINE URPP (XCBL,XCBR,YCOB,DXLE,DXRE,YCOT)
                          ...(code to process a trapezoid)...
                          RETURN
                        END

                   The bottom and top of the trapezoid are horizontal (parallel to the X axis);
                   the arguments XCBL and XCBR define the X coordinates of its bottom left and
                   bottom right corners, YCOB is the Y coordinate of its bottom edge, DXLE and
                   DXRE are the inverses (dx/dy) of the slopes of its left and right edges, and
                   YCOT is the Y coordinate of its top edge. The corners of the trapezoid are
                   therefore as follows: (XCBL,YCOB), (XCBR,YCOB), (XCBL+DXLE*(YCOT-YCOB),YCOT),
                   and (XCBR+DXRE*(YCOT-YCOB),YCOT).

       IERR        (an output variable of type INTEGER) is returned with the value zero if no
                   errors occurred in the execution of PPDITR 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 probably indicate some problem with
                   the algorithm.  If IERR is returned non-zero, one can be sure that there have
                   been no calls to URPT only if IERR = 1 or 2; otherwise, some trapezoids
                   probably have been generated and delivered to URPT.

C-BINDING DESCRIPTION

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

USAGE

       The FORTRAN statement

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

       causes the formation of a difference polygon (the subject polygon minus the clip polygon)
       and the delivery of trapezoids representing the interior of that polygon, one at a time,
       to the user-specified trapezoid-processing routine URPT.

EXAMPLES

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

ACCESS

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

SEE ALSO

       Online: polypack, ppdipo, 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.