SCRYMAMEReferenceScreenpaletteAlso in DOSBox-X
palette
Read the colours the palette holds now, as a list and as a picture of colour swatches.
palette(palette="", first=0, count=0, scale=0, dest="", seconds=5.0)
Try it
Show me the 32 palette entries from 832 on, and save the swatches as palette.png.
palette(first=832, count=32, dest="./tmp/demos/tour/palette.png"){
"summary": "palette :palette: pens 0x340..0x35f of 2048, more after; 1128x128 PNG x8, inline",
"colors": [
"#8866bb",
"#ff0000",
"#cc0000",
"#660000",
"#ccff88",
"#77cc44",
"... 26 more"
]
}The summary's pens are palette entries: this palette has 2048, and the reply lists 32 of them, from 832 (0x340), as colours. The swatches went to a PNG enlarged 8 times.
The whole reply
{
"summary": "palette :palette: pens 0x340..0x35f of 2048, more after; 1128x128 PNG x8, inline",
"status": "ok",
"palette": ":palette",
"entries": 2048,
"first": 832,
"count": 32,
"truncated": false,
"shadows": false,
"highlights": false,
"indirect_entries": 0,
"colors": ["#8866bb", "#ff0000", "#cc0000", "#660000", "#ccff88", "#77cc44", "... 26 more"],
"image": {
"path": "./tmp/demos/tour/palette.png",
"bytes": "<volatile>",
"sha256": "<volatile>",
"width": 1128,
"height": 128,
"scale": 8,
"indexed": false,
"inline": true
},
"evaluated_by": "one step",
"lines_ahead": 0,
"thread_errors": 0,
"console_reruns": 0,
"call": "MAME_MCP_LUA_END#10",
"pc_before": "0x0000fd84",
"cause": "palette: one step",
"stop_seq": 12,
"pc": "0x0000fd86",
"cpu": ":maincpu",
"frame": 545,
"regs": {
"A": "0x00",
"B": "0x72",
"D": "0x0072",
"X": "0x0100",
"Y": "0x00f1",
"U": "0xc66d",
"PC": "0xfd86",
"S": "0x07f4",
"CC": "0xf4",
"DP": "0x00"
},
"instruction": {"address": "FD86", "bytes": "2604", "text": "BNE $FD8C", "symbol": "irq", "delta": 6},
"following": ["FD88: 0C B3 INC <$B3", "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", "... 9 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
- palette string, default
"" - The palette device to read, by its MAME tag. Left empty, the machine's only one.
- first integer or string, default
0 - The first entry to read: an integer or a
0xstring. Left out, 0. - count integer, default
0 - How many entries to read, at most 256. Left at 0, to the end; read a larger palette in pages, with
first. - scale integer, default
0 - The whole factor the picture is enlarged by, 1 to 8. Left at 0, the largest that fits.
- dest string, default
"" - A new path for the PNG, absolute or starting with
~. Left empty, the session's temporary folder, deleted atclose. - seconds number (> 0, <= 600.0), default
5.0 - The time limit of the read, in seconds of your clock. Left out, 5.
What comes back
- colors
- Each entry read, as
#rrggbb, in order fromfirst. - entries
- How many entries the palette has.
- truncated
truewhen a read to the end stopped at 256 entries with more left.- alpha
- Each entry's alpha, listed only when some entry is not fully opaque.
- indirect_entries
- How many entries MAME's second, indirect colour table holds for this device.
- image
- The PNG: its
path,bytes,sha256,width,heightandscale, whether it isindexed, andinlineor the reason innot_inlined.
All 29 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)alpha(array)call(string)colors(array)count(integer)entries(integer)evaluated_by(string)first(integer)highlights(boolean)image(object)indirect_entries(integer)lines_ahead(integer)palette(string)palettes(array)pc_before(string)reader_steps(integer)shadows(boolean)truncated(boolean)
What it refuses
- A
palettetag the machine does not have; the refusal lists itspalettes(unknown_ref). - An empty
paletteon a machine with several palette devices (ambiguous_ref) or with none (no_channel). - A
firstandcountthat reach past the last entry (bad_argument). - A machine that is running (
not_stopped).
Why it works this way
The colours come from MAME's own palette device, the entries the screen is drawn with. On many boards nothing else can be read: a RAMDAC is write-only, and some drivers keep their colours in an array of their own.
The read costs one instruction of the program: MAME's console runs a line only when the machine moves, so the call steps once and reads after it. Nothing is altered. The reply is also a stop, and pc_before says where the program stood.
In the picture each row holds 16 entries, with the index of its first entry written at its left in hexadecimal, so no entry has to be counted across.
More on why
shadows and highlights say whether the device has those two of MAME's tables on. The fields about MAME's console (evaluated_by, lines_ahead, reader_steps, resent, thread_errors, console_reruns, call) are explained on the Lua page.
Related tools
The contract your client receives
The pens of a palette device as the machine holds them now, as a table and a swatch: the
route to the colours of a write-only RAMDAC.
`palette` is the device tag (empty: the only one).
`scale`: the integer the swatch is enlarged by, 0 the largest that fits; `dest`: a new
path it is written to, else the session's scratch; `seconds` bounds the read.
Reply: `palette`, `entries`, `first`, `count`, `truncated`, `colors`, `alpha` (not fully
opaque), `indirect_entries`, `image`. `unknown_ref`, `ambiguous_ref`, `no_channel`: no such
device, several, none. `bad_argument`: past the last pen.
Reference: REFERENCE.md, Input and the screen.