SCRYMAMEReferenceScreenscreen_signatureAlso in DOSBox-X
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
Give me the signature of the screen as it is now, so I can tell later whether it changed.
screen_signature(){
"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
{
"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
- A
cropthat leaves the screen (bad_argument). - A machine with no screen, or a vector screen (
no_channel). - A machine with several screens (
ambiguous_ref). - A machine that is running (
not_stopped).
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.
Related tools
The contract your client receives
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.