Add Sprite Overlay

Places an image overlay at a pixel location without resizing it to the full destination image. This is intended for sprite-like or billboard-like overlays such as labels, icons, glyphs, and screen-space annotations.

render_sprite_overlay(
  image,
  image_overlay = NULL,
  convert_overlay_colorspace = TRUE,
  alpha = NA,
  overlay_coords = c(1, 1),
  overlay_dims = NULL,
  overlay_anchor = "nw",
  overlay_just = NULL,
  hjust = NULL,
  vjust = NULL,
  preserve_channels = TRUE,
  filename = NULL,
  preview = FALSE
)

Arguments

image

3-layer RGB/4-layer RGBA array, rayimg class, or filename of an image.

image_overlay

Default NULL. 3-layer RGB/4-layer RGBA array, rayimg class, or filename of the sprite overlay.

convert_overlay_colorspace

Default TRUE. Whether to convert the overlay's colorspace to match the underlying image.

alpha

Default NA, using overlay's alpha channel. Otherwise, this sets the alpha transparency by multiplying the existing alpha channel by this value (between 0 and 1).

overlay_coords

Default c(1, 1). Pixel coordinate c(x, y) used to position the overlay. x increases from left to right and y from top to bottom, starting at 1.

overlay_dims

Default NULL. Dimensions for the overlay in pixels. If provided, the overlay is resized with render_resized() before compositing.

overlay_anchor

Default "nw". Which corner of the overlay is placed at overlay_coords when no numeric justification is supplied. Options: "nw", "ne", "sw", "se".

overlay_just

Default NULL. Optional numeric c(hjust, vjust) justification used to place the overlay relative to overlay_coords. If set, the overlay's left/top pixel is computed as round(x - hjust * overlay_width) and round(y - vjust * overlay_height).

hjust

Default NULL. Optional horizontal justification. Overrides the first value of overlay_just.

vjust

Default NULL. Optional vertical justification. Overrides the second value of overlay_just.

preserve_channels

Default TRUE. If TRUE, RGB input images return RGB output and RGBA input images return RGBA output.

filename

Default NULL. File to save the image to. If NULL and preview = FALSE, returns an image array.

preview

Default FALSE. If TRUE, it will display the image in addition to returning it.

Value

A rayimg array.

Examples

dragon_clipped = dragon
dragon_clipped[dragon_clipped > 1] = 1

# Render a transparent dragon emoji and center it on a pixel with hjust/vjust:
dragon_emoji = render_text_image(
 "\U0001F409",
 size = 80,
 background_alpha = 0,
 use_ragg = TRUE,
 trim = TRUE,
 trim_padding = 8
)
render_sprite_overlay(
 dragon_clipped,
 image_overlay = dragon_emoji,
 overlay_coords = c(ncol(dragon_clipped) / 2, nrow(dragon_clipped) / 2),
 hjust = 0.5,
 vjust = 0.5,
 preview = TRUE
)


# The same justification can be supplied as overlay_just = c(hjust, vjust):
render_sprite_overlay(
 dragon_clipped,
 image_overlay = dragon_emoji,
 overlay_coords = c(ncol(dragon_clipped), nrow(dragon_clipped)),
 overlay_just = c(1, 1),
 preview = TRUE
)