SCRYDOSBox-XReferenceScreenscreen_signatureAlso in MAME

DOSBox-XScreen

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)

Try it

On Bricks, the game this repository builds, stopped once its play screen is drawn. The rectangle is the word SCORE at the top left.
Ask

Give me the signature of the SCORE label, the 52 by 8 pixels at the top left of the screen.

Call
screen_signature(crop=[0, 0, 52, 8])
Reply 5 of 8 fields
{
  "summary": "screen_signature M_VGA 52x8 at [0, 0]: f38d22147fd6e2bd",
  "signature": "f38d22147fd6e2bd",
  "kind": "pixel",
  "vga_mode": "M_VGA",
  "crop": [0, 0, 52, 8]
}

f38d22147fd6e2bd stands for those 52x8 pixels, hashed by colour (kind pixel). While the label stays unchanged, the same rectangle gives the same 16 characters.

The whole reply
JSON
{
  "summary": "screen_signature M_VGA 52x8 at [0, 0]: f38d22147fd6e2bd",
  "status": "ok",
  "signature": "f38d22147fd6e2bd",
  "kind": "pixel",
  "vga_mode": "M_VGA",
  "width": 320,
  "height": 200,
  "crop": [0, 0, 52, 8]
}

Arguments

crop array of integer, optional
The rectangle to hash, [x, y, width, height], in characters in a text mode and in pixels otherwise. Left out, the whole screen.

What comes back

signature
16 hex characters. Two screens, or two crops of one size, show the same when their signatures are equal.
kind
text when characters were hashed, pixel when pixels were.
crop
The rectangle that was hashed.
vga_mode
The video mode, as the debugger names it.
All 6 reply fields
  • crop (array)
  • height (integer)
  • kind (string)
  • signature (string)
  • vga_mode (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 what the program put in video memory and in the palette, not of what the window drew. An unchanged screen has one signature on any computer.

A character counts by its byte and the two colours its attribute gives it, a pixel by its colour. A palette fade or a recoloured character is a new signature; the cursor's blink is not.

More on why

It reads what screen_view reads. Each row of a series carries a signature in the same format, which Media files sets out.

The signature is BLAKE2b with an 8-byte digest, written as 16 lowercase hex characters. It hashes scry-sig/1|<kind>|<w>x<h>| and then the crop's cells, row by row, w and h being the crop's.

A text cell is its code page 437 byte, then its foreground and background colours as the VGA shows them. Each goes through the Attribute Controller's palette registers (VGA AC), then the DAC. When mode_control bit 7 is set, color-select supplies bits 5 and 4 in place of the register's. With blinking on, mode_control bit 3, the background has three bits and the fourth blinks.

The contract your client receives
Text
One hex string for what is on screen or on `crop` `[x, y, width, height]`: the `scry-sig/1`
signature of a series row (text cells by byte and colours, 256-colour pixels by DAC colour;
no cursor). Reads what `screen_view` reads.

Reply: `signature`, `kind`, `width`, `height`, `crop`, `vga_mode`. Refusals as
`screen_view`, `dest` and `scale` aside.

Reference: REFERENCE.md, Media files.
Tools