ddw3/docs/tim.md

Image files (tim)

The games use the tim file format to store all images.

File format

Supports either:

• Indexed images (4-bit or 8-bit indexes with 16-bit (R5G5B5A1) colors)
• Color images (16-bit (R5G5B5A1) or 24-bit (R8G8B8))

They also store an x, y position to place the image at. If they are indexed, the clut (Color LookUp Table, or palette) also has an x, y position to place.

Color images / cluts are mapped directly to VRAM at their respective position, so they mustn't overlap.

Usage

They are built by ddw3-mktim from yaml header files, with the following structure:

bpp: Indexed4 | Indexed8 | Color16 | Color24

# Palette data
# Note: Only used if `Indexed4` or `Indexed8`
clut:
  # Position to store the clut at
  pos:
    - <x position>
    - <y position>

  # Kind of palette:
  # - `include`: Uses the clut to generate the indices
  #   for the image, and will include the clut.
  # - `external`: Uses the clut to generate the indices
  #   for the image, but will *not* include the clut.
  # - `auto`. Automatically calculates the clut from
  #   the given image, and includes it.
  kind: include
  path: 0.clut.png

# Image data
img:
  # Note: Required even when using indexed images
  pos:
    - <x position>
    - <y position>

  # Path to the image
  # Note: Even when indexed, this should be a png.
  #       The indices will be calculated from the clut.
  path: <path to image>

Then using build/tools/ddw3-mktim <yaml> --output <tim>

Organization

The header files are stored in tim/, alongside the image files themselves.

TODO: Maybe they should be split? Especially so we can create them from files other than png without cluttering tim/. For example when we want to make a spritesheet / animation, it might be worth it to have a img/ directory for status images, spritesheet/ for spritesheets and anim/ for animations or something like that.

Notes

The games only ever seem to use 4-bit indexed images, always with their clut.

Using auto for the clut kind is currently unsupported. This should be fixed.