---
title: "CairoHacks: Bookmarks and Rasters"
author: "Don Armstrong"
output:
    html_document:
        toc: TRUE
vignette: >
  %\VignetteIndexEntry{CairoHacks}
  %\VignetteEngine{knitr::knitr}
  \usepackage[utf8]{inputenc}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo=TRUE)
```

# Bookmarks

CairoHacks allows you to create bookmarks in PDF documents. This
requires the use of pdftk to actually create the bookmarks at the end
of the pdf creation.

Here is a simple example:

```{r, eval=FALSE}
     Cairo::CairoPDF(file="example.pdf",onefile=TRUE)
     plot(y~x,data.frame(x=1:5,y=1:5))
     bookmarks <- make.pdf.bookmark("First plot")
     plot(y~x,data.frame(x=1:5,y=1:5))
     bookmarks <- bookmarks + make.pdf.bookmark("Second plot")
     dev.off()
     write.pdf.bookmarks(file="example.pdf",bookmarks)
```

This will create two bookmarks in the file `example.pdf` named "First
plot" and "Second plot" which point to the first and second pages,
respectively.

Bookmarks requires the use of the CairoPDF device so that the current
page number can be obtained using the onSave Cairo Hook. In the
future, if other devices allow reporting the current page number, they
will be supported.

# Raster Images

CairoHacks also allows you to create raster images (bitmaps) which can
then be embedded into a PDF. This is very useful, because sometimes
you have a huge number (millions) of points which you would like to
plot on a single plot without making the resultant PDF megabytes in
size. For example:

```{r echo=TRUE,fig.keep="last"}
library("CairoHacks")
start_rasterplot(width=1024)
plot(y~x,
     data=data.frame(y=rnorm(1E5),x=rnorm(1E5)))
raster.image <- stop_rasterplot(plot=FALSE)
grid::grid.raster(raster.image)
```

produces a plot with 10 million points, but is only 1024 pixels wide
by 1024 pixels tall. (The width is 1024 by default, and the height is
automatically scaled on the basis of the underlying graphics device.)