SCRYDOSBox-XReferenceScreenpaletteAlso in MAME

DOSBox-XScreen

palette

Read the colours the palette holds now, as a list and as a picture of colour swatches.

palette(first=0, count=0, scale=0, dest="")

Try it

On Bricks, the game this repository builds, stopped once its play screen is drawn. Entries 32 to 39 are colours the game itself sets.
Ask

Show me palette entries 32 to 39, and save the swatches as palette.png.

Call
palette(first=32, count=8, dest="./tmp/demos/tour/files/palette.png")
Reply 2 of 10 fields
{
  "summary": "palette: entries 32 to 39 of 256; 1024x128 PNG x8, inline",
  "colors": [
    "#ff2020",
    "#ff9200",
    "#fff330",
    "#41eb41",
    "#20d3eb",
    "#5161ff",
    "... 2 more"
  ]
}

Eight of the palette's 256 entries, from 32, each as #rrggbb: the VGA's six-bit components widened to eight bits. The swatches went to a PNG enlarged 8 times, attached to the reply.

The whole reply
JSON
{
  "summary": "palette: entries 32 to 39 of 256; 1024x128 PNG x8, inline",
  "status": "ok",
  "entries": 256,
  "first": 32,
  "count": 8,
  "colors": ["#ff2020", "#ff9200", "#fff330", "#41eb41", "#20d3eb", "#5161ff", "... 2 more"],
  "rgb": ["3f0808", "3f2400", "3f3c0c", "103a10", "08343a", "14183f", "... 2 more"],
  "bits": 6,
  "pel_mask": "ffh",
  "image": {
    "path": "./tmp/demos/tour/files/palette.png",
    "bytes": "<volatile>",
    "sha256": "<volatile>",
    "width": 1024,
    "height": 128,
    "scale": 8,
    "indexed": true,
    "inline": true
  }
}

Arguments

first integer (>= 0, <= 255) or string, default 0
The first entry to read, 0 to 255: an integer or a 0x string. Left out, 0.
count integer (>= 0, <= 256), default 0
How many entries to read. Left at 0, every entry from first to the last.
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.

What comes back

colors
Each entry read, as #rrggbb, in order from first.
rgb
Each entry as the debugger prints it: three six-bit components in hex.
entries
How many entries the palette has: 256.
bits
The width of each component in the DAC, the chip that holds the palette: 6, or the call is refused.
pel_mask
The DAC's pixel mask register, as the debugger prints it.
image
The PNG: its path, bytes, sha256, width, height and scale, whether it is indexed, and inline or the reason in not_inlined.
All 8 reply fields
  • bits (integer)
  • colors (array)
  • count (integer)
  • entries (integer)
  • first (integer)
  • image (object)
  • pel_mask (string)
  • rgb (array)

What it refuses

Why it works this way

The colours are the VGA DAC's 256 entries, read from the debugger's VGA DAC and VGA DACPAL listings. Each six-bit component is widened to eight bits as the emulator draws it, by repeating its two top bits below.

The picture is an indexed PNG: every pixel of a swatch holds that entry's index into the DAC, so the file carries the palette as data.

The contract your client receives
Text
The VGA DAC's 256 colours at this stop, read off the `VGA DAC` listings, with an indexed
PNG swatch. `first` and `count` (0 for all from `first`)
choose entries, `first + count` at most 256. `scale` 0 fits the largest enlargement up to 8;
`dest` a new path, else a scratch gone at `close`.

Reply: `entries`, `first`, `count`, `colors` (`#rrggbb`), `rgb`, `bits`, `pel_mask`,
`image`.

Refused: an entry past 255, a bad `scale`, a relative or existing `dest` (`bad_argument`);
a running guest (`not_stopped`); a DAC not six-bit (`unexpected_answer`); a picture not
taken whole (`host_failed`).

Reference: REFERENCE.md, Media files.
Tools