SCRYMAMEReferenceScreengfx_view

MAMEScreen

gfx_view

Draw bytes of a ROM region or of memory as tiles, in a layout you state in MAME's gfx_layout terms.

gfx_view(layout, palette="none", tag="", ref="", offset=0, first=0, count=0, columns=16, pen_base=0, scale=0, dest="", attach=true, cpu="", seconds=5.0)

Try it

On Gridlee, a free ROM from mamedev.org, stopped in attract mode. The example session's manifest, docs/reference/tour/gridlee-gfx.yaml, is loaded and names the format sprite.
Ask

Show me sprite tiles 88 to 95 of Gridlee's graphics ROM in the palette's colours, starting at pen 832.

Call
gfx_view(layout="sprite", tag="gfx1", palette="palette", first=88, count=8, columns=8, pen_base=832,
    dest="./tmp/demos/tour/tiles.png")
Reply 4 of 35 fields
{
  "summary": "gfx_view region :gfx1: tiles 88..95 of 256, 8x16x4, palette  ... (92 characters)",
  "status": "ok",
  "tiles_available": 256,
  "real_colors": true
}

Tiles 88 to 95 of the 256 the region holds, 8 by 16 pixels at 4 bits a pixel. real_colors says they are drawn in the machine's own colours.

The whole reply
JSON
{
  "summary": "gfx_view region :gfx1: tiles 88..95 of 256, 8x16x4, palette :palette; 512x128 PNG x8, inline",
  "status": "ok",
  "layout": {
    "name": "sprite",
    "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
  },
  "kind": "region",
  "tag": ":gfx1",
  "size": 16384,
  "bytewidth": 1,
  "endianness": "little",
  "offset": "0x00000000",
  "first": 88,
  "count": 8,
  "tiles_available": 256,
  "columns": 8,
  "palette": ":palette",
  "pen_base": 832,
  "real_colors": true,
  "image": {
    "path": "./tmp/demos/tour/tiles.png",
    "bytes": "<volatile>",
    "sha256": "<volatile>",
    "width": 512,
    "height": 128,
    "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": "0x0000fd8a",
  "cause": "gfx_view: one step",
  "stop_seq": 15,
  "pc": "0x0000fd8c",
  "cpu": ":maincpu",
  "frame": 545,
  "regs": {
    "A": "0x00",
    "B": "0x72",
    "D": "0x0072",
    "X": "0x0100",
    "Y": "0x00f1",
    "U": "0xc66d",
    "PC": "0xfd8c",
    "S": "0x07f4",
    "CC": "0xf0",
    "DP": "0x00"
  },
  "instruction": {"address": "FD8C", "bytes": "B603BE", "text": "LDA    $03BE", "symbol": "irq", "delta": 12},
  "following": ["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", "FD9A: 85 10    BITA   #$10", "... 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

layout object or string, required
The tile format: an object, a format name of the loaded gfx.yaml or a gfx_sweep candidate's id. An object has width, height, planes, planeoffset, xoffset, yoffset and charincrement, in bits.
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.
tag string, default ""
The memory region or share to read, such as gfx1. Give this or ref, never both.
ref string, default ""
An address or symbol in a cpu's memory where tile 0 starts, instead of tag. It needs count.
offset integer or string, default 0
Bytes into the tag block where tile 0 starts: an integer or a 0x string. Not taken with ref.
first integer, default 0
The index of the first tile drawn. Left out, 0.
count integer, default 0
How many tiles to draw, at most 1024. 0 draws every tile the block holds, up to that many.
columns integer (>= 1, <= 64), default 16
Tiles in a row of the picture, 1 to 64. Left out, 16.
pen_base integer or string, default 0
The first pen of the palette the tiles are drawn with. It needs a palette other than 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.
attach boolean, default true
false writes the picture without attaching it to the reply.
cpu string, default ""
The cpu whose memory ref is in. Left empty, the one the debugger is showing; not taken with tag.
seconds number (> 0, <= 600.0), default 5.0
The time limit of the read, in seconds.

What comes back

image
The PNG. It is indexed, and its index is the pixel value under any palette.
tiles_available
How many whole tiles of this layout the block holds from the offset.
real_colors
false under palette none: the greys are not the machine's colours.
layout
The layout with every expression worked out to numbers, and its name.
kind
Where the bytes came from: region, share or space, a cpu's memory. tag, size, bytewidth, endianness and offset describe it, and a ref adds addr and addr_cpu.
All 40 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)
  • columns (integer)
  • count (integer)
  • endianness (string)
  • entries (integer)
  • evaluated_by (string)
  • first (integer)
  • formats (array)
  • image (object)
  • kind (string)
  • layout (object)
  • lines_ahead (integer)
  • 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)
  • tag (string)
  • tags (object)
  • tiles_available (integer)

What it refuses

Why it works this way

The layout is written in MAME's own gfx_layout terms, so a driver's layout copies over as it is. Its total becomes first and count, and plane 0 is the top bit. Those terms also state formats a bit depth cannot: byte-interleaved planes, planes a third of a region apart, packed nibbles, a linear framebuffer.

To try other colours, replace the palette inside the PNG: the tool takes a palette device, never a list of colours.

tag names a memory region, the ROM data MAME loads, or a share, RAM a driver names. A region is read whole, in the block's own byte order. A share is read a byte at a time, so the largest share it reads is smaller.

More on why

RGN_FRAC is a fraction of a block's length, and a range of a cpu's memory has no length of its own, so ref refuses it.

The contract your client receives
Text
Bytes as tiles in a format you state, as MAME's `gfx_layout`.

`layout`: a manifest format's name, or `width`, `height`, `planes` (1..8),
`planeoffset`, `xoffset`, `yoffset`, `charincrement` in bits; values may use
`RGN_FRAC(n,d)`, `+ - *`, hex, `STEPn(a,b)`.

Source: `tag` with `offset` (an integer or a `0x` string), or `ref` (tile 0; `count` required). `count` 0:
the block, at most 1024; `columns` 1..64; `first` starts the tiles
at that index. `palette`: `none` or a tag. `pen_base`: the pen each pixel starts at.
`scale`: the integer the picture is enlarged by, 0 the largest that fits; `dest`: a new path
it is written to, else the scratch; `attach=false` writes it without attaching it; `cpu`:
whose address space, the visible one when empty; `seconds` bounds the read.

Reply: `layout`, `tiles_available`, `palette`, `real_colors`, `image`. `bad_argument`: not a
layout, tiles past the block, too few pens, over 1048576 pixels or 67108864
bytes. `unknown_ref`: missing tag, palette or name.

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