SCRYMAMEReferenceScreengfx_locate
gfx_locate
Find which tile of a block is drawn in a patch of the screen, and so prove the tile format against the picture.
gfx_locate(layouts, patch, tag="", ref="", offset=0, first=0, count=0, transparent=null, flips=null, cpu="", seconds=5.0)
Try it
gfx_sweep of the region gfx1 has given the id s1c1.Which tile of the graphics ROM is the sprite at (148, 164) on screen, 8 by 16 pixels, with value 0 transparent?
gfx_locate(layouts=["s1c1"], patch=[148, 164, 8, 16], tag="gfx1", transparent=0){
"summary": "gfx_locate region :gfx1 for patch [148, 164, 8, 16]: 1 match ... (101 characters)",
"matched": true,
"matches_total": 1,
"ambiguous": false,
"evidence": {"locate": 1}
}One tile of the region equals the window on screen, and nothing else matched it (ambiguous). Which tile, with its flip and its palette base, is in matches, in the whole reply below.
The whole reply
{
"summary": "gfx_locate region :gfx1 for patch [148, 164, 8, 16]: 1 match, first s1c1 tile 91 flip none base 0x340",
"status": "ok",
"patch": [148, 164, 8, 16],
"screen": ":screen",
"frame_screen": 545,
"palette": ":palette",
"kind": "region",
"tag": ":gfx1",
"size": 16384,
"bytewidth": 1,
"endianness": "little",
"offset": "0x00000000",
"transparent": 0,
"flips": ["none", "x", "y", "xy"],
"candidates": [
{
"layout": {
"name": "s1c1",
"width": 8,
"height": 16,
"planes": 4,
"planeoffset": [0, 1, 2, 3],
"xoffset": [0, 4, 8, 12, 16, 20, "... 2 more"],
"yoffset": [0, 32, 64, 96, 128, 160, "... 10 more"],
"charincrement": 512
},
"tiles_searched": [0, 256],
"windows": 1,
"windows_uniform": 0,
"windows_mixed_bank": 0,
"matches": 1,
"tiles_available": 256
}
],
"matched": true,
"matches_total": 1,
"matches": [
{
"layout": "s1c1",
"window": [148, 164],
"tile": 91,
"flip": "none",
"base": 832,
"bit": 46592,
"byte": 5824,
"compared": 78,
"shape": [16, 8, 1],
"ambiguous": false
}
],
"ambiguous": false,
"ambiguous_windows": 0,
"pen_map": {"available": false, "why": "the single-bank search matched, so no pen map was tried"},
"evidence": {"locate": 1},
"evaluated_by": "one step",
"lines_ahead": 0,
"thread_errors": 0,
"console_reruns": 0,
"call": "MAME_MCP_LUA_END#12",
"pc_before": "0x0000fd88",
"cause": "gfx_locate: one step",
"stop_seq": 14,
"pc": "0x0000fd8a",
"cpu": ":maincpu",
"frame": 545,
"regs": {
"A": "0x00",
"B": "0x72",
"D": "0x0072",
"X": "0x0100",
"Y": "0x00f1",
"U": "0xc66d",
"PC": "0xfd8a",
"S": "0x07f4",
"CC": "0xf8",
"DP": "0x00"
},
"instruction": {"address": "FD8A", "bytes": "0CB4", "text": "INC <$B4", "symbol": "irq", "delta": 10},
"following": ["FD8C: B6 03 BE LDA $03BE", "FD8F: 26 28 BNE $FDB9", "FD91: F6 95 01 LDB $9501", "FD94: 1F 98 TFR B,A", "FD96: D0 BD SUBB <$BD", "FD98: C4 0F ANDB #$0F", "... 8 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
- layouts array of object or string, required
- A list of 1 to 8 formats to try, a list even for one. Each is a
gfx_viewlayout or agfx_sweepcandidate's id such ass1c3. - patch array of integer, required
- The rectangle of the screen to search,
[x, y, width, height]. It must hold a whole tile. - tag string, default
"" - The memory region or share whose tiles are searched. Give this or
ref. - ref string, default
"" - An address or symbol where tile 0 starts, instead of
tag. It needscount. - offset integer or string, default
0 - Bytes into the
tagblock where tile 0 starts: an integer or a0xstring. - first integer, default
0 - The index of the first tile tried. Left out, 0.
- count integer, default
0 - How many tiles are tried, up to 65536. 0 tries every tile the block holds.
- transparent integer or string, optional
- A pixel value left out of the comparison, as for a sprite over a background. Left out, every pixel is compared.
- flips array of one of
"none","x","y","xy", optional - The flips tried, from
none,x,yandxy. Left out, all four. - cpu string, default
"" - The cpu whose memory
refis in. Left empty, the one the debugger is showing. - seconds number (> 0, <= 600.0), default
5.0 - The time limit of reading the screen and the block, in seconds. The search itself is not timed.
What comes back
- matched
truewhen a tile equals a window of the patch pixel for pixel.matches_totalcounts the matches.- matches
- The first 32, each with
layout,window,tile,flip,base,bit,byte,compared,shapeand its ownambiguous. - ambiguous
truewhen more than one tile or flip matched the same window.ambiguous_windowscounts such windows.- pen_map
- Whether the second search ran (
tried) and itsmatches, orwhyit did not. - nearest
- With no match, the closest miss:
layout,window,tile,flip,disagreepixels out ofof, the firstpixelsthat differ,is_a_matchandcomplete. - candidates
- One row per layout:
layout,tiles_searched,tiles_available,windows,windows_uniform,windows_mixed_bank,matchesandpen_map_matches.
All 47 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)addr(string)addr_cpu(string)ambiguous(boolean)ambiguous_windows(integer)bytewidth(integer)call(string)candidates(array)endianness(string)evaluated_by(string)evidence(object)flips(array)frame_screen(integer)height(integer)kind(string)lines_ahead(integer)matched(boolean)matches(array)matches_total(integer)nearest(object)offset(string)palette(string)patch(array)pc_before(string)pen_map(object)pending(boolean)reader_steps(integer)screen(string)screen_type(string)screens(array)seen_bytes(integer)size(integer)tag(string)tiles_available(integer)transparent(integer or object)width(integer)
What it refuses
- A
patchthat leaves the screen or holds no whole tile of any layout (bad_argument). - A search larger than one call does, or a pattern repeated so often that its matches tell nothing apart (
bad_argument). - A screen drawn in direct colour, which holds no pens to search for (
no_channel). - Whatever
gfx_viewrefuses of a layout or oftag,ref,offsetandcpu.
Why it works this way
gfx_view draws bytes in a format you state, and nothing there says the format is right. A match here does: a tile whose pixels are exactly the pens on screen proves the format, where the tile sits in the block and its palette bank together. Each pixel must equal base plus the tile's value, exactly.
A window is a tile-sized rectangle of the patch, named by its top-left corner, and every one is tried against every tile. A window of one pen matches every blank tile, so it is counted and skipped. With one bit a pixel, sparse or symmetric glyphs match more than the tile drawn there, hence ambiguous and flips.
Nothing is ranked. Each answer is kept for gfx_draft, and evidence gives its number in the session's record. shape is the window's distinct rows, distinct columns and rarest pen's pixels, by which gfx_draft rules out a chance match.
More on why
A board can draw a tile's ink and paper from two palette banks, or show one value in two pens, and then no window is base plus value. So when the first search matches nothing, a second tries a table from each pen of the window to the value it stands for.
That table must give each pen one value and read at least two, since a tile of one value proves nothing. Its match proves the format and the tile, never the palette bank: it carries pen_map and no base.
With transparent, a match needs two different values among the pixels compared. A one-bit tile has one, so it matches only through the pen table, and proves its shape only when the ink's pens appear nowhere among the pixels left out.
nearest goes by the smallest share of disagreeing pixels, never their count, which would favour the smallest tile. Each of its pixels is [x, y, screen pen, decoded value].
Related tools
The contract your client receives
Search a screen `patch` `[x, y, width, height]` for a block's tiles under `layouts`, a list
of 1..8 (plural even for one), each a `gfx_view` layout or a `gfx_sweep`
id (`s1c3`).
Tiles `first`.. (`count` 1..65536, 0 all) are tried under `flips` (absent: all
four). `transparent` leaves a pixel value out. `cpu`: whose address space, the visible one
when empty; `seconds` bounds the capture read, not the search. Source as `gfx_view` (`tag`,
`ref`, `offset`:
an integer or a `0x` string).
Reply: `candidates`, `matched`, `matches_total`, `matches` (first 32:
`layout`, `window`, `tile`, `flip`, `base`, `shape`), `ambiguous`, `pen_map`, `nearest`
(nothing matched), `evidence`. `bad_argument`: a patch off the screen or without a whole tile,
past a bound; else `gfx_view`'s.
Reference: REFERENCE.md, Input and the screen.