SCRYMAMEReferenceScreengfx_blit_source

MAMEScreen

gfx_blit_source

Show the rectangle of graphics one blit reads, decoded from the command's asset with the live palette, always unscaled.

gfx_blit_source(draw_command, frame=null, index=null, pc="", margin=0, scale=0, dest="", seconds=5.0)

Try it

This tool needs a board whose draw command states where in the source each blit reads; neither free program has one. The reply shown comes from a test program that is not distributed.
Ask

Show me the graphics the first blit of the newest frame reads from its source.

Call
gfx_blit_source(draw_command="blit", index=0)
Reply 4 of 41 fields
{
  "summary": "gfx_blit_source blit frame 6 #0 pc 0x00002738: pages tile 0  ... (93 characters)",
  "rect": {"tile": 0, "x": 22, "y": 11, "width": 2, "height": 1, "dir_x": 1, "dir_y": 1},
  "wrap": true,
  "reads_source": true
}

The first blit of frame 6 reads a 2 by 1 rectangle at (22, 11) of tile 0 of the asset pages. reads_source is true: the manifest says this blit does read its source.

The whole reply
JSON
{
  "summary": "gfx_blit_source blit frame 6 #0 pc 0x00002738: pages tile 0 (22, 11) 2x1; 16x8 PNG x8, inline",
  "status": "ok",
  "draw_command": "blit",
  "frame_blit": 6,
  "index": 0,
  "n": 5,
  "blit_pc": "0x00002738",
  "blit_symbol": "boot_init+0x15c",
  "callback_errors": {
    "count": 0,
    "first": {"available": false, "why": "no callback raised"}
  },
  "asset": "pages",
  "tag": ":gfx1",
  "format": "page_512x512x8",
  "palette": ":palette",
  "pen_base": 0,
  "rect": {"tile": 0, "x": 22, "y": 11, "width": 2, "height": 1, "dir_x": 1, "dir_y": 1},
  "margin": 0,
  "box": [0, 0, 2, 1],
  "wrap": true,
  "destination": {"x": 0, "y": 0, "width": 2, "height": 1, "dir_x": 1, "dir_y": 1},
  "note": "shown unscaled: the rectangle is the destination walk's size from the source origin; a scaled blit reads another extent, which is the project's scale law and is not applied here",
  "not_proved": ["dest_x", "source_dir_y", "source_x", "source_y", "planes.sprites", "planes.background"],
  "reads_source": true,
  "image": {
    "path": "$TMPDIR/mame-mcp-<run>/gfx/source-1.png",
    "bytes": "<volatile>",
    "sha256": "<volatile>",
    "width": 16,
    "height": 8,
    "scale": 8,
    "indexed": true,
    "inline": true
  },
  "evaluated_by": "one step",
  "lines_ahead": 0,
  "thread_errors": 0,
  "console_reruns": 0,
  "call": "MAME_MCP_LUA_END#13",
  "pc_before": "0x000027ac",
  "cause": "gfx_blit_source: one step",
  "stop_seq": 14,
  "pc": "0x000027ac",
  "cpu": ":maincpu",
  "frame": 8,
  "regs": {
    "D0": "0x0103a923",
    "D1": "0x00000000",
    "D2": "0x00000000",
    "D3": "0x00000000",
    "D4": "0x00000000",
    "D5": "0x00000000",
    "D6": "0x00000000",
    "D7": "0x00000000",
    "A0": "0x00004842",
    "A1": "0x000f27de",
    "A2": "0x00720003",
    "A3": "0x00000000",
    "A4": "0x00000000",
    "A5": "0x00000000",
    "FP": "0x00000000",
    "SP": "0x00200fc4",
    "PS": "0x2708",
    "PC": "0x000027ac"
  },
  "instruction": {
    "address": "0027AC",
    "bytes": "51C8FFFE",
    "text": "dbra    D0, $27ac",
    "symbol": "boot_init",
    "delta": 464
  },
  "following": ["0027B0: 33FC 0000 0070 0000 move.w  #$0, $700000.l", "0027B8: 33FC 0000 0070 0004 move.w  #$0, $700004.l", "0027C0: 33FC 0000 0070 000C move.w  #$0, $70000c.l", "0027C8: 33FC 000F 0070 000E move.w  #$f, $70000e.l"],
  "errorlog": {"lines_total": 0, "truncated": false, "lines": [], "mark": 14},
  "watches": [
    {
      "ref": "0x700000",
      "cpu": ":maincpu",
      "state": "captured",
      "total": 7,
      "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, as for gfx_blits.
frame integer, optional
The frame the blit belongs to. Left out, the newest frame before this stop that has blits.
index integer, optional
The blit's order in its frame, as gfx_blits lists it. Give this or pc.
pc string, default ""
The address or symbol of the code that issued the blit, instead of index. It must have issued one blit in the frame.
margin integer (>= 0, <= 16), default 0
Pixels of context shown round the rectangle, 0 to 16, dimmed. Left out, none.
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

rect
What the blit reads: the tile, the x, y, width and height inside it, and the directions dir_x and dir_y.
image
The picture. With a margin it is a view: the context dimmed, the rectangle ringed in white.
data
With a margin, the exact indexed PNG of the whole window, each pixel its value.
box
Where the rectangle sits inside the picture: [x, y, width, height].
reads_source
false when the manifest says this blit reads no source. The rectangle is then where its registers point, not what it drew.
not_proved
The command's fields 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)
  • asset (string)
  • blit_pc (string)
  • blit_symbol (string)
  • blits_in_frame (integer)
  • box (array)
  • call (string)
  • callback_errors (object)
  • data (object)
  • destination (object)
  • draw_command (string)
  • entries (integer)
  • evaluated_by (string)
  • format (string)
  • frame_blit (integer)
  • image (object)
  • index (integer)
  • indexes (array)
  • lines_ahead (integer)
  • margin (integer)
  • n (integer)
  • not_proved (array)
  • palette (string)
  • palettes (array)
  • pc_before (string)
  • pen_base (integer)
  • reader_steps (integer)
  • reads_source (boolean)
  • rect (object)
  • source_tile (integer)
  • tag (string)
  • tile_height (integer)
  • tile_width (integer)
  • tiles_available (integer)
  • wrap (boolean)

What it refuses

Why it works this way

The picture is unscaled on purpose. A blit drawn enlarged or shrunk reads another extent of the source, and how a board scales is that project's rule, which is not applied here. The rectangle is the size of the destination, taken from the source origin.

A margin is dimmed because, drawn like the rectangle, its pixels would read as part of the blit: an offset that does not exist. That view is RGB, since an indexed file cannot dim a pen without a second palette entry, which a board using all 256 pens does not have.

More on why

The rectangle is decoded with the tile's own layout, its offsets narrowed to the rectangle, which is exact for every layout MAME's layout terms can state. The origin carries each field's add from the manifest, and the rectangle wraps inside the tile when the asset says wrap.

The contract your client receives
Text
The rectangle one blit reads, decoded from the manifest command's `asset` under the live
palette. Always unscaled: no zoom or scale register is applied, so it never shows the blit as
it lands on screen.

The blit: `frame` (as `gfx_blits`) and `index`, or `pc` (the writer; refused when it fired
more than once). `draw_command` is the name of a `gfx_blits` capture. `margin`
(0..16) dims pixels round the rectangle: `image` is that view, `data` the
exact indexed PNG. `dest`: a new path the picture is written to, else the scratch;
`seconds` bounds the read.

Reply: `frame_blit`, `index`, `blit_pc`, `asset`, `format`, `palette`, `rect` (`tile`, `x`,
`y`, `width`, `height`), `margin`, `box`, `wrap`, `not_proved`, `reads_source`, `image`,
`data` (with `margin` above 0). `bad_argument`: `gfx_blits`'s, no `asset`, a tile or rectangle
past its bounds, a pc that fired none or several. `unknown_ref`: an unknown symbol.

Reference: REFERENCE.md, Input and the screen.
Tools