SCRYMAMEReferenceScreenscreen_signatureAlso in DOSBox-X

MAMEScreen

screen_signature

Get a short hash of what the screen shows, so two screens can be told the same without comparing pictures.

screen_signature(crop=null, seconds=5.0)

Try it

On Gridlee, a free ROM from mamedev.org, stopped five seconds after power-on, with its attract screen showing.
Ask

Give me the signature of the screen as it is now, so I can tell later whether it changed.

Call
screen_signature()
Reply 4 of 24 fields
{
  "summary": "screen_signature 256x240 at [0, 0]: 0b0a637e5b000571",
  "signature": "0b0a637e5b000571",
  "kind": "pixel",
  "crop": [0, 0, 256, 240]
}

0b0a637e5b000571 stands for the whole 256x240 screen, hashed by the colour of each pixel (kind pixel). The same screen gives the same 16 characters at any later stop.

The whole reply
JSON
{
  "summary": "screen_signature 256x240 at [0, 0]: 0b0a637e5b000571",
  "status": "ok",
  "signature": "0b0a637e5b000571",
  "kind": "pixel",
  "width": 256,
  "height": 240,
  "crop": [0, 0, 256, 240],
  "screen": ":screen",
  "frame_screen": 295,
  "evaluated_by": "one step",
  "lines_ahead": 0,
  "thread_errors": 0,
  "console_reruns": 0,
  "call": "MAME_MCP_LUA_END#2",
  "pc_before": "0x0000a631",
  "cause": "screen_signature: one step",
  "stop_seq": 3,
  "pc": "0x0000a633",
  "cpu": ":maincpu",
  "frame": 295,
  "regs": {
    "A": "0x0a",
    "B": "0x4b",
    "D": "0x0a4b",
    "X": "0xc901",
    "Y": "0xf2e6",
    "U": "0xbef1",
    "PC": "0xa633",
    "S": "0x0800",
    "CC": "0xc4",
    "DP": "0x00"
  },
  "instruction": {"address": "A633", "bytes": "24FC", "text": "BCC    $A631", "symbol": "wait_frame", "delta": 2},
  "following": ["A635: B7 93 80 STA    $9380", "A638: B6 97 00 LDA    $9700", "A63B: 43       COMA", "A63C: 85 20    BITA   #$20", "A63E: 27 03    BEQ    $A643", "A640: 7E F0 00 JMP    $F000", "... 6 more"],
  "errorlog": "<volatile>"
}

Arguments

crop array of integer, optional
The rectangle to hash, [x, y, width, height]. Left out, the whole screen.
seconds number (> 0, <= 600.0), default 5.0
The time limit of the read, in seconds of your clock. Left out, 5.

What comes back

signature
16 hex characters. Two screens, or two crops of one size, show the same when their signatures are equal.
crop
The rectangle that was hashed.
All 24 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)
  • call (string)
  • crop (array)
  • evaluated_by (string)
  • frame_screen (integer)
  • height (integer)
  • kind (string)
  • lines_ahead (integer)
  • pc_before (string)
  • reader_steps (integer)
  • screen (string)
  • signature (string)
  • width (integer)

What it refuses

Why it works this way

The signature answers "is it the same screen" with two strings, never two pictures. A caller that waits for a screen, compares two moments or keeps a reference holds 16 characters, not a PNG.

It is made of the colour each pixel shows, never its palette index, so a palette change is a new signature and two screens that look the same have one. Only a screen map can be told to fingerprint palette indices (screen_map_write).

series_capture writes the same signature for each frame it keeps, so a frame of a series and the screen now compare directly.

More on why

The format is scry-sig/1: BLAKE2b with an 8-byte digest, 16 lowercase hex characters. It covers the text scry-sig/1|pixel|<w>x<h>|, with the crop's size, and then the crop's pixels row by row as RGB.

The read costs one instruction of the program, as palette explains, and the reply is also a stop.

kind is pixel, screen is the screen's MAME tag and frame_screen its own frame number at the read. The fields about MAME's console (evaluated_by, lines_ahead, reader_steps, resent, thread_errors, console_reruns, call) are explained on the Lua page.

The contract your client receives
Text
One hex string for the screen, or its `crop` `[x, y, width, height]`: "same screen?" is two
strings compared; `series_capture` writes it too. `seconds` bounds the read.

Reply: `signature`, `width`, `height`. `bad_argument`: `crop` off the screen. `no_channel`,
`ambiguous_ref`: no or several screens, or a vector one.

Reference: REFERENCE.md, Input and the screen.
Tools