SCRYDOSBox-XReferenceCapturessnapshotAlso in MAME

DOSBox-XCaptures

snapshot

Save a still of the screen as it is now to a PNG file.

snapshot(dest="", seconds=10.0)

Try it

On Bricks, the game this repository builds, while the game runs with the mouse holding the paddle.
Ask

Save a picture of the screen as it is now to held.png, without stopping the game.

Call
snapshot(dest="./tmp/demos/tour/files/held.png")
Reply 2 of 6 fields
{
  "route": "guest",
  "path": "./tmp/demos/tour/files/held.png"
}

The route named guest is the way used while the program runs: the picture is taken inside the emulated machine. The file is at path.

The whole reply
JSON
{
  "summary": "<volatile>",
  "status": "ok",
  "route": "guest",
  "path": "./tmp/demos/tour/files/held.png",
  "bytes": "<volatile>",
  "sha256": "<volatile>"
}

Arguments

dest string, default ""
A new path for the PNG, absolute or starting with ~. Left empty, the emulator's capture folder.
seconds number (> 0, <= 600.0), default 10.0
While the program runs: how long to wait for the picture, in seconds. Left out, 10; not used at a stop.

What comes back

path
The PNG.
sha256
The file's SHA-256: the value a line of reference checksums holds for image_compare(method="golden").
route
How the still was taken: guest while the program ran, video_memory at a stop.
All 4 reply fields
  • bytes (integer)
  • path (string)
  • route (string)
  • sha256 (string)

What it refuses

Why it works this way

The still is taken one of two ways, chosen by whether the program runs. While it runs, the input helper inside DOS takes the screenshot, with no window or menu involved.

At a stop no frame is being drawn, so the still is decoded from video memory as screen_view decodes it: unscaled, and without running the machine. A text mode has no picture there; screen_view reads its text.

The running way needs a session started with logfile. Only the log says which input helper is loaded, and an older one would read the command as the Delete key.

The contract your client receives
Text
A still of the screen as a PNG, at `dest` if given (absolute or `~`-led, new). Running: taken
in the guest into the captures directory within `seconds` (`route` `guest`; `wait_expired` when
none appears); refused with no `logfile` or no stub in the log. At a stop: written from video
memory through `screen_view`'s decoder (`route` `video_memory`), unscaled, without running the
machine; a text mode is refused (`no_channel`), and `seconds` is not used.

Reply: `route`, `path`, `bytes`, `sha256`.
Tools