Provided by: libncarg-dev_6.4.0-9_amd64 bug

NAME

       CPCLDM - Draws contour lines masked by an existing area map. The object of this may be
       simply to avoid drawing contour lines through label boxes, but the routine may be used for
       more complicated tasks, like limiting the drawing of contour lines to the ocean areas on
       an Ezmap background.

SYNOPSIS

       CALL CPCLDM (ZDAT, RWRK, IWRK, IAMA, RTPL)

C-BINDING SYNOPSIS

       #include <ncarg/ncargC.h>

       void c_cpcldm (float *zdat, float *rwrk, int *iwrk,
       int *iama, int (*rtpl)(float *xcs, float *ycs, int *ncs,
       int *iai, int *iag, int *nai))

DESCRIPTION

       The first three arguments are arrays used in the last call to CPRECT, CPSPS1, or CPSPS2,
       the contents of which must not have been changed since that call.

       ZDAT        (REAL array, dimensioned as specified in the last call to CPRECT, CPSPS1, or
                   CPSPS2, input) is the data array.

       RWRK        (REAL array, dimensioned as specified in the last call to CPRECT, CPSPS1, or
                   CPSPS2, input/output) is the real workspace array.

       IWRK        (INTEGER array, dimensioned as specified in the last call to CPRECT, CPSPS1,
                   or CPSPS2, input/output) is the integer workspace array.

       IAMA        (INTEGER array, dimensioned as specified in a call to ARINAM, in the package
                   Areas, input/output) is the array containing the area map which is to be used
                   to mask the contour lines as they are drawn.

       RTPL        (EXTERNAL subroutine) is the user subroutine which is to process the polylines
                   which result from masking the generated contour lines and other edges against
                   the area map. It must be declared EXTERNAL in the routine which calls CPCLDM.
                   It will be called repeatedly and must have the following form:

                        SUBROUTINE RTPL (XCS,YCS,NCS,IAI,IAG,NAI)
                          DIMENSION XCS(*),YCS(*),IAI(*),IAG(*)
                          ...
                          (CODE TO PROCESS POLYLINE DEFINED BY ARGUMENTS)
                          ...
                          RETURN
                        END

                   The real arrays XCS and YCS hold the X and Y coordinates of NCS points
                   defining a polyline which is to be considered for drawing. For each I greater
                   than or equal to 1 and less than or equal to NAI, IAI(I) is the area
                   identifier for the area in which the polyline lies, relative to the area-
                   identifier group IAG(I). The X and Y coordinates are all normalized device
                   coordinates and it may be assumed that the appropriate SET call has been done.
                   If it is decided to draw the line, it may be done with a call to the SPPS
                   routine CURVE, to the Dashline routine CURVED, or to the GKS routine GPL. The
                   value of 'PAI' will have been set to the appropriate value (1 through 'NCL',
                   -1, -2, or -3) for the line of which the polyline is a part. The color and
                   line width will have been set as implied by the values of the appropriate
                   elements of the parameter arrays 'CLC' and 'CLL'. The dash pattern will have
                   been defined as implied by the value of the appropriate elements of the
                   parameter arrays 'CLD' and 'CLU' and the value of the parameter 'DPU'. If a
                   dash pattern is defined, it may be retrieved by a "CALL CPGETC ('CTM',CVAL)".

                   If the only object of using CPCLDM is to avoid drawing contour lines through
                   label boxes, then the Conpack routine CPDRPL may be used for RTPL. In the
                   routine that calls CPCLDM, insert the declaration

                        EXTERNAL CPDRPL

                   and then use CPDRPL for the last argument.

C-BINDING DESCRIPTION

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

