Changelog

# Changelog

All notable changes to **epaper-image** are documented in this file. The project
follows [semantic versioning](https://semver.org/).

## v0.6.0

Adds a runtime version call and a calibration ID on every panel, so a stored
frame can be checked against the library and calibration that would render it
now. The API is otherwise unchanged.

**Panel output:** unchanged.

### Added

- `epi_version()` returns the version of the library linked, packed as
  `major << 16 | minor << 8 | patch`; the `EPI_VERSION_*` macros give the
  version of the header compiled against.
- `epi_panel_t.id`, 16 bytes identifying the calibration inputs that can change
  the bits sent to the panel: the kind, size, each ink's code and measured
  colour, the detail sigma and the neutral-cast knots. The name, nominal colours
  and presets are not part of it. `epi_grey_panel_init` and
  `epi_colour_panel_init` compute it, and the built-in panels carry the same
  value. It does not change with the rendering algorithm, so a frame is current
  while the pair (library version, ID) is unchanged. All zeros means unknown, as
  in a hand-built panel. The bytes are opaque: compare them, but don't rely on
  how they are computed.

### Changed

- `epi_panel_t` gains the `id` member at its end, so the panel storage that
  `epi_grey_panel_size` and `epi_colour_panel_size` report grows slightly.
- Firmware that uses only the built-in panels no longer links
  `epi_grey_panel_init`: the grey presets have their own file. The hash behind
  the ID links only with the inits.

## v0.5.0

Lays out a chosen region of the source, adds an undithered pop for quick
drafts, and documents rendering a frame in steps. The layout helpers and the
resampler's source rectangle change, which breaks the API.

**Panel output:** unchanged.

### Breaking changes

- `epi_resampler_config_t`'s `src_x`, `src_y`, `src_w` and `src_h` become one
  field, `src`, an `epi_rect_t`.
- `epi_layout_cover(cfg, region)` and `epi_layout_fit(cfg, region)` take the
  region of the source to lay out, `NULL` for the whole source as before, and
  return `epi_err_t`. They return `EPI_ERR_INVALID_ARG`, leaving the config
  untouched, for invalid input or a result that breaks the rectangle rule.

### Added

- `epi_rect_t`, a rectangle in source pixels, for regions and the resampler's
  source.
- `epi_converter_pop_undithered` pops a row as sRGB8 colours instead of ink
  codes: the colour the dither aims for, in the panel's measured ink colours.
  Rendered this way at a reduced size, a draft predicts the full render's
  preview without the coarser dither grain. A converter pops with one function,
  fixed by its first successful pop.
- The design notes describe rendering in steps: each push and pop does about a
  row's work, and the output does not depend on how the calls are scheduled.
- `convert` rejects an image over 65535 pixels a side while decoding it, and an
  input file over 512 MiB.

## v0.4.0

Adds `epi_panel_preset`, which finds a panel's preset by name. The API is
otherwise unchanged, and so is panel output.

### Added

- `epi_panel_preset(panel, name)` returns the intent of the panel's preset with
  that name, ignoring the case of ASCII letters, or the default preset for a
  `NULL` name. It returns `NULL` for a name the panel lacks, which
  `epi_config_t` also takes as the default.
- The docs now say to start a custom intent from a copy of a preset: a
  zero-initialised intent has vibrance 0, which removes colour.

## v0.3.0

Lightens the colour presets' lower midtones, corrects the EL133UF1's green cast
on near-neutral greys, and replaces the Vivid preset with Bright. Intents and
colour panel configs gain fields, which breaks the API.

**Panel output:** EL133UF1 frames change for every preset: lower midtones are
lighter, and greys built from coloured inks no longer look green. Grey and mono
output is unchanged.

### Breaking changes

- `epi_intent_t` gains `lift`: L* added to lower midtones, fading out by L* 82
  and sparing saturated colours, 0 to 20. An intent initialised without it gets
  0, the old rendering.
- `epi_colour_panel_config_t` gains `neutral` and `neutral_count`, an optional
  neutral-cast correction. A zero-initialised config has none. Init rejects a
  `NULL` `neutral` with a non-zero count, or the reverse.
- The EL133UF1 and runtime colour panels offer Default, Soft, Deep and Bright.
  Vivid is gone; for its chroma boost, set `vibrance` to 1.3 on any intent.

### Added

- Colour presets lift by 8, because paper white is far darker than a screen's
  and unlifted lower midtones read dark. Bright (tone 0.5, lift 16) is for
  low-key images that still read dark at 8. Grey presets keep lift 0.
- `epi_neutral_knot_t`: a* and b* offsets keyed on final L*, interpolated
  between up to 16 knots and faded out between chroma 12 and 32. The built-in
  EL133UF1 carries knots measured on the glass.
- `convert` gains `--lift`, and `--compare` keys record it.

## v0.2.0

Adds linear-light previews of any size, and colour panels built at runtime from
measured inks. The converter now outputs ink codes only, which breaks the API.

**Panel output:** EL133UF1 frames change. Two cusp table entries move by one,
which reseeds the dither, so the frames differ pixel by pixel but look the same
on the panel. Grey and mono output is unchanged.

### Breaking changes

- `epi_converter_pop` writes `width` ink codes into a `uint8_t*`. Pack them for
  the panel with `epi_pack_row`, or pass them to `epi_preview_push`. Firmware
  streaming to a panel needs that call and a row buffer, and the converter's
  workspace shrinks by one row.
- `epi_output_t`, `EPI_OUT_*`, `epi_config_t.output` and `epi_output_row_size`
  are removed.
- A panel whose codes don't fit a packed format is rejected by `epi_pack_row`,
  not at converter init.
- `epi_grey_panel_init` takes a new `const char** reason`, which may be `NULL`.
  It gets a short static string on every `EPI_ERR_INVALID_ARG`.

### Added

- `epi_preview_*` reduces rows of ink codes to an RGB preview of any smaller
  size, averaging in linear light with integer weights, so the output is the
  same on every platform.
- `epi_pack_row`, `epi_pack_row_size` and `epi_pack_format_t` pack a row of ink
  codes for the panel.
- `epi_colour_panel_init` and `epi_colour_panel_size` build a colour panel from
  5 to 16 measured inks in caller storage, with no allocation or libm, and the
  same result on every target. This takes about 6 s on a 240 MHz ESP32-S3. An
  optional `epi_progress_fn_t` callback can yield to other tasks, or cancel,
  which returns the new `EPI_ERR_CANCELLED`.
- `convert` gains `--preview-scale`.

Init rejects inks whose nominal colours disagree with the measurements: a white
ink (the largest measured Y) whose nominal Y is below another ink's, or a black
ink (the smallest measured Y) whose nominal Y is above another ink's.

### Tools and packaging

- `panelgen` now runs the library's derivation, so a built-in panel equals the
  runtime panel from the same inks. It no longer needs numpy or scipy.
- The component package leaves out `.clang-format`, `.clang-format-ignore`,
  `.gitignore`, `docs/Doxyfile`, `docs/html` and `docs/xml`.

## v0.1.1

`epi_panel_t` can now be forward-declared, so a header can use it without
including `<epaper_image.h>`: `typedef struct epi_panel epi_panel_t;`. Its fields
and layout are unchanged, existing code still compiles, and panel output is
unchanged.

Also tidies the remaining American spellings in code comments and docs. The
public API was already British and doesn't change.

## v0.1.0

First release of epaper-image, a C11 library that converts images for e-paper
panels: streaming resampling, tone adjustment, palette matching and error
diffusion.

Built-in panels: EL133UF1 (Spectra 6) and GDEY075T7 (mono and 4 greys).