run_loop.RdCreate a new X11() graphics device and setup event callbacks such
that the user-supplied callback function is run with appropriate
parameters at the specified rate.
run_loop(
user_func,
init_func = NULL,
width = 7,
height = 7,
fps_target = 30,
show_fps = FALSE,
double_buffer = TRUE,
verbose = FALSE
)user-supplied callback function. This function will be
run by the system at the rate specified by fps_target.
At a minimum, this function should accept the ... argument,
but the current full list of allowed arguments is:
event- Event information from the graphics device.
This is NULL when no event occurred, otherwise it is a list
with a type element where:
event$type = 'mouse_down' indicates a mouse button
was clicked. event$button gives the integer
index of the button.
event$type = 'mouse_up' indicates a mouse button
was released. event$button gives the integer
index of the button.
event$type = 'mouse_move' indicates the mouse
was moved. event$button gives the integer
index of the button being pressed
event$type = 'key_press' indicates a key was pressed
on the keyboard. event$str holds the identifier as
to what was pressed as
a string value. Note: this string can be multiple characters because
of how the graphics device treats modifier keys like CTRL,
and arrow keys (UP, LEFT, RIGHT, DOWN). See docs for
grDevices::setGraphicsEventHandlers to learn more.
mouse_x, mouse_y- current location of mouse within window in normalised coordinates in the range [0, 1]. If mouse is not within window, this will be set to the last available coordinates
frame_num- Current frame number (integer)
fps_actual, fps_target- the curent framerate and the framerate specified by the user
dev_width, dev_height- the width and height of the output device in pixels. Note: this does not cope with window resizing
event_env- Experts only! An environment object through which the user can return
values to the framework. Currently supports setting event_env$close to a non-NULL
value to terminate the program. Set event_env$fps_target to change the
FPS of the running app.
...- Catch any other arguments. Note that this is
a required argument in all user_func callback functions
user-supplied function to be run once when the window is first initialised.
e.g. The following init function could be used to set the initial background colour
init_func = function() {grid.rect(gp = gpar(fill='blue'))}.
Default: NULL means no initialisation function is run. The supplied
function should take no arguments.
size of graphics device to open in inches. Default: 7x7 inches
target frames-per-second. If rendering speed surpasses this then slight pauses will be added to each loop to bring this back to the target rate. Set to NA to run as fast as possible. Note that even though the user supplied function might be called at a very high rate, the actual screen update rate may be much much lower.
show the fps as text in the bottom left of the window. Default: FALSE
use a double buffered device? Default: TRUE. A double buffered device is essential if you are updating the display every frame e.g. a game of SuperMario. For more static games e.g Chess, there's no need to double buffer as you are only updating the game when user events occur (like moving a chess piece). Double buffered devices avoid "screen tearing" when rendering, but because of the way R handles the dev.hold/dev.flush operations, the mouse will flicker between a normal pointer and a busy pointer.
Show more debugging information. Default: FALSE
None. This function returns nothing, and only terminates when the user
presses ESC within the window, or some other terminating
condition occurs e.g. an error
if (FALSE) {
if (interactive()) {
my_fun <- function(...) { cat(".") }
run_loop(my_fun)
}
}