SCRYDOSBox-XReferenceScreenscreen_viewAlso in MAME
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
Show me the screen as it is now and save the picture as wall.png.
screen_view(dest="./tmp/demos/tour/files/wall.png"){
"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
{
"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,histogramorpixel, 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 forpixel. Left out, the whole screen. - scale integer, default
0 - The whole factor the picture is enlarged by, 1 to 8; not for
histogramor 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 atclose. - attach boolean, default
true falsewrites 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,heightandscale, whether it isindexed, andinlineor the reason innot_inlined. Not forhistogram. - pen
- For
pixel: the palette index under the point;coloris the colour it shows. - 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 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
- An argument the mode does not take, or
dest,scaleorattachin a text mode or withhistogram(bad_argument). - A
cropor apointoff the screen, ascaleoutside 0 to 8, or adestthat is relative or exists (bad_argument). isolate,histogramorpixelin a text mode or a direct-colour mode, which hold no palette index (no_channel).- A video mode it does not read, a split screen or panning, or a build whose debugger has no
VGAMEMDUMPcommand for a mode that needs it (no_channel). - A machine that is running (
not_stopped). - A DAC that is not in six-bit mode (
unexpected_answer).
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.
Related tools
The contract your client receives
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.