SCRYMAMEReferenceTimelinegfx_load

MAMETimeline

gfx_load

Load a project's gfx.yaml, the file that names its tile formats, graphics assets, draw commands and palette ports for the other tools.

gfx_load(path)

Try it

On Gridlee, a free ROM from mamedev.org, at any stop. The manifest is the example session's, docs/reference/tour/gridlee-gfx.yaml in this repository.
Ask

Load the graphics manifest this repository keeps for Gridlee.

Call
gfx_load(path="./docs/reference/tour/gridlee-gfx.yaml")
Reply 5 of 13 fields
{
  "summary": "gfx_load ./docs/reference/tour/gridlee-gfx.yaml: 1 format, 1 ... (125 characters)",
  "draft": false,
  "formats": {"sprite": "proved"},
  "assets": {
    "sprites": {"format": "sprite", "tag": "gfx1", "palette": "palette"}
  },
  "status_counts": {"proved": 9, "declared": 0, "human": 0}
}

One format and one asset, and all nine entries of the file are proved. The asset sprites reads the region gfx1 in the format sprite, with the palette device palette.

The whole reply
JSON
{
  "summary": "gfx_load ./docs/reference/tour/gridlee-gfx.yaml: 1 format, 1 asset, 1 command, 0 palette ports; 9 proved, 0 declared, 0 human",
  "status": "ok",
  "loaded": true,
  "replaced_path": {"available": false, "why": "no manifest was loaded in this session before this one"},
  "path": "./docs/reference/tour/gridlee-gfx.yaml",
  "sha256": "b79a770ebbbc34d15656c24e1aa3ec68ed95065ab8dc3606d69c43845846e753",
  "draft": false,
  "systems": ["gridlee"],
  "formats": {"sprite": "proved"},
  "assets": {
    "sprites": {"format": "sprite", "tag": "gfx1", "palette": "palette"}
  },
  "commands": {
    "player": {
      "block": "0x0000000c",
      "length": 4,
      "trigger_addr": "0x00000010",
      "fires_with": "any write",
      "asset": "sprites",
      "roles": ["dest_x", "dest_y", "height", "source_tile", "width"],
      "flags": [],
      "planes": []
    }
  },
  "palette_ports": {},
  "status_counts": {"proved": 9, "declared": 0, "human": 0}
}

Arguments

path string, required
The absolute path of the gfx.yaml. A load replaces the one before.

What comes back

draft
true when the first line is gfx_draft's draft marker. Deleting that line confirms the draft.
formats
Each format's name with its status.
assets
Each asset's format, tag and palette.
commands
Each draw command: its block address and length, its trigger_addr and the value it fires_with, its asset, roles, flags and planes.
palette_ports
Each entry's palette, space, protocol, index_port, data_port, index_flag_mask, order, component_bits, components_bit_reversed and pen_range.
status_counts
How many entries are proved, declared and human.
All 13 reply fields
  • assets (object)
  • commands (object)
  • draft (boolean)
  • formats (object)
  • loaded (boolean)
  • palette_ports (object)
  • path (string)
  • replaced_path (string or object)
  • sha256 (string)
  • status_counts (object)
  • still_loaded (string or object)
  • system (string)
  • systems (array)

What it refuses

Why it works this way

The file is checked whole, so a half-loaded manifest never answers a later call. A misspelt key is refused with its full path, such as commands.blit.fields.dest_x.parts[1].maks, because a key silently ignored is a setting silently left at its default. A refusal keeps the previous load and names it in still_loaded.

A manifest states what a project knows, and nothing in it runs; it loads while the program runs too. It holds no measured figure, which would go out of date there: a figure belongs in the report or the commit that measured it.

The reader takes a subset of YAML and refuses a value another YAML reader could type differently: no, 012, 1e3, a date, 1:20. Quote such a value. Anchors, tags, block scalars, tabs and duplicate keys are outside the subset.

More on why

The format of a gfx.yaml, as a small manifest that loads:

YAML
schema: 1
systems: [myboard]                 # the MAME systems it describes
formats:
  chars:
    layout:                        # as gfx_view takes one
      width: 8
      height: 8
      planes: 1
      planeoffset: [0]
      xoffset: '{ STEP8(0,1) }'
      yoffset: '{ STEP8(0,8) }'
      charincrement: 8*8
    status: declared
    source: myboard.cpp charlayout
assets:
  font: {format: chars, tag: gfx1, palette: palette, status: declared, source: myboard.cpp}
commands:
  blit:
    # the registers a capture watch records, and the write that makes a row a blit
    block: {address: 0x700000, words: 16, word_bytes: 2, status: declared, source: myboard.cpp}
    fire: {word: 15, value: 0xffff, status: declared, source: myboard.cpp}
    asset: font
    fields:                        # the roles the server computes with
      dest_x:
        parts:
          - {word: 0, mask: 0x00ff}
          - {word: 7, mask: 0x0040, at: 8}
        status: proved
        source: the boxes checked against the screen
      dest_y: {parts: [{word: 2, mask: 0x00ff}], status: declared, source: myboard.cpp}
      width: {const: 8, status: declared, source: myboard.cpp}
      height: {const: 8, status: declared, source: myboard.cpp}
palette_ports:
  ramdac:
    palette: palette
    index_port: 0x720001
    data_port: 0x720003
    order: [r, g, b]
    component_bits: 8
    auto_increment: true
    status: declared
    source: myboard.cpp

An asset may add offset, pen_base and wrap, for coordinates that wrap inside a tile. A command's block may name its cpu. Its fire is a word of the block with a value, or an address outside the block; with no value, every write there fires.

The roles are dest_x, dest_y, then dest_x_end and dest_y_end (inclusive) or width and height; dest_dir_x, dest_dir_y; source_x, source_y, source_tile, source_dir_x, source_dir_y; plane; reads_source. Anything else to show goes under flags, read the same way and never interpreted.

A field is a list of parts: each takes the bits of mask from one word, low bit first, and puts them from bit at of the value. An optional add is added, and sign: -1 reads a value stored reversed. A fixed size is a const, and a one-bit role says with asserted which value means it holds.

A command's planes each have a name and the width and height they wrap at. One is picked by the plane role's value (when), and a higher order is drawn over a lower. origin_x and origin_y are an integer or {field, scale, add} read from the blit's own row, and page names the field that says which page.

A palette_ports entry may add cpu, space (program or io), pen_base, pen_count and protocol; component_bits is 1 to 8. Two entries on one palette may not set the same pens.

protocol is ramdac (the default), latch, which needs index_flag_mask and may leave index_port out, or sequence. The last two may set components_bit_reversed. pen_count is a power of two up to 1024, and always 256 for ramdac.

A section named ramdacs is read as palette_ports, and note says so. The reply also carries the file's sha256 and its systems.

The contract your client receives
Text
Load a project's `gfx.yaml` (an ABSOLUTE `path`): `formats`, `assets`, draw `commands`,
`palette_ports`. A load replaces the previous one; answers while running.

Judged whole: an unknown or missing key, wrong type or dangling name is `bad_argument`
naming its path; a manifest not listing the session's `system` is refused (`still_loaded`).

Reply: `loaded`, `replaced_path`, `path`, `draft`, `formats`, `assets`, `commands`,
`palette_ports`, `status_counts`, `note`.

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