diff --git a/DESCRIPTION b/DESCRIPTION index 421d9aff..26c3278d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -40,3 +40,4 @@ Encoding: UTF-8 RoxygenNote: 7.3.1 SystemRequirements: freetype2, libpng, libtiff, libjpeg Config/testthat/edition: 3 +Roxygen: list(markdown = TRUE) diff --git a/man/agg_capture.Rd b/man/agg_capture.Rd index 58c32e75..7fbf0723 100644 --- a/man/agg_capture.Rd +++ b/man/agg_capture.Rd @@ -19,11 +19,11 @@ agg_capture( \arguments{ \item{width, height}{The dimensions of the device} -\item{units}{The unit `width` and `height` is measured in, in either pixels -(`'px'`), inches (`'in'`), millimeters (`'mm'`), or centimeter (`'cm'`).} +\item{units}{The unit \code{width} and \code{height} is measured in, in either pixels +(\code{'px'}), inches (\code{'in'}), millimeters (\code{'mm'}), or centimeter (\code{'cm'}).} -\item{pointsize}{The default pointsize of the device in pt. This will in -general not have any effect on grid graphics (including ggplot2) as text +\item{pointsize}{The default pointsize of the device in pt. This will in +general not have any effect on grid graphics (including ggplot2) as text size is always set explicitly there.} \item{background}{The background colour of the device} @@ -34,28 +34,28 @@ to pixels. Further, it will be used to scale text sizes and linewidths} \item{scaling}{A scaling factor to apply to the rendered line width and text size. Useful for getting the right dimensions at the resolution that you -need. If e.g. you need to render a plot at 4000x3000 pixels for it to fit -into a layout, but you find that the result appears to small, you can -increase the `scaling` argument to make everything appear bigger at the +need. If e.g. you need to render a plot at 4000x3000 pixels for it to fit +into a layout, but you find that the result appears to small, you can +increase the \code{scaling} argument to make everything appear bigger at the same resolution.} \item{snap_rect}{Should axis-aligned rectangles drawn with only fill snap to -the pixel grid. This will prevent anti-aliasing artifacts when two +the pixel grid. This will prevent anti-aliasing artifacts when two rectangles are touching at their border.} -\item{bg}{Same as `background` for compatibility with old graphic device APIs} +\item{bg}{Same as \code{background} for compatibility with old graphic device APIs} } \value{ A function that when called returns the current state of the buffer. -The return value of the function depends on the `native` argument. If `FALSE` -(default) the return value is a `matrix` of colour values and if `TRUE` the -return value is a `nativeRaster` object. +The return value of the function depends on the \code{native} argument. If \code{FALSE} +(default) the return value is a \code{matrix} of colour values and if \code{TRUE} the +return value is a \code{nativeRaster} object. } \description{ -Usually the point of using a graphic device is to create a file or show the -graphic on the screen. A few times we need the image data for further +Usually the point of using a graphic device is to create a file or show the +graphic on the screen. A few times we need the image data for further processing in R, and instead of writing it to a file and then reading it back -into R the `agg_capture()` device lets you get the image data directly from +into R the \code{agg_capture()} device lets you get the image data directly from the buffer. In contrast to the other devices this device returns a function, that when called will return the current state of the buffer. } diff --git a/man/agg_jpeg.Rd b/man/agg_jpeg.Rd index 0755b3ae..f256664f 100644 --- a/man/agg_jpeg.Rd +++ b/man/agg_jpeg.Rd @@ -21,17 +21,17 @@ agg_jpeg( ) } \arguments{ -\item{filename}{The name of the file. Follows the same semantics as the file -naming in [grDevices::png()], meaning that you can provide a [sprintf()] +\item{filename}{The name of the file. Follows the same semantics as the file +naming in \code{\link[grDevices:png]{grDevices::png()}}, meaning that you can provide a \code{\link[=sprintf]{sprintf()}} compliant string format to name multiple plots (such as the default value)} \item{width, height}{The dimensions of the device} -\item{units}{The unit `width` and `height` is measured in, in either pixels -(`'px'`), inches (`'in'`), millimeters (`'mm'`), or centimeter (`'cm'`).} +\item{units}{The unit \code{width} and \code{height} is measured in, in either pixels +(\code{'px'}), inches (\code{'in'}), millimeters (\code{'mm'}), or centimeter (\code{'cm'}).} -\item{pointsize}{The default pointsize of the device in pt. This will in -general not have any effect on grid graphics (including ggplot2) as text +\item{pointsize}{The default pointsize of the device in pt. This will in +general not have any effect on grid graphics (including ggplot2) as text size is always set explicitly there.} \item{background}{The background colour of the device} @@ -42,43 +42,43 @@ to pixels. Further, it will be used to scale text sizes and linewidths} \item{scaling}{A scaling factor to apply to the rendered line width and text size. Useful for getting the right dimensions at the resolution that you -need. If e.g. you need to render a plot at 4000x3000 pixels for it to fit -into a layout, but you find that the result appears to small, you can -increase the `scaling` argument to make everything appear bigger at the +need. If e.g. you need to render a plot at 4000x3000 pixels for it to fit +into a layout, but you find that the result appears to small, you can +increase the \code{scaling} argument to make everything appear bigger at the same resolution.} \item{snap_rect}{Should axis-aligned rectangles drawn with only fill snap to -the pixel grid. This will prevent anti-aliasing artifacts when two +the pixel grid. This will prevent anti-aliasing artifacts when two rectangles are touching at their border.} -\item{quality}{An integer between `0` and `100` defining the quality/size -tradeoff. Setting this to `100` will result in no compression.} +\item{quality}{An integer between \code{0} and \code{100} defining the quality/size +tradeoff. Setting this to \code{100} will result in no compression.} -\item{smoothing}{A smoothing factor to apply before compression, from `0` (no -smoothing) to `100` (full smoothing). Can also by `FALSE` (no smoothing) or -`TRUE` (full smoothing).} +\item{smoothing}{A smoothing factor to apply before compression, from \code{0} (no +smoothing) to \code{100} (full smoothing). Can also by \code{FALSE} (no smoothing) or +\code{TRUE} (full smoothing).} -\item{method}{The compression algorithm to use. Either `'slow'`, `'fast'`, or -`'float'`. Default is `'slow'` which works best for most cases. `'fast'` -should only be used when quality is below `97` as it may result in worse -performance at high quality settings. `'float'` is a legacy options that -calculate the compression using floating point precission instead of with +\item{method}{The compression algorithm to use. Either \code{'slow'}, \code{'fast'}, or +\code{'float'}. Default is \code{'slow'} which works best for most cases. \code{'fast'} +should only be used when quality is below \code{97} as it may result in worse +performance at high quality settings. \code{'float'} is a legacy options that +calculate the compression using floating point precission instead of with integers. It offers no quality benefit and is often much slower.} -\item{bg}{Same as `background` for compatibility with old graphic device APIs} +\item{bg}{Same as \code{background} for compatibility with old graphic device APIs} } \description{ -The JPEG file format is a lossy compressed file format developed in -particular for digital photography. The format is not particularly -well-suited for line drawings and text of the type normally associated with -statistical plots as the compression algorithm creates noticable artefacts. +The JPEG file format is a lossy compressed file format developed in +particular for digital photography. The format is not particularly +well-suited for line drawings and text of the type normally associated with +statistical plots as the compression algorithm creates noticable artefacts. It is, however, great for saving image data, e.g. heightmaps etc. Thus, for -standard plots, it would be better to use [agg_png()], but for plots that +standard plots, it would be better to use \code{\link[=agg_png]{agg_png()}}, but for plots that includes a high degree of raster image rendering this device will result in smaller plots with very little quality degradation. } \note{ -Smoothing is only applied if ragg has been compiled against a jpeg +Smoothing is only applied if ragg has been compiled against a jpeg library that supports smoothing. } \examples{ diff --git a/man/agg_png.Rd b/man/agg_png.Rd index 075a93c8..71099673 100644 --- a/man/agg_png.Rd +++ b/man/agg_png.Rd @@ -19,17 +19,17 @@ agg_png( ) } \arguments{ -\item{filename}{The name of the file. Follows the same semantics as the file -naming in [grDevices::png()], meaning that you can provide a [sprintf()] +\item{filename}{The name of the file. Follows the same semantics as the file +naming in \code{\link[grDevices:png]{grDevices::png()}}, meaning that you can provide a \code{\link[=sprintf]{sprintf()}} compliant string format to name multiple plots (such as the default value)} \item{width, height}{The dimensions of the device} -\item{units}{The unit `width` and `height` is measured in, in either pixels -(`'px'`), inches (`'in'`), millimeters (`'mm'`), or centimeter (`'cm'`).} +\item{units}{The unit \code{width} and \code{height} is measured in, in either pixels +(\code{'px'}), inches (\code{'in'}), millimeters (\code{'mm'}), or centimeter (\code{'cm'}).} -\item{pointsize}{The default pointsize of the device in pt. This will in -general not have any effect on grid graphics (including ggplot2) as text +\item{pointsize}{The default pointsize of the device in pt. This will in +general not have any effect on grid graphics (including ggplot2) as text size is always set explicitly there.} \item{background}{The background colour of the device} @@ -40,31 +40,31 @@ to pixels. Further, it will be used to scale text sizes and linewidths} \item{scaling}{A scaling factor to apply to the rendered line width and text size. Useful for getting the right dimensions at the resolution that you -need. If e.g. you need to render a plot at 4000x3000 pixels for it to fit -into a layout, but you find that the result appears to small, you can -increase the `scaling` argument to make everything appear bigger at the +need. If e.g. you need to render a plot at 4000x3000 pixels for it to fit +into a layout, but you find that the result appears to small, you can +increase the \code{scaling} argument to make everything appear bigger at the same resolution.} \item{snap_rect}{Should axis-aligned rectangles drawn with only fill snap to -the pixel grid. This will prevent anti-aliasing artifacts when two +the pixel grid. This will prevent anti-aliasing artifacts when two rectangles are touching at their border.} \item{bitsize}{Should the device record colour as 8 or 16bit} -\item{bg}{Same as `background` for compatibility with old graphic device APIs} +\item{bg}{Same as \code{background} for compatibility with old graphic device APIs} } \description{ -The PNG (Portable Network Graphic) format is one of the most ubiquitous -today, due to its versatiliity +The PNG (Portable Network Graphic) format is one of the most ubiquitous +today, due to its versatiliity and widespread support. It supports transparency as well as both 8 and 16 bit colour. The device uses default compression and filtering and will not use a -colour palette as this is less useful for antialiased data. This means that +colour palette as this is less useful for antialiased data. This means that it might be possible to compress the resulting image even more if size is of -concern (though the defaults are often very good). In contrast to -[grDevices::png()] the date and time will not be written to the file, meaning -that similar plot code will produce identical files (a good feature if used +concern (though the defaults are often very good). In contrast to +\code{\link[grDevices:png]{grDevices::png()}} the date and time will not be written to the file, meaning +that similar plot code will produce identical files (a good feature if used with version control). It will, however, write in the dimensions of the image -based on the `res` argument. +based on the \code{res} argument. } \examples{ file <- tempfile(fileext = '.png') diff --git a/man/agg_ppm.Rd b/man/agg_ppm.Rd index 5e843ee6..90fd1de7 100644 --- a/man/agg_ppm.Rd +++ b/man/agg_ppm.Rd @@ -18,17 +18,17 @@ agg_ppm( ) } \arguments{ -\item{filename}{The name of the file. Follows the same semantics as the file -naming in [grDevices::png()], meaning that you can provide a [sprintf()] +\item{filename}{The name of the file. Follows the same semantics as the file +naming in \code{\link[grDevices:png]{grDevices::png()}}, meaning that you can provide a \code{\link[=sprintf]{sprintf()}} compliant string format to name multiple plots (such as the default value)} \item{width, height}{The dimensions of the device} -\item{units}{The unit `width` and `height` is measured in, in either pixels -(`'px'`), inches (`'in'`), millimeters (`'mm'`), or centimeter (`'cm'`).} +\item{units}{The unit \code{width} and \code{height} is measured in, in either pixels +(\code{'px'}), inches (\code{'in'}), millimeters (\code{'mm'}), or centimeter (\code{'cm'}).} -\item{pointsize}{The default pointsize of the device in pt. This will in -general not have any effect on grid graphics (including ggplot2) as text +\item{pointsize}{The default pointsize of the device in pt. This will in +general not have any effect on grid graphics (including ggplot2) as text size is always set explicitly there.} \item{background}{The background colour of the device} @@ -39,21 +39,21 @@ to pixels. Further, it will be used to scale text sizes and linewidths} \item{scaling}{A scaling factor to apply to the rendered line width and text size. Useful for getting the right dimensions at the resolution that you -need. If e.g. you need to render a plot at 4000x3000 pixels for it to fit -into a layout, but you find that the result appears to small, you can -increase the `scaling` argument to make everything appear bigger at the +need. If e.g. you need to render a plot at 4000x3000 pixels for it to fit +into a layout, but you find that the result appears to small, you can +increase the \code{scaling} argument to make everything appear bigger at the same resolution.} \item{snap_rect}{Should axis-aligned rectangles drawn with only fill snap to -the pixel grid. This will prevent anti-aliasing artifacts when two +the pixel grid. This will prevent anti-aliasing artifacts when two rectangles are touching at their border.} -\item{bg}{Same as `background` for compatibility with old graphic device APIs} +\item{bg}{Same as \code{background} for compatibility with old graphic device APIs} } \description{ -The PPM (Portable Pixel Map) format defines one of the simplest storage -formats available for -image data. It is basically a raw 8bit RGB stream with a few bytes of +The PPM (Portable Pixel Map) format defines one of the simplest storage +formats available for +image data. It is basically a raw 8bit RGB stream with a few bytes of information in the start. It goes without saying, that this file format is horribly inefficient and should only be used if you want to play around with a simple file format, or need a file-based image stream. diff --git a/man/agg_supertransparent.Rd b/man/agg_supertransparent.Rd index 8404bb6c..c1a1612b 100644 --- a/man/agg_supertransparent.Rd +++ b/man/agg_supertransparent.Rd @@ -19,17 +19,17 @@ agg_supertransparent( ) } \arguments{ -\item{filename}{The name of the file. Follows the same semantics as the file -naming in [grDevices::png()], meaning that you can provide a [sprintf()] +\item{filename}{The name of the file. Follows the same semantics as the file +naming in \code{\link[grDevices:png]{grDevices::png()}}, meaning that you can provide a \code{\link[=sprintf]{sprintf()}} compliant string format to name multiple plots (such as the default value)} \item{width, height}{The dimensions of the device} -\item{units}{The unit `width` and `height` is measured in, in either pixels -(`'px'`), inches (`'in'`), millimeters (`'mm'`), or centimeter (`'cm'`).} +\item{units}{The unit \code{width} and \code{height} is measured in, in either pixels +(\code{'px'}), inches (\code{'in'}), millimeters (\code{'mm'}), or centimeter (\code{'cm'}).} -\item{pointsize}{The default pointsize of the device in pt. This will in -general not have any effect on grid graphics (including ggplot2) as text +\item{pointsize}{The default pointsize of the device in pt. This will in +general not have any effect on grid graphics (including ggplot2) as text size is always set explicitly there.} \item{background}{The background colour of the device} @@ -40,28 +40,28 @@ to pixels. Further, it will be used to scale text sizes and linewidths} \item{scaling}{A scaling factor to apply to the rendered line width and text size. Useful for getting the right dimensions at the resolution that you -need. If e.g. you need to render a plot at 4000x3000 pixels for it to fit -into a layout, but you find that the result appears to small, you can -increase the `scaling` argument to make everything appear bigger at the +need. If e.g. you need to render a plot at 4000x3000 pixels for it to fit +into a layout, but you find that the result appears to small, you can +increase the \code{scaling} argument to make everything appear bigger at the same resolution.} \item{snap_rect}{Should axis-aligned rectangles drawn with only fill snap to -the pixel grid. This will prevent anti-aliasing artifacts when two +the pixel grid. This will prevent anti-aliasing artifacts when two rectangles are touching at their border.} -\item{alpha_mod}{A numeric between 0 and 1 that will be multiplied to the +\item{alpha_mod}{A numeric between 0 and 1 that will be multiplied to the alpha channel of all transparent colours} -\item{bg}{Same as `background` for compatibility with old graphic device APIs} +\item{bg}{Same as \code{background} for compatibility with old graphic device APIs} } \description{ The graphic engine in R only supports 8bit colours. This is for the most part fine, as 8bit gives all the fidelity needed for most graphing needs. However, -this may become a limitation if you need to plot thousands of very +this may become a limitation if you need to plot thousands of very translucent shapes on top of each other. 8bit only afford a minimum of 1/255 -alpha, which may end up accumulating to fully opaque at some point. This -device allows you to create a 16bit device that modifies the alpha level of -all incomming colours by a fixed multiplier, thus allowing for much more +alpha, which may end up accumulating to fully opaque at some point. This +device allows you to create a 16bit device that modifies the alpha level of +all incomming colours by a fixed multiplier, thus allowing for much more translucent colours. The device will only modify transparent colour, so if you pass in an opaque colour it will be left unchanged. } diff --git a/man/agg_tiff.Rd b/man/agg_tiff.Rd index 3bd78097..dd469c24 100644 --- a/man/agg_tiff.Rd +++ b/man/agg_tiff.Rd @@ -20,17 +20,17 @@ agg_tiff( ) } \arguments{ -\item{filename}{The name of the file. Follows the same semantics as the file -naming in [grDevices::png()], meaning that you can provide a [sprintf()] +\item{filename}{The name of the file. Follows the same semantics as the file +naming in \code{\link[grDevices:png]{grDevices::png()}}, meaning that you can provide a \code{\link[=sprintf]{sprintf()}} compliant string format to name multiple plots (such as the default value)} \item{width, height}{The dimensions of the device} -\item{units}{The unit `width` and `height` is measured in, in either pixels -(`'px'`), inches (`'in'`), millimeters (`'mm'`), or centimeter (`'cm'`).} +\item{units}{The unit \code{width} and \code{height} is measured in, in either pixels +(\code{'px'}), inches (\code{'in'}), millimeters (\code{'mm'}), or centimeter (\code{'cm'}).} -\item{pointsize}{The default pointsize of the device in pt. This will in -general not have any effect on grid graphics (including ggplot2) as text +\item{pointsize}{The default pointsize of the device in pt. This will in +general not have any effect on grid graphics (including ggplot2) as text size is always set explicitly there.} \item{background}{The background colour of the device} @@ -41,27 +41,27 @@ to pixels. Further, it will be used to scale text sizes and linewidths} \item{scaling}{A scaling factor to apply to the rendered line width and text size. Useful for getting the right dimensions at the resolution that you -need. If e.g. you need to render a plot at 4000x3000 pixels for it to fit -into a layout, but you find that the result appears to small, you can -increase the `scaling` argument to make everything appear bigger at the +need. If e.g. you need to render a plot at 4000x3000 pixels for it to fit +into a layout, but you find that the result appears to small, you can +increase the \code{scaling} argument to make everything appear bigger at the same resolution.} \item{snap_rect}{Should axis-aligned rectangles drawn with only fill snap to -the pixel grid. This will prevent anti-aliasing artifacts when two +the pixel grid. This will prevent anti-aliasing artifacts when two rectangles are touching at their border.} -\item{compression}{The compression type to use for the image data. The -standard options from the [grDevices::tiff()] function are available under +\item{compression}{The compression type to use for the image data. The +standard options from the \code{\link[grDevices:png]{grDevices::tiff()}} function are available under the same name.} \item{bitsize}{Should the device record colour as 8 or 16bit} -\item{bg}{Same as `background` for compatibility with old graphic device APIs} +\item{bg}{Same as \code{background} for compatibility with old graphic device APIs} } \description{ The TIFF (Tagged Image File Format) format is a very versatile raster image storage format that supports 8 and 16bit colour mode, true transparency, as -well as a range of other features not relevant to drawing from R (e.g. +well as a range of other features not relevant to drawing from R (e.g. support for different colour spaces). The storage mode of the image data is not fixed and different compression modes are possible, in contrast to PNGs one-approach-fits-all. The default (uncompressed) will result in much larger @@ -70,13 +70,13 @@ types produced in R. Still, TIFF has its purposes and sometimes this file format is explicetly requested. } \note{ -`'jpeg'` compression is only available if ragg is compiled with a -version of `libtiff` where jpeg support has been turned on. +\code{'jpeg'} compression is only available if ragg is compiled with a +version of \code{libtiff} where jpeg support has been turned on. } \section{Transparency}{ -TIFF have support for true transparency, meaning that the pixel colour is -stored in pre-multiplied form. This is in contrast to pixels being stored in +TIFF have support for true transparency, meaning that the pixel colour is +stored in pre-multiplied form. This is in contrast to pixels being stored in plain format, where the alpha values more function as a mask. The utility of this is not always that important, but it is one of the benefits of TIFF over PNG so it should be noted.