/*
 * pop_arc.h — архив ресурсов PBA1: много файлов в одном, один open на всех.
 *
 * ЗАЧЕМ.  Замер в MAME (2026-08-25): `open` стоит 51,4 мс, а чтение 16 КБ из
 * уже открытого файла — 32,6 мс.  То есть 61 % времени загрузки уходит на
 * открытие, а не на данные, и одна только стартовая пачка ресурсов (~142
 * файла) — это 7,3 секунды чистого `open`.  Архив открывается ОДИН раз на
 * группу, и эта цена платится один раз вместо сотни.
 *
 * ФОРМАТ (генерирует toolchain/pop_pack_arc.py):
 *   0..3  'PBA1'   магия и версия
 *   4     count    число записей, 1..126
 *   8..   записи по 4 байта: offset в СЕКТОРАХ по 512 (uint16),
 *                            size в байтах (uint16)
 *   данные с 512, каждый элемент выровнен на 512.
 * Оффсет в секторах, потому что архив может быть больше 64 КБ (pv — мегабайт);
 * размер в байтах, потому что ни один ресурс не крупнее 16 КБ — он обязан
 * помещаться в EMM-страницу.
 *
 * ТАБЛИЦУ ДЕРЖИТ ВЫЗЫВАЮЩИЙ, на своём стеке: 4 байта на запись, у самой
 * большой группы 320 байт.  В W2 её класть нельзя — там осталось около сотни
 * байт, — а стека в точке загрузки ресурсов израсходовано 75 байт из 1279
 * (замер там же).  Так модуль не занимает постоянной памяти вовсе.
 */
#ifndef POP_ARC_H
#define POP_ARC_H

#include <stdint.h>
#include <sprite.h>   /* atlas_t */

#define POP_ARC_HEADER   512
#define POP_ARC_SECTOR   512
#define POP_ARC_MAX      126     /* (512-8)/4 */
#define POP_ARC_REC      4       /* байт на запись таблицы */

/* Имя у структуры есть намеренно: так на неё можно сослаться из заголовков,
 * которым незачем тянуть весь pop_arc.h (pop_ui.h). */
typedef struct pop_arc_s {
    int     fd;
    uint8_t count;
} pop_arc_t;

/* ИМЕНА АРХИВОВ ЗНАЕТ САМ МОДУЛЬ, и это не вкусовщина: строковый литерал
 * лежит в rodata СВОЕГО банка, а pop_arc.c живёт в банке 8.  Указатель на
 * литерал из другого банка после переключения W3 показывает на чужие
 * данные — ровно так «BG\bg.arc» превращался в мусор и загрузка фона
 * падала (поймано 2026-08-26).  Поэтому наружу отдаём НОМЕР архива. */
typedef enum {
    POP_ARC_BG = 0,
    POP_ARC_KID,
    POP_ARC_GUARD,
    POP_ARC_SKEL,
    POP_ARC_VIZIER,
    POP_ARC_SHADOW,
    POP_ARC_TITLE,
    POP_ARC_PV,
    POP_ARC_SND,
    POP_ARC_IDS
} pop_arc_id_t;

/* Открыть архив по номеру: то же, что pop_arc_open, но имя берётся из
 * таблицы внутри модуля. */
int8_t pop_arc_open_id(pop_arc_t *a, uint8_t id,
                       uint8_t *tbl, uint8_t tbl_max) __banked;

/* Открыть архив и вычитать таблицу в буфер вызывающего (count*4 байт).
 * tbl_max — сколько записей помещается в буфер.
 * Возврат: число записей; -1 — не открылся, не PBA1 либо таблица не влезла. */
int8_t pop_arc_open(pop_arc_t *a, const char *path,
                    uint8_t *tbl, uint8_t tbl_max) __banked;

/* Размер элемента idx по таблице (0, если индекс за пределами). */
uint16_t pop_arc_size(const uint8_t *tbl, uint8_t idx);

/* Прочитать кусок элемента idx в EMM-страницу: skip байт от его начала,
 * size байт, в страницу page со смещением off.  size == 0 — весь элемент.
 * Возврат: сколько прочитано, -1 — ошибка. */
int pop_arc_read(pop_arc_t *a, const uint8_t *tbl, uint8_t idx, uint16_t skip,
                 uint8_t page, uint16_t off, uint16_t size) __banked;

void pop_arc_close(pop_arc_t *a) __banked;

/* Атлас ПРЯМО ИЗ АРХИВА: выделить страницу, вычитать в неё элемент idx и
 * отдать libbgi (atlas_attach — проверка магии + подготовка страницы к
 * маппингу в W0).  Полный эквивалент atlas_load, только источник другой.
 * 0 — OK, -1 — ошибка (страница освобождена). */
int8_t pop_arc_atlas(pop_arc_t *a, const uint8_t *tbl, uint8_t idx,
                     atlas_t *at) __banked;

#endif /* POP_ARC_H */