NAME

       ARDRLN - Draws a polyline that is masked by a given area map.

SYNOPSIS

       CALL ARDRLN (MAP,XCD,YCD,NCD,XCS,YCS,MCS,IAI,IAG,MAI,LPR)

C-BINDING SYNOPSIS

       #include <ncarg/ncargC.h>

       void c_ardrln (int *map, float *xcd, float *ycd, int ncd, float *xcs, float *ycs, int mcs, int *iai, int
       *iag, int mai, int (*lpr)(float *xcs, float *ycs, int *ncs, int *iai, int *iag, int *nai))

DESCRIPTION

       MAP         (an  input/output  array  of  type  INTEGER)  - An array containing an area map that has been
                   initialized by a call to ARINAM and to which edges have been added by calls  to  AREDAM.   If
                   you  did not preprocess the area map by calling ARPRAM, ARDRLN calls it before doing anything
                   else.

                   Note: As part of initializing the area map, ARINAM stores the dimension  of  MAP  in  MAP(1);
                   therefore, the dimension does not have to be given as an argument in calls to ARDRLN.)

       XCD         (an  input  array, dimensioned NCD, of type REAL) - The X coordinates, in the user coordinate
                   system, of the points defining the polyline.

       YCD         (an input array, dimensioned NCD, of type REAL) - The Y coordinates, in the  user  coordinate
                   system, of the points defining the polyline.

       NCD         (an input expression of type INTEGER) - The number of points defining the polyline.

       XCS         (a  workspace  array,  dimensioned  MCS,  of type REAL) - Used by ARDRLN in calls to LPR, the
                   user-supplied line-processing routine, to hold the X  coordinates  of  the  polyline  segment
                   contained in a given area.

       YCS         (a  workspace  array,  dimensioned  MCS,  of type REAL) - Used by ARDRLN in calls to LPR, the
                   user-supplied line-processing routine, to hold the Y  coordinates  of  the  polyline  segment
                   contained in a given area.

       MCS         (an input expression of type INTEGER) - Dimension of each of the arrays XCS and YCS.

       IAI         (a  workspace  array,  dimensioned MAI, of type INTEGER) - The area identifier array, used in
                   calls to LPR, the user-supplied line-processing routine.

       IAG         (a workspace array, dimensioned MAI, of type INTEGER) - The group identifier array,  used  in
                   calls to LPR, the user-supplied line-processing routine.

       MAI         (an input expression of type INTEGER) - Dimension of each of the arrays IAI and IAG. MAI must
                   be greater than or equal to n, where n is the number of groups in the area map.

       LPR         (a  subroutine)  -  A line-processing routine that you supply for ARDRLN to call. LPR must be
                   declared EXTERNAL in the routine that calls ARDRLN. LPR must have the following structure:

                   SUBROUTINE LPR (XCS,YCS,NCS,IAI,IAG,NAI)
                   DIMENSION XCS(*),YCS(*),IAI(*),IAG(*)

                   (code to process polyline defined by XCS, YCS, IAI, and IAG)

                   RETURN
                   END

                   XCS,YCS     (input arrays, dimensioned NCS, of type REAL) - Hold the X and Y coordinates,  in
                               NDCs,  of NCS points defining a piece of the original polyline that is completely
                               contained in one of the areas defined by the area map.

                   NCS         (an input expression of type INTEGER) - Number of X  and  Y  coordinates  in  the
                               arrays XCS and YCS.

                   IAI,IAG     (input  arrays,  dimensioned  NAI,  of  type  INTEGER)  -  Hold NAI pairs of area
                               identifiers and group identifiers, respectively, for the area in which the  piece
                               of  the  polyline  lies.  For  each  value of I from 1 to NAI, IAI(I) is the area
                               identifier for the area with respect to the group of edges specified by the group
                               identifier IAG(I).

                   NAI         (an input expression of type INTEGER) - Number of values given in  IAI  and  IAG.
                               NAI equals the number of groups of edges that you put in the area map.

       Before  executing  the first call to LPR, ARDRLN calls GETSET to retrieve the current user-system mapping
       parameters and then executes the following statement:

            CALL SET (VPL,VPR,VPB,VPT,VPL,VPR,VPB,VPT,1)

       where VPL, VPR, VPB, and VPT are the viewport left, right, bottom, and top coordinates in NDCs.

       This ensures correct results if the NDCs in XCS and YCS are used by the line-processing  routine  LPR  in
       calls to such routines as GPL and CURVE, and it allows for clipping at the edges of the viewport. LPR may
       make  its  own  SET  call  to achieve some other effect. Before returning control to the calling routine,
       ARDRLN calls SET again to restore the original mapping parameters.

C-BINDING DESCRIPTION

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

EXAMPLES

       Use the ncargex command to see the following relevant examples: carline, tareas, fsppoint.

ACCESS

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

MESSAGES

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

SEE ALSO

       Online:  areas,  areas_params,  ardbpa,  aredam,  argeti, argetr, argtai, arinam, armvam, arpram, arscam,
       arseti, arsetr, 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.

UNIX                                               March 1993                                     ARDRLN(3NCARG)