SCRYMAMEReferenceScreenscreen_viewAlso in DOSBox-X
screen_view
Read the screen at a stop: its picture, the pixels that hold chosen palette indices, the indices in use, or one pixel.
screen_view(mode="render", pens=null, point=null, crop=null, scale=0, dest="", attach=true, seconds=5.0)
Try it
Which palette index does the pixel at 151, 172 hold, and what colour does it show?
screen_view(mode="pixel", point=[151, 172], dest="./tmp/demos/tour/pixel.png"){
"mode": "pixel",
"x": 151,
"y": 172,
"pen": 838,
"color": "#449933",
"entries": 2048,
"crop": [127, 148, 48, 48],
"point_in_crop": [24, 24]
}The pixel holds pen 838, a palette index out of 2048 entries, which shows as #449933. The picture written is the 48-pixel square crop round the point, which sits at its centre.
The whole reply
{
"summary": "screen_view pixel :screen frame 545: (151, 172) is pen 0x346 #449933; no logged write to it: no manifest is loaded: `gfx_load` a gfx.yaml whose `palette_ports` names this palette, then `palette_log(palette_port=..., arm=True)` arms the log ... (290 characters)",
"status": "ok",
"mode": "pixel",
"screen": ":screen",
"width": 256,
"height": 240,
"frame_screen": 545,
"palette": ":palette",
"entries": 2048,
"screen_indexed": true,
"x": 151,
"y": 172,
"pen": 838,
"color": "#449933",
"set_by": {
"available": false,
"why": "no manifest is loaded: `gfx_load` a gfx.yaml whose `palette_ports` names this palette, then `palette_log(palette_port=..., arm=True)` arms the log that answers who set a pen"
},
"crop": [127, 148, 48, 48],
"point_in_crop": [24, 24],
"image": {
"path": "./tmp/demos/tour/pixel.png",
"bytes": "<volatile>",
"sha256": "<volatile>",
"width": 388,
"height": 388,
"scale": 8,
"indexed": false,
"inline": true,
"border": 2
},
"evaluated_by": "one step",
"lines_ahead": 0,
"thread_errors": 0,
"console_reruns": 0,
"call": "MAME_MCP_LUA_END#9",
"pc_before": "0x0000fd82",
"cause": "screen_view: one step",
"stop_seq": 11,
"pc": "0x0000fd84",
"cpu": ":maincpu",
"frame": 545,
"regs": {
"A": "0xbc",
"B": "0x72",
"D": "0xbc72",
"X": "0x0100",
"Y": "0x00f1",
"U": "0xc66d",
"PC": "0xfd84",
"S": "0x07f4",
"CC": "0xf8",
"DP": "0x00"
},
"instruction": {"address": "FD84", "bytes": "8403", "text": "ANDA #$03", "symbol": "irq", "delta": 4},
"following": ["FD86: 26 04 BNE $FD8C", "FD88: 0C B3 INC <$B3", "FD8A: 0C B4 INC <$B4", "FD8C: B6 03 BE LDA $03BE", "FD8F: 26 28 BNE $FDB9", "FD91: F6 95 01 LDB $9501", "... 9 more"],
"errorlog": "<volatile>",
"watches": [
{
"ref": "0xc",
"cpu": ":maincpu",
"state": "captured",
"total": 3,
"callback_errors": {
"count": 0,
"first": {"available": false, "why": "no callback raised"}
},
"since_last_stop": 0
}
],
"omitted": ["addr", "by", "fmt", "frame_as_of", "install_resent", "installed", "... 12 more"],
"how": "`declaration_list(kind=\"watch\")` answers each watch whole: its declaration, the debugger's row for it, and a count's or a capture's tables"
}The four modes
| mode | what it answers |
|---|---|
render |
The screen as a PNG. On a screen drawn through a palette, each pixel of the file is its palette index. |
isolate |
The picture with the palette indices in pens in magenta and every other pixel grey, and how many pixels hold them. |
histogram |
No picture: each palette index in use with how many pixels hold it, and the ranges nothing uses. |
pixel |
The palette index and the colour under point, with a small picture of the pixels round it. |
Arguments
- mode one of
"render","isolate","histogram","pixel", default"render" render,isolate,histogramorpixel, as above. Left out,render.- pens array of integer or string, optional
- For
isolate: the palette indices to show, 1 to 64 of them. A pen is the palette index a pixel holds. - point array of integer, optional
- For
pixel: the pixel to read,[x, y]on the screen. - crop array of integer, optional
- The rectangle to read,
[x, y, width, height]; not forpixel. Left out, the whole screen. - scale integer, default
0 - The whole factor the picture is enlarged by, 1 to 8; not for
histogram. Left at 0, the largest that fits. - dest string, default
"" - A new path for the PNG, absolute or starting with
~. Left empty, the session's temporary folder, deleted atclose. - attach boolean, default
true falsewrites the picture without attaching it to the reply. Left out,true.- 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
- image
- The PNG: its
path,bytes,sha256,width,heightandscale, whether it isindexed, andinlineor the reason innot_inlined. Not forhistogram. - screen_indexed
truewhen the screen is drawn through a palette. The PNG itself is indexed when that palette has at most 256 entries.- pen
- For
pixel: the palette index under the point;coloris the colour it shows. - set_by
- For
pixel: the newest writepalette_logrecorded for that entry, or the reason there is none. - histogram
- For
histogram: one[pen, pixels]pair for each palette index in use.pens_usedcounts them;unusedlists the rest as ranges. - pixels
- For
isolate: how many pixels hold the indices asked for.bboxis the rectangle that holds them all, as[left, top, right, bottom].
All 45 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)bbox(array)call(string)color(string)crop(array)entries(integer)evaluated_by(string)frame_screen(integer)height(integer)histogram(array)image(object)isolate_color(string)lines_ahead(integer)mode(string)palette(string or object)pc_before(string)pen(integer)pens(array)pens_not_restored(array)pens_used(integer)pixels(integer)point_in_crop(array)reader_steps(integer)rows_cut(boolean)same_color_write(object)screen(string)screen_indexed(boolean)screen_type(string)screens(array)set_by(object)unused(array)width(integer)x(integer)y(integer)
What it refuses
- An argument the mode does not take:
pensoutsideisolate,pointoutsidepixel, a picture argument withhistogram(bad_argument). - A
cropor apointoff the screen (bad_argument). isolate,histogramorpixelon a screen drawn in direct colour, which holds no palette index (no_channel).- A machine with no screen, a vector screen, or a palette with
shadowsorhighlightson (no_channel). - A machine with several screens (
ambiguous_ref). - A palette entry that did not read back as saved, or a screen that changed across the read (
readback_refused). - A machine that is running (
not_stopped).
Why it works this way
A colour picture cannot say which palette index a pixel holds, and two entries can share a colour. MAME hands the screen back as colours, so one script saves every palette entry, sets entry i to the colour i, reads the screen and puts every entry back.
No instruction of the program runs inside that script, so the program never sees the changed palette, and the entries go back even when the read fails. The reply is refused, never drawn, when the picture cannot be trusted.
isolate draws the other pixels in greys with no black or white. Dimming would lose a dark entry in a dark screen, and one hue over greys stands out whatever the entry's colour.
More on why
The read costs one instruction of the program, as palette explains, and the reply is also a stop.
- Refused: an index past the palette's entries.
- Refused: a saved entry that is not the colour the screen showed, as under a contrast or gamma setting.
- Refused: an entry that did not read back. It counts as a write to the machine, and
pens_not_restoredlists it. - Refused: a screen that changed across the read.
For pixel, agrees inside set_by says whether the colour that write left is the entry's colour now. When it is not, something other than a port write changed the entry: a driver copying entries itself, a Lua set_pen_color, a loaded state.
The reply then names same_color_write, the newest recorded write that left that colour; rows_cut says whether the log had lost rows.
For pixel the picture is a crop of 48 pixels round the point, in colour, with the point ringed and a border round the crop. point_in_crop is the point inside it.
A refusal names what it found: screens lists the screens of a machine with several, screen_type the kind of a screen that has no pixels to read. frame_screen is the screen's 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
The screen as the pens it holds: each pixel's palette index, recovered exactly.
`mode`: `render`, `isolate` (`pens`, 1..64, in `isolate_color` over grey),
`histogram` (pens used, no picture), `pixel` (`point` `[x, y]`). `crop` `[x, y, width,
height]` narrows all but `pixel`. `scale`: the integer the picture is enlarged by, for
every mode but histogram (enlarged four times is `scale=4`), 0 the largest that fits;
`dest`: a new path it is written to, else the session's scratch;
`attach=false` writes it without attaching it to the reply; `seconds` bounds the read.
Reply: `mode`, `screen`, `width`, `height`, `frame_screen`, `palette`, `entries`,
`screen_indexed`, `crop`, `image` (not for mode histogram); `isolate`: `pixels`, `bbox`,
`pens`, `isolate_color`; mode histogram: `histogram`, `pens_used`, `unused`; `pixel`: `x`,
`y`, `pen`, `color`, `set_by`, `point_in_crop`. `no_channel`: no pens to read, or no screen.
`ambiguous_ref`: several screens. `readback_refused`: a pen did not read back. `bad_argument`:
off the screen.
Reference: REFERENCE.md, Input and the screen.