SCRYDOSBox-XReferenceScreenscreen_viewAlso in MAME

DOSBox-XScreen

screen_view

Read the screen at a stop: its text or 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)

Try it

On Bricks, the game this repository builds, stopped once its play screen is drawn.
Ask

Show me the screen as it is now and save the picture as wall.png.

Call
screen_view(dest="./tmp/demos/tour/files/wall.png")
Reply 8 of 12 fields
{
  "summary": "screen_view M_VGA: 320x200 at [0, 0] pixels; 1280x800 PNG x4, inline",
  "vga_mode": "M_VGA",
  "kind": "pixel",
  "width": 320,
  "height": 200,
  "mode": "render",
  "screen_indexed": true,
  "entries": 256
}

The screen is in the 256-colour mode the debugger names M_VGA, 320x200, drawn through a palette of 256 entries (screen_indexed). The PNG is enlarged 4 times, to 1280x800, and attached.

The whole reply
JSON
{
  "summary": "screen_view M_VGA: 320x200 at [0, 0] pixels; 1280x800 PNG x4, inline",
  "status": "ok",
  "vga_mode": "M_VGA",
  "kind": "pixel",
  "width": 320,
  "height": 200,
  "mode": "render",
  "crop": [0, 0, 320, 200],
  "screen_indexed": true,
  "entries": 256,
  "image": {
    "path": "./tmp/demos/tour/files/wall.png",
    "bytes": "<volatile>",
    "sha256": "<volatile>",
    "width": 1280,
    "height": 800,
    "scale": 4,
    "indexed": true,
    "inline": true
  },
  "display_start": "0h"
}

The four modes

mode what it answers
render The screen: its text in a text mode, else a PNG. In a mode drawn through the 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, 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], in characters in a text mode and in pixels otherwise; 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 or a text mode. 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.

What comes back

text
In a text mode: one string for each row of the crop, as code page 437 draws it, trailing spaces dropped.
cursor
In a text mode: [column, row] inside the crop. Unavailable when the cursor is hidden or outside it.
image
In a graphics mode: 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.
pen
For pixel: the palette index under the point; color is the colour it shows.
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 24 reply fields
  • bbox (array or object)
  • color (string)
  • crop (array)
  • cursor (array or object)
  • display_start (string)
  • entries (integer)
  • height (integer)
  • histogram (array)
  • image (object)
  • isolate_color (string)
  • kind (string)
  • mode (string)
  • pen (integer)
  • pens (array)
  • pens_used (integer)
  • pixels (integer)
  • point_in_crop (array)
  • screen_indexed (boolean)
  • text (array)
  • unused (array)
  • vga_mode (string)
  • width (integer)
  • x (integer)
  • y (integer)

What it refuses

Why it works this way

The screen is read from video memory and never by touching the video card, so reading it does not change it. Text and mode 13h come through the CPU's own view of that memory; planar, unchained and linear modes come from the video RAM, through the debugger's VGAMEMDUMP command.

In a mode drawn through the palette, the PNG's pixels are the bytes the program wrote and its palette is the DAC, so the file is data. A 16-colour pixel goes through the Attribute Controller to its DAC entry; a 15- or 16-bit one is widened to eight bits a component by repeating its high bits.

The views by palette index need a mode drawn through the palette: 256 colours, 16-colour planar or 8-bit linear. Nothing says who set a colour, because the debugger does not log writes to the DAC.

More on why

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.

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.

In protected mode the screen is read through a data segment that covers it: the lowest present one of the GDT, then of the LDT. With paging on, every page must map to the same physical address; otherwise the call is refused (no_channel).

A 256-colour picture, each pixel doubled each way as the emulator draws mode 13h, equals the emulator's own capture. A screen that runs past its memory window is refused, and a picture the disk could not take whole is host_failed.

vga_mode is the video mode as the debugger names it, kind is text or pixel, and display_start is where in video memory the screen begins. screen_indexed and entries come in a graphics mode drawn through the palette.

The contract your client receives
Text
What the screen shows at this stop, read from video memory: text as text, a graphics mode
as a PNG (256 colours chained or not, 16-colour planar, 8-, 15-, 16- or 32-bit linear; all
but chained through `VGAMEMDUMP`). `mode`: `render`, `isolate` (`pens`, 1..64,
in `isolate_color` over grey), `histogram` (pens used, no picture), `pixel` (`point`
`[x, y]`); the last three read a palette-indexed graphics mode, where a pen is the DAC entry
a pixel holds, and no `set_by` is answered. `crop` is `[x, y, width, height]` in characters
or pixels and narrows all but `pixel`. `scale` 0 fits the largest up to 8x; `dest` a new
path (else a scratch); `attach` false leaves it unattached.

Reply: `mode`, `vga_mode`, `kind`, `width`, `height`, `crop`, `display_start`; in text `text`,
`cursor`; in graphics `screen_indexed`, `entries` (indexed) and `image` (not for mode
histogram); `isolate`: `pixels`, `bbox`, `pens`, `isolate_color`; mode histogram: `histogram`,
`pens_used`, `unused`; `pixel`: `x`, `y`, `pen`, `color`, `point_in_crop`.

Refused: a relative or existing `dest`, a bad `scale`, `crop`, `mode`, `pens` or `point`, an
argument the mode ignores, `dest`/`scale`/`attach` in text or `histogram`, a `point` off the
screen (`bad_argument`); another mode or a build without `VGAMEMDUMP` (naming
`capture_frame`), an undecodable layout, or `isolate`/`histogram`/`pixel` on a text or
direct-colour mode (`no_channel`); a running guest (`not_stopped`); a DAC not six-bit
(`unexpected_answer`).

Reference: REFERENCE.md, Media files.
Tools