SCRYMAMEReferenceTimelinegfx_film

MAMETimeline

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

On Gridlee, a free ROM from mamedev.org, stopped in attract mode with the example session's symbols loaded, so credits names the byte that counts coins.
Ask

Keep a picture of every frame in the next 90 where the game writes its credits, two pictures at most.

Call
gfx_film(trigger="credits", frames=90, keep=2, film_dir="./tmp/demos/tour/film")
Reply 4 of 26 fields
{
  "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:

Call
gfx_film()
Reply 5 of 26 fields
{
  "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:

JSON
{
  "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:

JSON
{
  "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, default 1
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 0x string. Not taken with changed.
changed boolean, default false
true counts 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 trigger is 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
true removes 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"
io when trigger is an I/O port. Left out, program, the cpu's memory.

What comes back

armed_now
true on 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: judging while frames are still being checked, then finished. Before any result it is no_dump_yet, install_failed or install_lost, with why.
met
How many of the judged frames held the write. kept counts the pictures kept and refused those that failed their check.
cells
One row per kept frame on this page: k, frame, hits_in_frame, hit_counters, the first hit's pc, symbol and value, and the picture's path.
image
The contact sheet of this page, once a frame is kept. next_first starts 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

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_counters and 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.

The contract your client receives
Text
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.
Tools