Desktop Screenshots cheat sheet

This is a function "cheat sheet" for Desktop Screenshots extension by YellowAfterlife. The extension can be acquired from itch.io or GM:Marketplace. For questions/support, use forums (itch.io), or send me an email. A most up-to-date version of this document is always available online.

Click on sections to expand/collapse them.
Quick display controls: Categories · Sections · Everything · Toggle night mode

A global variable indicating whether the DLL has loaded successfully.

A global array containing the bounding box of last capture operation or last successful display_capture_measure call.

Values are stored like so,

0: X
1: Y
2: Width
3: Height

By default (if no successful calls were made yet) the contents are

0: 0
1: 0
2: display_get_width()
3: display_get_height()

Changes capture/measure behaviour.

If set to false (default), the primary display (where the game window would appear) is measured and captured.

If set to true, a region containing all displays is captured.

If multiple displays are being captured and do not cover the entire rectangle, "vacant" parts of the image are left transparent.

Measures the area that would be captured by the next display_capture_buffer / display_capture_surface / display_capture_combined call.

Returns whether the operation succeeded and display_capture_rect was modified. Currently, can only fail if the DLL failed to load or is amiss entirely.

For example,

if (display_capture_measure()) {
    var rect = display_capture_rect;
    show_debug_message(string(rect[0]) + "," + string(rect[1]) + " "
        + string(rect[2]) + "x" + string(rect[3]));
} else show_debug_message("Couldn't measure!");

Measures the area of all available screens.

This returns an array of per-screen data, where each element is in turn an array of information about the specific screen. The contents of the later are as following:

0..3: x,y,width,height of screen
4..7: same, except for screen's workspace area.
(this excludes the taskbar or other "occlusions")
8: bit flags for screen's properties.
According to MSDN, currently only first bit is used, indicating that it's a primary screen.
9: display name.
In majority of cases it's just "DISPLAY<index>"

For example, you could do:

var screens = display_capture_measure_all();
for (var i = 0; i < array_length_1d(screens); i++) {
    var screen = screens[i];
    var msg = screen[9];
    if (screen[8] & 1) msg += " (primary)";
    msg += " " + string(screen[2]) + "x" + string(screen[3])
        + " at " + string(screen[0]) + "," + string(screen[1]);
    show_debug_message(msg);
}

and on a 3-monitor system that might print something like

DISPLAY1 (primary) 1920x1080 at 0,0
DISPLAY2 1920x1080 at -1920,0
DISPLAY3 1600x900 at 1920,180

Captures the primary (or all active, depending on mode) display into a surface.

If out_surface is omitted or does not exist, a new surface is created (if needed).

If the surface is of wrong size, it is resized automatically.

Returns the ID of the resulting (new or reused) surface or -1 in case of error. Currently, can only fail if the DLL failed to load or is amiss entirely.

Creating a surface:

// setup/capture:
surf = display_capture_surface();

// when drawing:
if (surface_exists(surf)) draw_surface(surf, x, y);

Reusing a surface:

// setup:
surf = 1;

// when capturing:
var sf = display_capture_surface(surf);
if (sf != 1) surf = sf;

// when drawing:
if (surface_exists(surf)) draw_surface(surf, x, y);

Same as display_capture_surface but copies screen pixels to a buffer instead. Use this if you need captured data to be persistent so that you can recover it via buffer_set_surface later.

If out_buffer is specified, it is resized (if needed) and overwritten with new data. Otherwise a new buffer is created (if needed).

Returns the ID of the resulting (new or reused) buffer or -1 in case of error. Currently, can only fail if the DLL failed to load or is amiss entirely.

Creating a buffer:

// setup/capture:
buf = display_capture_buffer();
width = display_capture_rect[2];
height = display_capture_rect[3];
surf = 1;

// draw:
if (!surface_exists(surf) && buf != 1) {
    surf = surface_create(width, height);
    buffer_set_surface(buf, surf, 0, 0, 0);
}
if (surface_exists(surf)) draw_surface(surf, x, y);

Reusing a buffer:

// setup:
buf = 1;
surf = 1;

// capture:
var b = display_capture_buffer(buf);
if (b != 1) {
    buf = b;
    width = display_capture_rect[2];
    height = display_capture_rect[3];
}

// draw:
if (!surface_exists(surf) && buf != 1) {
    surf = surface_create(width, height);
    buffer_set_surface(buf, surf, 0, 0, 0);
}
if (surface_exists(surf)) draw_surface(surf, x, y);

Combines display_capture_surface and display_capture_buffer. Use this if you want a surface to draw, but also a buffer copy so that you can later recover it.

out_buffer is required here (but is auto-resized so can be 1-byte-long) out_surface is optional and will be created/resized as with display_capture_surface.

Returns the resulting (new/reused) surface ID or -1 in case of error. Currently, can only fail if the DLL failed to load or is amiss entirely.

Example:

// setup:
buf = buffer_create(1, buffer_grow, 1);
surf = 1;
has_data = false;

// capture:
var sf = display_capture_combined(buf, surf);
if (sf != 1) {
    has_data = true;
    surf = sf;
    width = display_capture_rect[2];
    height = display_capture_rect[3];
}

// draw:
if (!surface_exists(surf) && has_data) {
    surf = surface_create(width, height);
    buffer_set_surface(buf, surf, 0, 0, 0);
}
if (surface_exists(surf)) draw_surface(surf, x, y);

Much like display_capture_surface, but allows you to specify the region to capture.