SCRYMAMEReferenceScreengfx_sweep
gfx_sweep
Draw a block of unknown format under a set of candidate layouts on one labelled sheet, to pick the one that looks like graphics.
gfx_sweep(tag="", ref="", offset=0, count=32, planes=null, sizes=null, palette="none", pen_base=0, scale=0, dest="", cpu="", seconds=5.0)
Try it
gfx1 is the region that holds its sprites.I don't know the format of Gridlee's sprite ROM: draw its first 16 tiles as 4-bit 8 by 16 candidates on one sheet.
gfx_sweep(tag="gfx1", planes=[4], sizes=[[8, 16]], count=16, dest="./tmp/demos/tour/sweep.png"){
"summary": "gfx_sweep region :gfx1: sweep 1, 3 candidates s1c1..s1c3, 3 ... (90 characters)",
"candidates": [
{"id": "s1c1", "what": "4bpp 8x16 packed, rows", "tiles_available": 256, "shown": 16},
{"id": "s1c2", "what": "4bpp 8x16 planar, rows", "tiles_available": 256, "shown": 16},
{"id": "s1c3", "what": "4bpp 8x16 split, rows", "tiles_available": 256, "shown": 16}
],
"real_colors": false
}Three arrangements of 4 bits a pixel were drawn, each with an id the next call can take, such as s1c1. real_colors is false: the greys are not the game's colours.
The whole reply
{
"summary": "gfx_sweep region :gfx1: sweep 1, 3 candidates s1c1..s1c3, 3 drawn; 1568x384 PNG x2, inline",
"status": "ok",
"kind": "region",
"tag": ":gfx1",
"size": 16384,
"bytewidth": 1,
"endianness": "little",
"offset": "0x00000000",
"sweep": 1,
"count": 16,
"palette": "none",
"pen_base": 0,
"real_colors": false,
"cell_scale": 4,
"candidates": [
{"id": "s1c1", "what": "4bpp 8x16 packed, rows", "tiles_available": 256, "shown": 16},
{"id": "s1c2", "what": "4bpp 8x16 planar, rows", "tiles_available": 256, "shown": 16},
{"id": "s1c3", "what": "4bpp 8x16 split, rows", "tiles_available": 256, "shown": 16}
],
"next": "gfx_locate(layouts=[<ids>]) proves one against the screen; gfx_draft(choose={\"candidate\": <id>, \"chosen_by\": <who>}) records a person's pick",
"note": "palette `none`: a grey ramp over the pixel values, NOT the machine's colours",
"image": {
"path": "./tmp/demos/tour/sweep.png",
"bytes": "<volatile>",
"sha256": "<volatile>",
"width": 1568,
"height": 384,
"scale": 2,
"indexed": false,
"inline": true
},
"evaluated_by": "one step",
"lines_ahead": 0,
"thread_errors": 0,
"console_reruns": 0,
"call": "MAME_MCP_LUA_END#11",
"pc_before": "0x0000fd86",
"cause": "gfx_sweep: one step",
"stop_seq": 13,
"pc": "0x0000fd88",
"cpu": ":maincpu",
"frame": 545,
"regs": {
"A": "0x00",
"B": "0x72",
"D": "0x0072",
"X": "0x0100",
"Y": "0x00f1",
"U": "0xc66d",
"PC": "0xfd88",
"S": "0x07f4",
"CC": "0xf4",
"DP": "0x00"
},
"instruction": {"address": "FD88", "bytes": "0CB3", "text": "INC <$B3", "symbol": "irq", "delta": 8},
"following": ["FD8A: 0C B4 INC <$B4", "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", "... 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
- tag string, default
"" - The memory region or share to draw. Give this or
ref. - ref string, default
"" - An address or symbol in a cpu's memory to draw from, instead of
tag. - offset integer or string, default
0 - Bytes into the
tagblock where the tiles start: an integer or a0xstring. - count integer (>= 1, <= 64), default
32 - How many tiles each cell of the sheet shows, 1 to 64. Left out, 32.
- planes array of integer (>= 1, <= 8), optional
- The bit depths to try, each 1 to 8. Left out, 1, 2 and 4.
- sizes array of array of one of
8,16,24,32, optional - The tile sizes to try, each
[width, height]with sides of 8, 16, 24 or 32. Left out, 8 by 8. - palette string, default
"none" - The colours:
nonefor a grey ramp, a palette device's tag, or empty for the machine's only palette. Left out,none. - pen_base integer or string, default
0 - The first pen the tiles are drawn with, under a palette other than
none. - scale integer, default
0 - The whole factor the sheet is enlarged by, up to 8. 0 picks the largest that fits.
- dest string, default
"" - A new file the sheet is written to. Left empty, it goes to the session's temporary folder.
- 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 the read, in seconds.
What comes back
- candidates
- One row per layout tried: its
idsuch ass1c3,whatit is in words, itstiles_availableand how many areshown. - sweep
- The number of this sheet in the session, the first half of each candidate's id.
- image
- The sheet, each cell labelled with its id and its layout.
- cell_scale
- The factor the tiles inside each cell are enlarged by.
- next
- The two calls that take an id from this sheet, written out.
- real_colors
falseunder palettenone: the greys are not the machine's colours.
All 38 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)bytewidth(integer)call(string)candidates(integer or array)cell_scale(integer)count(integer)endianness(string)entries(integer)evaluated_by(string)image(object)kind(string)lines_ahead(integer)next(string)offset(string)palette(string)palettes(array)pc_before(string)pen_base(integer)pending(boolean)reader_steps(integer)real_colors(boolean)seen_bytes(integer)size(integer)sweep(integer)tag(string)
What it refuses
- More than 16 candidates: narrow
planesorsizes(bad_argument). - A block that holds no whole tile of any candidate, or a sheet too large to attach (
bad_argument). - Both
tagandref, or neither (bad_argument). - A tag or a palette the machine does not have (
unknown_ref).
Why it works this way
A board nobody has described has no format to state, and a format must not be guessed. So the block is drawn under every arrangement MAME's layouts are made of, side by side, and you pick the cell that looks like graphics.
Nothing ranks the cells: a ranking that looks like proof is worse than an honest list. A candidate's id is a layout for gfx_view and for gfx_locate, which checks it against the screen. gfx_draft(choose=...) records your pick.
The set of candidates is fixed and never tuned to a board. Give planes or sizes only when you know them.
More on why
Each candidate is a depth, a tile size, a pixel order and, past one plane, a plane arrangement, in the words what uses. Candidates with the same offsets are drawn once.
in what |
meaning |
|---|---|
rows |
pixels row by row |
cells across |
a tile of several 8x8 cells, across and then down |
cells down |
the cells down and then across |
packed |
a pixel's bits together, plane 0 the top bit |
planar |
the planes' bytes of each 8-pixel group in turn |
split |
each plane a fraction of the block apart: tag only |
Related tools
The contract your client receives
A block of unknown format drawn under a fixed family of candidate layouts as one sheet, each
cell labelled (`S1C3`); nothing is ranked.
The family: `planes` x `sizes` ([width, height], sides 8..32) x pixel order x
`packed`, `planar` or `split` (`tag` only); at most 16 candidates. `count`: tiles a
cell shows (1..64). Source: a memory region's or share's `tag` with
`offset` (an integer or a `0x` string), or `ref`.
`palette` as `gfx_view`. `pen_base`: the pen each pixel starts at; `dest`: a new path the
sheet is written to, else the scratch; `cpu`: whose address space, the visible one when
empty; `seconds` bounds the read.
Reply: `sweep`, `count`, `cell_scale`, `candidates` (`id`, `what`, `tiles_available`,
`shown`), `next`, `image`. `bad_argument`: too many candidates, no whole tile, a sheet past
the ceiling. `unknown_ref`: a tag or palette it lacks.
Reference: REFERENCE.md, Input and the screen.