SCRYMAMEReferenceScreenpaletteAlso in DOSBox-X

MAMEScreen

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

On Gridlee, a free ROM from mamedev.org, stopped while its attract mode plays. Entry 838, in the range asked for, is the colour of a pixel of the player's sprite.
Ask

Show me the 32 palette entries from 832 on, and save the swatches as palette.png.

Call
palette(first=832, count=32, dest="./tmp/demos/tour/palette.png")
Reply 2 of 30 fields
{
  "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
JSON
{
  "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 0x string. 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 at close.
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 from first.
entries
How many entries the palette has.
truncated
true when 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, height and scale, whether it is indexed, and inline or the reason in not_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

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.

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