SCRYDOSBox-XReferenceReadscreen_map_writeAlso in MAME
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
load reads a file, whether or not the game runs.Load the screen map of Bricks.
screen_map_write(method="load", path="./demos/bricks/bricks-screen-map.json"){
"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
{
"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,loadorsave, 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:indexcompares 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:truereplaces a file already atdest. Left out, an existing file is refused. - pointer object, optional
- For
pointer:{"x": ref, "y": ref, "bytes": 2}, a symbol or aSEG:OFFaddress for each axis.bytesis 1, 2 or 4; left out, 2.
What comes back
- match
add: each region as recorded, with itscropand itssignature, the fingerprint taken from the screen.- replaced
add:truewhen a screen of that name was already added this session.shadows_fileistruewhen the loaded file has one too.- kept
add: readsN saved for promoteonce the map is a candidate thatpromotecan write into your repository's.scry/folder.- screens
loadandsave: how many screens the map holds;controlscounts their named areas.- mode
loadandsave:verifiedwhen a screen is checked each time it is reached,consolidatedwhen 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
- An argument the method does not take.
- A name, rectangle, area, pointer or file that is not well formed, or a rectangle outside the screen (
bad_argument). - An
addwithoutanchorwhen the loaded map isconsolidated, or asaveof one holding a screen with none (bad_argument). - A
pointeron a map loaded with ascaleor amargin(bad_argument). cellsindexin a mode with no palette (15-, 16- or 32-bit colour), or a video modescreen_viewcannot read (no_channel).- A
savewith nothing mapped and no pointer (needs_call).
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.
{"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.
Related tools
The contract your client receives
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.