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:

`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)