% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/render_image_overlay.R
\name{render_sprite_overlay}
\alias{render_sprite_overlay}
\title{Add Sprite Overlay}
\usage{
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{
\item{image}{3-layer RGB/4-layer RGBA array, \code{rayimg} class, or filename of an image.}

\item{image_overlay}{Default \code{NULL}. 3-layer RGB/4-layer RGBA array, \code{rayimg}
class, or filename of the sprite overlay.}

\item{convert_overlay_colorspace}{Default \code{TRUE}. Whether to convert the overlay's colorspace
to match the underlying image.}

\item{alpha}{Default \code{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).}

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

\item{overlay_dims}{Default \code{NULL}. Dimensions for the overlay in pixels. If
provided, the overlay is resized with \code{render_resized()} before compositing.}

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

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

\item{hjust}{Default \code{NULL}. Optional horizontal justification. Overrides the
first value of \code{overlay_just}.}

\item{vjust}{Default \code{NULL}. Optional vertical justification. Overrides the
second value of \code{overlay_just}.}

\item{preserve_channels}{Default \code{TRUE}. If \code{TRUE}, RGB input images return
RGB output and RGBA input images return RGBA output.}

\item{filename}{Default \code{NULL}. File to save the image to. If \code{NULL} and
\code{preview = FALSE}, returns an image array.}

\item{preview}{Default \code{FALSE}. If \code{TRUE}, it will display the image in addition
to returning it.}
}
\value{
A \code{rayimg} array.
}
\description{
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.
}
\examples{
\dontshow{if (interactive() || identical(Sys.getenv("IN_PKGDOWN"), "true")) withAutoprint(\{ # examplesIf}
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
)
\dontshow{\}) # examplesIf}
}
