/*
 * pop_snd_tbl.h — РАСКЛАДКА ОЦИФРОВАННЫХ ЭФФЕКТОВ: тип и инварианты.
 *
 * Раньше этот файл ПЕЧАТАЛ упаковщик (gen/pop_sound_tbl.h), и конкретные
 * page/off/len становились частью EXE — из-за чего замена звукового набора
 * (SDLPoP <-> MSDOS) требовала перекомпиляции игры.  Теперь значения
 * приезжают с диска (SND/snd.idx, формат PSI1 — tools/pop_idx.py), а
 * здесь остаётся только то, что от набора НЕ зависит: устройство записи и
 * пределы, на которые рассчитан загрузчик.
 *
 * ЗАПИСЬ ЧИТАЕТСЯ С ДИСКА ПОБАЙТОВО, прямо в pop_snd_tbl[].  Значит
 * раскладка структуры в ABI SDCC z80 (uint8 + uint16 + uint16 подряд, без
 * выравнивания = 5 байт) — часть дискового контракта, а не деталь
 * компилятора.  Расхождение молча разъехало бы весь набор, поэтому оно
 * ловится статически (pop_snd_data.c) и проверяется загрузчиком по полю
 * размера записи в заголовке индекса.
 */
#ifndef POP_SND_TBL_H
#define POP_SND_TBL_H

#include <stdint.h>

/* Пространство id оригинала: 0..56.  От набора не зависит. */
#define POP_SND_COUNT       57
/* Блок запроса CBL при 8 бит; страница EMM кратна ему, поэтому ни один
 * блок не пересекает границу страницы (см. docs/sound_plan.md). */
#define POP_SND_BLOCK       128
/* СКОЛЬКО СТРАНИЦ ГОТОВ ПРИНЯТЬ ЗАГРУЗЧИК — вместимость, а НЕ размер
 * конкретного набора: тот приходит в индексе (pop_snd_pages).  Запас
 * ради будущих наборов без перекомпиляции; цена — 16 байт таблицы
 * страниц вместо 9-10. */
#define POP_SND_MAX_PAGES   16

/* ПЕРВЫЙ БЛОК СТРАНИЦЫ 0 — ТИШИНА.  Насос льёт её, когда играть нечего:
 * без этого железо доигрывает по кругу хвост своего буфера (жужжание).
 * Это инвариант ПРОГРАММЫ — упаковщик обязан оставить блок свободным, а
 * загрузчик проверяет, что ни одна запись в него не залезла. */
#define POP_SND_SILENCE_PAGE 0
#define POP_SND_SILENCE_OFF  0x0000

/* page — индекс в pop_snd_page[] (физические страницы EMM), off — начало
 * внутри страницы, len — длина PCM.  Оба кратны POP_SND_BLOCK; len == 0
 * значит «у этого id нет оцифровки» (это музыка, см. sound_plan.md). */
typedef struct {
    uint8_t  page;
    uint16_t off;
    uint16_t len;
} pop_snd_ent_t;

#endif /* POP_SND_TBL_H */