SCRYDOSBox-XReferenceReadscreen_map_writeAlso in MAME

DOSBox-XRead

screen_map_write

Build the screen map, the file that names your program's screens and their areas: add the screen showing, load a file, or save one.

screen_map_write(method, screen="", match=null, controls=null, cells="", anchor="", path="", scale=null, margin=null, dest="", overwrite=null, pointer=null)

Try it

On Bricks, the game this repository builds, at any moment: a load reads a file, whether or not the game runs.
Ask

Load the screen map of Bricks.

Call
screen_map_write(method="load", path="./demos/bricks/bricks-screen-map.json")
Reply 5 of 7 fields
{
  "summary": "screen_map_write load: 1 screen, 1 control of bricks",
  "application": "bricks",
  "mode": "verified",
  "screens": 1,
  "controls": 1
}

The map of bricks holds one screen and one named area. Its mode is verified: a screen is checked each time it is reached.

The whole reply
JSON
{
  "summary": "screen_map_write load: 1 screen, 1 control of bricks",
  "status": "ok",
  "path": "./demos/bricks/bricks-screen-map.json",
  "application": "bricks",
  "mode": "verified",
  "screens": 1,
  "controls": 1
}

The four methods

method what it does
add Records the screen showing now under a name, with the regions that identify it and its named areas. Needs the program stopped.
pointer Says where the program keeps its own mouse pointer, so a move can be checked against it. Works while the program runs.
load Reads a map file; nothing is written to disk. Works while the program runs.
save Writes the loaded map and the screens added since as one file, which becomes the loaded map. Works while the program runs.

Arguments

method one of "add", "pointer", "load", "save", required
add, pointer, load or save, as above.
screen string, default ""
For add: the name the screen is recorded under.
match array of array of integer, optional
For add: 1 to 16 rectangles [x, y, width, height] that always look the same on this screen. They are what identifies it.
controls array of object, optional
For add: the screen's named areas, each {"name", "rect"}. Left out, none.
cells one of "", "rgb", "index", default ""
For add: index compares palette indices, not the colours shown, so one map serves a program shown through two palettes. Left out, rgb.
anchor string, default ""
For add: a symbol or an address the program reaches once the screen is fully drawn. run_to(screen=) runs to it.
path string, default ""
For load: the map file, named <application>-screen-map.json, as an absolute or ~-led path.
scale integer, optional
For load: how many times larger this machine shows the program's picture, 1 to 8. Left out, 1.
margin array of integer, optional
For load: [x, y], the border in machine pixels on each side of the program's picture. Left out, none.
dest string, default ""
For save: the file to write, named <application>-screen-map.json, as an absolute or ~-led path.
overwrite boolean, optional
For save: true replaces a file already at dest. Left out, an existing file is refused.
pointer object, optional
For pointer: {"x": ref, "y": ref, "bytes": 2}, a symbol or a SEG:OFF address for each axis. bytes is 1, 2 or 4; left out, 2.

What comes back

match
add: each region as recorded, with its crop and its signature, the fingerprint taken from the screen.
replaced
add: true when a screen of that name was already added this session. shadows_file is true when the loaded file has one too.
kept
add: reads N saved for promote once the map is a candidate that promote can write into your repository's .scry/ folder.
screens
load and save: how many screens the map holds; controls counts their named areas.
mode
load and save: verified when a screen is checked each time it is reached, consolidated when it is trusted without a check.
promoted
save: the names of the screens added this session that the file now holds.
All 16 reply fields
  • anchor (string)
  • application (string)
  • cells (string)
  • controls (integer)
  • kind (string)
  • kept (string)
  • match (array)
  • mode (string)
  • path (string)
  • pointer (object)
  • promoted (array)
  • replaced (boolean)
  • screen (string)
  • screens (integer)
  • shadows_file (boolean)
  • size (array)

What it refuses

Why it works this way

