# Blitting

Blitting is a term used in computer graphics to describe the copying of whole or part of one image into another.

This copying is optinised for speed and forms a significant part of the underlying mechanics for 2D games and interactive applications. For example:

- putting a players character on the scrolling background in a game
- Assembling a background image from a small library of tiled images
- Placing pre-rendered pieces on a game board

`{nara}` includes two blitting functions:

- `nr_blit()`
  - Blit a single source image at one (or multiple) locations in the destination image.
- `nr_blit_multi()`
  - Define a complex sequence of blitting operations using a data.frame

# `nr_blit()`

Use `nr_blit()` when you want to use a single source image only

### Blit a single image

    library(nara)

    # Create a canvas to draw on
    w <- 300
    h <- 300
    nr <- nr_new(w, h, 'grey90')

    # Place a deer on the canvas
    nr_blit(nr, deer[[1]], w/2, h/2)

    plot(nr)

### Blit a single image to multiple locations

    # Create a canvas to draw on
    nr <- nr_new(w, h, 'grey90')

    # Place a deer on the canvas at many locations
    xs <- runif(20, 0, w)
    ys <- runif(20, 0, h)
    nr_blit(nr, deer[[1]], xs, ys)

    plot(nr)

### Blit a single image to multiple locations with varying angles and scales

    # Create a canvas to draw on
    nr <- nr_new(w, h, 'grey90')

    # Place a deer on the canvas at many locations
    xs <- runif(20, 0, w)
    ys <- runif(20, 0, h)
    angles <- runif(20, 0, 2*pi)
    scales <- runif(20, 0.5, 2)
    nr_blit(nr, deer[[1]], xs, ys, angle = angles, scale = scales)

    plot(nr)

# `nr_blit_multi()`

If you have multiple source images to blit, there are two possible approaches:

- Loop over the images and blit them one-at-a-time with `nr_blit()`
- Set-up a configuration data.frame and blit them all-at-once with `nr_blit_multi()`

For most simple tasks, `nr_blit()` should be sufficient.

For larger structures, it may be useful to store blitting parameters in a data.frame for organisation purposes.

The `{nara}` packages includes a `tileset` (a list of nativerasters which can tile together to form an image) and a `tileset_config` giving one possible arrangement of tiles.

Combining `tileset` with `tileset_config` in `nr_blit_multi()` creates a complex image with a single function call.

    head(tileset_config)
    #>         name   x   y idx hjust vjust
    #> 1     cloud3   0  35   5     0     0
    #> 2     cloud3  35  35   5     0     0
    #> 3     cloud3 700  70   5     0     0
    #> 4  brickWall  70 140   2     0     0
    #> 5 boxItemAlt 140 140   1     0     0
    #> 6  brickWall 420  35   2     0     0

    w <- 70 * 11
    h <- 70 * 8
    nr <- nr_new(w, h, fill = 'lightblue')
    nr_blit_multi(nr, tileset, config = tileset_config)

    plot(nr)

### Blit with a mask

`{nara}` supports masked rendering of most drawing operations.

`blit_mask_begin()` and `blit_mask_end()` are used to delineate the use of a mask on an image.

    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Setup a drawing canvas and an image to use as a mask
    #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    w <- 300
    h <- 300
    canvas <- nr_new(w, h, fill = 'lightblue')
    mask   <- nr_new(w, h, fill = 'transparent')

    # Set the top-left area of the mask to be the active area by making it
    # not transparent
    nr_rect(mask, x=0, y=0, w=w/2, h=h/2)
    plot(mask)

    # Attach the mask to the canvas
    nr_mask_begin(canvas, mask)
    {
      # Draw random deer on the image -
      xs <- runif(50, 0, w)
      ys <- runif(50, 0, h)
      nr_blit(canvas, deer[[1]], xs, ys)
    }
    nr_mask_end(canvas) # Finalise the masked operation

    plot(canvas)