SCRYMAMEReferenceTimelinegfx_film
gfx_film
Keep a picture of each frame in which a chosen write happened, and read them back as one contact sheet.
gfx_film(trigger="", length=1, value=null, changed=false, pc="", cpu="", frames=600, keep=12, crop=null, film_dir="", first=0, clear=false, seconds=5.0, space="program")
Try it
credits names the byte that counts coins.Keep a picture of every frame in the next 90 where the game writes its credits, two pictures at most.
gfx_film(trigger="credits", frames=90, keep=2, film_dir="./tmp/demos/tour/film"){
"summary": "gfx_film on credits: armed, installed when the console next reads a line",
"armed_now": true,
"installed": false,
"pending": true
}Then, after a coin and those 90 frames, read the film:
gfx_film(){
"summary": "gfx_film on credits: finished, 90 judged, 1 met, 1 kept; 792x864 PNG x3, inline",
"state": "finished",
"judged": 90,
"met": 1,
"kept": 1
}The film waits to be installed, then checks 90 frames (judged). One of them held a write to credits (met), and its picture was kept.
The two replies, whole
The first call's:
{
"summary": "gfx_film on credits: armed, installed when the console next reads a line",
"status": "ok",
"armed_now": true,
"film": {
"trigger": "credits",
"trigger_addr": "0x0000042b",
"length": 1,
"value": {"available": false, "why": "no `value` was given"},
"changed": false,
"pc": {"available": false, "why": "no `pc` was given"},
"pc_addr": {"available": false, "why": "no `pc` was given"},
"cpu": ":maincpu",
"frames": 90,
"keep": 2,
"crop": {"available": false, "why": "no `crop`: the whole screen"},
"film_dir": "./tmp/demos/tour/film",
"screen": ":screen",
"checked": true,
"space": "program"
},
"trigger_maps_to": "memory@0",
"tally_id": "film",
"installed": false,
"pending": true,
"install_call": "MAME_MCP_LUA_END#5",
"install_lines_ahead": 0,
"note": "the film judges from the first whole frame after the install, which runs when the console next reads a line; read it with `gfx_film()`",
"evaluated_by": "one step",
"lines_ahead": 0,
"thread_errors": 0,
"console_reruns": 0,
"call": "MAME_MCP_LUA_END#4",
"pc_before": "0x0000a7d5",
"cause": "gfx_film: one step",
"stop_seq": 6,
"pc": "0x0000a7dd",
"cpu": ":maincpu",
"frame": 419,
"regs": {
"A": "0x00",
"B": "0x00",
"D": "0x0000",
"X": "0x0150",
"Y": "0x00e1",
"U": "0x00e3",
"PC": "0xa7dd",
"S": "0x07fe",
"CC": "0x84",
"DP": "0x00"
},
"instruction": {"address": "A7DD", "bytes": "33A4", "text": "LEAU ,Y", "symbol": "wait_frame", "delta": 428},
"following": ["A7DF: 31 3E LEAY -$2,Y", "A7E1: 11 93 80 CMPU <$80", "A7E4: 26 E6 BNE $A7CC", "A7E6: DE 84 LDU <$84", "A7E8: 31 5E LEAY -$2,U", "A7EA: DC 80 LDD <$80", "... 6 more"],
"errorlog": "<volatile>"
}The second call's:
{
"summary": "gfx_film on credits: finished, 90 judged, 1 met, 1 kept; 792x864 PNG x3, inline",
"status": "ok",
"film": {
"trigger": "credits",
"trigger_addr": "0x0000042b",
"length": 1,
"value": {"available": false, "why": "no `value` was given"},
"changed": false,
"pc": {"available": false, "why": "no `pc` was given"},
"pc_addr": {"available": false, "why": "no `pc` was given"},
"cpu": ":maincpu",
"frames": 90,
"keep": 2,
"crop": {"available": false, "why": "no `crop`: the whole screen"},
"film_dir": "./tmp/demos/tour/film",
"screen": ":screen",
"checked": true,
"space": "program"
},
"tally_id": "film",
"installed": true,
"pending": false,
"cpu": ":maincpu",
"state": "finished",
"frame_as_of": 543,
"superseded": false,
"callback_errors": {
"count": 0,
"first": {"available": false, "why": "no callback raised"}
},
"judged": 90,
"judged_frames": [420, 509],
"met": 1,
"kept": 1,
"refused": 0,
"dropped_total": 0,
"dropped_frames": {"available": false, "why": "no frame was dropped"},
"lost": {},
"pending_picture": false,
"cost": "<volatile>",
"listing_path": "./tmp/demos/tour/film/film.json",
"cells": [
{
"k": 1,
"frame": 425,
"hits_in_frame": 1,
"hit_counters": [425, 425],
"pc": "0x0000b583",
"value": "0x02",
"symbol": "count_coin",
"path": "./tmp/demos/tour/film/frame-1.png"
}
],
"listed": {"first": 0, "count": 1, "of": 1},
"image": {
"path": "./tmp/demos/tour/film/sheet-0.png",
"bytes": "<volatile>",
"sha256": "<volatile>",
"width": 792,
"height": 864,
"scale": 3,
"indexed": false,
"inline": true
},
"animation": {
"path": "./tmp/demos/tour/film/film-anim.png",
"bytes": "<volatile>",
"sha256": "<volatile>",
"frames": 1,
"frame_period_s": 0.016896
}
}Arguments
- trigger string, default
"" - The address or symbol whose write is watched. Giving it arms the film, with the program stopped; left empty, the call reads the film.
- length one of
1,2,4, default1 - How many bytes the write covers: 1, 2 or 4. Left out, 1.
- value integer or string, optional
- Only a write of this value counts: an integer or a
0xstring. Not taken withchanged. - changed boolean, default
false truecounts only a write whose value differs from the one before.- pc string, default
"" - Only a write made from this address or symbol counts.
- cpu string, default
"" - The cpu whose memory
triggeris in. Left empty, the one the debugger is showing. - frames integer, default
600 - How many frames the film checks before it finishes, up to 216000. Left out, 600.
- keep integer, default
12 - How many pictures it keeps, up to 64. Left out, 12.
- crop array of integer, optional
- The rectangle of the screen each picture keeps,
[x, y, width, height]. Left out, the whole screen. - film_dir string, default
"" - A new absolute folder for the film's files. Left empty, a new folder in the session's temporary folder.
- first integer, default
0 - When reading, the first kept frame the sheet shows, counted from 0.
- clear boolean, default
false trueremoves the film. Its files stay.- seconds number (> 0, <= 600.0), default
5.0 - The time limit of the read that arms the film, in seconds. Reading the sheet is not timed.
- space one of
"program","io", default"program" iowhentriggeris an I/O port. Left out,program, the cpu's memory.
What comes back
- armed_now
trueon the call that arms the film. It starts at the first whole frame after it is installed.- film
- What the film was armed with, and
checked: whether each kept frame is compared with MAME's own rendering. - state
- When reading:
judgingwhile frames are still being checked, thenfinished. Before any result it isno_dump_yet,install_failedorinstall_lost, withwhy. - met
- How many of the
judgedframes held the write.keptcounts the pictures kept andrefusedthose that failed their check. - cells
- One row per kept frame on this page:
k,frame,hits_in_frame,hit_counters, the first hit'spc,symbolandvalue, and the picture'spath. - image
- The contact sheet of this page, once a frame is kept.
next_firststarts the next page.
All 57 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)animation(object)armed_now(boolean)baseline_value(string or object)call(string)callback_errors(object)cells(array)cleared(boolean)cost(object)cpus_with_io(array)dropped_frames(array or object)dropped_total(integer)evaluated_by(string)files_kept(string)film(object)frame_as_of(integer)frame_baseline(integer or object)height(integer)image(object)install_call(string)install_lines_ahead(integer)install_resent(integer)installed(boolean)judged(integer)judged_frames(array or object)kept(integer)lines_ahead(integer)listed(object)listing_path(string)lost(object)met(integer)next_first(integer)nothing_kept(string)pc_before(string)pending(boolean)pending_picture(boolean)reader_steps(integer)refused(integer)refused_frames(array)removal(string)state(string)superseded(boolean)tally_id(string)trigger_maps_to(string)why(string)width(integer)
What it refuses
- Arming while the program runs (
not_stopped); reading and clearing need no stop. - A second film while one is armed: one a session (
bad_argument). - A read with no film armed (
needs_call). valuetogether withchanged, or an argument that arming, reading or clearing does not take (bad_argument).- A
triggerwhoselengthbytes cross a bus word: one bus write must cover them (bad_argument). - A
firstpast the kept frames, or acropoff the screen (bad_argument).
Why it works this way
A breakpoint cannot follow a write that happens many times a frame. So the film runs inside MAME at full speed: a hook on the write marks the frame, and at the frame's end only a marked frame has its picture kept.
A register a game writes every frame meets a fixed value on nearly every frame, which records everything and filters nothing. changed is the question a film is usually asked. Its pc filter applies to the write, not to the value it is compared with, and a reset or a state load starts no new comparison.
A write made during vblank belongs to this frame's picture, yet MAME's frame counter still reads the frame before. So each hit keeps the counter it read. A row joins gfx_blits(frame=...) and a capture's rows by hit_counters, never by frame, which names the picture.
More on why
Each picture is read one frame late, at the next frame's end. MAME turns the screen's double buffer over before its frame notifiers run, so one of them reads the frame that ended only after the next turn. That rule says nothing about a read at a debugger stop, which Screen covers.
With frameskip the buffer turns only on a frame that was drawn, so a frame that held the write and was skipped is counted in lost.
Where MAME's snapshot is the bare screen, each kept frame is compared with it pixel for pixel, and one that differs is refused with no picture. refused_frames gives each one's k, code and why.
Elsewhere the film says checked: false, and mismatch measures how the snapshot differed at the stop where the film was armed. It asserts no cause: its candidates names the one its rule leaves standing.
in candidates |
when |
|---|---|
orientation |
a mirrored screen equals the snapshot |
frame_lag |
no mirror, and every differing pixel is in a pen's colour |
colour_adjustment |
each screen colour is drawn as one snapshot colour, no two alike |
overlay_or_artwork |
anything else, and a snapshot of another size, where nothing is compared |
A start does not arm the film again. A film spends its frames and pictures from the moment it is armed, and a new start would spend them on the boot. clear keeps the files, and a later film writes into a folder of its own.
frame-K.png: one per kept frame.film.json: every kept frame with its file,sha256, check,hits_in_frame,hit_countersand first hits, and every refused one with its reason.sheet-F.png: one per page read.film-anim.png: every kept frame as an animation, never attached.
cost is the frame notifier's own host time inside MAME; the hook's cost per write is not in it.
A film whose callbacks raised says so in nothing_kept when it kept no picture: frames that met the condition may not have been marked.
Related tools
The contract your client receives
The frames in which a write happened; one film per session.
Arm (STOPPED): `trigger` (symbol or `0x` on `cpu`; `space` `io` for a port) is a write of
`length` bytes, from `pc`, carrying `value` (an integer or a `0x` string), or with `changed=True` a value
unlike the one before. Judges `frames` (max 216000), keeps `keep` pictures (max
64) cropped to `crop`, into a new absolute `film_dir`.
Read (no `trigger`; works while running): a contact sheet from `first`. `clear=True` clears.
`seconds` bounds the read that arms the film, not the sheet's.
Reply (arm): `film`, `armed_now`. Reply (read): `film`, `state`, `judged`, `met`, `kept` (once
the film has dumped), `cells` (each `frame`, `pc`, `path`), `image` (once frames are kept),
`next_first` (more kept frames remain). `bad_argument`: film armed
already, none to read.
Reference: REFERENCE.md, Input and the screen.