A screen is recognised by a few regions that never change, not by the whole picture: a cursor or a moving ball would change a fingerprint of the whole screen.

The map has two layers. Screens you add live in the session and win over a loaded file's screen of the same name; save writes both as one file. A new start empties the session layer and keeps the file.

A map's mode says who keeps it true. In a verified map, run_to(screen=) checks the screen's regions on reaching it and refuses a map that no longer matches (stale_map). In a consolidated map the screen is trusted at its anchor, which lets one map serve two versions of a program whose pixels differ.

More on why

The mode is the file's own: save keeps the loaded map's, and writes verified when none was loaded. screen_map_find checks the regions in either mode.

Rectangles are in the program's units: character cells in a text mode, pixels in a graphics mode. With scale and margin, this machine's picture is the program's size times the scale, plus the margin on each side. A read is sampled back to the program's size before it is compared.

A map file is kept in the program's repository, as .scry/maps/<application>-screen-map.json, and looks like this.

JSON
{"format": "scry-screen-map/1", "application": "bricks", "mode": "verified",
 "screens": [{"name": "play", "kind": "pixel", "size": [320, 200], "anchor": "main_loop",
              "match": [{"crop": [0, 0, 52, 8], "signature": "<16 hex>"}],
              "controls": [{"name": "court", "rect": [200, 80, 80, 40]}]}]}

A program that keeps a mouse pointer of its own and clamps it drifts from the mouse driver's. With pointer given, send_mouse reads the program's pointer back and corrects until it is where it was asked to be. A save keeps the pointer, and a load replaces it.

In the replay test perform_export writes, load and add are replayed as steps and screen_map_find becomes a check of what it matched. A save is left out, since a replay would find its file there.

The contract your client receives
Text
The screen map: an application's screens, each known by the signatures of its stable regions, and their controls, in a session layer and a file layer.

`add`: the screen shown now as `screen` in the session layer, one read signing each `match` crop ([x, y, width, height], 1..16), `controls` ([{"name", "rect"}]) in the screen's own units; needs the machine stopped. Reply: `screen`, `kind`, `size`, `cells`, `match`, `controls`, `replaced`, `shadows_file`, `anchor` (when given), `kept` (a complete map is kept for `promote`).

`pointer`: the program's own pointer as an object, `{"x": ref, "y": ref, "bytes": 2}` (a symbol or
`SEG:OFF` for each axis; `bytes` 1, 2 or 4), as a map file declares it; kept by `save`, replaced by a `load`; a misshapen object is `bad_argument`. Reply: `pointer`.

`add`'s `cells` `index` (a pixel screen; default
`rgb`) signs the palette indices drawn, not the colours shown, so one map knows a program
shown through two palettes; a screen with no palette refuses it (`no_channel`).

`add`'s `anchor` (a symbol or an address, as `run_to`'s `ref`) is the place after which the screen is whole,
what `run_to(screen=)` runs to: a consolidated map refuses an `add` without one (`bad_argument`),
since it enters its screens by theirs.

`load`: `path` (`<application>-screen-map.json`, absolute or `~`-led) as the file layer, held by the
server; nothing is written to disk. `scale` (1..8) and `margin` [x, y] (machine pixels on
each side) say how the program's picture sits on this machine's screen; maps and `add`'s
crops are in the program's units. Reply: `path`, `application`, `mode`, `screens`, `controls`, `pointer`
(a map that declares the program's pointer).

`save`: both layers as one map to `dest`, refused there without `overwrite`, made the file
layer, in the loaded map's `mode` (`verified` when none was loaded). Reply: `path`,
`application`, `mode`, `screens`, `controls`, `promoted`.

Refused: an argument the method does not take; a misshapen name, crop, control, view or file; an `add` without an `anchor` to a consolidated map, and a save of one holding a screen with none (`bad_argument`); neither a screen nor a `pointer` to save (`needs_call`); the modes `screen_view` refuses.

Reference: REFERENCE.md, Screen maps.
Tools