SCRYMAMEReferenceScreenscreen_viewAlso in DOSBox-X

MAMEScreen

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

On Gridlee, a free ROM from mamedev.org, stopped while its attract mode plays. The point is a pixel of the player's sprite at that stop; any point of the 256x240 screen can be asked.
Ask

Which palette index does the pixel at 151, 172 hold, and what colour does it show?

Call
screen_view(mode="pixel", point=[151, 172], dest="./tmp/demos/tour/pixel.png")
Reply 8 of 36 fields
{
  "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
JSON
{
  "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, histogram or pixel, 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 for pixel. 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 at close.
attach boolean, default true
false writes 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, height and scale, whether it is indexed, and inline or the reason in not_inlined. Not for histogram.
screen_indexed
true when 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; color is the colour it shows.
set_by
For pixel: the newest write palette_log recorded for that entry, or the reason there is none.
histogram
For histogram: one [pen, pixels] pair for each palette index in use. pens_used counts them; unused lists the rest as ranges.
pixels
For isolate: how many pixels hold the indices asked for. bbox is 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

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_restored lists 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.

The contract your client receives
Text
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.
Tools