USAGE

       The routine CPCLDM may be called at any time after the initialization call to CPRECT,
       CPSPS1, or CPSPS2 to draw contour lines masked by an existing area map.  Actually, CPCLDM
       does not draw the lines; it generates them, masks them against a user-specified area map,
       and generates calls, one for each polyline resulting from the masking process, to the user
       specified routine RTPL.  Each such polyline lies entirely within precisely one of the
       areas defined by the area map.  The routine RTPL may use the information provided by its
       arguments, describing the area the polyline is in, to decide whether or not to draw the
       polyline.

       The contour lines generated are those specified by the first 'NCL' elements of the
       parameter arrays 'CLV' and 'CLU'.  If 'NCL' is zero, CPPKCL is called to generate these
       values.  Each element of 'CLV' specifies a contour level and the corresponding element of
       'CLU' specifies whether or not contour lines are to be generated at that level.  If the
       parameter 'T2D' has a non-zero value, the contour lines are smoothed, using cubic splines
       under tension.

       If the element of the parameter array 'CLU' corresponding to 'PAI' = -1 is non-zero, the
       edge of the grid is also generated.  If the element of 'CLU' corresponding to 'PAI' = -2
       is non-zero, the edges of special-value areas, if any, are generated.  If the element of
       'CLU' corresponding to 'PAI' = -3 is non-zero, the edges of out-of-range areas, if any,
       are generated.  The default values are such that none of these edges is generated.

       Groups of lines are generated in the following order:

       •  contour lines for each of the specified levels, in ascending numeric order,

       •  the edges of special-value areas, if any,

       •  the edges of out-of-range areas, if any, and

       •  the edge of the grid.

       The color, dash pattern, and line width to be used for the lines drawn may be specified by
       elements of the parameter arrays 'CLC', 'CLD', and 'CLL', respectively.  Each of these
       contains elements corresponding to values of 'PAI' from 1 to 'NCL' and three special
       elements, corresponding to 'PAI' = -1, -2, and -3.   Before and after each group of lines
       is generated, the routine CPCHCL is called; a user-supplied version of this routine may
       override the settings of color, dash pattern, and line width.  Also, of course, the
       routine RTPL, which actually does the drawing, may override the settings of these
       quantities.

       You can use the dash-pattern-usage parameter ('DPU') to affect the pattern used to draw
       the lines.  Set the value of 'DPU' as follows:

       Value       Description

       < 0 or = 0  Lines are drawn by calling the SPPS routine CURVE.  Lines are all solid and
                   unlabeled; specified dash patterns are not used.

       > 0         Lines are drawn by calling the Dashline routine CURVED.  Lines are solid or
                   dashed, depending on the dash pattern specified by the appropriate element of
                   'CLD'.

                   If ABS('LLP') = 1, then the dash pattern for those lines that are to be
                   labeled is constructed by replicating, 'DPU' times, the dash pattern specified
                   by the appropriate element of 'CLD', and then appending to it the characters
                   specified by the appropriate element of 'LLT'.

       If, during the last call to CPRECT, CPSPS1, or CPSPS2, the data being contoured were found
       to be essentially constant, then no contour lines are generated; instead, the constant-
       field label is written.  Other lines are still generated.

EXAMPLES

       Use the ncargex command to see the following relevant examples: ccpcldm, ccpllc, ccpllo,
       ccpllp, ccpllt, ccppc, ccppc1, ccppc2, ccppc3, ccppc4, ccppole, ccprc, ccpscam, colcon,
       cpex01, cpex02, cpex03, cpex04, cpex06, cpex08, cbex01, vvex01, fcover, ffex03, ffex05.

ACCESS

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

MESSAGES

       See the conpack man page for a description of all Conpack error messages and/or
       informational messages.

SEE ALSO

       Online: conpack, cpback, cpchcf, cpchcl, cpchhl, cpchil, cpchll, cpcica, cpclam, cpcldr,
       cpcltr, cpcnrc, cpdrpl, cpezct, cpgetc, cpgeti, cpgetr, cplbam, cplbdr, cpmpxy, cpmviw,
       cpmvrw, cppkcl, cppklb, cprect, cprset, cpscae, cpsetc, cpseti, cpsetr, cpsps1, cpsps2,
       ncarg_cbind

       Hardcopy: NCAR Graphics Contouring and Mapping Tutorial

COPYRIGHT

       Copyright (C) 1987-2009
       University Corporation for Atmospheric Research

       The use of this Software is governed by a License Agreement.