SCRYMAMEReferenceScreengfx_blits
gfx_blits
Show every draw (blit) a board made in one frame as a box over the screen, coloured by the code that issued it.
gfx_blits(draw_command, frame=null, area=null, detail=false, first=0, scale=0, dest="", seconds=5.0)
Try it
0xc, 4 bytes, trigger 0x10) has recorded two frames.Which code drew over the rectangle at (148, 164), 8 by 16 pixels, in frame 545?
gfx_blits(draw_command="player", frame=545, area=[148, 164, 8, 16],
dest="./tmp/demos/tour/blits.png"){
"summary": "gfx_blits player frame 545: 1 of 1 blit covers [148, 164, 8, ... (115 characters)",
"legend": [
{"pc": "0x0000a81f", "symbol": "write_sprites+0x29", "color": "#ff4040", "blits": 1}
],
"topmost": {
"index": 0,
"n": 3,
"pc": "0x0000a81f",
"plane": {"available": false, "why": "the command declares no plane"}
}
}One blit covers the area, issued from write_sprites+0x29, whose boxes are drawn in #ff4040. topmost names it as the likeliest painter; its n is the capture's row, and it has no plane because the command names none.
The whole reply
{
"summary": "gfx_blits player frame 545: 1 of 1 blit covers [148, 164, 8, 16], topmost #0 pc 0x0000a81f; 1024x960 PNG x4, inline",
"status": "ok",
"draw_command": "player",
"frame_blit": 545,
"frame_complete": false,
"rows_cut": false,
"screen": ":screen",
"frame_screen": 545,
"width": 256,
"height": 240,
"rows_path": "<volatile>",
"rows_kept": 3,
"overflow_rows": 0,
"callback_errors": {
"count": 0,
"first": {"available": false, "why": "no callback raised"}
},
"frames_with_blits": {"first": 543, "last": 545, "count": 3},
"blits_in_frame": 1,
"legend": [
{"pc": "0x0000a81f", "symbol": "write_sprites+0x29", "color": "#ff4040", "blits": 1}
],
"colors_repeat": false,
"by_plane": [
{
"plane": {"available": false, "why": "the command declares no plane"},
"page": {"available": false, "why": "the plane is not drawn in pages"},
"blits": 1,
"on_screen": 1
}
],
"area": [148, 164, 8, 16],
"covering": 1,
"topmost": {
"index": 0,
"n": 3,
"pc": "0x0000a81f",
"plane": {"available": false, "why": "the command declares no plane"}
},
"note": "a box COVERS the area; what painted a pixel also needs the source pixels, their transparency and the scale, which the rows do not carry: `topmost` is the last covering blit of the highest plane, the likeliest painter, not a proven one",
"listed": {"first": 0, "count": 1, "of": 1},
"blits": [
{
"index": 0,
"n": 3,
"pc": "0x0000a81f",
"box": {"x": 148, "y": 164, "width": 8, "height": 16, "dir_x": 1, "dir_y": 1},
"plane": {"available": false, "why": "the command declares no plane"},
"screen": [
[148, 164, 8, 16]
],
"on_screen": true,
"clipped": false,
"fields": {"source_tile": 91, "dest_y": 164, "dest_x": 148, "width": 8, "height": 16},
"flags": {},
"symbol": "write_sprites+0x29"
}
],
"not_proved": [],
"image": {
"path": "./tmp/demos/tour/blits.png",
"bytes": "<volatile>",
"sha256": "<volatile>",
"width": 1024,
"height": 960,
"scale": 4,
"indexed": false,
"inline": true
},
"evaluated_by": "one step",
"lines_ahead": 0,
"thread_errors": 0,
"console_reruns": 0,
"call": "MAME_MCP_LUA_END#14",
"pc_before": "0x0000fd8c",
"cause": "gfx_blits: one step",
"stop_seq": 16,
"pc": "0x0000fd8f",
"cpu": ":maincpu",
"frame": 545,
"regs": {
"A": "0x00",
"B": "0x72",
"D": "0x0072",
"X": "0x0100",
"Y": "0x00f1",
"U": "0xc66d",
"PC": "0xfd8f",
"S": "0x07f4",
"CC": "0xf4",
"DP": "0x00"
},
"instruction": {"address": "FD8F", "bytes": "2628", "text": "BNE $FDB9", "symbol": "irq", "delta": 15},
"following": ["FD91: F6 95 01 LDB $9501", "FD94: 1F 98 TFR B,A", "FD96: D0 BD SUBB <$BD", "FD98: C4 0F ANDB #$0F", "FD9A: 85 10 BITA #$10", "FD9C: 26 01 BNE $FD9F", "... 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"
}Arguments
- draw_command string, required
- The name of a draw command in the loaded
gfx.yaml, whose register block a capture watch is recording. - frame integer, optional
- The frame whose blits are shown. Left out, the newest frame before this stop that has any.
- area array of integer, optional
- A rectangle of the screen,
[x, y, width, height]. The reply then lists the blits covering it, in the order drawn. - detail boolean, default
false truelists every blit of the frame, 24 a page.- first integer, default
0 - The first blit of the list to show, for the next page. It needs
areaordetail. - scale integer, default
0 - The whole factor the picture is enlarged by, up to 8. 0 picks the largest that fits.
- dest string, default
"" - A new file the PNG is written to. Left empty, it goes to the session's temporary folder.
- seconds number (> 0, <= 600.0), default
5.0 - The time limit of the read, in seconds.
What comes back
- frame_blit
- The frame shown.
frame_completeisfalsewhen this stop is still inside it or rows were lost. - legend
- One row per writer: its
pc, itssymbol, thecolorof its boxes and how manyblitsit made. - by_plane
- The blits by
planeandpage: how manyblits, and how many areon_screen. - topmost
- With
area, the last covering blit of the highest plane: itsindex,n(the capture's row),pcandplane. - blits
- With
areaordetail, a page of blits:index,n,pc,box,plane,page, thescreenrectangles,on_screen,clipped,fieldsandflags. - not_proved
- The fields and planes of the command this answer relied on whose status in the manifest is not
proved.
All 46 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)area(array)blits(array)blits_in_frame(integer)by_plane(array)call(string)callback_errors(object)colors_repeat(boolean)commands(array)covering(integer)declare(string)draw_command(string)evaluated_by(string)frame_blit(integer)frame_complete(boolean)frame_screen(integer)frames_with_blits(object)height(integer)image(object)legend(array)lines_ahead(integer)listed(object)listed_of(integer)next_first(integer)not_proved(array)overflow_rows(integer)pc_before(string)reader_steps(integer)rows_cut(boolean)rows_kept(integer)rows_path(string)screen(string)tally_id(string)topmost(object)width(integer)
What it refuses
- No manifest loaded (
needs_call), or a command it does not have (unknown_ref). - No capture watch on the command's block;
declaregives thewatch_addcall that sets one (bad_argument). - A capture that was never installed, or one with no rows yet (
bad_argument). - A frame with no blit, or one past the rows the capture kept (
bad_argument). - Captures on two cpus for a command whose
blocknames none (bad_argument). - An
areaoff the screen, or afirstpast the list (bad_argument).
Why it works this way
Covering is not painting. A box says where a blit's destination lands; what painted a pixel also depends on the source pixels, their transparency and any scaling, which the rows do not carry. So topmost is the likeliest painter, not a proven one.
The tool reads rows a capture watch already recorded and never sets one itself: a watch set behind your back would change the run. With none, the refusal gives the watch_add call to make, and the rows start at the next run.
The reply is a summary by default, because every blit of a frame with every field would not fit a reply. Ask for an area or for detail, and page with the same frame: a finished frame's rows do not change.
More on why
A capture keeps its rows in order and drops every row past its limit. Only the last kept frame can have lost some, and it says rows_cut.
A box is the destination rectangle wrapped at its plane's size, moved by the plane's origin read from the same row, and cut to the screen. On a plane drawn in pages each blit names its page; which page the screen shows is not in the rows.
The picture is RGB, the screen's colours with the boxes over them: a view of the data. screen_view gives the pens themselves. A listed blit that covers no pixel says why.
Related tools
The contract your client receives
Who painted this area: every blit of a `frame` from the manifest's `draw_command` capture,
as a box over the screen, one colour per writer pc.
A missing capture is refused, naming the `watch_add`. `frame` defaults to the newest with
blits. A summary by default; `area` `[x, y, width, height]` lists the blits covering it in
drawn order; `detail` lists all, 24 a page from `first`. `scale`: the integer the
picture is enlarged by, 0 the largest that fits; `dest`: a new path it is written to, else
the scratch; `seconds` bounds the read.
Reply: `frame_blit`, `rows_cut`, `blits_in_frame`, `legend`, `by_plane`, `covering`,
`topmost` (with `area`), `listed`, `blits` (with `area` or `detail`), `next_first` (more
blits remain), `not_proved`, `image`. `bad_argument`: no
manifest, capture or rows; a frame without blits or past the rows kept. `unknown_ref`: no
such command.
Reference: REFERENCE.md, Input and the screen.