Sprinter-SDCC/libbgi/include/sprite.h

/*
 * sprite.h — managed-движок спрайтов (retained-модель) поверх ядра
 * gfx_blit/gfx_heal.  Дизайн: docs/sprite-api-design.md §9.1.
 *
 * Мотивация — profile examples/balls vs asm-референса docs/samples/balls
 * (2026-07-12): ~2× разрыв не в W3-скобке, а в per-call C-обвязке
 * (клип/парс заголовка/save-restore банка/SDCC-фрейм), повторяемой 2×N
 * раз за кадр.  Движок амортизирует её: sprite_update держит ОДНУ
 * W3-скобку и ОДИН банк на весь ПРОХОД, вызывая bracket-free ядра
 * (_gfx_heal_full/_gfx_blit_full) в цикле по спрайтам.  DI остаётся
 * гранулярным (по строке в leaf) — под CBL/IM2-аудио длинный DI
 * недопустим.
 *
 * Retained-модель: sprite_move/frame/show/hide/touch меняют ТОЛЬКО
 * состояние (O(1), сколько угодно раз за кадр); всё рисование —
 * один раз в sprite_update, двухпроходно «heal ВСЕ → блит ВСЕ» (слияние
 * per-sprite выкусывает соседей на перекрытии — проверено).  Учёт
 * «где спрайт реально нарисован на КАЖДОЙ из двух страниц» (drawn[2])
 * ведёт движок, не приложение.
 *
 * Формат картинки — getimage (uint16 w, uint16 h, пиксели построчно,
 * 1 байт/пиксель в 256-режиме); 0xFF = прозрачно (банк 0x5C).  Буфер
 * обязан лежать ВНЕ W3 (< 0xC000).  Размер КАДРА спрайта ≤ 64×64
 * (требование движка): кэш w,h — uint8_t, и блит идёт лин-ядром без
 * split'а на полосы >256 (спрайт заведомо ≤256 в строке).  Для больших
 * картинок — gfx_blit/putimage напрямую (там общий путь со split'ом).
 * ЛЕНТА-АТЛАС может быть шире 64 (img_w — шаг), но КАДР ≤ 64.
 *
 * z-order = индекс в массиве (последний рисуется сверху).  Массив
 * владеет приложением: без malloc, без лимитов; пересортировка z =
 * перестановка элементов (drawn-состояние едет со структурой).
 */
#ifndef SPRITE_H
#define SPRITE_H

#include <stdint.h>

/* Публичные флаги sprite_t.flags. */
#define SPR_VISIBLE  0x01u   /* спрайт рисуется в sprite_update            */
#define SPR_ALWAYS   0x02u   /* перерисовывать КАЖДЫЙ кадр (статик, над    */
                             /* которым постоянно ходят активные спрайты) */

/* Внутренние dirty-биты (владеет движок): «страница p требует обновления
 * этого спрайта».  Приложению не трогать — только через sprite_*. */
#define _SPR_DIRTY0  0x04u
#define _SPR_DIRTY1  0x08u
#define _SPR_DIRTY   (_SPR_DIRTY0 | _SPR_DIRTY1)

typedef struct {
    const void *img;     /* getimage-формат / атлас-лента (вне W3)         */
    int   x, y;          /* ЛОГИЧЕСКАЯ позиция левого-верхнего угла кадра  */
    int   sx, sy;        /* смещение кадра внутри img (атлас; 0 = целая)   */
    uint8_t w, h;        /* размер кадра (кэш заголовка), 1..255           */
    uint8_t flags;       /* SPR_* | внутренние dirty                       */
    uint8_t page;        /* 0 = img в обычной памяти; иначе физ. страница  *
                          * W0-атласа (img — адрес 0x0100-0x3FFF, движок   *
                          * сам мапит страницу в W0 на время блита)        */
    /* --- внутреннее (владеет движок) --- */
    struct {
        int x, y;        /* где нарисован на странице p                    */
        uint8_t on;      /* нарисован ли на странице p                     */
    } drawn[2];
} sprite_t;

/* Инициализация: w,h из заголовка img, невидим, ничего не нарисовано.
 * Для АТЛАСА (кадр — под-прямоугольник) после init выставить s->w/s->h
 * в размер кадра и s->sx/s->sy — на нужный кадр (или sprite_frame). */
void sprite_init(sprite_t *s, const void *img);

