SCRYMAMEReferenceScreengfx_sweep

MAMEScreen

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

On Gridlee, a free ROM from mamedev.org, stopped in attract mode. gfx1 is the region that holds its sprites.
Ask

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.

Call
gfx_sweep(tag="gfx1", planes=[4], sizes=[[8, 16]], count=16, dest="./tmp/demos/tour/sweep.png")
Reply 3 of 36 fields
{
  "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
JSON
{
  "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 tag block where the tiles start: an integer or a 0x string.
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: none for 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 ref is 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 id such as s1c3, what it is in words, its tiles_available and how many are shown.
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
false under palette none: 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

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