SCRYDOSBox-XReferenceScreenscreen_signatureAlso in MAME
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
Give me the signature of the SCORE label, the 52 by 8 pixels at the top left of the screen.
screen_signature(crop=[0, 0, 52, 8]){
"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
{
"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
textwhen characters were hashed,pixelwhen 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
- A
cropthat leaves the screen (bad_argument). - A video mode
screen_viewdoes not read, or a build whose debugger has noVGAMEMDUMPcommand for a mode that needs it (no_channel). - A machine that is running (
not_stopped). - A DAC that is not in six-bit mode (
unexpected_answer).
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.
Related tools
The contract your client receives
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.