/* Кадр всей сцены: на ТЕКУЩЕЙ draw-странице (gfx_get_draw_page)
 * heal ВСЕХ старых позиций → блит ВСЕХ видимых (двухпроходно, одна
 * скобка/банк на проход).  Спрайты без изменений с прошлого визита этой
 * страницы (и без SPR_ALWAYS) не трогаются.  Для дабл-буфера звать после
 * gfx_set_draw_page(hidden); для одиночной страницы/курсора — прямо на
 * видимой. */
void sprite_update(sprite_t *arr, uint8_t count);

/* Сахар канонического дабл-буфер-кадра: draw-страница = скрытая →
 * sprite_update → gfx_wait_vsync → сделать скрытую видимой (tear-free).
 * Динамический фон/HUD рисовать банком 0x50 на скрытой странице ДО
 * sprite_flip — тогда heal учтёт его через ОЗУ-копию. */
void sprite_flip(sprite_t *arr, uint8_t count);

/* --- O(1) изменения состояния (inline: без call-оверхеда в физике) --- */

/* Переместить: меняет только логическую позицию + грязнит обе страницы. */
inline void sprite_move(sprite_t *s, int x, int y) {
    if (s->x != x || s->y != y) { s->x = x; s->y = y; s->flags |= _SPR_DIRTY; }
}

/* Сменить кадр атласа (под-прямоугольник img). */
inline void sprite_frame(sprite_t *s, int sx, int sy) {
    if (s->sx != sx || s->sy != sy) { s->sx = sx; s->sy = sy; s->flags |= _SPR_DIRTY; }
}

/* Показать (если был скрыт — грязнит обе страницы). */
inline void sprite_show(sprite_t *s) {
    if (!(s->flags & SPR_VISIBLE)) s->flags |= (SPR_VISIBLE | _SPR_DIRTY);
}

/* Скрыть (если был виден — грязнит: sprite_update сотрёт heal'ом). */
inline void sprite_hide(sprite_t *s) {
    if (s->flags & SPR_VISIBLE) { s->flags &= ~SPR_VISIBLE; s->flags |= _SPR_DIRTY; }
}

/* Принудительная перерисовка на ОБЕИХ страницах (напр. после того как
 * активный спрайт прошёл над статиком — приложение помечает статик). */
inline void sprite_touch(sprite_t *s) { s->flags |= _SPR_DIRTY; }

/* ==== Атласы в EMM-страницах (W0) ====================================
 * Файл .atl (docs/sprite-api-design.md §3.1, вариант II): 0x100-байтовый
 * заголовок (магия 'SPA1', count; каталог с 0x68) + getimage-ленты;
 * файл-офсет == офсет в странице == адрес в W0.  Загрузчик читает файл
 * ЦЕЛИКОМ в EMM-страницу через W3 и патчит ISR-стаб (0x38/0x66) —
 * страница безопасна в W0 при включённых прерываниях (§9в).
 *
 * ВАЖНО: указатели лент — адреса 0x0100-0x3FFF, разыменовывать их можно
 * ТОЛЬКО при подключенной странице (sprite_update мапит сам; для ручного
 * putsprite/gfx_blit_part — обернуть в gfx_w0_map/gfx_w0_unmap).
 * Пока страница в W0 — НИКАКИХ ESTEX/BIOS-вызовов. */

typedef struct {
    uint8_t page;        /* физ. страница (маппить в W0/W3)     */
    uint8_t blk;         /* EMM-блок — для atlas_free           */
    uint8_t count;       /* число лент в атласе                 */
} atlas_t;

/* Загрузить .atl в свежую EMM-страницу (read в W3 + патч стаба).
 * 0 — OK; -1 + errno (файл/память/формат). */
int  atlas_load(atlas_t *a, const char *path);

/* Освободить EMM-страницу атласа (все sprite_t с его лентами должны
 * быть скрыты/переинициализированы ДО вызова). */
void atlas_free(atlas_t *a);

/* Указатель-лента idx (W0-адрес, см. ВАЖНО выше) — для gfx_blit_part
 * и ручных вызовов; кадр (i,j) ленты: sx = i*fw, sy = j*fh. */
const void *atlas_image(const atlas_t *a, uint8_t idx);

/* Инициализировать спрайт лентой idx атласа: img/w/h (размер КАДРА из
 * каталога) /page; невидим, кадр (0,0).  Аналог sprite_init для W0. */
void atlas_sprite_init(sprite_t *s, const atlas_t *a, uint8_t idx);

/* Ручное подключение страницы атласа в W0 (для putsprite/gfx_blit_part
 * вне движка).  map ставит и _gfx_w0_cur (ISR-стаб восстановит страницу
 * после прерывания), unmap возвращает страницу ядра DSS. */
void gfx_w0_map(uint8_t page);
void gfx_w0_unmap(void);

#endif