/*
 * pop_ui.h — общий экранный слой PoP (FG5, банк 9).
 *
 * Здесь только примитивы: исходный SDLPoP-шрифт, палитровый fade и сборка
 * полной страницы. Menu, title и cutscene держат собственные автоматы и
 * строки, но не дублируют формат FONT.ATL или опасную работу с W0.
 */
#ifndef POP_UI_H
#define POP_UI_H

#include <stdint.h>

typedef enum {
    POP_TEXT_SMALL = 0,
    POP_TEXT_BIG = 1
} pop_text_font_t;

/* Жизненный цикл единственного FONT\FONT.ATL. Загрузка — в холодном boot,
 * освобождение — после закрытия графики; повторные вызовы безопасны. */
int     pop_ui_init(void) __banked;
void    pop_ui_free(void) __banked;
uint8_t pop_ui_ready(void);

/* Группа text_*_mapped требует активного pop_text_map() и не вызывает
 * BIOS/ESTEX. Для прозрачных букв установить GFX_BANK_SPRITE до рисования. */
void    pop_text_map(void);
void    pop_text_unmap(void);
uint8_t pop_text_width_mapped(pop_text_font_t font, const char *s);
void    pop_text_draw_mapped(pop_text_font_t font, int x, int baseline,
                             const char *s);
void    pop_text_center_mapped(pop_text_font_t font, int center, int baseline,
                               const char *s);
void    pop_text_right_mapped(pop_text_font_t font, int right, int baseline,
                              const char *s);

/* Снимок обеих (идентичных по контракту) палитр хранится в свободном хвосте
 * FONT.ATL. dim_step: 0 — исходная, 1 — ~75%, 2 — 50%, 3 — 25%, 4 — чёрная.
 * keep_ui сохраняет диапазон 0x37..0x3F ярким для текста/рамки меню. */
void pop_ui_palette_snapshot(void) __banked;
void pop_ui_palette_dim(uint8_t dim_step, uint8_t keep_ui) __banked;
void pop_ui_palette_restore(void) __banked;

/* Немедленно погасить все 256 цветов обеих страниц. В отличие от dim(),
 * не требует загруженного FONT.ATL: это ранний экран запуска, когда в VRAM
 * ещё может лежать картинка предыдущей программы. */
void pop_ui_palette_black(void) __banked;

/* Пошаговый fade к снимку: fade_out сначала делает снимок, fade_in требует
 * его сохранить. Каждый шаг показывается на следующем фронте. */
void pop_ui_fade_out(uint8_t steps) __banked;
void pop_ui_fade_in(uint8_t steps) __banked;

/* Полная экранная страница: begin выбирает скрытую страницу, fill рисует
 * непрозрачный фон и present делает ГОТОВУЮ страницу видимой на фронте.
 * Текст на второй странице надо нарисовать заново — GFX_BANK_SPRITE не
 * меняет shadow-копию, и это сознательный контракт временного UI. */
uint8_t pop_screen_begin(void) __banked;
void    pop_screen_fill(uint8_t color) __banked;
/* Индекс палитры для всего, что ВНЕ игрового поля 320x192 (борта, полоса
 * HP).  В палитре он чёрный, но НЕ нулевой — поэтому вспышки, которые
 * подменяют цвет 0, не задевают рамку и жизни. */
#define POP_COL_OUTSIDE 1
/* Подготовить экран под игру: вне поля POP_COL_OUTSIDE, внутри — цвет 0.
 * Звать на СТАРТЕ и смене уровня; заодно сбрасывает служебные полосы. */
void    pop_screen_fill_game(void) __banked;
/* Только игровое поле (борта и всё, что на них, не трогает) — это путь
 * входа в комнату. */
void    pop_screen_fill_field(void) __banked;
void    pop_screen_present(uint8_t page) __banked;

/* Нарисовать в уже выбранную draw-страницу набор вертикальных полос SPA1.
 * Полоса загружается, блитится и тут же освобождается; функция не вызывает
 * BIOS/vsync, поэтому её можно безопасно применять в title и cutscene.
 * Возвращает -1 при ошибке чтения очередной полосы. */
int     pop_screen_blit_atlas_strips(const char * const *parts,
                                     uint8_t count, int x, int y) __banked;

/* Те же полосы, но из архива ресурсов: элементы base..base+count-1.
 * Один `open` на экран вместо одного на полосу. */
int     pop_screen_blit_atlas_arc(struct pop_arc_s *arc, const uint8_t *tbl,
                                  uint8_t base, uint8_t count,
                                  int x, int y) __banked;

#endif /* POP_UI_H */