SCRYMAMEReferenceScreengfx_blits

MAMEScreen

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

On Gridlee, a free ROM from mamedev.org, with the example session's manifest loaded. A capture watch on the player's sprite entry (0xc, 4 bytes, trigger 0x10) has recorded two frames.
Ask

Which code drew over the rectangle at (148, 164), 8 by 16 pixels, in frame 545?

Call
gfx_blits(draw_command="player", frame=545, area=[148, 164, 8, 16],
    dest="./tmp/demos/tour/blits.png")
Reply 3 of 45 fields
{
  "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
JSON
{
  "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
true lists 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 area or detail.
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_complete is false when this stop is still inside it or rows were lost.
legend
One row per writer: its pc, its symbol, the color of its boxes and how many blits it made.
by_plane
The blits by plane and page: how many blits, and how many are on_screen.
topmost
With area, the last covering blit of the highest plane: its index, n (the capture's row), pc and plane.
blits
With area or detail, a page of blits: index, n, pc, box, plane, page, the screen rectangles, on_screen, clipped, fields and flags.
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

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.

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