SCRYMAMEReferenceScreengfx_blit_source
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
Show me the graphics the first blit of the newest frame reads from its source.
gfx_blit_source(draw_command="blit", index=0){
"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
{
"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 forgfx_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_blitslists it. Give this orpc. - 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, thex,y,widthandheightinside it, and the directionsdir_xanddir_y. - image
- The picture. With a
marginit 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
falsewhen 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
- Whatever
gfx_blitsrefuses of the manifest, the capture or the frame. - A command with no
asset, or without thesource_xandsource_yroles (bad_argument). - Both
indexandpc, or neither (bad_argument). - A
pcthat issued no blit in the frame, or several;indexeslists them (bad_argument). - A tile past the asset's block, or a rectangle that leaves a tile whose asset does not wrap (
bad_argument). - A
pcsymbol the session does not know (unknown_ref).
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.
Related tools
The contract your client receives
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.