Sprites Image Media Storage

Contents

The record in the data store is just the id and the data object. Everything a listing shows, the name, size and mode summary, is the meta record, so this store carries only the picture.

Data

The data object carries the size and mode the whole image is drawn at, the tile side the pixels are cut into, and its layers. Width, height and mode live here, on the picture itself; the meta record's info summary is a copy for listings.

Layers

layers is an array of layer objects, back to front, flattened bottom to top to make the picture. A flat image has a single layer. There are no frames: an image is layers only. Each layer holds the whole picture as a grid of tiles and a visible flag.

The editor adds, clones, reorders, hides and deletes layers. A transparent pixel on an upper layer, alpha zero, lets the layer below show through when the layers are flattened bottom to top.

Tiles and pixel encoding

Each layer cuts the picture into a grid of square tiles of side tile, so the pixels sit in a high-resolution tiled grid rather than one flat array. tiles holds those tiles in row order, ceil(w / tile) columns by ceil(h / tile) rows, and the tile at tile column tc, tile row tr is at index tr × ceil(w / tile) + tc. An edge tile holds a few unused cells past the pixel size, so a 20-wide image over a tile of 16 keeps two tiles across, the second half used.

Each tile is one Uint32Array of tile × tile packed RGBA colours, in row order within the tile. The pixel at tile-local column c, row r is at index r × tile + c.

The pixels are always full colour, whatever the platform. The mode fixes the screen size and the palette the picker offers, but each stored pixel is its own packed RGBA value, not a slot index.

Attribute images

The Spectrum, the C64 hires and the Oric store an attribute image, a different data shape. Where a direct image holds a packed RGBA colour for every pixel in a tiled Uint32Array grid, an attribute image holds a one bit ink or paper mask at full resolution over an ink and a paper colour grid at attribute cell resolution, each cell a flat palette index. The data object is { media, platform, mode, w, h, cellWidth, cellHeight, inline, pixels, ink, paper }.

The mask reads full resolution, so a pixel is ink or paper wherever it falls; the ink and paper grids are coarse, one entry per attribute cell, so two colours meet inside a per cell block as colour clash. An undefined colour cell reads the mode's default ink or paper. This is the shape Sprites.Media.Image.Cells reads and writes.

Persistence

The record is structured-clone persisted in IndexedDB, the data store, keyed by id. The meta record, the name, size, mode summary and thumbnail, lives beside it under the same id in the meta store. Because the tiles are typed arrays, structured clone stores them directly, with no JSON stringify: a Uint32Array is written as a typed array, not turned into text. A JSON export is a separate path, and there a Uint32Array serialises as a plain array of numbers, which is why the examples on this page show tiles as arrays of integers. See Sprites.Media.Image for the editor that reads and writes this format.

Full example

A tiny 16×16 freeform image, one tile per layer, a single layer. The tile side is 16, so the whole picture is one tile of 256 packed RGBA colours in row order. Here the corners are opaque white, 4294967295, and the rest is transparent, 0.

{
  "media": "image",
  "w": 16,
  "h": 16,
  "tile": 16,
  "mode": null,
  "layers": [
    {
      "tiles": [
        [ 4294967295, 0, /* ... 252 more ... */ 0, 4294967295 ]
      ],
      "visible": true
    }
  ]
}

A platform image has the same shape, with its mode named in data.mode, for example "Mode 13h". The pixels stay full-colour packed RGBA; the mode only fixes the screen size and the palette the picker offers.

{
  "media": "image",
  "w": 320,
  "h": 200,
  "tile": 16,
  "mode": "Mode 13h",
  "layers": [
    {
      "tiles": [ /* 20 × 13 tiles of 256 packed RGBA ints */ ],
      "visible": true
    }
  ]
}