SCRYMAMEReferenceTimelinegfx_load
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
docs/reference/tour/gridlee-gfx.yaml in this repository.Load the graphics manifest this repository keeps for Gridlee.
gfx_load(path="./docs/reference/tour/gridlee-gfx.yaml"){
"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
{
"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
truewhen the first line isgfx_draft's draft marker. Deleting that line confirms the draft.- formats
- Each format's name with its status.
- assets
- Each asset's
format,tagandpalette. - commands
- Each draw command: its
blockaddress andlength, itstrigger_addrand the value itfires_with, itsasset,roles,flagsandplanes. - palette_ports
- Each entry's
palette,space,protocol,index_port,data_port,index_flag_mask,order,component_bits,components_bit_reversedandpen_range. - status_counts
- How many entries are
proved,declaredandhuman.
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
- An unknown or missing key, a wrong type or a name that points at nothing; the message gives its full path (
bad_argument). - YAML outside the subset the reader takes; the message names the line (
bad_argument). - A manifest whose
systemsdoes not list the session's system (bad_argument). - A
paththat is not absolute (bad_argument).
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:
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.cppAn 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.
Related tools
The contract your client receives
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.