Bindings: handle-only graphics API with index addressing and options objects #440

Closed
opened 2026-10-30 22:53:44 +01:00 by jqueuniet · 0 comments
Owner

The graphics.dat bindings grew one function per decoder, twice (free function + GraphicsArchive method), with positional options. Each new option (fill, language, style/light) changed signatures in wasm, FFI and Python, the C header and both READMEs.

Proposal

One deliberate break (pre-1.0), after which options are additive.

1. GraphicsArchive only

Drop the graphics* free functions. They have no performance case: one call through a handle costs the same as one free call, and every further call is ~9× slower through the free functions (#431). Their only advantage is not needing free():

  • wasm: build with --weak-refs so a forgotten free() is reclaimed by a FinalizationRegistry.
  • Python: a one-shot helper is a few lines over the class, with no FFI exports.

2. Records by listing index

entries() gains index, the ENT1 record position. Decoders take it instead of (cls1, cls2, cls4). That addresses every record exactly, including cls5 language variants, which a tuple lookup resolves last-wins (#429). Wrong-kind checks stay: image(i) on a sound errors. A convenience lookup by tuple stays: find(cls1, cls2, cls3, cls4, {language}) returns an index.

3. One options type per kind

Defined once in dm2-convert, passed through by every binding:

#[derive(Deserialize, Default)]
#[serde(default, deny_unknown_fields)]
#[non_exhaustive]
pub struct ImageOptions {
    pub transparent: bool,
    pub style: Option<u8>,
    pub light: Option<u8>,
}
binding options arrive as a new option is
Rust &ImageOptions a field
wasm a JS object, via serde-wasm-bindgen a field
C options_json + length; empty = defaults a key; the header does not change
Python keyword arguments, sent as JSON a keyword

deny_unknown_fields turns typos into errors. decodePng and decodePngTransparent merge into one image with transparent.

Resulting surface

const g = new GraphicsArchive(bytes);
for (const e of JSON.parse(g.entries()))
  if (e.kind === "image") show(g.image(e.index, { transparent: true, style: 2 }));
g.free();

Methods: header, entries, find, labels, image, icon, sound, music, font, text, palette.

Costs

  • Option errors move from compile time to runtime in Rust and C.
  • New wasm dependency serde-wasm-bindgen. TypeScript sees any for options unless a type declaration is hand-written.
  • Consumers (dm2-web-editor, the save editor's item icons) migrate once.

Acceptance

  • Graphics in every binding is handle-only, index-addressed, with options objects; free graphics* exports are gone.
  • Adding an option to any decoder changes no signature and no C header line.
  • Outputs are byte-identical to the current functions for the same record and options.

Later

The same shape fits the magic map: dungeon_map_png re-parses graphics.dat on every call. Dungeon and save handles would follow this pattern.

https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7

The `graphics.dat` bindings grew one function per decoder, twice (free function + `GraphicsArchive` method), with positional options. Each new option (`fill`, `language`, `style`/`light`) changed signatures in wasm, FFI and Python, the C header and both READMEs. ## Proposal One deliberate break (pre-1.0), after which options are additive. ### 1. `GraphicsArchive` only Drop the `graphics*` free functions. They have no performance case: one call through a handle costs the same as one free call, and every further call is ~9× slower through the free functions (#431). Their only advantage is not needing `free()`: - wasm: build with `--weak-refs` so a forgotten `free()` is reclaimed by a `FinalizationRegistry`. - Python: a one-shot helper is a few lines over the class, with no FFI exports. ### 2. Records by listing index `entries()` gains `index`, the ENT1 record position. Decoders take it instead of `(cls1, cls2, cls4)`. That addresses every record exactly, including `cls5` language variants, which a tuple lookup resolves last-wins (#429). Wrong-kind checks stay: `image(i)` on a sound errors. A convenience lookup by tuple stays: `find(cls1, cls2, cls3, cls4, {language})` returns an index. ### 3. One options type per kind Defined once in `dm2-convert`, passed through by every binding: ```rust #[derive(Deserialize, Default)] #[serde(default, deny_unknown_fields)] #[non_exhaustive] pub struct ImageOptions { pub transparent: bool, pub style: Option<u8>, pub light: Option<u8>, } ``` | binding | options arrive as | a new option is | |---|---|---| | Rust | `&ImageOptions` | a field | | wasm | a JS object, via `serde-wasm-bindgen` | a field | | C | `options_json` + length; empty = defaults | a key; the header does not change | | Python | keyword arguments, sent as JSON | a keyword | `deny_unknown_fields` turns typos into errors. `decodePng` and `decodePngTransparent` merge into one `image` with `transparent`. ### Resulting surface ```js const g = new GraphicsArchive(bytes); for (const e of JSON.parse(g.entries())) if (e.kind === "image") show(g.image(e.index, { transparent: true, style: 2 })); g.free(); ``` Methods: `header`, `entries`, `find`, `labels`, `image`, `icon`, `sound`, `music`, `font`, `text`, `palette`. ## Costs - Option errors move from compile time to runtime in Rust and C. - New wasm dependency `serde-wasm-bindgen`. TypeScript sees `any` for options unless a type declaration is hand-written. - Consumers (`dm2-web-editor`, the save editor's item icons) migrate once. ## Acceptance - Graphics in every binding is handle-only, index-addressed, with options objects; free `graphics*` exports are gone. - Adding an option to any decoder changes no signature and no C header line. - Outputs are byte-identical to the current functions for the same record and options. ## Later The same shape fits the magic map: `dungeon_map_png` re-parses `graphics.dat` on every call. Dungeon and save handles would follow this pattern. https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jqueuniet/dm2-tools#440
No description provided.