# 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).