\Header{polygon}{Polygon Drawing}
\keyword{aplot}{polygon}
\begin{Description}\relax
\code{polygon} draws the polygons whose vertices are
given in \code{x} and \code{y}.
\end{Description}
\begin{Usage}
\begin{verbatim}
polygon(x, y = NULL, density = NULL, angle = 45,
        border = NULL, col = NA, lty = NULL, xpd = NULL, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x,y}] vectors containing the coordinates of the vertices
of the polygon.
\item[\code{density}] the density of shading lines, in lines per inch.  The
default value of \code{NULL} means that no shading lines are drawn.
A zero value of \code{density} means no shading lines whereas
negative values (and \code{NA}) suppress shading (and so allow
color filling).
\item[\code{angle}] the slope of shading lines, given as an angle
in degrees (counter-clockwise).
\item[\code{col}] the color for filling the polygon.
The default, \code{NA}, is to leave polygons unfilled.
\item[\code{border}] the color to draw the border.  The default, \code{NULL},
uses \code{\Link{par}("fg")}.  Use \code{border = NA} to omit borders.

For compatibility with S, \code{border} can also be logical, in
which case \code{FALSE} is equivalent to \code{NA} (borders omitted)
and \code{TRUE} is equivalent to \code{NULL} (use the foreground colour),

\item[\code{lty}] the line type to be used, as in \code{\Link{par}}.
\item[\code{xpd}] (where) should clipping take place?  Defaults to
\code{\Link{par}("xpd")}.
\item[\code{...}] graphical parameters can be given as arguments to
\code{polygon}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The coordinates can be passed in a plotting structure
(a list with \code{x} and \code{y} components), a two-column matrix,
\dots.  See \code{\Link{xy.coords}}.

It is assumed that the polygon is closed by joining the last point to
the first point.

The coordinates can contain missing values.  The behaviour is similar
to that of \code{\Link{lines}}, except
that instead of breaking a line into several lines, \code{NA}
values break the polygon into several complete polygons
(including closing the last point to the first point).  See
the examples below.

When multiple polygons are produced,
the values of \code{density}, \code{angle}, \code{col}, \code{border},
and \code{lty} are recycled in the usual manner.
\end{Details}
\begin{Section}{Bugs}
The present shading algorithm can produce incorrect results for
self-intersecting polygons.
\end{Section}
\begin{Author}\relax
The code implementing polygon shading was donated by
Kevin Buhr \email{buhr@stat.wisc.edu}.
\end{Author}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\Link{segments}} for even more flexibility, \code{\Link{lines}},
\code{\Link{rect}}, \code{\Link{box}}, \code{\Link{abline}}.

\code{\Link{par}} for how to specify colors.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- c(1:9,8:1)
y <- c(1,2*(5:3),2,-1,17,9,8,2:9)
op <- par(mfcol=c(3,1))
for(xpd in c(FALSE,TRUE,NA)) {
  plot(1:10, main=paste("xpd =", xpd)) ; box("figure", col = "pink", lwd=3)
  polygon(x,y, xpd=xpd, col = "orange", lty=2, lwd=2, border = "red")
}
par(op)

n <- 100
xx <- c(0:n, n:0)
yy <- c(c(0,cumsum(rnorm(n))), rev(c(0,cumsum(rnorm(n)))))
plot   (xx, yy, type="n", xlab="Time", ylab="Distance")
polygon(xx, yy, col="gray", border = "red")
title("Distance Between Brownian Motions")

# Multiple polygons from NA values
# and recycling of col, border, and lty
op <- par(mfrow=c(2,1))
plot(c(1,9), 1:2, type="n")
polygon(1:9, c(2,1,2,1,1,2,1,2,1),
        col=c("red", "blue"),
        border=c("green", "yellow"),
        lwd=3, lty=c("dashed", "solid"))
plot(c(1,9), 1:2, type="n")
polygon(1:9, c(2,1,2,1,NA,2,1,2,1),
        col=c("red", "blue"),
        border=c("green", "yellow"),
        lwd=3, lty=c("dashed", "solid"))
par(op)

# Line-shaded polygons
plot(c(1,9), 1:2, type="n")
polygon(1:9, c(2,1,2,1,NA,2,1,2,1),
        density=c(10, 20), angle=c(-45, 45))
\end{ExampleCode}
\end{Examples}

