Skip to content

Resources

The resource types are in the core MrKWatkins.OakIO package, under the MrKWatkins.OakIO.Resources namespace. They provide a common data model for image, palette and tile formats. Concrete formats include BMP, GIMP GPL, JASC PAL and Paint.NET palettes. The MrKWatkins.OakIO.ZXSpectrumNext package also supports NXP palettes, NXI images, SPR sprite patterns and NXT tiles. It also supports NXM tile or block maps with explicitly supplied layouts. Reusable tile-index blocks are supported as NXB files. The MrKWatkins.OakIO.ZXSpectrum package supports SCR screen dumps. Resource formats are not yet included in the CLI or online converter.

Files and formats

ResourceFile inherits from IOFile, so resource files use the existing synchronous and asynchronous writing, compression and conversion infrastructure. ResourceFormat inherits from IOFileFormat. Each specialized pair has the same relationship:

File Format Shared data
ImageFile ImageFormat ImageData
PaletteFile PaletteFormat PaletteData
TilesFile TilesFormat TilesData
TileMapFile TileMapFormat TileMapData
TileBlocksFile TileBlocksFormat TileBlocksData

Each format also has a generic variant for strongly typed reads and writes. A concrete format implements its binary reader and writer hooks and registers applicable converters through CreateConverters. Concrete resource files retain their own format-specific headers and data components, following the tape and snapshot formats. The image, palette and tiles bases take only a format; their abstract Image, Palette and Tiles properties provide convenience views implemented by each concrete file. Shared data models are conversion views, not a replacement for the on-disk structure or a second source of truth. Resource formats are separate from the Spectrum and Next snapshot/tape format lists. Call IOFileFormat.Load or LoadAsync with ResourceFileFormats.AllFormats to discover resource formats. For general and Next resource formats together, use ZXSpectrumNextResourceFileFormats.AllFormats from the Next package's Resources namespace.

SL2 and SLR also require explicit modes. Use ZXSpectrumNextResourceFileFormats.WithScreens(Sl2Format.Wide, SlrFormat.EightBit) to include them; their byte-backed optional headers, bitmaps and appended palettes expose derived indexed image views. See SL2, SLR and the Next resource audit for supported variants and exclusions. For general and Spectrum resources, use ZXSpectrumResourceFileFormats.AllFormats from the Spectrum package's Resources namespace. The Next list includes these Spectrum resources too. SPR and NXT require explicit bit depths and are excluded from unqualified discovery. Use ZXSpectrumNextResourceFileFormats.WithTiles(spriteBitsPerPixel, tileBitsPerPixel) to include them.

Colours and palettes

Colour stores eight-bit red, green, blue and alpha components. The three-component constructor defaults alpha to 255 (opaque); zero alpha is transparent. Quantization to hardware colour depths belongs to the target-format converter, not this shared type.

PaletteData contains one or more ordered colours. Order and duplicates are preserved because an index identifies a specific entry. The general palette model does not impose a hardware size limit; concrete formats and indexed images impose their own limits.

Images

ImageData has positive width and height, a pixel count and GetPixel(x, y). The origin is at the top-left. Pixels are row-major: left to right within each row, then top to bottom.

  • ColourImageData stores one Colour per pixel.
  • IndexedImageData stores one byte per palette index and references a reusable PaletteData. Its index bit depth is 1, 2, 4 or 8.

Indexed pixels are always unpacked in memory, even for four-bit images. Every index must identify an existing palette entry, and the palette must fit the bit depth. Disk-specific packing, row padding and row/column order are handled by the concrete file format.

var palette = new PaletteData([new Colour(0, 0, 0), new Colour(255, 0, 0)]);
var image = new IndexedImageData(2, 2, [0, 1, 1, 0], palette, bitsPerPixel: 1);
Colour red = image.GetPixel(1, 0);

Tiles

TilesData stores equally sized indexed tiles. Width and Height describe each tile; Count is calculated from the pixel data. An empty tile collection is allowed, but partial tiles are not.

Pixels are tile-major: all of tile zero, then all of tile one, continuing in sequence. Within each tile, indices are row-major and unpacked, with a bit depth of 1, 2, 4 or 8. Tiles do not own a palette, so a palette can be supplied separately and shared between images or tiles.

Tilemaps

TileMapData stores a rectangular grid of TileMapEntry values in top-left-origin row-major order. Dimensions count entries, not pixels. GetEntry(x, y) validates coordinates. An entry refers to a tile or reusable block and carries a nonnegative index and palette offset, plus optional X/Y mirrors, clockwise rotation and a priority flag. Offset units and priority interpretation belong to the concrete format; unsupported fields are rejected by conversion, not discarded. No referenced graphics are embedded in the shared map model.

Concrete files retain their byte-backed components and expose derived maps. ResourceDataOrder lets formats explicitly select row-major or column-major wire layouts without changing the shared view. NXM is excluded from unqualified discovery because its dimensions and entry encoding are not stored in its bytes. Supply one NxmFormat alongside the existing formats when loading by filename.

Tile blocks

TileBlocksData stores equally sized rectangles of TileMapEntry values. Width and height count map entries, not pixels; Count is derived from the entry count. Entries are block-major, with row-major ordering within each block. Empty collections are valid, incomplete blocks are rejected. GetBlock(index) returns an independent TileMapData view.

The shared model retains attributes for future formats; NXB supports only plain indices and rejects attributes rather than silently removing them. Concrete block files retain their native byte-backed components and expose derived shared views. Referenced tile graphics and palettes remain separate. NXB is excluded from unqualified discovery; supply one explicit NxbFormat when loading by filename.

Ownership and validation

The concrete shared data models copy input sequences and expose read-only collections. A shared palette can therefore be safely reused without later input mutations changing the image colours. Invalid dimensions, pixel counts, bit depths and indices are rejected when the data model is constructed.