SCRYMAMEReferenceScreengfx_view
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
docs/reference/tour/gridlee-gfx.yaml, is loaded and names the format sprite.Show me sprite tiles 88 to 95 of Gridlee's graphics ROM in the palette's colours, starting at pen 832.
gfx_view(layout="sprite", tag="gfx1", palette="palette", first=88, count=8, columns=8, pen_base=832,
dest="./tmp/demos/tour/tiles.png"){
"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
{
"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.yamlor agfx_sweepcandidate's id. An object haswidth,height,planes,planeoffset,xoffset,yoffsetandcharincrement, in bits. - 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. - tag string, default
"" - The memory region or share to read, such as
gfx1. Give this orref, never both. - ref string, default
"" - An address or symbol in a cpu's memory 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. Not taken withref. - 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
paletteother thannone. - 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 falsewrites the picture without attaching it to the reply.- cpu string, default
"" - The cpu whose memory
refis in. Left empty, the one the debugger is showing; not taken withtag. - 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
falseunder palettenone: 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,shareorspace, a cpu's memory.tag,size,bytewidth,endiannessandoffsetdescribe it, and arefaddsaddrandaddr_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
- A
layoutthat is not one, or one that usesRGN_FRACwithref(bad_argument). - Both
tagandref, neither, orrefwithoutcount(bad_argument). - Tiles past the end of the block, or a palette with fewer pens than the depth needs, which is never padded (
bad_argument). - More than 1048576 pixels in one call, or a block too large to read (
bad_argument). - A tag, a palette or a format name that is not there (
unknown_ref).
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.
Related tools
The contract your client receives
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.