% File src/library/grDevices/man/rgb.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2014 R Core Team
% Distributed under GPL 2 or later

\name{rgb}
\title{RGB Color Specification}
\usage{
rgb(red, green, blue, alpha, names = NULL, maxColorValue = 1)
}
\alias{rgb}
\description{
  This function creates colors corresponding to the given
  intensities (between 0 and \code{max}) of the red, green and blue
  primaries.  The colour specification refers to the
  standard \abbr{sRGB} colorspace (\abbr{IEC} standard 61966).

  An alpha transparency value can also be specified (as an opacity, so
  \code{0} means fully transparent and \code{max} means opaque).  If
  \code{alpha} is not specified, an opaque colour is generated.

  The \code{names} argument may be used to provide names for the
  colors.

  The values returned by these functions can be used with a
  \code{col=} specification in graphics functions or in \code{\link{par}}.
}
\arguments{
  \item{red, blue, green, alpha}{numeric vectors with values in \eqn{[0, M]}
    where \eqn{M} is \code{maxColorValue}.  When this is \code{255}, the
    \code{red}, \code{blue}, \code{green}, and \code{alpha}
    values are coerced to integers in \code{0:255} and the result is
    computed most efficiently.}
  \item{names}{character vector. The names for the resulting vector.}
  \item{maxColorValue}{number giving the maximum of the color values
    range, see above.}
}
\details{
  The colors may be specified by passing a matrix or data frame as argument
  \code{red}, and leaving \code{blue} and \code{green} missing.
  In this case the first three columns of \code{red} are taken to be
  the \code{red}, \code{green} and \code{blue} values.

  Semi-transparent colors (\eqn{0 < \code{alpha} < 1}) are supported only on
  some devices: at the time of writing on the \code{\link{pdf}},
  \code{windows}, \code{quartz} and \code{X11(type = "cairo")} devices and
  associated bitmap devices (\code{jpeg}, \code{png}, \code{bmp},
  \code{tiff} and \code{bitmap}). They are supported by several
  third-party devices such as those in packages \CRANpkg{Cairo},
  \CRANpkg{cairoDevice} and \CRANpkg{JavaGD}.  Only some of these
  devices support semi-transparent backgrounds.

  Most other graphics devices plot semi-transparent colors as fully
  transparent, usually with a warning when first encountered.
  
  \code{NA} values are not allowed for any of \code{red}, \code{blue}, 
  \code{green} or \code{alpha}.
}
\value{
  A character vector with elements of 7 or 9 characters,
  beginning with \code{"#"} followed by the red, 
  blue, green and optionally alpha values in hexadecimal (after 
  rescaling to \code{0 ... 255}).  The optional alpha values range 
  from \code{0} (fully transparent) to \code{255} (opaque). 

  \R does \strong{not} use \sQuote{premultiplied alpha}.
}
\seealso{
  \code{\link{col2rgb}} for translating \R colors to RGB vectors;
  \code{\link{rainbow}}, \code{\link{hsv}}, \code{\link{hcl}},
  \code{\link{gray}}.
}
\examples{
rgb(0, 1, 0)

rgb((0:15)/15, green = 0, blue = 0, names = paste("red", 0:15, sep = "."))

rgb(0, 0:12, 0, maxColorValue = 255) # integer input

ramp <- colorRamp(c("red", "white"))
rgb( ramp(seq(0, 1, length.out = 5)), maxColorValue = 255)
}
\keyword{color}
