1PPPLCL(3NCARG)                   NCAR GRAPHICS                  PPPLCL(3NCARG)
2
3
4

NAME

6       PPPLCL - clips a polyline against a clipping rectangle. It is intended
7       that, eventually, there should be a better routine that will clip a
8       polyline against an arbitrary polygon, but that routine has not yet
9       been written.
10

SYNOPSIS

12       CALL PPPLCL (XMIN,XMAX,YMIN,YMAX,XCPL,YCPL,NCPL,RWRK,LRWK,URPF,IERR)
13

C-BINDING SYNOPSIS

15       #include <ncarg/ncargC.h>
16
17       void c_ppplcl(float xmin,
18                     float xmax,
19                     float ymin,
20                     float ymax,
21                     float *xcpl,
22                     float *ycpl,
23                     int ncpl,
24                     float *rwrk,
25                     int lwrk,
26                     int (*urpf_)(float *xcra,
27                                  float *ycra,
28                                  int *ncra),
29                     int *ierr)
30

DESCRIPTION

32       XMIN        (an input expression of type REAL) is the X coordinate
33                   value defining the position of the left edge of the
34                   clipping rectangle.
35
36       XMAX        (an input expression of type REAL) is the X coordinate
37                   value defining the position of the right edge of the
38                   clipping rectangle.
39
40       YMIN        (an input expression of type REAL) is the Y coordinate
41                   value defining the position of the bottom of the clipping
42                   rectangle.
43
44       YMAX        (an input expression of type REAL) is the Y coordinate
45                   value defining the position of the top of the clipping
46                   rectangle.
47
48       XCPL        (an input array of type REAL) is the X coordinate array for
49                   the polyline that is to be clipped.
50
51       YCPL        (an input array of type REAL) is the Y coordinate array for
52                   the polyline that is to be clipped.
53
54       NCPL        (an input expression of type INTEGER) is the number of
55                   points defining the input polyline (the number of
56                   meaningful elements in each of the arrays XCPL and YCPL).
57
58       RWRK        (a scratch array of type REAL) is a workspace array for
59                   PPPLCL to use.  It is divided into halves; one half is used
60                   for X coordinates and the other half for Y coordinates.
61                   This array doesn't have to be too big unless it is
62                   important not to break the polyline except at the edges of
63                   the clipping rectangle.
64
65       LRWK        (an input expression of type INTEGER) is the length of the
66                   array RWRK.
67
68       URPF        is the name of a user-provided routine to process the
69                   fragments of the polyline resulting from the clipping
70                   process.  This name must appear in an EXTERNAL statement in
71                   the routine that calls PPPLCL and the routine itself must
72                   have the following form:
73
74                        SUBROUTINE URPF (XCRA,YCRA,NCRA)
75                          DIMENSION XCRA(NCRA),YCRA(NCRA)
76                          ...(code to process a polyline)...
77                          RETURN
78                        END
79
80                   Each of the arguments XCRA and YCRA is a real array,
81                   dimensioned NCRA; the former holds the X coordinates, and
82                   the latter the Y coordinates, of a polyline fragment.
83
84       IERR        (an output variable of type INTEGER) is returned with the
85                   value zero if no errors occurred in the execution of PPPLCL
86                   or with a small positive value if an error did occur. The
87                   value 1 indicates that NCPL is less than or equal to zero
88                   and the value 2 indicates that LRWK is less than 4.
89

C-BINDING DESCRIPTION

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

USAGE

95       The FORTRAN statement
96
97       CALL PPPLCL (XMIN,XMAX,YMIN,YMAX,XCPL,YCPL,NCPL,RWRK,LRWK,URPF,IERR)
98
99       clips a polyline against a rectangle and delivers the portions of the
100       polyline that fall within the rectangle, one by one, to the user-
101       specified polyline-fragment-processing routine URPF.
102

EXAMPLES

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

ACCESS

108       To use PPPLCL or c_ppplcl, load the NCAR Graphics libraries ncarg,
109       ncarg_gks, and ncarg_c, preferably in that order.
110

SEE ALSO

112       Online: polypack, ppdipo, ppditr, ppinpo, ppintr, ppppap, ppunpo,
113       ppuntr, ncarg_cbind.
114
115       Hardcopy: None.
116

COPYRIGHT

118       Copyright (C) 1987-2007
119       University Corporation for Atmospheric Research
120
121       This documentation is free software; you can redistribute it and/or
122       modify it under the terms of the GNU General Public License as
123       published by the Free Software Foundation; either version 2 of the
124       License, or (at your option) any later version.
125
126       This software is distributed in the hope that it will be useful, but
127       WITHOUT ANY WARRANTY; without even the implied warranty of
128       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
129       General Public License for more details.
130
131       You should have received a copy of the GNU General Public License along
132       with this software; if not, write to the Free Software Foundation,
133       Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
134
135
136
137UNIX                              March 1995                    PPPLCL(3NCARG)