SCRYMAMEReferenceCapturesseries_captureAlso in DOSBox-X

MAMECaptures

series_capture

Save chosen frames of the screen as PNGs beside a manifest, for image_compare to read.

series_capture(at_frames=null, first=null, last=null, step=1, crop=null, dest="", seconds=60.0)

Try it

On Gridlee, a free ROM from mamedev.org, stopped at frame 553, as a game begins. The frames asked for must be ahead of the frame the machine is at.
Ask

Keep every eighth frame from 557 to 581 as pictures in a folder named series.

Call
series_capture(first=557, last=581, step=8, dest="./tmp/demos/tour/series", seconds=300)
Reply 8 of 30 fields
{
  "summary": "series_capture: 4 frames 557..581, 3 distinct, manifest ./tm ... (93 characters)",
  "verdict": "ELAPSED",
  "frame_before": 553,
  "frame_after": 583,
  "count": 4,
  "distinct": 3,
  "lost": [],
  "kept_after_close": true
}

Four frames between 557 and 581 were kept, three of them different pictures, and none was lost. ELAPSED means the run reached its end: the machine went from frame 553 to 583.

The whole reply
JSON
{
  "summary": "series_capture: 4 frames 557..581, 3 distinct, manifest ./tmp/demos/tour/series/manifest.json",
  "status": "ok",
  "verdict": "ELAPSED",
  "frame_before": 553,
  "frame_after": 583,
  "emulated_before_s": 9.3604,
  "emulated_after_s": 9.86728,
  "cycles": 633600,
  "polls": 31,
  "cause": "series_capture: one step",
  "stop_seq": 24,
  "pc": "0x0000fd82",
  "cpu": ":maincpu",
  "frame": 583,
  "regs": {
    "A": "0x01",
    "B": "0x10",
    "D": "0x0110",
    "X": "0x0014",
    "Y": "0xf2e6",
    "U": "0x4071",
    "PC": "0xfd82",
    "S": "0x07f4",
    "CC": "0xd0",
    "DP": "0x00"
  },
  "instruction": {"address": "FD82", "bytes": "96B2", "text": "LDA    <$B2", "symbol": "irq", "delta": 2},
  "following": ["FD84: 84 03    ANDA   #$03", "FD86: 26 04    BNE    $FD8C", "FD88: 0C B3    INC    <$B3", "FD8A: 0C B4    INC    <$B4", "FD8C: B6 03 BE LDA    $03BE", "FD8F: 26 28    BNE    $FDB9", "... 9 more"],
  "errorlog": "<volatile>",
  "manifest": "./tmp/demos/tour/series/manifest.json",
  "count": 4,
  "first": 557,
  "last": 581,
  "distinct": 3,
  "crop": [0, 0, 256, 240],
  "lost": [],
  "frames_asked": 4,
  "kept_after_close": true,
  "frame_source": "frame_number",
  "thread_errors": 0,
  "console_reruns": 0
}

Arguments

at_frames array of integer, optional
The frames to keep, as an ascending list of frame numbers. Give this or first and last, never both.
first integer, optional
The first frame of an evenly spaced range, given with last.
last integer, optional
The last frame of the range. A series holds at most 1000 frames.
step integer, default 1
The spacing of the range: every step-th frame from first. Left out, 1.
crop array of integer, optional
The rectangle of the screen each PNG holds, [x, y, width, height]. Left out, the whole screen.
dest string, default ""
A new folder for the series, absolute or starting with ~, which outlives close. Left empty, a folder in the session's temporary folder, deleted at close.
seconds number (> 0, <= 600.0), default 60.0
The time limit of the run, in seconds of your clock. Left out, 60.

What comes back

manifest
The path of the series' manifest, manifest.json; the PNGs sit beside it, named by frame as f000123.png.
count
How many frames were written; first and last are their lowest and highest numbers.
distinct
How many different pictures the series holds. One means nothing changed on screen.
kept_after_close
true when the series is in a dest you named, false when close deletes it.
lost
Frames asked for that the emulator skipped drawing, as [first, last] ranges. They have no picture and are left out.
verdict
How the run ended, as run_for reports it: ELAPSED when every frame ran.
All 29 reply fields
  • console_reruns (integer)
  • cpu (string)
  • following (array of string)
  • instruction (StopInstruction)
  • errorlog (object)
  • frame (integer)
  • pc (string)
  • regs (object)
  • resent (integer)
  • stop_seq (integer)
  • thread_errors (integer)
  • watches (array)
  • emulated_after_s (number or object)
  • emulated_before_s (number or object)
  • count (integer)
  • crop (array)
  • cycles (integer)
  • distinct (integer)
  • first (integer)
  • frame_after (integer)
  • frame_before (integer)
  • frame_source (string)
  • frames_asked (integer)
  • kept_after_close (boolean)
  • last (integer)
  • lost (array)
  • manifest (string)
  • polls (integer)
  • verdict (string)

What it refuses

Why it works this way

Frame numbers are the emulated frame counter, the one run_for(frames=) counts, and every frame asked for must still be ahead. The call runs the program to two frames past the last one and stops there.

Each picture is MAME's own rendering of its frame, in the colours the palette held at the frame's end, read one frame later. A frame the emulator skipped drawing is listed in lost, never filled in.

A series frame is always an RGB PNG, because a series is for comparing what the screen showed. gfx_film may write the same frame as an indexed PNG, so their checksums never match: compare the two with image_compare(method="image").

More on why

The reply is also a stop: it carries verdict and the fields run_for returns, with the readings taken at each stop.

frames_asked is how many frames the call named, and frame_source says what the numbers count: frame_number, the emulated frame counter.

The contract your client receives
Text
Screen frames kept inside MAME as PNGs and a manifest, for `image_compare`. Stops two frames
past the last.

Frames by `run_for`'s counter, all ahead: `at_frames` or `first`, `last`, `step`, at most
1000. `crop` is `[x, y, width, height]`. `dest`: a new absolute or `~`-led
directory, kept after `close`. Needs a stopped machine; `seconds` bounds the read.

Reply: `manifest`, `count`, `first`, `last`, `crop`, `distinct`, `lost`, `kept_after_close`,
`run_for`'s fields. Refused: `bad_argument`, `cut_by_other_stop`.

Reference: REFERENCE.md, Media files.
Tools