Учебник: игра класса Zuma на ZX-Evo TS-Config + VDAC2/FT812

Практическое руководство по FT812, TS-Config, SD-Card и General Sound на реальном проекте Zuma VDAC2

Накопительный конспект материала. По мере разбора датшитов, источников и собственных экспериментов — здесь оседают факты, формулы, код-примеры, схемы и решения. Из этого вырастет полноценный учебник.

Целевая аудитория: разработчики на Z80 (sjasmplus / asm), которые хотят разобраться с ZX-Evo, TS-Conf, VDAC2 и выводом через FT812.

Короткие определения перед стартом:

• ZX-Evo / ZX Evolution (Pentevo) — современная ZX Spectrum-совместимая платформа, на которой работает проект.

• TS-Conf — расширенная конфигурация ZX-Evo от TS-Labs: видеорежимы, страничная память, DMA и порты управления экраном/периферией. В этом учебнике TS-Conf даёт Z80-окружение, страницы памяти, DMA и порты, а финальную картинку игры выводит FT812 через VDAC2.

• VDAC2 — плата видеовыхода для ZX-Evo с видеочипом FT812.

• FT812 — видеочип Bridgetek/FTDI EVE. Z80 отправляет ему команды и данные через SPI, а FT812 сам формирует VGA/RGB-сигнал.

• Display List (DL) — список 32-битных команд рисования FT812. Он хранится во внутренней памяти RAM_DL (8 КБ, адреса 0x300000..0x301FFF). Это не готовая картинка, а команды вроде CLEAR, BITMAP_HANDLE, VERTEX2II, DISPLAY.

• Командный процессор FT812 — внутренний обработчик команд FT812; в документации EVE/TSLib его часто называют co-processor (далее — копроцессор). Z80 пишет команды в кольцевой буфер RAM_CMD (4 КБ), а копроцессор разворачивает их в настоящий Display List или операции с памятью.

Структура учебника

Учебник состоит из двух частей. Подробное оглавление со ссылками генерируется автоматически (раздел «Оглавление» выше в HTML/PDF).

Часть I. Основы FT812 / VDAC2 (главы 1–11) — фундамент, выведенный из датшитов и TSLib: аппаратная связка ZX-Evo+VDAC2, SPI-протокол, memory map, видеотайминги 640×480, список команд рисования FT812 (Display List / DL), bitmap-форматы, производительность/DMA, главный цикл рендера и карта TSLib API. Читается линейно как введение.

Часть II. Журнал разработки Zuma (главы 12–40) — практический опыт в хронологическом порядке: каждая глава фиксирует конкретную задачу/баг/решение с датой и ссылками на код, baseline и память. Главы самодостаточны — можно читать выборочно по теме. Сквозные темы:

Маршрут по подсистемам для первого чтения:

• FT812 / VDAC2: главы 1–7, 9–12, 15–27, 35 и 40.1–40.2. Здесь memory map, SPI-транзакции, Display List (DL), RAM_CMD, bitmap-форматы, копроцессор FT812, матрицы, стоимость форматов и ограничения pixel-clock budget.

• TS-Config: главы 1.2–1.3, 7, 22, 28, 32, 34 и 40.3. Здесь VCONFIG/DMA, страничная память, общая SPI-шина, Mr.Gluk RTC и AT/PS/2-клавиатура.

• Дисковая подсистема SD-Card: главы 30 и 36. Здесь CMD17, FAT32/LFN, RawPak, PAK-таблицы, двойной проход сборки и инжект в образ.

• Звуковая подсистема General Sound: главы 33, 37 и 40.5. Здесь порты, handshake, MOD, SFX, preload, FIFO и отличия эмулятора от реального железа.

• Реальное железо против эмулятора: главы 25, 29, 34, 38 и 40.7. Здесь указано, какие проверки можно доверять харнессам, а какие обязаны проходить на настоящем FT812/ZX-Evo.

• Рендеринг и оптимизация списка команд FT812 (DL): 12 (bitmap matrix/scale/paletted), 16 (persistent DL state), 17 (vsync-first), 20 (render-loop приёмы), 21 (адаптивная группировка матриц шаров), 23 (PALETTED4444 шаров), 24 (бюджет строки FT812), 26 (BITMAP_HANDLE binding), 27 (matrix LUT, ARGB4 frog → fix tearing).

• Фон уровня: 18–19 (DXT1-эмуляция L2/L4), 24 (почему перешли на единый PALETTED4444-проход).
• Игровые объекты: 13, 15 (композиция лягушки), 14 (RNG), 28 (RTC-часы).
• Инструменты и методология: 25 (эмулятор EveApps + дамп RAM_DL), 29 (когда эмулятор сам врёт — источник истины = RAM dump).
• Загрузка с SD: 30 (FAT32-драйвер: эволюция от WC ZiFi к собственному CMD17+LFN).
• Игровые системы (adventure): 31 (выбор уровня, параметры из таблицы, перенос счёта, Win/Pause).
• Ввод: 28 (RTC через Mr.Gluk), 32 (опрос PC-клавиатуры через PS/2 FIFO + единый глобальный модуль Input.asm: клавиатура/Kempston/мышь, навигация меню).
• Звук (General Sound): 33 (музыка MOD и SFX из PAK: порты/handshake, загрузка модуля, возврат в меню без повторного BASS_MusicLoad, добивка хвоста сэмпла тишиной).
• Реальное железо vs эмулятор: 34 (SPI SD-карта на общей шине с FT812, byte/block-адресация и «кирпич» карты, граница LBA; General Sound на реале — поиск пака в папке, порядок данных в FIFO; инициализация; диагностика на железе без F12), 38 (clear-on-read REG_INT_FLAGS → зависание всех переходов; привязка анимации к progress-событиям, а не к времени/циклам; фолты/таймауты копроцессора; чем харнесс/эмулятор НЕ моделируют реал).
• Апскейл-рефактор: 35 (640×480 → 1024×768 ×1.6: запрет нецелого CMD_SCALE, запечённые матрицы 160/256, точная арифметика констант, переполнение VERTEX2F/VERTEX2II, BILINEAR-стык тайлов).
• Дисковая подсистема (сборка): 36 (четыре пака; грабля рассинхрона make_main_pack.py --table↔--pack и двойной проход; трек-сплит на 2 страницы; инжект в образ) — дополняет 30 (ридер).
• Звук (углубление): 37 (детект GS_Present; ловушка «звук молчит без PRELOAD_IDS»; стрим MOD и его роль в тиках анимации; SFX с питчем GS_PlaySfxNote) — дополняет 33.
• Подтяжка цепи: 39 (PULL/CATCH-UP/отдача в slot-модели; 5 дефектов рывков квантованной модели; дробный накопитель декея; rear-comp до конца цепи; Z80-ловушка PUSH AF/POP AF; win-регрессия и урок gaugeFull=1).
• Свод граблей: 40 (чек-лист перед коммитом по всем классам: матрицы/координаты, DL и копроцессор FT812, SPI-шина, сборка, звук, Z80-идиомы, реал-vs-эмулятор, тестирование).

Нумерация глав сквозная (1→40). Историческое примечание: ранние версии учебника использовали отдельные пометки §N/§M/§R и нумерацию журнала с 18 — в ревизии 2026-05-26 всё приведено к сплошной нумерации.

1. Аппаратная связка ZX-Evo + VDAC2

1.1. Что такое VDAC2

VDAC2 — расширительная плата для ZX-Evo, заменяющая стандартный 5-bit VDAC. Содержит чип FT812 (FTDI Embedded Video Engine):

• 1 МБ графической памяти RAM_G
• Display List (DL): список 32-битных команд рисования в RAM_DL (8 КБ)
• копроцессор FT812 с командным буфером RAM_CMD (4 КБ)

• VGA/RGB-выход; в проекте 640×480 — логическое пространство игровой механики, а 1024×768 — поздний режим вывода с апскейлом 8/5

• RGB-выход 8 бит на канал

• SPI-интерфейс к хосту (Z80): FT812 допускает SCLK до 30 MHz, но в нашем Z80-пути скорость ограничивает не этот предел, а OUT/OTIR через порт SPI_DATA. При SYS_ZCLK14 это примерно 14 МГц / 21 такт = ~666 КБ/с для длинного OTIR-блока без учёта заголовка SPI; при 7 МГц было бы ~333 КБ/с.

В STATUS-регистре TS-Conf версия адаптера:

• 000 — 2-bit VDAC + PWM
• 001/010/011 — 3/4/5-bit VDAC
• 111 — VDAC2 (FT812) ← наш случай

Sanity-check на старте программы:

    IN A, (0xAF)      ; STATUS
    AND %00000111
    CP  %00000111
    JR  NZ, .no_vdac2 ; на этой плате FT812 нет → fallback на TS-Conf рендер

1.2. Порты TS-Conf для общения с FT812

Магические значения SPI_CTRL:

• 0x03 — SPI_FT_CS_OFF (FT812 disable)
• 0x07 — SPI_FT_CS_ON (FT812 enable)

1.3. VCONFIG для VDAC2-режима

    LD  A, %00100100   ; FT_EN=1 (bit 2), NO_GFX=1 (bit 5)
    OUT (0xAF), A

NO_GFX=1 отключает обычный TS-Config рендер пикселей. Это экономит DMA-циклы: лимит DMA на строку = 448 циклов, обычно расходуются на чтение VRAM для отрисовки спектрум-экрана. С NO_GFX=1 эти циклы целиком уходят CPU и DMA-пересылке байт в FT812. На бордюре чтения и так нет — там всегда полный лимит свободен.

2. SPI-протокол FT812

2.1. Три типа транзакций (по 2-битному префиксу)

На уровне Z80 префикс — это два старших бита первого отправляемого байта адреса:

• Read: первый байт = addr[21:16] (биты 7..6 = 00)
• Write: первый байт = addr[21:16] OR 0x80 (биты 7..6 = 10)
• Host command: первый байт = 0x40 OR cmd[5:0]

2.2. Каждая транзакция в обёртке CS

FT_ON                  ; OUT (0x77), 0x07 — взвести CS
... последовательность OUT/IN через 0x57 ...
FT_OFF                 ; OUT (0x77), 0x03 — снять CS

Внутри одной транзакции адрес FT812 авто-инкрементируется — длина блока не ограничена, если данные пишутся в непрерывную область памяти. Это позволяет одной транзакцией залить весь Display List или большой bitmap.

2.3. Готовые asm-функции (из учебника #2)

Макросы CS

FT_ON:   MACRO
    LD  A, 0x07         ; SPI_FT_CS_ON
    OUT (0x77), A       ; SPI_CTRL
ENDM

FT_OFF:  MACRO
    LD  A, 0x03         ; SPI_FT_CS_OFF
    OUT (0x77), A
ENDM

FT_VMODE: MACRO
    LD  A, %00100100    ; FT_EN=1, NO_GFX=1
    OUT (0xAF), A
ENDM

FT_RD8 — чтение байта из RAM_REG

; In:  DE = addr[15..0] (адрес внутри RAM_REG, старший байт фиксирован = 0x30)
; Out: A  = прочитанный байт
; Corrupts: AF
FT_RD8:
    FT_ON
    LD  A, 0x30          ; FT_RAM_REG >> 16 = 0x30
    OUT (0x57), A        ; addr[21..16] (префикс 00b — read)
    LD  A, D
    OUT (0x57), A        ; addr[15..8]
    LD  A, E
    OUT (0x57), A        ; addr[7..0]
    OUT (0x57), A        ; dummy OUT (FT812 готовится)
    IN  A, (0x57)        ; dummy IN (особенность чтения)
    IN  A, (0x57)        ; реальные данные
    PUSH AF
    FT_OFF
    POP AF
    RET

Важно: для чтения всегда нужен один dummy OUT + один dummy IN после трёх байт адреса, иначе следующий IN вернёт мусор.

FT_RD16

; In:  DE = addr[15..0]
; Out: BC = прочитанное 16-битное значение (little-endian)
FT_RD16:
    FT_ON
    LD  A, 0x30 : OUT (0x57), A
    LD  A, D    : OUT (0x57), A
    LD  A, E    : OUT (0x57), A
    OUT (0x57), A         ; dummy OUT
    IN  A, (0x57)         ; dummy IN
    IN  A, (0x57) : LD C, A   ; младший байт
    IN  A, (0x57) : LD B, A   ; старший байт
    FT_OFF
    RET

FT_WR8 — запись байта в регистр

; In:  DE = addr[15..0], A = записываемое значение
FT_WR8:
    PUSH AF
    FT_ON
    LD  A, (0x30) OR 0x80   ; bit 7 = 1 → префикс 10b → write
    OUT (0x57), A
    LD  A, D : OUT (0x57), A
    LD  A, E : OUT (0x57), A
    POP AF
    OUT (0x57), A           ; данные
    FT_OFF
    RET

FT_Write — блочная запись через OTIR

; In:  HL = Z80-источник, BC = количество байт,
;      A  = addr[21..16] (без bit 7), DE = addr[15..0]
; Out: HL += BC, ADE += BC (для chained-вызовов)
FT_Write:
    PUSH AF
    FT_ON
    POP  AF
    PUSH AF
    OR   0x80               ; включаем bit 7 — write префикс
    OUT  (0x57), A
    LD   A, D : OUT (0x57), A
    LD   A, E : OUT (0x57), A
    POP  AF

    ; пересчитать адрес для следующего вызова: HL += BC, ADE += BC
    EX   DE, HL
    ADD  HL, BC
    EX   DE, HL
    ADC  A, 0
    PUSH AF

    ; основной OTIR loop (256-байтные пакеты)
    LD   A, C   : OR A      ; есть младший хвост?
    LD   A, B               ; A = количество полных пакетов
    LD   B, C               ; B = младший байт count'а
    LD   C, 0x57            ; SPI_DATA
    JR   Z, .loop

    OTIR                    ; неполный пакет
    OR   A
    JR   Z, .exit

.loop:
    OTIR                    ; B=0 → 256 байт
    DEC  A
    JR   NZ, .loop

.exit:
    FT_OFF
    POP  AF
    RET

FT_Read строится симметрично через INIR, без bit 7 в первом байте + dummy перед циклом.

2.4. Когда размер блока удобен

• Заливка bitmap в RAM_G — одна транзакция на килобайты
• Полный DL (до 8 KB) — одна транзакция
• Запись в RAM_CMD кольцевого буфера — порциями до wrap’а

3. Memory Map FT812

22-битное адресное пространство; всё mapped единообразно по SPI:

Endianness: little-endian для всех многобайтных значений (Z80-friendly).

3.1. Ключевые регистры RAM_REG

3.2. DLSWAP modes

После записи нового DL → FT_WR8(REG_DLSWAP, DLSWAP_FRAME) — кадр обновится в следующем vsync.

4. Видеотайминги для 640×480

TSLib содержит выверенные таблицы для трёх режимов 640×480 в Docs/TSLib/Include/FT/81x Const.inc (блок ; Video modes):

4.1. Главный вывод: 74 Гц выбрали ради строки, а не ради FPS

Выбор VM_640_480_74Hz был осознанным компромиссом: мы пошли на риск сузить парк поддерживаемых мониторов ради дополнительных тактов FT812 на строку. Режим около 60 Гц совместимее для VGA-мониторов, но в тяжёлых кадрах Zuma срывалась именно строка, а не игровая логика.

Для FT812 важен HCYCLE: сколько pixel-clock’ов есть на одну строку, чтобы чип успел пройти Display List и выдать пиксели. У 57/76 Гц строка даёт 800 PCLK, а у 74 Гц — 832 PCLK. Это всего +32 PCLK на строку, но в момент, когда бюджет был на грани, именно этот запас имел смысл. VM_640_480_76Hz быстрее по refresh, но HCYCLE у него те же 800, поэтому проблему строки он не решал.

Позже переход на 1024×768@59 дал уже 1344 PCLK на строку и вернул режим ближе к универсальным ~60 Гц, но на этапе 640×480 выбор 74 Гц был именно выбором строки.

F_MUL — значение, которое TSLib пишет в REG_PCLK. На плате VDAC2 (внешний клок через CLKEXT + CLKSEL #C0) результирующий pixel clock получается как 8 МГц × F_MUL: 8×3 = 24 МГц (а при F_MUL=4 → 32 МГц, §4.2). Это подтверждается независимо: HCYCLE × VCYCLE × refresh = 800×524×57 ≈ 24 МГц.

⚠️ Уточнение семантики (важно при переносе). «8 × F_MUL» — мнемоника ИМЕННО нашей настройки клока на VDAC2, а не общая семантика регистра. По даташиту FT81x REG_PCLK — это ДЕЛИТЕЛЬ системного клока: PCLK = f_sys / REG_PCLK (не множитель и не «база 8 МГц»). У FT81x системный клок задаётся CLKSEL (по умолчанию 60 МГц; варианты 24/36/48; 72 МГц — уже у BT81x), и после смены клока надо обновить REG_FREQUENCY. Переносите на другой клок — считайте PCLK по формуле делителя из даташита, не по «×8».

4.2. Константы TSLib для трёх 640×480-режимов

• VM_640_480_57Hz: F0_MUL=3, H0_FPORCH=16, H0_SYNC=96, H0_BPORCH=48, H0_VISIBLE=640, V0_FPORCH=11, V0_SYNC=2, V0_BPORCH=31, V0_VISIBLE=480.

• VM_640_480_74Hz: F1_MUL=4, H1_FPORCH=24, H1_SYNC=40, H1_BPORCH=128, H1_VISIBLE=640, V1_FPORCH=9, V1_SYNC=3, V1_BPORCH=28, V1_VISIBLE=480.

• VM_640_480_76Hz: F2_MUL=4, H2_FPORCH=16, H2_SYNC=96, H2_BPORCH=48, H2_VISIBLE=640, V2_FPORCH=11, V2_SYNC=2, V2_BPORCH=31, V2_VISIBLE=480.

4.3. Соответствие регистрам FT812

TSLib-макрос FT_ModeTab из Docs/TSLib/Include/FT/81x Const.inc укладывает значения в следующие регистры FT812:

Именно строка REG_HCYCLE объясняет выбор 74 Гц: у него единственного из трёх 640×480-режимов строковый бюджет больше 800 PCLK. Цена — менее универсальный refresh для мониторов.

4.4. Применение через TSLib-макрос

В TSLib переключение режима — одна строчка:

                FT_RESOLUTION VM_640_480_57Hz, ResolutionWidthPtr

Где ResolutionWidthPtr — Z80-указатель на 2-байтную ячейку в RAM, куда макрос сохраняет ширину экрана для последующего использования (Docs/TSLib/Examples/2.HelloWorld/Include.inc).

FT_RESOLUTION из Docs/TSLib/Include/FT/812 Macro.inc сам разворачивается в нужную таблицу

• серию FT_WR_REG16 по адресам HCYCLE/HOFFSET/HSIZE/HSYNC0/HSYNC1/VCYCLE/VOFFSET/VSIZE/VSYNC0/VSYNC1
• FT_WR_REG8 FT_REG_PCLK со значением F_MUL.

4.5. Полная init-последовательность (TSLib FT_BOOT_UP)

Макрос FT_BOOT_UP находится в Docs/TSLib/Include/FT/812 Macro.inc:

FT_BOOT_UP      macro
                FT_SEND_COMMAND FT_CMD_PWRDOWN_       ; #50 — power-down
                FT_DELAY 3
                FT_SEND_COMMAND FT_CMD_CLKEXT         ; #44 — внешний clock
                FT_DELAY 3
                LD B, FT_CMD_CLKSEL                   ; #61 — clock select
                LD C, #C0                             ; PLL range / MUL
                CALL FT.SendCommand.Param
                FT_SEND_COMMAND FT_CMD_ACTIVE         ; #00 — активировать
                FT_DELAY 15

.WaitIntReady   FT_RD_REG8 FT_REG_ID                  ; ждать REG_ID == 0x7C
                CP #7C
                JR NZ, .WaitIntReady

.WaitCPU_Reset  FT_RD_REG8 FT_REG_CPURESET            ; ждать REG_CPURESET == 0
                OR A
                JR NZ, .WaitCPU_Reset

                FT_WR_REG8  FT_REG_PCLK,    0         ; PCLK выкл — тайминги настраиваются "тихо"
                FT_WR_REG16 FT_REG_HCYCLE,  0x224     ; default тайминги
                FT_WR_REG16 FT_REG_HOFFSET, 0x02B
                ; ... HSYNC0/1, VCYCLE/OFFSET/VSYNC0/1, SWIZZLE, PCLK_POL ...
                FT_WR_REG16 FT_REG_HSIZE,   0x1E0
                FT_WR_REG16 FT_REG_VSIZE,   0x110
                FT_WR_REG16 FT_REG_CSPREAD, 0x001
                FT_WR_REG16 FT_REG_DITHER,  0x001
                FT_WR_REG16 FT_REG_OUTBITS, 0x000
                FT_WR_REG16 FT_REG_GPIOX_DIR, 0xFFFF  ; все GPIOX выходы
                FT_WR_REG16 FT_REG_GPIOX,     0xFFFF  ; включить DISP
                FT_WR_REG8  FT_REG_PCLK,    2         ; PCLK on (временное значение)
                endm

На реальном FT812 это не формальность. После ACTIVE чип поднимает oscillator/PLL, делает внутреннюю проверку RAM и только потом начинает корректно отвечать как EVE. По даташиту boot-up может занимать до 300 ms, поэтому нельзя заменить ожидание на короткий busy-loop и сразу писать регистры. Правильный критерий готовности — не «прошло немного времени», а REG_ID == #7C и затем REG_CPURESET == 0, как показано выше. Если начать запись раньше, на эмуляторе это может случайно пройти, а на реальной плате FT812 выглядит как «не включился»: SPI отвечает мусором или часть ранних записей пропадает.

REG_PCLK=2 в конце FT_BOOT_UP — временное значение: оно лишь включает развёртку с default-таймингами, чтобы видеовыход «ожил». Рабочий PCLK для 640×480 задаёт следующий шаг — FT_RESOLUTION (REG_PCLK = F_MUL = 3 или 4). Прежний комментарий «60/2 = 30 МГц» был прикидкой по даташит-формуле делителя при условном sys-clock 60 МГц (см. уточнение в §4.1).

После FT_BOOT_UP нужный режим выставляется через FT_RESOLUTION VM_640_480_57Hz. Финальный шаг — переключить выход TS-Conf на FT812 и отключить обычный gfx:

                Video_Setting VID_FT812 | VID_NOGFX  ; OUT (0xAF), %00100100

Video_Setting — TSLib-макрос из Docs/TSLib/Include/Video/Macro.inc. Флаги VID_FT812 и VID_NOGFX объявлены в Docs/TSLib/Include/TSConf.inc. По смыслу это тот же вывод в VCONFIG-порт, который описан в учебнике #2.

5. Display List (DL): список команд рисования FT812

Display List, или DL, — это не готовая растровая картинка и не экранный буфер. Это маленькая программа для видеочипа FT812: список 32-битных команд «очистить экран», «выбрать bitmap», «нарисовать вершину», «закончить кадр». FT812 читает этот список из RAM_DL во время вывода кадра.

5.1. Структура

DL (Display List) = массив 32-битных команд в RAM_DL (0x300000..0x301FFF). Размер RAM_DL — 8 КБ, одна команда занимает 4 байта, поэтому верхний предел — 2048 команд. Каждая команда — 4 байта little-endian. Последняя команда обязана быть DISPLAY().

После записи DL → REG_DLSWAP=DLSWAP_FRAME → следующий vsync покажет новый кадр.

5.2. Базовые opcodes (минимальный набор для Zuma)

prim для BEGIN:

• 1 BITMAPS, 2 POINTS, 3 LINES, 4 LINE_STRIP, 5 EDGE_STRIP_R/L/A/B (6,7,8,9), 9 RECTS

5.3. Минимальный «Hello World» DL

Заливаем экран синим цветом:

0x02_00_00_64  ; CLEAR_COLOR_RGB(0,0,100)   [синий]
0x26_00_00_07  ; CLEAR(1,1,1)               [color, stencil, tag]
0x00_00_00_00  ; DISPLAY()

Записать 12 байт в 0x300000, затем REG_DLSWAP = 2 → синий экран на следующем vsync.

5.4. Цепочка спрайтов из атласа

Для рендера 240 шаров Zuma из атласа (handle 0, 6 cells × 40×40):

SAVE_CONTEXT()
BITMAP_HANDLE(0)
BEGIN(BITMAPS)
; per-ball loop:
;   COLOR_RGB(255,255,255)     ; без тинта
;   VERTEX2II(x, y, 0, color)  ; одна 32-bit команда на шар
END()
RESTORE_CONTEXT()
DISPLAY()

Для 240 шаров = ~244 32-bit команды = ~976 байт DL (вмещается в 8KB).

5.5. Копроцессор FT812 (RAM_CMD) — для удобства

Командный буфер 0x308000+ — кольцевой, его читает копроцессор FT812. Команды:

• cmd_dlstart — открыть новый DL
• cmd_swap — REG_DLSWAP
• cmd_loadimage — JPEG/PNG → RAM_G
• cmd_text, cmd_number — рендер текста (DL команды генерируются автоматически)
• cmd_rotate, cmd_translate, cmd_scale, cmd_setmatrix — матричные трансформации

Запись в RAM_CMD управляется парой REG_CMD_WRITE (наша запись) и REG_CMD_READ (читает FT812). Wrapping — 4KB. После записи → REG_CMD_WRITE = новый offset. Ждать пока FT812 не прочитает: REG_CMD_READ == REG_CMD_WRITE.

6. Bitmap-форматы для FT812

Для Zuma 640×480 рекомендации:

• Background: PALETTED8 (256 цветов) → 640×480 = 307KB; либо RGB565 → 614KB.
• Шары 6 цветов × 40×40: PALETTED8 → 9.6KB атлас; либо RGB565 → 19.2KB. Маска 1-bit для прозрачности отдельным L1-bitmap’ом.
• Жаба 128×128: ARGB4 (есть альфа) → 32KB.
• Курсор 32×32: ARGB1555 → 2KB.
• Killzone 64×64 (1 frame): ARGB4 → 8KB.

Итого ~360 KB из 1024 KB RAM_G — есть запас на анимации.

7. Производительность и DMA

7.1. Оценка bandwidth Z80 → FT812 через SPI

• В проекте включён режим SYS_ZCLK14: Z80 работает на 14 МГц.

• OTIR = 21 такт/байт. Для длинного блока это 14 МГц / 21 = ~666 КБ/с полезных данных без учёта 3-байтного адресного заголовка SPI и FT_ON/FT_OFF.

• Если Z80 работает на 7 МГц, оценка вдвое ниже: ~333 КБ/с.

• Через DMA TS-Conf (если задействована) — выше, до ~1 MB/s.

7.2. Полный кадр при 60 fps

• Frame budget: 16.7 ms

• DL обновление 240 шаров: ~1 KB → примерно 1.5 ms через длинный OTIR-блок на 14 МГц, плюс накладные расходы кадра.

• Background не обновляется каждый кадр (статичен в RAM_G после init)

7.3. NO_GFX=1 экономит DMA

С NO_GFX=1 лимит DMA на строку (448 циклов) полностью доступен для FT812-передач, а не делится с TS-Config рендером. Это критично для частых обновлений RAM_G (анимация фона).

9. Главный цикл рендера (Hello World pattern из TSLib)

Docs/TSLib/Examples/2.HelloWorld/Core/MainLoop.asm — образцовая структура кадра:

.Loop           FT_CMD_Start                 ; начать собирать команды в буфер RAM Z80
                FT_DL_Start                  ; команда DLSTART для копроцессора FT812

                FT_ClearColorRGB32 0x000000  ; чёрный фон
                FT_ClearAll                  ; clear color + stencil + tag

                CALL ShowText                ; <- наш контент
                CALL Fizz

                FT_Display                   ; конец DL
                FT_CMD_Write                 ; залить буфер из RAM Z80 в RAM_CMD FT812

                FT_WR_REG8 FT_REG_DLSWAP, FT_DLSWAP_FRAME  ; запросить swap

.WaitIntSwap    FT_RD_REG8 FT_REG_INT_FLAGS  ; дождаться SWAP interrupt
                AND FT_INT_SWAP
                JR Z, .WaitIntSwap

                FT_DELAY 2
                JP .Loop

9.1. Что делает FT_CMD_Start/FT_CMD_Write

FT_CMD_Start — устанавливает Z80-указатель FT.Coprocessor.BufferPtr в начало локального буфера CMD_ADDRESS_PTR в RAM Z80 (см. Docs/TSLib/Include/FT/Coprocessor/BufferMacro.inc). Все последующие FT_CMD_BUF/FT_ClearAll/FT_Begin/FT_Vertex2ii — это запись 4-байтных команд в этот локальный буфер (через LD (HL), E : INC HL × 4).

FT_CMD_Write — считает длину буфера (текущий ptr − начало) и блочно отправляет всё в RAM_CMD FT812 через FT.Coprocessor.Write (вызывает FT_Write/OTIR-цикл).

Это ключевой паттерн: DL собирается в RAM Z80, затем одной транзакцией уходит в FT812. Гораздо эффективнее чем командировать FT812 по одной команде за раз.

9.2. FT_DLSWAP_FRAME / FT_INT_SWAP

После записи команд REG_DLSWAP = FT_DLSWAP_FRAME (=2) запрашивает swap в начале ближайшего vsync. REG_INT_FLAGS бит FT_INT_SWAP поднимается когда swap состоялся — это сигнал «можно начинать новый кадр». Без ожидания будут «глитчи»: писать в DL пока движок FT812 ещё рендерит — неопределённое состояние.

FT_INT_MASK и FT_INT_EN нужно настроить в init (Hello World делает: FT_REG_INT_MASK = FT_INT_SWAP, FT_REG_INT_EN = 1).

10. TSLib API — карта макросов

10.1. Низкий уровень:

Docs/TSLib/Include/FT/812 Macro.inc

10.2. Прямой Display List в RAM_DL:

Docs/TSLib/Include/FT/DL Macro.inc

Каждый макрос разворачивается в DEFD <opcode> (4 байта в текущем месте сборки). Используется когда DL зашит в постоянную область (например, статическая графика уровня), не строится каждый кадр.

prim для BEGIN: 1=BITMAPS, 2=POINTS, 3=LINES, 4=LINE_STRIP, 5/6/7/8=EDGE_STRIP_*, 9=RECTS.

10.3. Сборка DL через копроцессор:

Docs/TSLib/Include/FT/Coprocessor/BufferMacro.inc

Те же команды, но макросы пишут не DEFD, а FT_CMD_BUF (накапливают в RAM Z80 для последующего FT_CMD_Write). Используется в MainLoop каждый кадр.

10.4. Функции TSLib FT.Coprocessor.*

Реализация: Docs/TSLib/Include/FT/Coprocessor/Buffer.asm и Docs/TSLib/Include/FT/Coprocessor/Cmd.asm.

Дополнительные runtime-функции:

• FT.Coprocessor.PointSize — LD DE, size → пишет POINT_SIZE в буфер
• FT.Coprocessor.ColorRGB — LD C, R : LD D, G : LD E, B
• FT.Coprocessor.ColorA — LD E, A
• FT.Coprocessor.Vertex2f — LD HL, X : LD DE, Y (subpixel)
• FT.Coprocessor.WaitFlush — ждать пока FT прочитает RAM_CMD
• FT.Coprocessor.GetPtr — получить текущий REG_CMD_DL (для return-адресов в DL)
• FT.Coprocessor.IsFault — проверка ошибки копроцессора
• FT.Coprocessor.Inflate — распаковать deflate-blob в RAM_G

10.5. Прочее

• Docs/TSLib/Include/Cache/Macro.inc — Cache_Setting EN_0000 | EN_4000 | EN_8000 — TS-Conf cache
• Docs/TSLib/Include/DMA/Macro.inc — TS-Conf DMA helpers
• Docs/TSLib/Include/Input/Kempston/Mouse — мышь Kempston
• Docs/TSLib/Include/Math — fixed-point/F16 математика

10.6. Готовый Init_Video для Zuma VDAC2

Реализовано в Source/ASM/Init_Video.asm. Собирается под sjasmplus (--syntax=ab) с TSLib.

Зависимости (порядок важен):

                DEVICE ZXSPECTRUM4096
                define MAPPING_REGISTERS              ; Video_Setting через FMADDR

                include "Docs/TSLib/Include/TSConf.inc"
                include "Docs/TSLib/Include/Video/Macro.inc"
                include "Docs/TSLib/Include/FT/81x Const.inc"
                include "Docs/TSLib/Include/FT/DL  Macro.inc"
                include "Docs/TSLib/Include/FT/812 Macro.inc"
                module FT
                include "Docs/TSLib/Include/FT/812 Func.asm"
                endmodule

ResolutionWidthPtr   EQU #40F3                        ; Z80-RAM ячейки (FT_RESOLUTION пишет туда W/H)
ResolutionHeightPtr  EQU #40F5

                include "Init_Video.asm"

Сама логика (см. файл):

1. Sanity-check VDAC2: IN A,(STATUS) : AND %111 : CP %111 — если бит-маска ≠ 111, возврат с Z=0 (нет VDAC2 на плате).
2. FT_BOOT_UP — полная init FT812: PWRDOWN→CLKEXT→CLKSEL #C0→ACTIVE, ждать REG_ID=0x7C, default тайминги, GPIOX=0xFFFF, REG_PCLK=2 → видеовыход активирован.
3. FT_CMD_RESET — обнулить REG_CMD_READ/WRITE (на случай висящих команд).
4. FT_RESOLUTION VM_640_480_57Hz, ResolutionWidthPtr — переключить тайминги: PCLK=24 МГц (F_MUL=3), HCYCLE 800, VCYCLE 524, HSIZE/VSIZE 640×480.
5. Залить пустой DL (12 байт = CLEAR_COLOR_RGB(0,0,0); CLEAR(1,1,1); DISPLAY()) в RAM_DL через FT.WriteDL, потом REG_DLSWAP=2 — чёрный экран до первого MainLoop-кадра.
6. REG_INT_MASK = FT_INT_SWAP, REG_INT_EN = 1 — разрешить swap-interrupt для синхронизации MainLoop’а.
7. Video_Setting VID_FT812 | VID_NOGFX = OUT (0xAF), %00100100 — переключить TS-Conf выход на FT812 + отключить TS-Config gfx (освобождает 448 DMA-циклов/строку).

Возврат: A=0/Z=1 на успех, A=1/Z=0 если VDAC2 не обнаружен (caller выбирает fallback).

После Init_Video можно входить в MainLoop с FT_CMD_Start/FT_CMD_Write/DLSWAP паттерном (§9).

10.7. Готовый MainLoop для Zuma VDAC2 (каркас)

Реализовано в MainLoop.asm в корне проекта. Собирается без ошибок (см. _test_init_video.asm — там полная цепочка include’ов и Init_Video → MainLoop точка входа).

На текущем этапе MainLoop — proof-of-life каркас: тёмно-синий фон + одна оранжевая точка 16 px радиуса, отскакивающая от краёв 640×480. По мере добавления game-state’а сюда подключатся VDC engine update, цикл по slots[], frog/cursor/score.

Структура одного кадра (6 шагов):

.Loop           ; 1. Открываем DL, заливаем общую очистку
                FT_CMD_Start
                FT_DL_Start
                FT_ClearColorRGB32 0x102030
                FT_ClearAll

                ; 2. Контент кадра
                CALL ZL_DrawFrame             ; PointSize + ColorRGB + Begin POINTS + Vertex2f + End

                ; 3. Закрытие DL и заливка в FT812
                FT_Display
                FT_CMD_Write                  ; OTIR-блок RAM Z80 → RAM_CMD FT812

                ; 4. Запросить swap при следующем vsync
                FT_WR_REG8 FT_REG_DLSWAP, FT_DLSWAP_FRAME

                ; 5. Заблокироваться до swap-interrupt'а
.WaitIntSwap    FT_RD_REG8 FT_REG_INT_FLAGS
                AND FT_INT_SWAP
                JR Z, .WaitIntSwap

                ; 6. Update game state (между swap'ом и следующим DL)
                CALL ZL_UpdateGame
                JP .Loop

Важно про порядок в одном кадре:

• FT_CMD_Start сбрасывает указатель локального буфера в RAM Z80 (CMD_ADDRESS_PTR, по умолчанию #C000).
• Все макросы группы FT_* из BufferMacro.inc только пишут в этот буфер — пока не вызван FT_CMD_Write, ничего на FT812 не уходит.
• FT_CMD_Write — одна OTIR-транзакция в REG_CMDB_WRITE (FT_RAM_CMD). Эффективнее команд по одной.
• REG_DLSWAP=FT_DLSWAP_FRAME запрашивает swap. Без ожидания FT_INT_SWAP следующий DL может начать строиться поверх ещё рендерящегося → артефакты.
• Update после WaitIntSwap — пока движок FT812 отрисовывает только что засвопленный кадр, Z80 свободен для физики. Это естественная двойная буферизация: кадр N+1 готовится пока кадр N показывается.

Точка состояния (ZL_PointX/ZL_PointY etc.) хранится в коде через DEFW 0 — после загрузки .bin это валидные ячейки, MainLoop при первом входе явно их инициализирует на (SCR_W/2, SCR_H/2) и скорость (3, 2) px/frame в 1/16-формате (VertexFormat=4, по умолчанию).

ZL_DrawFrame использует runtime-функции FT.Coprocessor.ColorRGB/PointSize/Vertex2f (из Coprocessor/Buffer.asm) — они принимают значения в регистрах (BC/DE), а не immediate, что нужно для динамической позиции.

ZL_UpdateGame — bouncing: X += VelX, если X >= MAX_X или X < MIN_X → clamp + VelX = -VelX через мини-helper ZL_NegateW. То же по Y.

Глава 12. Bitmap rendering — matrix transform, scale, paletted formats (опыт 2026-05-09)

12.1 Главный урок: BITMAP_TRANSFORM работает на bitmap UV, не на screen position

В FT81x матрица BITMAP_TRANSFORM_A..F (set через cmd_setmatrix после cmd_loadidentity + операций) трансформирует bitmap UV-coordinates (= какой пиксель bitmap читать), не screen position.

Render-formula: pixel at screen (vertex_pos.x + u, vertex_pos.y + v) reads bitmap at M * (u, v).

Из этого следует:

• cmd_translate(X, Y) сдвигает источник читаемых пикселей. Для UV outside bitmap → BORDER возвращает transparent → sprite невидим.
• Screen position спрайта задаётся через Vertex2f((X-half)*16, (Y-half)*16) (subpixel coords), не через matrix.
• Matrix используется только для transformations внутри sprite-rect: rotation вокруг центра, scale, shear.

Pattern для rotated sprite (rotation around center)

Sprite size 56×56, центр (28, 28):

CALL ZL_EmitLoadId
LD HL, 28 : LD DE, 28 : CALL ZL_EmitTranslate     ; UV center to origin
LD A, (tangent) : CALL ZL_EmitRotate              ; rotate UV around (0,0) which is sprite center
LD HL, -28 : LD DE, -28 : CALL ZL_EmitTranslate   ; restore offset
CALL ZL_EmitSetMatrix                              ; emits BITMAP_TRANSFORM_A..F (6 DL cmds)
FT_BitmapHandle 0 / FT_BitmapSource ...
FT_Begin FT_BITMAPS
LD A, cell : CALL FT.Coprocessor.Cell
LD BC, (X-28)*16 : LD DE, (Y-28)*16 : CALL FT.Coprocessor.Vertex2f
FT_End

Matrix формула: M = T(28,28) * R(angle) * T(-28,-28). Combined rotations (tangent + spin) можно складывать в одну: R(tangent + spin) → один cmd_rotate.

12.2 cmd_scale convention

cmd_scale(sx, sy) где sx, sy — f16.16 fixed-point. scale(N, N) отображает bitmap в N раз больше на экране (= sprite displayed at N× native size), не наоборот. Counter-intuitive потому что matrix transforms UV.

Пример: bg хранится 400×300 в RAM_G, нужно отобразить 640×480. Scale factor = 640/400 = 480/300 = 1.6. cmd_scale(0x1999A, 0x1999A) (= 1.6 in f16.16).

12.3 BITMAP_SIZE при upscale

FT_BitmapSize filter, wrap_x, wrap_y, screen_width, screen_height определяет output area on screen (clipping bounds). При upscale указываем целевой размер 640×480, не native размер bitmap.

FT_BitmapLayout format, linestride_bytes, native_height определяет storage в RAM_G — linestride = native_width × bpp, height = native_height (= 300 для 400×300 RGB565).

Filter FT_BILINEAR (vs FT_NEAREST) даёт smooth interpolation между native pixels при upscale — обязательно для качественного render scaled bitmap.

12.4. Бюджет памяти для background (1 МБ RAM_G FT812)

Расчёт ниже — для фона 640×480. В колонке «RAM_G» указаны реальные байты картинки/слоёв; если грузить данные полными 16-КБ страницами spgbld, в RAM_G надо дополнительно держать выравнивающий хвост до следующей страницы.

Важно про pseudo-DXT. Это не аппаратный формат FT812 и не распаковка в RAM_G. Мы храним три обычных bitmap-слоя: две цветовые плоскости c0/c1 в RGB565 с размером 160×120 и полноэкранную маску 640×480. Вариант L2 использует 2-битную маску (4 уровня смешивания), вариант L4 — 4-битную маску (16 уровней смешивания). Рендер идёт несколькими проходами через blend.

Unreal эмулятор НЕ реализует часть palette-formats — серый фон при попытке. На реальном железе ZX-Evo+FT812 PALETTED должен работать по стандарту FT81x, но для проекта всё равно нужна проверка на реальном VDAC2.

12.5 Asymmetric downscale (X≠Y)

Можно хранить bg с разными scale по осям. Пример: 480×240 RGB565 (X=0.75×, Y=0.5×) = 230 KB. cmd_scale(640/480, 480/240) = cmd_scale(1.33×, 2×). Полезно если detail неравномерно: больше горизонтально (Y blur приемлем) или вертикально.

Для типичных Zuma backgrounds (rotational symmetry — спираль, swirley) — detail изотропен, симметричный downscale (320×240, 400×300) лучше.

12.6. Почему нули в конце spgbld-страницы могут затереть соседний ресурс

spgbld раскладывает данные по страницам TS-Config. Одна страница = 16 384 байта. Если файл занимает не всю страницу, оставшийся хвост страницы заполняется нулями. Это обычное выравнивание страницы.

Проблема появляется на этапе загрузки в RAM_G FT812. Если загрузчик каждый раз копирует всю 16-КБ страницу через FT.WriteMem 16384, он отправляет в RAM_G не только реальные байты файла, но и эти нули в конце последней страницы. Нули пишутся сразу после полезных данных.

Если следующий ресурс в RAM_G лежит вплотную, хвост из нулей может стереть его начало.

Пример:

RAM_G:
#010000..#04A7FF  background, реальные данные
#04A800..#04FFFF  нули из хвоста последней spgbld-страницы
#04A800..#05FFFF  следующий ресурс, если положить его вплотную

В таком layout загрузка background’а сотрёт начало следующего ресурса.

Рабочие варианты защиты:

1. Грузить нижний по адресу ресурс первым, а следующий ресурс грузить после него поверх нулевого хвоста.

2. Оставлять между ресурсами зазор не меньше одной страницы, если загрузчик всегда копирует по 16 КБ.

3. Для последней страницы передавать в FT.WriteMem не 16 384 байта, а реальный остаток файла: real_size mod 16384.

См. также §12.8.2: из-за такого нулевого хвоста background затирал начало atlas’а шаров.

12.7. Сжатие PNG/JPEG: экономит файл, но не RAM_G

FT812 не рисует фон прямо из JPEG/PNG. Перед отрисовкой картинка всё равно должна лежать в RAM_G уже распакованной, почти как обычный BMP: пиксели подряд в одном из форматов FT812 (RGB565, ARGB4, PALETTED4444, L2, L4 и т.д.).

Поэтому маленький JPEG помогает только до момента загрузки:

• в .SPG или .PAK файл кладём маленький JPEG/PNG/zlib-поток;
• при загрузке cmd_loadimage или cmd_inflate распаковывает его в RAM_G;
• после распаковки фон занимает в RAM_G полный размер выбранного bitmap-формата.

Пример: JPEG 640×480 может занимать на диске 80 КБ, но после cmd_loadimage в RGB565 он займёт в RAM_G 614 400 байт. Сжатие уменьшает размер файла и объём чтения с SD, но не уменьшает занятый объём RAM_G после распаковки.

12.8 Финальный выбор для Zuma VDAC2 (level 1 spiral)

make_bg_level01.py: source levels/level_src_<NN>.png (clean 640×480) → resize 400×300 LANCZOS → RGB565 LE. MainLoop.asm ZL_DrawFrame: cmd_loadidentity + cmd_scale(0x1999A, 0x1999A) + cmd_setmatrix + bg setup + Begin/Vertex2ii(0,0,1,0)/End.

Memory: 240 KB bg + ~310 KB atlas + freedom для дальнейших assets (frog, score, particles).

12.8.1 Полный pipeline компрессии bg (нюансы практики)

Workflow make_bg_level01.py → spg → RAM_G:

1. Source PNG — levels/level_src_<NN>.png (clean 640×480). НЕ jpeg оригинал, потому что jpg-artifacts усиливаются после downscale + bilinear upscale в FT812.
2. Downscale 640×480 → 400×300 (LANCZOS) на Z80-стороне через Python. Важно — LANCZOS, не BICUBIC: на резких границах spirale Zuma BICUBIC ringing artifacts.
3. RGB565 LE pack — каждый пиксель 2 байта ((g>>2 & 7)<<13) | (b>>3) | ... little-endian. На FT812 LE — нативный порядок.
4. Запись в .bin файл размером 240 000 байт.

5. Сборка страниц через spgbld — Block = #0000, #07..#15, bg_level01_pNN.bin (15 страниц × 16 384 = 245 760 байт; на последней странице 5 760 байт нулевого хвоста).

6. Z80 upload-loop в Initialize: ставит page в slot 2, копирует через FT.WriteMem 16384 байт за раз в RAM_G начиная с BG_RAMG_ADDR=#010000.

7. DL render в ZL_DrawFrame: loadidentity + cmd_scale(0x1999A, 0x1999A) + setmatrix + BITMAP_LAYOUT FT_RGB565, ZL_BG_W*2, ZL_BG_H (stride 800 байт, height 300) + BITMAP_SIZE FT_BILINEAR, BORDER, BORDER, 640, 480 + Begin BITMAPS / Vertex2ii(0,0,1,0) / End.

12.8.2. Ретро-баг: нулевой хвост background затирал atlas шаров

Эта история относится к §12.6. Хронология:

• Background первый раз грузился после atlas’а. Atlas лежал в #050000..#0A6000 (302 КБ, старая версия 6×8 frames), background — в #010000..#04A800 (240 КБ).

• Последняя spgbld-страница background’а имела нулевой хвост. При копировании полных 16-КБ страниц эти нули записывались дальше реального background’а и доходили до #0A8000.

• В результате нули затирали первые 8 КБ atlas’а (#0A6000..#0A8000). Это были последние несколько cells, они рендерились пустыми, и цепочка шаров мерцала.

• Fix: background грузится первым, atlas — вторым. Atlas pages записывают свежие данные поверх нулевого хвоста background’а, поэтому atlas остаётся целым.

Универсальное правило для FT812-проектов: порядок upload pages = обратный к RAM_G layout (старший адрес последним), либо gap ≥16 KB между блоками.

Глава 13. Frog composition: HD-стиль pipeline (опыт 2026-05-09/10)

Композиция лягушки в Zuma-Deluxe (HD-версия github.com/GalaxyShad/Zuma-Deluxe-HD) — multi-sprite c rotation matrix. В VDAC2 реализуется через FT812 multiple BITMAP_HANDLE + matrix manipulation.

13.1 Источники подспрайтов в frog.png

frog.png (324×648 RGBA) — sprite-sheet. Координаты 1:1 из Zuma-Deluxe-HD/src/zuma/ResourceStore.c:

Resize 162→122 (LANCZOS) даёт scale ≈ 0.753. Соотношение body/ball = 122/40 ≈ 3.05 (HD соотношение 162/48 = 3.375; -10% — компромисс под 640×480).

13.2 Render pipeline (Frog_Draw порядок)

Из HD Frog.c:

Frog_Draw:
    DrawSprite(plate)                   // no rotation
    DrawSetAngle(angle - π/2)           
    DrawSprite(body)                    // rotated
    DrawSprite(tongue, pos + tongueExpand·dir)   // rotated
Frog_DrawTop:
    DrawSprite(currentBall, pos + ballExpand·dir)   // rotated
    DrawSetScale(1.5)
    DrawSprite(nextBallIndicator, pos - 40·dir)     // rotated
    DrawSprite(blinkAnim, pos)          // rotated

VDAC2 эквивалент в Frog.asm:

1. Frog_DrawPlate — handle 4, no matrix (обнулять matrix не нужно если предыдущий блок identity).
2. Frog_DrawBody — handle 2, matrix T(61,61) · R(angle-64) · T(-61,-61) (где 61 = sprite_W/2, -64 = -π/2 для native face=south).
3. Frog_DrawTongue — handle 5, та же matrix как body + offset Vertex2f на tongueExpand·dir. (на текущем этапе отключён до реализации recoil).

13.3 Rotation matrix pattern (см. также §12.1)

Frog_DrawBody:
    CALL ZL_EmitLoadId
    LD HL, 61 : LD DE, 61 : CALL ZL_EmitTranslate    ; T(+61,+61)
    LD A, (Frog_Angle) : CALL ZL_EmitRotate          ; R(angle-64), -64 встроен в EmitRotate
    LD HL, -61 & 0xFFFF : LD DE, -61 & 0xFFFF
    CALL ZL_EmitTranslate                             ; T(-61,-61)
    CALL ZL_EmitSetMatrix                             ; emit BITMAP_TRANSFORM_A..F

    FT_BitmapHandle 2
    FT_BitmapSource FROG_RAMG_ADDR
    FT_BitmapLayout FT_ARGB4, 122*2, 122
    FT_BitmapSize FT_BILINEAR, FT_BORDER, FT_BORDER, 122, 122
    FT_Begin FT_BITMAPS
    LD BC, FROG_VTX_X : LD DE, FROG_VTX_Y : CALL FT.Coprocessor.Vertex2f
    FT_End

    ; reset → identity для последующих ops в DL
    CALL ZL_EmitLoadId : CALL ZL_EmitSetMatrix
    RET

FROG_VTX_X = FROG_X*16 - 61*16 (subpixel top-left). Frog_Angle — raw BRAD 0..255 (0=east, 64=south, 128=west, 192=north). ZL_EmitRotate сам делает ADD A, 192 (= -64) для коррекции native face direction.

Ключевой урок: matrix НЕ задаёт screen position (это делает Vertex2f), matrix трансформирует UV-чтение внутри bitmap-rect. T(+61,+61) переносит UV-origin в центр sprite, R(angle) вращает UV вокруг этого origin, T(-61,-61) возвращает; результат — rotated bitmap внутри своего фиксированного screen-rect.

13.4 Atan2 от курсора → angle

Источник алгоритма — TS-Conf версия ComputeFrogAngle, перенесённая в Source/ASM/Frog.asm. Алгоритм:

1. dx = SmoothMouseX - FrogX, dy = SmoothMouseY - FrogY (16-bit signed).
2. Флаги октанта (3 бита): b0=dx<0, b1=dy<0, b2=swap (если |dy|>|dx|).
3. |dx|, |dy| через CPL+INC. Swap так чтобы C = max, E = min.
4. t = E*128 / C (16-bit/8-bit deление). 128, не 32 — даёт 4× разрешение и плавность на диагоналях.
5. Atan LUT[129]: atan(i/128) × 256/(2π), i=0..128, выход 0..32 BRAD.
6. Mirror at 90° если был swap: A = 64 - A.
7. Apply квадрант по флагам dx/dy: Q1 → A, Q2 → 128-A, Q3 → 128+A, Q4 → 256-A.

Возвращает BRAD 0..255: 0=east, 64=south, 128=west, 192=north.

13.5 Hybrid follow для плавного rotation

Прямое присваивание Frog_Angle = computed даёт jitter при mouse-jitter (kempston через Hyper-V — особенно):

• Big diff (≥4 BRAD = >5.6°) → snap
• Small diff (1..3 BRAD) → ±1 BRAD/frame ramp
• Diff = 0 → no-op
• Deadzone: max(|dx|,|dy|)<5 → не менять (курсор в frog-center)

Subjective результат: при медленном движении мыши лягушка плавно догоняет, при быстром — мгновенно прыгает. То же самое было в TS-Conf версии, проверено годами.

13.6 Tongue bbox (для будущего расчёта tongueExpand)

Native tongue (162×162 region из frog.png):

• bbox непрозрачных пикселей: x=59..103, y=53..132 (45×80)
• centroid (81, 89), sprite center (81, 81)

Это значит native tongue: язык чуть выше центра sprite до низа. После resize 162→122 bbox переходит в y=40..99. Если рендерить tongue в той же position что и body, язык физически выше центра body (до y=40 после resize).

В HD tongueExpand=24 (idle) сдвигает tongue по dir·24 вниз по native-face=south — язык легализуется под подбородком body. На рендере в VDAC2 (где rotation atan2-driven) это значит:

tongueX = FROG_X + (24·cos_lut[Frog_Angle]) >> 4
tongueY = FROG_Y + (24·sin_lut[Frog_Angle]) >> 4
Vertex2f((tongueX-61)*16, (tongueY-61)*16)

• та же matrix что и body. Реализуем когда дойдём до recoil/fire анимации.

Глава 14. RNG: LFSR Galois + bias + RTC-scramble (опыт 2026-05-10)

14.1 LFSR Galois 16-bit

Базовый PRNG, периодом 65535 (на любом non-zero seed):

LFSR16:                          ; state в HL
    LD A, L : AND 1              ; LSB
    SRL H : RR L                 ; HL >>= 1
    JR Z, .no_xor
    LD D, #B4 : LD E, 0          ; poly 0xB400 (CRC-16-IBM reverse)
    LD A, H : XOR D : LD H, A
    LD A, L : XOR E : LD L, A
.no_xor:
    RET                          ; HL = новое state

Альтернативные полиномы #D008, #A005 — те же свойства period-65535.

14.2 Bias-ловушка: AND N + clamp на не-степени двойки

Распространённая ошибка для распределения LFSR-output на N значений:

LD A, L
AND 7                ; 0..7
CP 6
JR C, .ok
SUB 6                ; 6→0, 7→1
.ok:
RET                  ; A в 0..5

Проблема: distribution неравномерное. Для NUM=6:

• Values 0, 1: вероятность 2/8 = 25% каждое
• Values 2..5: вероятность 1/8 = 12.5% каждое

Visible эффект: на экране в 2 раза больше синих и красных шаров (если color 0=blue, 1=red).

14.3 Mul-then-shift: равномерное распределение

LD A, L : XOR H              ; смешать обе половины LFSR (8 бит entropy)
LD H, 0 : LD L, A
LD D, 0 : LD E, A
ADD HL, HL                   ; HL = A*2
ADD HL, DE                   ; HL = A*3
ADD HL, HL                   ; HL = A*6  (A * NUM_COLORS=6)
LD A, H                      ; A = (A*N) >> 8 → 0..N-1
RET

Distribution: 256/N не делится нацело → bias ≤1/N. Для N=6 максимальное отклонение 2 / 256 = 0.78%.

Generic вариант для произвольного N:

LD E, N                      ; multiplier из RAM
LD HL, 0
LD B, 8
.loop:
    ADD HL, HL
    SLA A
    JR NC, .skip
    ADD HL, DE
.skip:
    DJNZ .loop
LD A, H                      ; (A * N) >> 8
RET

14.4 RTC-scramble seed (для разнообразия per launch)

LFSR с фиксированным seed → одна и та же последовательность каждый запуск. Решение — scramble через TS-Conf RTC секунды:

ReadRTCSeconds:
    LD BC, #DFF7 : XOR A : OUT (C), A     ; reg 0 = seconds
    LD BC, #BFF7 : IN A, (C)              ; A = BCD seconds
    LD B, A
    AND $0F : LD C, A                     ; low nibble
    LD A, B : AND $F0
    SRL A : SRL A : SRL A : SRL A         ; high nibble
    LD B, A
    ADD A, A : ADD A, A : ADD A, B        ; *5
    ADD A, A                              ; *10
    ADD A, C                              ; +low → 0..59 binary
    RET

VDC_Init:
    LD HL, #ACE1 : LD (VDC_LfsrSeed), HL
    CALL ReadRTCSeconds
    OR A : JR NZ, .have : LD A, 17        ; защита если RTC=0
.have:
    LD D, A : LD E, A                     ; multiplier
    LD HL, (VDC_LfsrSeed) : LD A, L       ; A = low_byte(seed)
    LD HL, 0 : LD B, 8
.mul:                                      ; HL = low_byte * RTC_sec через 8x mult
    ADD HL, HL : SLA A : JR NC, .skip
    ADD HL, DE
.skip:
    DJNZ .mul
    LD A, H : OR L : JR NZ, .ok
    LD HL, #1234                           ; protection если результат=0
.ok:
    LD (VDC_LfsrSeed), HL
    RET

Каждая секунда (RTC ticks) = разный multiplier → разное seed → разная LFSR-цепочка цветов в каждом запуске.

Глава 15. Frog с полной HD-композицией (2026-05-10)

15.1 Render order (HD-1:1)

plate (no rotation)         — диск под лягушкой
body (rotation matrix)      — frog с лапами + face/mouth
tongue (rotation matrix)    — язык, position = pos + tongueExpand·dir
ball-now (no rotation)      — выстреливаемый шар, position = pos + ballExpand·dir
next-ball (no rotation)     — индикатор на спине, position = pos - 28·dir
overlay (rotation matrix)   — face без лап (HD blink frame 0), маскирует корни tongue

Все 4 rotated спрайта (body, tongue, overlay) — одного размера 122×122. Это критично для feature alignment: после rotation eyes body и eyes overlay должны совпадать → они должны быть на одинаковых относительных pixel-offsets от sprite centra. Разный размер → разные относительные offsets → “moon-like” дрейф features при rotation.

15.2 RAM_G layout (1 МБ, baseline 2026-05-10)

#010000..#04C000  bg (15 pages, 400×300 RGB565 + scale 1.6 upscale)
#04C000..#04E000  killzone (1 страница, лежит после нулевого хвоста bg)
#050000..#09C000  balls atlas (19 pages — 6 colors × 8 phases × 56×56 ARGB4)
#09C000..#0A4000  body 122×122 ARGB4 (2 pages)
#0A4000..#0AC000  plate 122×122
#0AC000..#0B4000  tongue 122×122
#0B4000..#0BC000  overlay 122×122 (HD blink frame 0)
свободно           272 КБ для будущих assets

Balls atlas сжат с 16 phases до 8 — освободило 18 pages для overlay full-size. Chain spin formula поменялась: & 7 вместо & 15, cell = color*8 вместо *16.

15.3 Tongue — pos + tongueExpand·dir (HD orbit)

В отличие от tight-cropped sprite (32×80) с pivot (16, 29) — full 122×122 sprite даёт ту же rotation pattern что body:

; Frog_DrawTongue:
;   matrix = T(61, 61) · R(angle + 192) · T(-61, -61)
;   Vertex2f at (TmpX-61, TmpY-61), screen rect 122×122
;   TmpX = PosX + cos·tongueExpand/128
;   TmpY = PosY + sin·tongueExpand/128

tongueExpand = 24 idle (HD), 0..24 при выстреле. Tongue native асимметричный (stripe внутри 162×162 native занимает y=53..133), поэтому при rotation вокруг centra (61, 61) tongue tip “выходит” из mouth area body.

15.4 Ball-now / Next-ball через chain atlas (handle 0)

Используется тот же atlas что и chain rendering. Cell = color*8 + 0 (frame 0, не вращается). Native размер 56×56, рендерится без cmd_scale.

; Frog_DrawBallNow:
;   no rotation matrix (identity).
;   BITMAP_HANDLE 0 / SOURCE BALLS_RAMG_ADDR / LAYOUT 56*2/56 / SIZE 56/56.
;   Cell(ballColor*8) → frame 0 selected color.
;   Vertex2f((TmpX-28)*16, (TmpY-28)*16), centred at TmpX, TmpY.
;   TmpX = PosX + cos·ballExpand/128 (idle = 24).

Next-ball аналогично, но pos - NEXT_OFFSET·dir (= -28·dir, на спине после rotation body).

15.5 Recoil cycle (HD-style fire animation)

ЛКМ rise-edge → isFire=1, recoilTick=0, ballExpand=0, ballColor=nextBallColor, nextBallColor=random(0..3).

Каждый кадр:

• recoilTick += 10 BRAD (≈0.245 rad, HD = 0.25).
• recoil = sin(recoilTick) (signed byte, -127..127).
• Пока recoil ≥ 0:
• tongueExpand = 24 - (recoil·24)>>7 → язык втягивается в рот (24→0).
• ballExpand += 2 (cap 24) → шар выезжает.

• pos = posStart - (cos·recoil)/2048, posStart - (sin·recoil)/2048 → тело откатывается на ~8 px max.

• recoil < 0 → end fire, всё в idle.

Полу-цикл синуса = 13 кадров (≈260ms на 50fps), полное возврат ballExpand до 24 — ещё ~5 кадров.

15.6 FT81x cmd_scale: matrix хранит INVERSE

Param scale = visual ratio = output/native:

• bg upscale 400→640: cmd_scale(1.6) = 0x1999A. Matrix внутри S(1/1.6) = S(0.625). UV = 0.625·screen → UV(640) = 400. ✓ samples full bg.
• ball downscale 56→32: cmd_scale(0.5714) = 0x9249. Matrix S(1.75). UV = 1.75·screen → UV(32) = 56. ✓ samples full ball.

Документация FT81x неоднозначна — проверять empirically через bg upscale.

15.7 Critical bugs found and fixed (2026-05-10 session)

Bug 1 — Frog_ComputeAngle truncate без clamp. LD C, L для |dx| > 255 обрезает high byte H, остаётся младший байт. E.g., dx=313=0x139 → C=0x39=57. Swap-логика |dy| > |dx| инвертируется → frog резко крутится у краёв экрана.

Fix:

.dx_pos:
    LD   A, H
    OR   A
    JR   Z, .dx_clamped
    LD   L, 255              ; saturate to 255 if H ≠ 0
.dx_clamped:
    LD   C, L                ; true 8-bit clamp

То же для .dy_pos.

Bug 2 — Frog_DrawNextBall забывал cmd_scale. DrawBallNow применял scale matrix, DrawNextBall пропускал → next-ball рендерился at native 56×56 в screen rect 32×32, центрирован через 16-px half → визуально “огромный шар” с неправильной позицией.

Fix: либо добавить scale matrix в DrawNextBall, либо (как в baseline 2026-05-10) убрать scale из обеих функций и рендерить native 56×56.

Bug 3 — Multi-sprite feature alignment. Body 122 + overlay 80 → eyes на разных pixel-offsets от sprite centra → после rotation eyes body и overlay расходятся → “две точки вращения как Луна”.

Fix: все спрайты с одинаковыми features ОДНОГО размера. Required: balls atlas 16→8 phases для освобождения RAM_G.

15.8 Python visual_emulator.py — prototype-first workflow

Прототипирование parameters (rotation formula, pivot, offsets, recoil curve) в visual_emulator.py (tkinter+PIL) даёт Х30-Х100 ускорение vs цикла sjasmplus → spgbld → Unreal. Параметры подбираются интерактивно через keys (стрелки, [/], ,/., r), затем переносятся в asm как численные EQU.

Visual emulator не симулирует FT812 cmd_translate/rotate/scale 1:1 — но даёт визуальный target behavior для asm transfer. Различия rendering pipeline (PIL bilinear vs FT812 BILINEAR + cmd_scale convention) могут давать ±1-2 px смещения, но архитектурные параметры (radii, pivots, formulas) переносятся точно.

Ключевые количественные приёмы:

• scale 1.6 = 0x1999A в f16.16 (0.6×65536 ≈ 0x9999, целая 1 = 0x10000). Не 0x19999, не 0x1A000 — точное значение.
• stride = native_width × bpp, НЕ display_width. Для 400×300 RGB565 stride = 400×2 = 800. Если поставить 1280 (= 640×2 для display) — bitmap читается из неправильных адресов в RAM_G, на экране каша.
• BITMAP_SIZE.W/H = display, BITMAP_LAYOUT.height = native. Это обязательная асимметрия: SIZE определяет output rect (для clipping), LAYOUT — storage в RAM_G.
• FT_BILINEAR обязательно для качества. С FT_NEAREST 400×300→640×480 даёт ступеньки на диагоналях.

Что НЕ использовали и почему:

Полученный bg memory layout:

RAM_G:
  #000000..#040FFF  → reserved (DL/FONT/HANDLES area FT812)
  #010000..#04A8FF  → bg_level01 (240 000 bytes RGB565 400×300)
  #04A900..#04FFFF  → нулевой хвост bg (~5 KB) + свободная область
  #050000..#0E4FFF  → balls atlas (602 112 bytes ARGB4 6×16×56×56)
  #0E5000..#0FCFFF  → frog body/plate/tongue (3×30 KB ARGB4 122×122)
  #0FD000..#0FEFFF  → killzone (8 KB)

Дальше по AvailableRamG ещё ~6 KB до 1 MB конца — запас для score, particles.

Глава 16. FT81x DL persistent state — Cell, BITMAP_HANDLE и ловушки наследования (2026-05-10)

После сборки полной HD-композиции лягушки (глава 18) проявился неприятный интермиттент-баг: «крышка» (face overlay) иногда исчезала на N кадров после выстрела. Видимое поведение — после fire ~75% случаев overlay пропадает до следующего fire, ~25% случаев overlay виден.

Что мы исключили (типичные кандидаты, оказавшиеся неверными)

1. Координата overlay (recoil-сдвиг) — Frog_PosX/Y смещаются на ±8 px во время recoil. Заменили вычисление overlay-вершины на Frog_PosStartX/Y (статика). Баг остался → координаты ни при чём.

2. Cmd-buffer overflow — буфер CMD_ADDRESS_PTR=#C000 на 16 КБ, фактически используется ~2.5 КБ за кадр. Не близко к лимиту.

3. Исключение копроцессора — после ошибки копроцессор останавливается, всё что после игнорируется. Но overlay рендерится ПЕРЕД chain block, и chain рендерится корректно → копроцессор жив.

4. DL пострадал — снимок Z80 RAM (F12-dump) показал что DL для overlay полностью корректный: handle=6, source=#0B4000, ARGB4 244×122 BILINEAR, matrix valid, vertex (266, 170) внутри 640×480.

5. Matrix corruption — overlay использует ту же matrix что body (T(61)·R(angle+192)·T(-61)). Body не пропадает, overlay пропадает → matrix не виновата.

6. RAM_G corruption — overlay area #0B4000..#0BB740 не имеет writers после Initialize (никто туда не пишет). Layout правильный, padding tongue заканчивается ровно на #0B4000 (overlay start), не наезжает.

Root cause — Cell как persistent DL state

Frog block рендерит спрайты в порядке:

plate     handle 4   Vertex2f  без Cell  → cell наследован
body      handle 2   Vertex2f  без Cell  → cell наследован
tongue    handle 5   Vertex2f  без Cell  → cell наследован
ball-now  handle 0   Cell(BallColor*8) + Vertex2f  → cell ставится
next-ball handle 0   Cell(NextBallColor*8) + Vertex2f → cell перезаписывается
overlay   handle 6   Vertex2f  без Cell  → cell НАСЛЕДОВАН от next-ball!

Перед frog-блоком идёт bg, который рендерится через Vertex2ii(0, 0, 1, 0). Vertex2ii — специальная компактная команда, которая включает в себя handle и cell прямо в опкоде (поля 7 бит handle, 7 бит cell). Она ставит DL state cell=0 как побочный эффект.

После bg DL state: cell=0. Killzone, plate, body, tongue читают этот cell=0. Когда ball-now эмитит Cell(BallColor*8) — DL state cell меняется. Next-ball аналогично. После next-ball cell = NextBallColor*8.

Overlay не эмитит Cell перед своим Vertex2f → наследует cell от next-ball.

Overlay = 122×122 ARGB4 stride 244 = 29768 байт = 1 cell в layout. FT81x вычисляет адрес pixel-data:

addr = BITMAP_SOURCE + cell * cell_size_bytes
     = OVERLAY_RAMG_ADDR + cell * 29768
     = #0B4000 + cell * 0x7448

Для NextBallColor=1 → cell=8 → addr = #0B4000 + 829768 = #EE200. Это далеко за пределами реального overlay sprite в RAM_G (overlay-data заканчивается на #0BB740 < #EE200). Зона #EE200 — не используется, в RAM_G там zeros. ARGB4 нулевые байты = alpha=0 для всех пикселей → overlay полностью прозрачный → невидим*.

Когда NextBallColor=0 (= 25% случаев в randomize 0..3) → cell=0 → читаем правильный overlay из #0B4000 → виден. Отсюда интермиттент.

Fix

Frog_DrawFaceOverlay:
                  ; ... matrix setup ...
                  FT_BitmapHandle 6
                  FT_BitmapSource OVERLAY_RAMG_ADDR
                  FT_BitmapLayout FT_ARGB4, FROG_SPR_W * 2, FROG_SPR_W
                  FT_BitmapSize   FT_BILINEAR, FT_BORDER, FT_BORDER, FROG_SPR_W, FROG_SPR_W
                  FT_Begin FT_BITMAPS
                  XOR  A
                  CALL FT.Coprocessor.Cell      ; <-- сброс cell в 0
                  CALL Frog_EmitVertex2f_PosCentered
                  FT_End
                  ...

FT.Coprocessor.Cell = TSLib helper, эмитит DL command 0x06000000 | (cell & 0x7F).

Универсальное правило: какой DL state в FT81x persists

Practical rule: любой Vertex2f, идущий после atlas-блока (где Cell≠0 был эмитен), должен явно эмитить нужный Cell (даже Cell(0) для single-cell sprite). Не полагайся на наследование = 0 by default.

Нюанс VERTEX2II vs VERTEX2F. Ловушка наследования CELL касается прежде всего VERTEX2F: он берёт cell из persistent-состояния. У VERTEX2II номер ячейки (cell, биты 0..6) и handle зашиты прямо в 32-битную команду, поэтому такой вершине «унаследованный» CELL не страшен. НО VERTEX2II при этом сам перезаписывает глобальный CELL для последующих команд — так что если дальше в кадре идёт VERTEX2F, он подхватит cell от предыдущего VERTEX2II. Правило «эмить CELL явно» остаётся в силе именно из-за этого взаимодействия.

Методология поиска

Ловушка для одиночного отладчика — баг локализован в DL pipeline state, который не виден в дампе Z80 RAM (DL state живёт в FT81x регистрах). Дамп показывал все правильные команды; вычислить наследование Cell можно только мысленным прохождением DL.

Diagnostic A (изолировать координату): заменить Vertex источник на статику (Pos→PosStart). Баг не ушёл → не координаты.

Главная подсказка пришла от пользователя: «чем крышка отличается от остальных слоёв спрайта» — заставило сесть и последовательно сравнить overlay с другими frog-спрайтами по всем атрибутам. Различие в позиции в DL pipeline относительно atlas-блока (overlay = единственный single-cell sprite ПОСЛЕ atlas-блока) и привело к Cell.

Похожие ловушки могут возникнуть с любым persistent DL state. При добавлении новых sprite в frame — пройти по всем persistent settings и проверить, что текущий sprite их не наследует случайно (или явно ресетит).

Глава 17. Vsync-first sync: race между Z80 build и FT812 render (2026-05-10)

После сборки полного gameplay loop (chain physics + bullet + match-3) на реальном железе ZX-Evo + FT812 проявился класс артефактов: «цветной мусор / линии посередине экрана при ≥30 шарах в цепи». На эмуляторе Unreal x64 артефакт минимален или отсутствует. На железе — линейно нарастает с числом шаров и усиливается при движении мыши.

Гипотезы и проверка

Гипотеза 1 — RAM_CMD overflow (4 KB ring). Решение TSLib FT.Coprocessor.Write уже опрашивает REG_CMDB_SPACE перед каждой SPI-записью и ждёт, пока копроцессор освободит место. Переполнение невозможно через TSLib API. Гипотеза отклонена.

Гипотеза 2 — RAM_DL overflow (8K commands = 32 KB). Подсчёт DL команд на кадр: bg ~24 + killzone ~14 + frog 6 спрайтов с matrix ~75 + chain N шаров × 8 + cursor ~14 + bullet 1 × 8 ≈ 149 + 8N. При 60 шарах ≈ 629 DL — далеко от 8192 лимита. Подтверждено визуально через красную полоску внизу экрана (диагностика, потом убрана). Отклонено.

Гипотеза 3 — cmd_swap через CMD-FIFO вместо REG_DLSWAP. По FT81x документации cmd_swap = «копроцессор сам выполнит swap когда DL готов». Заменили manual REG_DLSWAP=FRAME на FT_CMD_Swap. Программа зависла (deadlock в CMD-FIFO). Откат, гипотеза отклонена.

Гипотеза 4 — vsync-first sync (HighLander). Кадровый sync с FT812 vsync перед SPI write. Идея: write попадает в vblank window, не накладывается на render. На железе частично помогло — артефакт исчез при стационарной мыши, остался при mouse motion.

Корень оставшегося артефакта: тяжёлый build при mouse motion. ZL_AimUpdate детектит motion → Frog_ComputeAngle запускается с atan2 LUT[129] + hybrid follow + 8-octant logic = десятки сложений/делений. Build удлиняется, SPI write выходит за vblank window в render time → race с FT812 RAM_DL read.

Решение — parallel build + vsync-first write

Перестраиваем main loop:

.Loop           ; --- 1. Input + game state + Build DL в Z80 buffer ---
                ; ВЫПОЛНЯЕТСЯ ПАРАЛЛЕЛЬНО с FT812 рендером prev frame.
                CALL Input.Mouse.UpdateMouseState
                CALL ZL_AimUpdate                  ; mouse/keyboard → Frog_Angle
                CALL ZL_SmoothMouse
                CALL Frog_Update                   ; ComputeFrogAngle + recoil
                CALL VDC_Update
                CALL Bullet_Update
                CALL Bullet_CheckCollision
                FT_CMD_Start                       ; reset Z80 buffer ptr
                FT_DL_Start                        ; cmd_dlstart
                FT_VertexFormat 4
                FT_ClearColorRGB32 0x102030
                FT_ClearAll
                CALL ZL_DrawFrame                  ; bg + frog + chain + cursor + bullet
                FT_Display

                ; --- 2. Sync с FT812 vsync ПОСЛЕ build ---
.WaitIntSync    FT_RD_REG8 FT_REG_INT_FLAGS
                AND  FT_INT_SWAP
                JR   Z, .WaitIntSync
.WaitDLSwap     FT_RD_REG8 FT_REG_DLSWAP
                AND  3
                JR   NZ, .WaitDLSwap

                ; --- 3. Burst write Z80 buffer → FT812 RAM_CMD (в vblank window) ---
                FT_CMD_Write
                CALL FT.Coprocessor.WaitFlush
                FT_WR_REG8 FT_REG_DLSWAP, FT_DLSWAP_FRAME
                JP .Loop

Ключевое отличие от предыдущей схемы: wait FT INT_SWAP перенесён в середину loop, между build и write. Z80 cycles на input + game state + DL build идут в параллель с тем, что FT812 рендерит предыдущий кадр. Когда Z80 готов — ждёт vsync, затем SPI burst попадает строго в vblank.

Почему это работает

При mouse motion build занимает ~3-5 ms (atan2 в ZL_KbdAimUpdate + matrix calc для frog). FT812 render @ 57Hz занимает ~15.5 ms из 17.5 ms кадра, vblank ~2 ms. В старой схеме build ел кусок vblank → write попадал в render. В новой — build делается в render time, write строго в vblank.

Урок (универсальный)

Sync на vsync должен быть ПЕРЕД сторонним I/O write, не ПОСЛЕ. Z80-only работа (input read из port, game state update в RAM, DL build в Z80 buffer) НЕ трогает FT812 → может идти в любое время, в т.ч. параллельно с render.

Только I/O в FT812 (FT_CMD_Write, FT_WR_REG) требует vblank window. Поэтому правильный sync = «build в любое время, sync прямо перед I/O burst».

Глава 18. DXT1-эмуляция на FT812: компрессия фона до 0.5 байт/пикс через L2-mask + RGB565 blend (2026-05-12)

Задача

Фон уровня 640×480 в нативном RGB565 занимает 614 400 байт в RAM_G FT812 — 60% от всего 1 МБ. Для multi-level игры (22 уровня Zuma Deluxe) это неприемлемо: 22 × 614 400 = 13.5 МБ — нужен какой-то стриминг или сжатие.

Раньше использовали трюк «400×300 RGB565 + cmd_scale(1.6) NEAREST до 640×480»: 240 000 байт, но качество ступенчатое (см. reference_zuma_vdac2_bg_compression.md). Хочется честные 640×480 при минимальном объёме.

Block-compressed форматы (DXT, ETC, ASTC) FT812 не поддерживает hardware’но. Список BITMAP_LAYOUT.format (FT81X PG Table 7): только ARGB1555, L1/L2/L4/L8, RGB332, ARGB2/4, RGB565, TEXT8X8, TEXTVGA, BARGRAPH, PALETTED565/4444/8. Никаких DXT/S3TC. BITMAP_EXT_FORMAT (под ASTC) появился только с BT815/816.

Идея

DXT1 кодирует 4×4 пиксельный блок 8 байтами:

• 2 байта c0 endpoint (RGB565)
• 2 байта c1 endpoint (RGB565)
• 4 байта = 16 × 2-битных индексов выбора цвета

Декодирование на лету: для каждого пикселя индекс 0..3 определяет цвет:

• 0 → c0
• 1 → c1
• 2 → (2·c0 + c1) / 3 (≈ ⅔c0 + ⅓c1)
• 3 → (c0 + 2·c1) / 3 (≈ ⅓c0 + ⅔c1)

FT812 умеет каждый из этих кусков по-отдельности:

• c0 и c1 endpoint цвета = два RGB565 цвета на блок 4×4 = массив (W/4)×(H/4) RGB565
• Индекс выбора = 2 бита на пиксель = формат FT_L2 W×H
• Интерполяция между c0 и c1 через индекс → реализуется аппаратным alpha-blending’ом: L2 пишет alpha канал, c0/c1 рисуются с DST_ALPHA / ONE_MINUS_DST_ALPHA blend

Это трюк из книги J. Bowman The Gameduino 2 Tutorial, Reference and Cookbook, раздел 15.6 DXT1: EVE/Gameduino 2 не поддерживает DXT1 напрямую, но может имитировать его несколькими bitmap-pass’ами и blend. Конвертер ft812_dxt_convert.py (автор — TS-Labs) раскладывает обычный DXT1 в нужный layout.

Формат raw файла

+------------------+ offset 0
|   c0 plane       |  RGB565, (W/4) × (H/4)
|   38400 bytes    |  для 640×480 → 160 × 120 cells × 2 байта
+------------------+ offset 38400
|   c1 plane       |  RGB565, (W/4) × (H/4)
|   38400 bytes    |
+------------------+ offset 76800
|   L2 mask        |  2 бит/пикс, W × H
|   76800 bytes    |  для 640×480 → 640 × 480 / 4 = 76800
+------------------+ offset 153600

Всего: 153 600 байт для 640×480 ровно 0.5 байт/пикс — теоретический минимум среди форматов FT812 (PALETTED8 = 1 байт/пикс минимум). Экономия 75% vs raw RGB565.

L2 alpha mapping (нелинейный)

Эмпирически FT812 декодирует 2-битный raw L2 в 8-битную alpha по таблице (0, 255, 85, 170) для (raw 0, 1, 2, 3). Не линейно — raw=1 → alpha=255, а не 85.

L2_ALPHAS = (0, 255, 85, 170)

Конвертер использует эту таблицу при выборе selector-ов так, чтобы итоговый композит после blend = c0 * (1-A/255) + c1 * A/255 давал:

Это точно DXT1 декомпрессия, без потерь относительно стандартного DXT1.

Display List — 3 прохода

        FT_CMD_BUF (ZL_DL_SAVE_CONTEXT)
        CALL  ZL_EmitLoadId
        CALL  ZL_EmitSetMatrix

        ; handle 1: RGB565 color cells (cell 0=c0, cell 1=c1)
        FT_BitmapHandle 1
        FT_BitmapSource ZL_BG_COLOR_ADDR
        FT_BitmapLayout FT_RGB565, ZL_BG_COLOR_STRIDE, ZL_BG_BLOCK_H
        FT_BitmapSize   FT_NEAREST, FT_BORDER, FT_BORDER, ZL_BG_W, ZL_BG_H

        ; handle 8: L2 mask на full resolution
        FT_BitmapHandle ZL_BG_L2_HANDLE
        FT_BitmapSource ZL_BG_L2_ADDR
        FT_BitmapLayout ZL_FT_L2, ZL_BG_L2_STRIDE, ZL_BG_H
        FT_BitmapSize   FT_NEAREST, FT_BORDER, FT_BORDER, ZL_BG_W, ZL_BG_H

        FT_Begin FT_BITMAPS

        ;--- Pass 1: L2 → alpha канал dst.A ---
        FT_CMD_BUF (ZL_DL_COLOR_MASK | ZL_COLOR_MASK_A)         ; только A
        FT_CMD_BUF (ZL_DL_BLEND_FUNC | (ZL_BLEND_ONE << 3) | ZL_BLEND_ZERO)
        FT_CMD_BUF (ZL_DL_COLOR_A | 255)
        FT_Vertex2ii 0, 0, ZL_BG_L2_HANDLE, 0

        ;--- готовимся к color planes ---
        FT_CMD_BUF (ZL_DL_COLOR_MASK | ZL_COLOR_MASK_RGB)       ; только RGB
        CALL  ZL_EmitLoadId
        FT_CMD_BUF FT_CMD_SCALE
        FT_CMD_BUF #00040000                  ; sx = 4.0
        FT_CMD_BUF #00040000                  ; sy = 4.0
        CALL  ZL_EmitSetMatrix

        ;--- Pass 2: c1 plane с DST_ALPHA blend ---
        FT_CMD_BUF (ZL_DL_BLEND_FUNC | (ZL_BLEND_DST_ALPHA << 3) | ZL_BLEND_ZERO)
        FT_Vertex2ii 0, 0, 1, 1               ; cell 1 = c1, out = c1 * A

        ;--- Pass 3: c0 plane с ONE_MINUS_DST_ALPHA сверху ---
        FT_CMD_BUF (ZL_DL_BLEND_FUNC | (ZL_BLEND_ONE_MINUS_DST_ALPHA << 3) | ZL_BLEND_ONE)
        FT_Vertex2ii 0, 0, 1, 0               ; cell 0 = c0, out = c0*(1-A) + dst

        FT_End
        FT_CMD_BUF (ZL_DL_RESTORE_CONTEXT)

Математика итогового пикселя:

после pass1: dst.A = L2_ALPHAS[selector] (∈ {0, 255, 85, 170})
после pass2: dst.RGB = c1 * dst.A / 255
после pass3: dst.RGB = c0 * (1 - dst.A/255) + dst.RGB * 1
           = c0 * (1 - A/255) + c1 * (A/255)

Подводные камни (на отладку ушёл вечер)

1. sjasmplus parsing macro-аргументов с |

В --syntax=ab запись FT_CMD_BUF ZL_DL_COLOR_MASK | 15 парсится криво — в макрос приходит только первый operand (ZL_DL_COLOR_MASK = #20000000), а | 15 пропадает.

Результат: COLOR_MASK эмитится с битами 0000 (всё запрещено к записи), все последующие draw-ы становятся no-op-ами, экран = clear color.

Лечение: ВСЕГДА оборачивать в скобки.

FT_CMD_BUF (ZL_DL_COLOR_MASK | 15)        ; правильно
FT_ColorMask 1, 1, 1, 1                    ; или штатный TSLib-макрос

2. FT_BitmapSize уже эмитит BITMAP_SIZE_H

FT_BitmapSize macro Filter?, WrapX?, WrapY?, Width?, Height?
    FT_CMD_BUF ((0x29 << 24) | ((W>>9)<<2) | (H>>9))    ; BITMAP_SIZE_H
    FT_CMD_BUF ((0x08 << 24) | ... | (W & 511) | ...)   ; BITMAP_SIZE
endm

Передаём 640/480 напрямую в макрос. Если попытаться вручную предварительно эмитить FT_CMD_BUF (ZL_DL_BITMAP_SIZE_H | hi) + потом FT_BitmapSize с младшими W_LO, H_LO — макрос затирает ручной SIZE_H своим (с нулевыми hi-битами, потому что W_LO=128, H_LO=480 укладываются в 9 бит). Высокие биты теряются → BITMAP_SIZE становится 128×480, draws обрезаются.

Также FT_BitmapLayout сам эмитит BITMAP_LAYOUT_H для linestride > 1023 / height > 511.

3. BITMAP_SIZE = screen extent, не source

Для c0/c1 cells источник 160×120 + cmd_scale(4,4) → screen draws 640×480. FT_BitmapSize должен быть 640×480 (final screen extent после matrix), не source 160×120. Иначе draws обрезаются до 160×120 в верхнем-левом углу.

L2 plane (handle 8) — source уже 640×480 нативно, scale identity → BITMAP_SIZE тоже 640×480.

4. Vertex2ii max 511×511

VERTEX2II имеет 9-битные поля координат (max 511). Для рисования full-screen 640×480 надо использовать Vertex2f с VertexFormat 0 (1 px) или 4 (1/16 px).

В нашем случае все draws начинаются с (0,0), поэтому Vertex2ii ОК — позиция ноль помещается, а размер контролируется через BITMAP_SIZE.

Сравнение объёмов 640×480

Когда использовать

OK Фотореалистичный фон (level background, splash screen) OK Текстуры с плавными цветовыми переходами OK Когда RAM_G сильно ограничен (multi-level игра)

NOT Спрайты с резкими краями и небольшим количеством цветов — артефакты на границах (DXT1 теряет alpha, плохо ловит тонкие линии). Для шаров/frog эффективнее ARGB4. NOT Текст и UI — здесь DXT1 даёт «лесенки» из-за грубых endpoint цветов.

Конвертер ft812_dxt_convert.py

Опции качества (effort -e 0..10):

• -e 0 — быстро, шумный (видны блоки 4×4 на градиентах)
• -e 3 — почти неотличим от оригинала (рекомендация TS-Labs)
• -e 6+ — perceptual weights + seam smoothing + residual diffusion, медленно

Базовый запуск:

python ft812_dxt_convert.py level01.png -o out/level01 -f l2 -t raw -e 3 -p

Выход:

• out/level01_l2.raw — 153 600 байт raw в формате c0|c1|L2 (грузим в RAM_G как есть)
• out/level01_l2.h — C-заголовок с offset-ами/strides (для интеграции)
• out/level01_l2_preview.png — реконструкция (для визуальной оценки качества)

Multi-level в Zuma — что меняется

22 уровня × 153 600 = 3.4 МБ pseudo-DXT L2 vs 13.5 МБ raw RGB565. Сейчас один уровень упаковывается в 10 spgbld-страниц по 16 КБ. При переключении уровней upload bg = 153 600 Б через длинный OTIR на 14 МГц Z80 — примерно 153600 / (14000000/21) = ~230 мс без учёта накладных расходов. Через DMA-передачу в SPI будет быстрее, но это отдельный путь и его надо мерить на реальном железе.

Объёмы по сравнению с zlib (cmd_inflate план):

• pseudo-DXT L2: 153 600 Б raw upload, ~230 мс через OTIR на 14 МГц, без CPU-decode
• pseudo-DXT L4: 230 400 Б raw upload, ~346 мс через OTIR на 14 МГц, без CPU-decode
• ZX0/zlib: ~100 КБ compressed → ~150 КБ uncompressed, upload меньше, но добавляется decode/inflate

pseudo-DXT выигрывает по объёму уже распакованных данных в RAM_G: мы храним не полный RGB565-кадр, а две маленькие цветовые плоскости и полноэкранную маску. CPU-decode не нужен; цена переносится в несколько проходов отрисовки FT812. Качество фотореалистичных фонов визуально приемлемое начиная с -e 3.

Глава 19. Апгрейд DXT1-эмуляции с L2 до L4: +50% SPI за фотокачество (2026-05-12)

Зачем понадобился L4

Глава 18 описала DXT1 на L2-маске: 0.5 байт/пикс, 153 600 байт на 640×480. Объёмно идеально, но на каменной текстуре фона level_src_01 оставалась заметная блочность 4×4.

Корень: L2-маска даёт всего 4 уровня между endpoints ({0, 85, 170, 255} → четыре цвета: c0, ⅔c0+⅓c1, ⅓c0+⅔c1, c1). На гладких градиентах внутри блока 8 уникальных оттенков в исходнике вынуждены коллапсировать в 4 → видна ступенька в каждом блоке.

Чтобы оценить «насколько лучше» — переходим на L4:

• 16 уровней маски (линейный ramp 0..255 шагом 17)
• 4×4 блок цветов c0/c1 тот же, размер endpoint planes не меняется
• mask 4bpp вместо 2bpp → +76 800 байт (76800 → 153600)
• Итого raw: 230 400 байт vs 153 600 = +50%

Пиксельный «бюджет фона» 200 КБ был принятой границей бюджета SPI/RAM_G. 230 КБ — чуть выше потолка, но bg уже по-настоящему фотореалистичен.

Сравнение L2 vs L4 в одном блоке

оригинал блока 4×4:          цвета на пиксель
+---+---+---+---+
| A | A | B | B |            A   = (200, 90,  60)
| A | A | B | B |            B   = (210, 130, 80)
| C | C | D | D |            C   = (180, 100, 70)
| C | C | D | D |            D   = (170, 110, 90)
+---+---+---+---+

L2 (4 уровня):                L4 (16 уровней):
endpoints: c0=A, c1=D         endpoints: c0=A, c1=D
selectors per pixel:          selectors per pixel:
  A→0  B→2 (⅔A+⅓D)             A→0   B→5  (a~85)
  C→3 (⅓A+⅔D)  D→1              C→10 (a~170)  D→15
ошибка перекраски:            ошибка перекраски:
  B → ⅔A+⅓D отличается от B     B → a*A+(1-a)*D с лучше подбираемым α
  → видимый шов между блоками  → плавная интерполяция, шов невидим

Что меняется в raw layout

Только размер маски и её stride:

+------------------+ offset 0
|   c0 plane       |  RGB565, (W/4) × (H/4)
|   38400 bytes    |  для 640×480 → 160 × 120 cells × 2 байта
+------------------+ offset 38400
|   c1 plane       |  RGB565, (W/4) × (H/4)
|   38400 bytes    |
+------------------+ offset 76800
|   L4 mask        |  4 бит/пикс, W × H  (вместо 2 бит/пикс)
|   153600 bytes   |  для 640×480 → 640 × 480 / 2 = 153600  ← х2 от L2
+------------------+ offset 230400

Изменения в asm (минимально)

main.asm: 10 → 15 spgbld pages

BG_FIRST_PAGE      EQU 7
; было:
; BG_PAGE_COUNT    EQU 10                ; DXT1-decomp 640×480 (c0|c1|L2 = 153600)
; стало:
BG_PAGE_COUNT      EQU 15                ; DXT1_L4 640×480 (c0|c1|L4 = 230400, last padded)

RAM_G layout не меняется: BG занимает #010000..#04C000 = 245 760 байт (230 400 реальных + 15 360 байт нулевого хвоста последней spgbld-страницы). Killzone сидит ровно на #04C000 — без overlap.

MainLoop.asm: формат маски и stride

; было:
; ZL_BG_L2_STRIDE EQU ZL_BG_W / 4                ; FT_L2 = 2bpp → 4 пикс/байт
; ZL_FT_L2        EQU 17                         ; format code FT_L2

; стало:
ZL_BG_L2_STRIDE EQU ZL_BG_W / 2                  ; FT_L4 = 4bpp → 2 пикс/байт
ZL_FT_L2        EQU FT_L4                        ; format code FT_L4 (=2)

FT_L4 = 2, FT_L2 = 17 — две разные ячейки в BITMAP_LAYOUT.format (см. FT81x PG §4.7.7, Table 7). Stride для 4bpp = (W+1)/2.

DL pipeline — без изменений

;--- Pass 1: маска → dst.A через ONE/ZERO blend ---
FT_CMD_BUF (ZL_DL_COLOR_MASK | ZL_COLOR_MASK_A)
FT_CMD_BUF (ZL_DL_BLEND_FUNC | (ZL_BLEND_ONE << 3) | ZL_BLEND_ZERO)
FT_CMD_BUF (ZL_DL_COLOR_A | 255)
FT_Vertex2ii 0, 0, ZL_BG_L2_HANDLE, 0          ; теперь L4 mask

;--- Pass 2/3: c1/c0 с DST_ALPHA blend — те же команды ---

L4 декодируется FT812 в линейный 8-битный alpha: raw_value × 17 (значения 0, 17, 34, …, 255). В отличие от L2 ({0, 255, 85, 170}), L4 без перестановок — selector k даёт alpha ≈ k/15 * 255. Конвертер автоматически использует правильное соответствие.

Финальный blend dst.RGB = c0*(1-A) + c1*A алгебраически одинаков — просто A теперь имеет 16 значений вместо 4.

Подводный камень: CPU энкодер на Windows нежизнеспособен

Для 640×480 = 19 200 блоков 4×4. Локальный энкодер (без GPU):

Multiprocessing у concurrent.futures.ProcessPoolExecutor на Windows не shared memory: каждый воркер получает копию blocks через pickle. Для 230 КБ blocks × 6 воркеров = 1.4 МБ × Python overhead ~50× = ~70 МБ накапливается; через несколько итераций OOM на 4 ГБ VM.

Single-process работает стабильно, но 19 200 блоков × ~0.5 сек/блок (effort 4 с perceptual weights) = 160 мин. Эта длительность была подтверждена эмпирически на CPU 2 × Xeon Gold 6132 под Hyper-V.

Решение: запускать энкодер на хост-машине с GPU через pyopencl.

python ft812_dxt_convert.py level_src_01.png -o out -f l4 -t raw -x -p -e 8

На AMD gfx1032 весь pipeline (initial pair generation + hybrid refine + write) проходит менее чем за 30 секунд на effort 8. Готовые файлы (out/level_src_01_l4.raw 230 400 байт) копируются в проект, режутся на страницы, собираются.

Разрезание файла на 16-КБ страницы для spgbld

# split_l4.py
PAGE = 16384
data = open('level_src_01_l4.raw', 'rb').read()
assert len(data) == 230400
n_pages = (len(data) + PAGE - 1) // PAGE     # = 15
for i in range(n_pages):
    chunk = data[i*PAGE:(i+1)*PAGE]
    if len(chunk) < PAGE:
        chunk += b'\x00' * (PAGE - len(chunk))   # padding zeros
    open(f'bg_l4_p{i:02d}.bin', 'wb').write(chunk)
# wrote 15 файлов, последний с 1024 реальных байт + 15360 нулей

spgbld_vdac2.ini:

Block = #0000, #07, bg_l4_p00.bin
Block = #0000, #08, bg_l4_p01.bin
...
Block = #0000, #15, bg_l4_p14.bin
Block = #0000, #16, killzone_p00.bin     ; следом, без overlap

Итоговый бюджет

L4 даёт 2/3 объёма native RGB565 при визуально неотличимом качестве — ровно та точка цена/качество, которая нужна для multi-level Zuma: 22 × 230 КБ = 5 МБ vs 13.5 МБ raw. Помещается в обычный TR-DOS + spgbld.

Когда выбирать L2 vs L4

• L2: tile-фон, splash-screen с большими flat-зонами, ограниченный RAM_G. Если 75% экономии важнее минимальной блочности — берём L2.

• L4: фотореалистичные уровни, фоны с плавными градиентами (наш случай), splash-screen с тонкой деталировкой. +50% к L2, но качество скачком вверх.

Глава 20. Render-loop оптимизации и DL-emit ловушки (2026-05-17)

Главы 15-19 закрыли визуальную часть Zuma. Эта глава — три приёма, которые выжали из FT812 ещё несколько процентов и закрыли тонкий баг рендера. Появились в процессе финального полировок kill-zone (плавное поглощение шаров) и frog-композиции.

20.1 Bucket-grouped tangent rotation: 32 cmd_rotate → 16, а потом обратно

VDC выдаёт каждому шару в цепи tangent 0..255 — направление трека в точке. HD-источник вращает каждый шар своим cmd_rotate(angle), но на FT812 это N call’ов cmd_loadidentity → cmd_translate → cmd_rotate → cmd_translate → cmd_setmatrix на каждый шар. При длине цепи 85 шаров это ~30% бюджета DL.

Bucket-grouping — группировка шаров по углу:

1. Pre-pass: для каждого шара вычисляем bucket = (tangent + N/2) >> log2(N) и кешируем (bucket, cell, Vx, Vy) в RAM.

2. Outer loop по N бакетам: emit matrix для bucket * (256/N), inner scan — все шары с этим bucket’ом → Cell + Vertex2f.

При N=32: шаг 11.25° (256/32 = 8 BRAD = 11.25°). Шар получит visually-acceptable rotation, плюс цены matrix-emit’а только 32 раза за кадр.

; 32-bucket scheme: bucket = (tangent+4) >> 3
LD   A, (VDC_LastTangent)
ADD  A, 4                              ; round-nearest
RRCA : RRCA : RRCA                    ; >> 3
AND  31                                ; mod 32
LD   (cache_bucket), A
; ...позже, в outer loop:
LD   A, (current_bucket)
ADD  A, A : ADD A, A : ADD A, A        ; bucket * 8
CALL ZL_EmitRotate                     ; A = BRAD 0..255

Lesson: 16 vs 32. Изначально 32 бакета считались избыточными — попробовали 16 (шаг 22.5°). На статичных шарах выглядело норм, но на быстро двигающихся по крутой кривой (вход в killzone, головной шар) проявился визуальный jitter — глаз ловит ступеньки. Откатили обратно в 32. Урок: не оптимизируй “на глаз” в статике; смотри на самые быстрые моменты gameplay.

20.2 Per-sprite alpha fade через COLOR_A — плавное поглощение

FT812 имеет команду COLOR_A(alpha) — умножает alpha-канал последующего bitmap’а на 0..255. Это позволяет делать dissolve-эффект на спрайте без изменения текстуры.

В нашем случае: head-шар цепи во время Game Over absorb должен плавно исчезать в kill-zone, а не пропадать дискретно. Алгоритм:

; Каждый тик absorb (state=1):
LD   A, (VDC_HSub)             ; HSub 0..31 in cell
ADD  A, A : ADD A, A : ADD A, A  ; * 8 (max 31*8 = 248)
CPL                              ; alpha = 255 - HSub*8
LD   (VDC_HeadAbsorbAlpha), A   ; смыкается с 255 до 7 за цикл

; В .BInner bucket-loop, перед Vertex2f head-шара:
LD   A, (VDC_HeadAbsorbAlpha)
LD   E, A
CALL FT.Coprocessor.ColorA      ; emit COLOR_A(alpha)
LD   C, (IX+2) : LD B, (IX+3)   ; перезагрузить BC (Cell/ColorA уничтожили)
LD   E, (IX+4) : LD D, (IX+5)
CALL FT.Coprocessor.Vertex2f
LD   E, 255
CALL FT.Coprocessor.ColorA      ; восстановить для остальных шаров

Ловушка: COLOR_A — persistent state DL. Если не восстановить до 255, все последующие спрайты в этом кадре будут полупрозрачные.

Identify the target sprite: head-шар = первая запись в кеше bucket-prepass по адресу ZL_BALL_CACHE_ADDR. В .BInner проверяем IX == ZL_BALL_CACHE_ADDR (PUSH IX / POP HL / CP HIGH / CP LOW) — это slot[0]. COLOR_A применяется только к этому одному Vertex2f.

20.3 Cell/ColorA корраптят BC/DE — координаты грузить ПОСЛЕ, а не ДО

Все одноаргументные DL-команды TSLib (Cell, ColorA, Tag, LineWidth…) эмитятся через Command_BCDE — формируют 4 байта опкода в BC/DE и пишут в буфер. После такого CALL’а BC и DE мусор.

Из этого следует жёсткое правило для пары Cell+Vertex2f:

; WRONG — баг, который у нас прятался месяц в DrawKillzoneDual:
LD   BC, x_scaled              ; BC = X
LD   DE, y_scaled              ; DE = Y
XOR  A
CALL FT.Coprocessor.Cell        ; BC, DE corrupted!
CALL FT.Coprocessor.Vertex2f    ; uses corrupted BC, DE → sprite в ?,?

; RIGHT — Cell первым, координаты после:
XOR  A
CALL FT.Coprocessor.Cell
LD   BC, x_scaled
LD   DE, y_scaled
CALL FT.Coprocessor.Vertex2f

Bug-symptom при wrong ordering: спрайт рисуется в верхнем-левом углу или вообще не виден — Cell оставляет в BC значение 0x0600 (опкод Cell), Vertex2f интерпретирует это как X*16 = 1536, что выходит за разумный экранный диапазон, либо clip.

Эвристика: если sprite появляется не там где ожидаешь, или мигает, или “то ли есть, то ли нет” — первое что проверить: между LD BC,coords и Vertex2f нет ли промежуточного CALL’а к Cell/ColorA/Tag/etc. Если есть — переставить порядок.

20.4 Скип лишнего DL: bg-baked = overlay не нужен

Иногда самый быстрый рендер — не рисовать вообще. Kill-zone “закрытый череп” уже запечён в bg-арте (golden 8-pointed sun); рисовать overlay поверх в idle-state — двойная работа.

DrawKillzoneDual:
                LD   A, (VDC_KzFrame)
                CP   2
                RET  C                  ; KzFrame=0/1 (idle / final GO) → bg сам показывает
                ; ...emit Cell + Vertex2f только когда KzFrame >= 2 (анимация)

Это экономит ~10 байт DL × 60 FPS = 600 байт/сек трафика SPI, который освобождает Z80 cycles для chain physics + input + sound. Микроптимизация, но накладывается на каждый “статичный” sprite в render-loop’е.

20.5 Continuous-motion absorb через HSub-advance (mirror of fast-spawn)

Last optimization-pattern: используй существующий механизм движения, не пиши свой. Игра уже умеет двигать цепь плавно — в fast-spawn phase chain двигается HSub++ × VDC_FAST_ADVANCE=12 раз за тик. Это даёт плавное скольжение шаров по треку.

Для Game Over absorb разумно использовать тот же механизм с другими параметрами:

VDC_UpdateAbsorb:
                LD   B, VDC_ABSORB_ADVANCE  ; e.g., 8 (32/8 = 4 ticks/cell)
.aa_loop:       PUSH BC
                CALL .ua_move_once          ; HSub++; on wrap → array shift, HSA capped
                POP  BC
                DJNZ .aa_loop
                ; alpha рассчитывается из HSub → синхрон с motion

.ua_move_once:

LD   A, (VDC_HSub)
INC  A
CP   VDC_CELL_SIZE
JR   C, .save                 ; HSub < CS → просто save
XOR  A                         ; wrap: HSub=0
LD   (VDC_HSub), A
; remove slot[0] (array shift), HSA capped → новый head в том же clamped
; последнем track sample → 1px continuity jump (invisible)

Эффект: tail-шары плавно скользят (sub-pixel HSub), head clamped на последнем сэмпле трека, alpha fade ↔ HSub progress. При wrap — array shift И сброс alpha в 255. Visual continuity = 1 px разрыв вместо discrete cell-jump.

Аналогичный паттерн можно применить к: уменьшению цепи после match-3 cascade, выбросу bonus-шаров, любым “цепь сжимается/растягивается” анимациям.

20.6 Тоннели: маскирование шаров не лечит бюджет строки

Практический вывод по уровням с тоннелями/top-mask на реальном FT812: попытки ускорить такие уровни через маскирование/отсечение шаров не дали рабочего результата. Проверялись подходы, где шары под тоннелем не рисуются или дополнительно ограничиваются маской/областью отрисовки. На реале это не дало выигрыша по pixel-clock budget строки.

Причина в том, что основной дорогой участок для этих сцен — не только overdraw top-mask, а широкие bitmap-pass’ы, DL-walk и matrix-команды на шарах:

• cmd_loadidentity / cmd_translate / cmd_rotate / cmd_setmatrix раздувают поток команд на каждый новый угол;

• FT812 всё равно должен разобрать DL-состояние и пройти команды матрицы;

• маскирование пикселей не уменьшает стоимость matrix-emit’а и DL-walk;
• если маска заменяет красивый alpha-край на жёсткую вырезку, тоннель начинает выглядеть грубо: шар не «уходит под край», а обрубается.

Что важно: у тоннелей/top-mask был красивый альфа-канал. Упрощённые маски ради экономии не только не спасли такты строки, но и ухудшили внешний вид — пропала мягкая граница, вырезка стала грубой. Это плохой обмен: качество потеряли, а строчный бюджет FT812 не выиграли.

Рабочее правило после перехода к 1024×768@59 и одному дешёвому fullscreen-проходу:

• не лечить тоннели грубым pixel-mask’ом;
• сохранять alpha-маски там, где они дают красивое перекрытие;

• выигрывать такты строки через формат/число полноэкранных проходов и группировку матриц, а не через визуальное урезание тоннелей;

• если строка сыпалась в двух отдельных случаях — на двухцепочных уровнях и на уровнях с тоннелями — не выключать анимацию шаров как workaround, если бюджет строки уже возвращён на уровне фона/режима;

• pause/dialog не должны рисовать поворот шаров вообще.

Урок: если проблема проявляется как срыв строк на реальном FT812, сначала проверять не «сколько пикселей шара видно», а сколько полноэкранных/широких bitmap-pass’ов лежит на той же строке и сколько state changes идёт через DL. Scissor/stencil/mask полезны против fillrate/overdraw, но не являются лекарством от перегруженного бюджета строки.

Глава 21. Per-ball matrix с per-slot hysteresis и grouped emit (2026-05-18)

21.1 Постановка задачи

Шары цепи Zuma вращаются по тангенсу трека: на изгибе спрайт повёрнут так, чтобы рисунок (рельеф/блик) шёл по направлению движения, а не «лежал на боку». На каждый шар нужна BITMAP_TRANSFORM с углом = tangent_at_track[i].

В лоб через FT812 это:

; per ball: 5 coproc-commands → 6 BITMAP_TRANSFORM_X DL entries
CALL ZL_EmitLoadId                ; cmd_loadidentity
LD   HL, ZL_BALL_HALF
LD   DE, ZL_BALL_HALF
CALL ZL_EmitTranslate             ; cmd_translate(+16, +16)
LD   A, (cache+0)
CALL ZL_EmitRotate                ; cmd_rotate(tangent_byte)
LD   HL, -ZL_BALL_HALF
LD   DE, -ZL_BALL_HALF
CALL ZL_EmitTranslate             ; cmd_translate(-16, -16)
CALL ZL_EmitSetMatrix             ; cmd_setmatrix

Translate(+16) → Rotate(θ) → Translate(-16) — стандартная связка чтобы повернуть spritе вокруг центра bitmap (16,16) для атласа 32×32, а не вокруг угла (0,0).

Стоимость на цепь 35 шаров: 175 coproc-команд + 210 DL-записей BITMAP_TRANSFORM.

FT812 coproc’у на это не хватает vblank-окна даже на 74Hz → тиринг на реале.

21.2 Альтернатива #1: бакеты — почему не подошло

Классический способ дёшево покрыть N шаров: разбить tangent диапазон 0..255 BRAD на K корзин (buckets), назначить каждому шару ближайшую корзину, и в outer-loop эмитить матрицу 1 раз на корзину, а внутри обходить все шары своей корзины.

матрицы за кадр = K (фиксированно)
DL записи      = K × 6 transform + N × (cell + vertex)

K=32 → 11.25° на bucket, ~6× быстрее чем per-ball. Так и было сделано до 2026-05-18.

Проблема: «глобальный flip». Если raw tangent шара трамплинит между двумя бакетами кадр-к-кадру (например, из-за округления track-данных), его поворот скачет на 11.25°. И — что хуже — поскольку соседние шары находятся в одной с ним корзине (общая матрица), они визуально мигают сегментом цепи целиком. Глаз ловит «волну» на изгибах.

Это была реальная жалоба пользователя за всю прошедшую неделю работы.

21.3 Альтернатива #2: чистый per-ball — почему сломалось на реале

Прямой переход к per-ball matrix (для каждого шара свой cmd_setmatrix) убирает эффект «сегмент мигает» начисто — каждый шар вращается независимо. Visual quality максимальный.

Но coproc-нагрузка взлетела в ~6 раз. На баре эмуляторе (Unreal x64) кадр строился, на реальном FT812 при 74Hz и DL ≥ 300 записей vblank-окна не хватало: коприйцессор не успевал обработать команды до следующего DLSWAP — экран рвало.

Симптом: верхняя половина — frame N, нижняя — frame N−1, с горизонтальной чертой разрыва. Появляется в самых нагруженных моментах (длинная цепь + жаба + bullet).

21.4 Гибрид: per-slot hysteresis + run-length grouped emit

Идея: хранить tangent per-ball независимо (это уже даёт per-slot stability — flicker нет), но эмитить матрицу только когда у соседних шаров в цепи tangent действительно поменялся.

На спирали Zuma соседние шары цепи находятся на одной дуге трека, поэтому их tangent’ы очень близки. С разумной квантизацией (16 BRAD, на длинной цепи 32 — адаптивно, см. §21.4.2) адъяцентные шары часто попадают в одинаковую дольку — для них достаточно одной матрицы.

21.4.1 Per-slot byte-level hysteresis

Pre-pass для каждого шара хранит свой «стабильный» tangent в page-5 RAM (#4100 + slot_idx), обновляется только когда raw отличается на ≥ THR=8 BRAD:

; D = raw tangent (preserved). HL = state addr через H = STATE_HI, L = slot.
LD   A, (VDC_LastTangent)
LD   D, A
LD   A, C                              ; slot index
LD   H, ZL_BALL_TANGENT_STATE_ADDR >> 8 ; #41 (low byte STATE_ADDR = 0 заведомо)
LD   L, A
LD   A, (HL)                           ; prev stable
LD   E, A
LD   A, D                              ; raw
SUB  E                                  ; (raw - prev) mod 256
JP   P, .stab_pos                      ; signed sign-bit check
NEG
.stab_pos: CP   ZL_BALL_TANGENT_HYSTERESIS_THR  ; = 8
JR   NC, .stab_update                  ; |delta| >= THR → update
LD   A, E                              ; else keep prev
JR   .stab_done
.stab_update: LD   A, D
LD   (HL), A
.stab_done:                            ; A = stable tangent (raw if updated, prev else)

Почему именно 8 BRAD threshold: должен быть ≥ ширине квантизационной корзины (8 BRAD), иначе raw, осциллирующий на границе ±4, заставит stable скакать между двумя бакетами. С 8: stable меняется только если raw уехал заметно в новую область → stable settles в одной корзине.

Почему ёлки H=STATE_ADDR>>8, L=slot (а не LD HL,…+LD DE,slot+ADD HL,DE): выбрали ZL_BALL_TANGENT_STATE_ADDR=#4100 с low-byte=0 специально, чтобы 8-bit slot index ставился прямо в L без сложения. Сохраняет регистр D (с raw tangent) от затирания через LD DE, addr.

21.4.2 Адаптивная квантизация: грубее по мере роста цепи

В per-ball loop квантуем stable tangent к корзине и сравниваем с tangent’ом, для которого мы УЖЕ эмитили матрицу. Совпал — пропускаем эмит матрицы.

Адаптивная грубость по длине цепи (ключевой приём — MainLoop.asm:.PerBallLoop): ширина корзины зависит от ZL_BallCount (= длина цепи). На короткой цепи запас DL-бюджета большой → можно квантовать мелко (плавнее поворот); на длинной цепи бюджет на исходе → квантуем грубее, чтобы число эмитов матриц не росло линейно с числом шаров:

• BallCount < 70 → AND #F0 = 16 корзин (шаг 16 BRAD = 22.5°);
• BallCount ≥ 70 → AND #E0 = 8 корзин (шаг 32 BRAD = 45°) — грубее.

.ChainDraw:     LD   A, #01                         ; sentinel (не кратен 16/32)
                LD   (ZL_TmpLastTangent), A
                LD   A, (ZL_BallCount)
                LD   B, A                            ; loop count
                LD   IX, ZL_BALL_CACHE_ADDR
.PerBallLoop:   LD   A, (IX+1)                       ; cell (+1) = 0xFF marks gap
                CP   #FF
                JP   Z, .PBSkip                      ; (JR out of range — body grew)
                PUSH BC
                LD   A, (IX+0)                       ; stable tangent
                LD   D, A
                LD   A, (ZL_BallCount)
                CP   70                              ; адаптивный порог
                LD   A, D
                JR   C, .PBQuant16
                AND  #E0                             ; длинная цепь (≥70): 8 корзин — грубее
                JR   .PBQuantDone
.PBQuant16:     AND  #F0                             ; обычно: 16 корзин
.PBQuantDone:   LD   HL, ZL_TmpLastTangent
                CP   (HL)
                JR   Z, .PBNoMatrix                  ; та же корзина → переиспользуем матрицу
                LD   (HL), A                          ; новая корзина → save
                ; матрица из ПРЕДРАСЧЁТНОГО LUT (минуя coproc, см. §27.6)
                LD   A, (ZL_TmpLastTangent)
                CALL ZL_EmitBallMatrixFromBRAD
.PBNoMatrix:
                ; ... handle, cell, vertex2f для текущего шара (без матрицы) ...

Два рычага вместе: (1) предрасчёт — матрица не строится coproc-командами на лету, а копируется готовой из ZL_ChainMatrixLUT (32×24 байта, генератор make_chain_matrix_lut.py, см. §27.6); (2) адаптивная группировка — соседи по дуге попадают в одну корзину, эмит делается раз на корзину, а ширина корзины растёт с длиной цепи. Итог — число матриц на кадр почти не зависит от длины цепи.

Sentinel #01 гарантирует что первый шар всегда триггерит эмит матрицы: реальные quantized tangent’ы кратны 16 (или 32), значению 1 никогда не равны.

21.4.3 Что в итоге

На спирали с 35 шарами цепи статистически на цепь приходится ~8–15 уникальных quantized buckets, и balls внутри bucket’а лежат подряд (соседи по track) → matrix emit срабатывает ~8–15 раз вместо 35. 3–4× падение coproc-нагрузки. Адаптивная грубость (§21.4.2) удерживает это число и на длинных цепях: при BallCount ≥ 70 корзины вдвое шире (8 вместо 16), так что эмитов не больше.

Доводка v030 (§27.6): сам эмит матрицы позже перевели на предрасчётный LUT (ZL_EmitBallMatrixFromBRAD) — матрица копируется готовой, coproc-команды на построение матрицы больше не тратятся вообще (строка coproc-cmd/frame ниже относится к реализации 2026-05-18 до LUT).

Метрики (snapshot 2026-05-18, до LUT):

              Bucketed (старое)    Per-ball naive     Per-ball + grouped
matrix/frame         32              35                  8-15
coproc-cmd/frame     160             175                 40-75
DL entries (chain)   294             315                 ~150
flip-flicker         YES             NO                  NO
vblank ok @ 74Hz     YES             NO (tear)           YES

21.5 Ловушки реализации

Регистр-сейв (B-clobber)

Helpers FT_BitmapLayout, FT_BitmapSize — макросы, разворачивающиеся в инлайн через FT_CMD_BUF, который клобает BCDE. Поэтому паттерн «сохрани цвет в B → emit setup macros → возьми обратно из B» молча даёт мусор:

LD A, (Bullet_Color)
LD B, A                                ; "save"
... CALL ZL_EmitBallHandle ...
FT_BitmapLayout ...                    ; ← кладёт B = 0x07 (opcode)
FT_BitmapSize ...                      ; ← кладёт B = 0x08
LD A, B                                ; ← А не цвет! → cell wrong
AND 3
CALL Cell                              ; рисует случайный цвет

Симптом был: жаба стреляет одним цветом, в цепь вставляется другой. Потому что в памяти Bullet_Color корректный (VDC_InsertAt(Bullet_Color)), а на экране во время полёта пуля рисовалась мусорным cell.

Фикс: перечитать color из памяти после макросов, не из регистра:

LD A, (Bullet_Color)
CP 4
LD A, 0
JR C, .h0
LD A, 9
.h0: CALL ZL_EmitBallHandle
FT_BitmapLayout ...
FT_BitmapSize ...
LD A, (Bullet_Color)                   ; re-read — macros clobbered registers
AND 3
ADD A,A : ... *32
CALL Cell

Аналогично для chain draw, но там есть IX → (IX+1) cache pointer — Cell читаем оттуда, IX через хелперы сохраняется.

Sentinel выбор

ZL_TmpLastTangent инициализируется #01, а не #FF — потому что после AND #F8 реальные quantized tangent’ы могут быть 0, 8, 16, ..., 248. Значение #FF после AND F8 даёт #F8 (валидный bucket), и если у первого шара quantized = 248 = #F8, он бы совпал с sentinel и пропустил matrix emit — а матрицы ещё нет (FT812 unitialized state) → шар нарисуется с identity matrix. Sentinel #01 гарантированно не совпадает ни с одним quantized = multiple-of-8.

JR vs JP — out of range

После добавления matrix-skip логики body цикла вырос. JR Z, .PBSkip (2 байта, ±127 диапазон) перестал доставать. Заменил на JP Z, .PBSkip (+1 байт но absolute address). Уроки прошлых сессий: при росте кода всегда чекать JR-distances через --lst.

21.6 RNG bias как побочный bug (2026-05-18)

Параллельно с per-ball рефакторингом расширил VDC_NUM_COLORS с 4 до 6 (атлас уже содержал colors 4-5: white + yellow). Жёлтый не появлялся в цепи СОВСЕМ.

LFSR Galois с polynomial #B400:

LD HL, (VDC_LfsrSeed)
LD A, L
AND 1                          ; bit out
SRL H : RR L                   ; shift HL right
JR Z, .no_xor
LD A, H : XOR #B4 : LD H, A    ; feed back via poly
.no_xor:
LD (VDC_LfsrSeed), HL
LD A, L
XOR H                          ; 8-bit "random"
AND 7                          ; → 0..7
CP NUM_COLORS                  ; reject если >= NUM
JR NC, retry
RET

Скрытая корреляция битов: для конкретного poly #B400, после XOR L⊕H и маски AND 7 результат покрывает почти исключительно {0,1,3,4}, а значения {2,5,6,7} встречаются ~1 раз на 1000. Rejection (CP NUM_COLORS) отсекает 6,7 — а 2 и 5 он не лечит. Цвета 2 (фиолетовый) и 5 (жёлтый) выпадают почти никогда.

Замер на baseline: 1000 вызовов VDC_RandomColor дали [306, 231, 2, 230, 230, 1].

Фикс — mul-then-shift вместо bit-masking:

LD A, L
XOR H                          ; A = 8-bit raw rand
LD L, A
LD H, 0                        ; HL = rand byte
LD A, VDC_NUM_COLORS           ; A = 6
CALL ZL_Mul16x8                ; HL = rand * NUM (max 6*255=1530, <16-bit)
LD A, H                        ; A = (rand * NUM) >> 8 = 0..NUM-1
RET

Принцип: любое значение rand 0..255 распределяется по NUM_COLORS bucket’ов пропорционально размеру bucket’а. Bias ≤ 1.4% даже при равномерном rand, и НЕ требует, чтобы определённые биты были некоррелированы.

После замера: [166, 111, 110, 57, 222, 334] — все 6 цветов появляются. Дистрибуция всё ещё неравномерна из-за самой неравномерности LFSR-байта, но колор 5 теперь в игре.

21.7 Применимость в других случаях

Паттерн «per-slot hysteresis + run-length grouped emit» обобщается:

1. Условие применимости: есть много объектов, которым нужно индивидуальное состояние (color, scale, rotation), но в смежных объектах состояние часто одинаково.

2. Шаг 1: state per-object с byte-level hysteresis (storage = N байт RAM, threshold ≥ quantization step).

3. Шаг 2: в draw-loop сравнивай с last-emitted state, пропускай emit при совпадении.

Кандидаты на это в Zuma VDAC2:

• Spin frame (cell number): соседние шары на одной фазе rolling — сейчас они уже имеют разные cell индексы из-за t × K, group skip = no-op.

• Bitmap handle 0 vs 9 (для colors 4-5 split): группировать по color group — уже работает (handle меняется только при cell ≥ 128).

Глава 22. Расщепление Core на main0 + main1 (slot 1 + slot 3) и невидимая ловушка CMD_ADDRESS_PTR (2026-05-18)

22.1 Проблема: лимит “считать байты Core” 9216

К v020 в Core (slot 1 page 5, ORG #5C00) набралось 9210 байт из 9216 — 6 байт запаса. Каждая новая фича режется на размере: match-3 explode pass добавили с трудом, шрифт “GAME OVER” вкручен между функциями, ring log переехал в slot 0 ещё раньше. Дальше расти некуда — а впереди 22 уровня + стартовый экран + level select + сжатие данных.

22.2 Архитектура split

В соседнем TS-Conf проекте ~/Desktop/Zuma Deluxe уже работает паттерн main0 / main1:

В VDAC2 main0 на 2026-05-18 ужался до 415 байт (Start + Initialize + Init_Core + Init_Int + INT_Handler), main1_play занял 8795 байт в 16K window’е. Лимит “считать байты Core” снят — теперь есть ~7.5K запаса в main1 и ~8.8K в main0.

                ; main0 (slot 1 page 5)
                ORG EntryPoint                         ; #5C00
                module Core
Start:          LD SP, StackTop
                CALL Initialize
                JP MainLoop                            ; target #C000+ in slot 3 — works
                                                       ; once Init_Core sets slot 3 = page 4

Initialize:     CALL Init_Core
                ...

Init_Core:      FMapAddrInit
                SetPage1 5                             ; slot 1 -> main0 page
                SetPage2 6                             ; slot 2 -> TrackData
                SetPage3 #04                           ; slot 3 -> main1_play page
                RET

Init_Int:       ...                                    ; IM2 setup + first INT wait
INT_Handler:    EI : RET
Main0_End:                                             ; ОБЯЗАТЕЛЬНО после всего main0 кода

                ; main1_play (slot 3 page #04)
                SLOT 3 : PAGE #04 : ORG #C000
Main1_Start:
                include "Init_Video.asm"
                include "VDC.asm"
                include "Frog.asm"
                include "Bullet.asm"
                include "MainLoop.asm"
Main1_End:
                endmodule

                SAVEBIN "Core.bin",       Core.Start,       Core.Main0_End - Core.Start
                SAVEBIN "main1_play.bin", Core.Main1_Start, Core.Main1_End - Core.Main1_Start

В spgbld_vdac2.ini добавляется блок:

Block = #C000, #04, main1_play.bin

22.3 Cross-slot CALL работает без thunks

Z80 видит slot 1 (#4000..#7FFF) и slot 3 (#C000..#FFFF) одновременно — они разные адресные диапазоны, оба маппятся через TS-Conf mapping регистры. Когда CALL Init_Video (target #C000+) делается из main0 (#5C00+), Z80 толкает return-addr в стек (стек в slot 1, #40F2) и прыгает в slot 3. Main1 код выполняется, делает RET — return-addr из стека → возвращаемся в slot 1. Никаких thunks не нужно, пока сцена одна.

Thunks потребуются позже, когда добавим Title/LevelSelect: тогда main0 будет свапать slot 3 на разные main1-страницы и JP в общую entry-точку сцены.

22.4 Ловушка 1: Main0_End в неправильном месте

В первой попытке split метка Main0_End: стояла сразу после RET функции Init_Core. Но Init_Int: и INT_Handler: определены ниже в файле — между Init_Core и SLOT 3 директивой. SAVEBIN "Core.bin", ..., Main0_End - Start покрыл только #5C00..#5D89 = 393 байта и обрезал Init_Int + INT_Handler.

На железе:

1. SPG-loader загружает Core.bin (393 байта) в page 5 → #5C00..#5D89
2. Остальная page 5 (#5D89..#7FFF) — нули (initialized)
3. Z80 на CALL Init_Int прыгает в #5D89 → читает 0 = NOP
4. NOPит через всю slot 1 → входит в slot 2 (#8000+) = TrackData
5. На байте 0xFF в TrackData выполняется RST 38 → прыжок в #0038 (RST vector)
6. NOPит из #0038 до #1000 (4040 NOP-ов)
7. На #1000 в TSLib живёт функция SetPage0: (LD (FMADDR_REGS+0x10), A : RET)
8. A = 8 (последнее значение из upload loops) → slot 0 переключается на page 8 = bg_l4_p01
9. TSLib исчезает → следующая инструкция читается из bg-картинки = chaos → виснет

Урок: Main0_End: ВСЕГДА последняя строчка main0 секции. Любая код-строка ниже неё (но выше SLOT 3 директивы) выпадает из SAVEBIN.

22.5 Ловушка 2: TSLib CMD_ADDRESS_PTR = #C000 молча затирает main1

После исправления Main0_End игра запустилась — frog/bg/cursor видны. Но цепочки шаров не появляются, фрог не стреляет, при попытке выстрела полностью виснет.

В эмуляторе VDC_TrySpawn и Bullet_Spawn работают идеально на изолированных вызовах. Регресс физики PASS. То есть код ОК. Проблема — где-то между кадрами.

Дамп с реального железа показал: содержимое #C000 — это FT812 display list команды (CLEAR_COLOR_RGB, VERTEX_FORMAT, CLEAR), а не main1_play код.

Источник в TSLib: Docs/TSLib/Include/FT/Coprocessor/Buffer.asm:

                ifndef CMD_ADDRESS_PTR
                define CMD_ADDRESS_PTR #C000
                endif

FT_CMD_Start макрос делает LD HL, CMD_ADDRESS_PTR : LD (BufferPtr), HL. Каждый FT_CMD_BUF пишет 4 байта на BufferPtr++. За кадр накапливается до ZL_CMD_WARN_BYTES = #0E00 ≈ 3.5 KB DL-команд поверх main1_play кода.

До split этот буфер тоже жил на #C000, но slot 3 содержал бесполезный bg_l4_p01 (или что было default). Buffer перезаписывал данные, которые никто не читал. Безобидно.

После split slot 3 = main1_play → буфер переписывает VDC_Update, Bullet_*, ZL_DrawFrame и т.д. Первый кадр успевает отрендериться (потому что buffer ещё не достиг этих адресов), второй — VDC функций нет, цепь не спавнится, при выстреле Bullet функция уже мусор, Z80 уходит в random код, виснет.

Fix. Перед include "FT/Coprocessor/Include.inc" в main.asm:

                ; FT command buffer: TSLib дефолтит на #C000 (slot 3). После
                ; main0/main1 split main1_play код живёт в slot 3 → буфер
                ; перекрывает код. Перенесён в slot 1 free area после main0.
                define CMD_ADDRESS_PTR #5E00

#5E00 — slot 1 page 5 после main0 (415 байт = ends at #5D9F). До конца slot 1 (#7FFF) → 8.5 KB запаса, в избытке для 3.5 KB буфера.

22.6 Чек-лист split-проекта

Любой split, в котором код переезжает в slot 3 (#C000+), должен пройти:

1. Main0_End: метка — строго после всего main0 кода, перед SLOT 3 директивой. SAVEBIN "main0.bin", Start, Main0_End - Start гарантирует что вся main0-логика попадает в bin.

2. Override CMD_ADDRESS_PTR — перед TSLib include-ами. Любое значение в writable RAM области, минимум 4 KB до границы window-а. Не #C000.

3. Init_Core SetPage3 на main1-страницу — например SetPage3 #04 если main1_play лежит на page 4 в SPG.

4. spgbld_vdac2.ini Block — Block = #C000, #04, main1_play.bin.

5. Cross-slot CALL без thunks — JP MainLoop из main0 в #C000 работает после Init_Core. Внутри одной сцены никаких thunks не нужно.

6. Paged simulator с FMADDR_REGS hook — zuma_full_z80_emulator.py ловит memory writes в #0410..#0413 (mapping registers) и обновляет pages map. Без этого hook-а эмулятор не воспроизводит SetPage* в режиме MAPPING_REGISTERS. Также полезны: ring buffer 4096 PC + PC watchpoint на #1000 (SetPage0 функция) — за минуты находят misjumps.

7. Дамп после F12 — RESET, не data. В Unreal F12 = RESET. Содержимое после F12 не отражает состояние во время виса. Для диагностики hang-а — F12 не подходит, нужен paged simulator или hardware-marker.

22.7 Запас на будущее

После v021 split (2026-05-18):

• main0: 8801 байт свободно (415/9216)
• main1_play: 7589 байт свободно (8795/16384)

• На каждую новую сцену (Title, LevelSelect, разные уровни) можно выделить свою 16K страницу под main1_.bin без касания main0

• FT command buffer 4 KB в slot 1 (#5E00..#7FFF) — запас в 4.5 KB

Следующий шаг: подключение Dzx7Turbo из TS-Conf проекта для сжатия per-level данных (15 страниц bg L4 × 22 уровня = 330 страниц без сжатия, с ZX7 ~245 страниц).

Глава 23. Экономия RAM_G шаров: путь к PALETTED4444 (v025)

23.1 Постановка задачи

Изначальный atlas шаров — 6 цветов × 32 spin-фазы × 32×32 px ARGB4 (2 байта/пиксель) = 384 KB. Из 1 MB RAM_G на FT812 после bg, frog, killzone, destroy, text, cursor, sparkle остаётся ~530 KB. Добавление UI-фрейма (gameinterface) требует ещё ~80 KB, остаётся 65 KB — впритык.

Цель: ужать atlas минимум вдвое, сохранив: 6 цветов, 32 spin-фазы, native цвета из source PNG, per-pixel alpha (anti-aliased силуэт).

23.2 Опции форматов FT812

L4/L8 на FT812 — alpha mask: output = tint × pixel/255. Это «силуэт + tint», тело шара теряется. Не годится для многоцветных балов с собственным shading.

23.3 Неудачные попытки (mid-may 2026)

Попытка 1: MONO ARGB4 + COLOR_RGB tint (64 KB). Один atlas silver-шара (R=G=B=L, A=alpha) + tint per ball. Maya-faces на всех цветах одинаковые (из silver-источника), нет белого specular highlight (silver L_max ≈ 230). Tint не работает для многоцветного shading.

Попытка 2: L8 + tint (32 KB). L8 на FT812 — alpha mask, не intensity. Шары полупрозрачные.

Попытка 3: PALETTED8 с BGRA byte order (192 KB + 1024B). FT812 читает палитру как RGBA, не BGRA. Все шары серые.

Попытка 4: PALETTED8 с RGBA byte order (192 KB + 1024B). На этом конкретном FT812 — по-прежнему серые. PALETTED8 трактуется как L8 (chip-revision quirk). Вывод после 4-х неудач — «PALETTED не работает». Этот вывод был ложным.

23.4 PALETTED4444: три условия

User-инсайт: PALETTED4444 (формат = 15) использует палитру СТРОГО 512 байт (256 × 2 ARGB4). Прошлые попытки попадали в одну из трёх ловушек:

1. Размер палитры ≠ 512. При 1024 (RGBA8) FT812 читает байты 512+ как PIXEL data за палитрой → corruption / hang. При меньшем размере → out-of-range index → hang.

2. Формат записи ≠ ARGB4 LE. Корректно: python word = (a4 << 12) | (r4 << 8) | (g4 << 4) | b4 # 16-bit LE pal_bytes += word.to_bytes(2, "little") 1024-байтная RGBA8 палитра ляжет как 256 пар бессмысленных ARGB4 → все цвета серые.

3. Адрес не выровнен на 4 байта. FT_PaletteSource берёт младшие 22 бита; FT812 требует 4-byte aligned. Невыровненный → junk.

23.5 Setup PALETTED4444 (baseline v025)

Palette generation (Python):

fake_q = Image.fromarray(opaque_rgb.reshape(-1, 1, 3), "RGB")               .quantize(colors=255, method=Image.Quantize.MEDIANCUT)
pal = bytearray()
pal += b""           # idx 0 = transparent
for i in range(255):
    r, g, b = pal_rgb_flat[i*3:i*3+3]
    a4 = 0xF
    word = (a4 << 12) | ((r >> 4) << 8) | ((g >> 4) << 4) | (b >> 4)
    pal += word.to_bytes(2, "little")
assert len(pal) == 512                  # СТРОГО

main.asm — upload:

BALLS_PALETTE_RAMG EQU #080000          ; 16K-aligned (4-byte aligned тоже)

LD A, BALLS_PALETTE_PAGE
SetPage2_A
LD HL, #8000
LD BC, 512                              ; ← не 1024!
LD A, (BALLS_PALETTE_RAMG >> 16) & 0xFF
LD DE, BALLS_PALETTE_RAMG & 0xFFFF
CALL FT.WriteMem

MainLoop.asm — render:

FT_PaletteSource BALLS_PALETTE_RAMG      ; опкод 0x2A
LD A, 9 : CALL ZL_EmitBallHandle         ; dual handle (192 cells > 128)
FT_BitmapLayout FT_PALETTED4444, ZL_BALL_W, ZL_BALL_H
FT_BitmapSize FT_NEAREST, FT_BORDER, FT_BORDER, ZL_BALL_W, ZL_BALL_H
XOR A : CALL ZL_EmitBallHandle           ; handle 0
FT_BitmapLayout FT_PALETTED4444, ZL_BALL_W, ZL_BALL_H
FT_BitmapSize FT_NEAREST, FT_BORDER, FT_BORDER, ZL_BALL_W, ZL_BALL_H

23.6 Результаты v025 (HW-verified)

Экономия 192 KB. 4 точки в коде (chain, bullet, frog hand, frog back) используют один FT_PaletteSource per frame.

23.7 Урок: «не работает» ≠ «формат не поддерживается»

Из 4-х неудач легко сделать вывод «PALETTED unsupported». Прежде:

1. Точно ли palette size совпадает со спекой формата? (565 = 512, 4444 = 512, 8 = 1024).

2. Точно ли byte order совпадает? FT81x: little-endian 16-bit для 565/4444, 32-bit для 8.

3. Выровнен ли адрес на 4 байта?

4. FT_PaletteSource эмитнут ДО Vertex2f в Begin BITMAPS?

Если 3 пункта проверены и всё равно не работает — попробовать другой PALETTED-вариант (4444 vs 8 — оказалось решением). На разных chip revisions FT812 поведение PALETTED8 / 4444 различается.

Глава 24. Почему отказались от псевдо-DXT фона (2026-05-19)

TL;DR

Псевдо-DXT (Глава 18–19) занимал ~80 КБ RAM_G и весил 0.5–0.75 байт/пикс — отличный компромисс по памяти. Но на реальном железе ZX-Evo вызывал то, что выглядело как «срыв строчной синхронизации»: дрожание строк, цветные полосы, мерцание. На Unreal x64 эмуляторе всё было идеально. Причина оказалась в переполнении бюджета пиксельных клоков FT812 на строку из-за трёх полноэкранных bitmap-проходов на каждый кадр. Решение: 400×300 PALETTED4444 + NEAREST upscale ×1.6 = один bitmap-проход. Канарейка v028-эпохи (2026-05-19) подтвердила на реале.

Что делал псевдо-DXT (краткое напоминание)

Из глав 18–19:

• Фон 640×480 раскладывался на три плоскости в pseudo-DXT:
• c0 — RGB565 цвет «низкий» для блоков 4×4 (160×120 пикс, 38 400 Б)
• c1 — RGB565 цвет «высокий» для блоков 4×4 (160×120 пикс, 38 400 Б)

• mask — полноэкранная маска 640×480: L2 = 76 800 Б или L4 = 153 600 Б

• Display List на каждый кадр:

• Begin BITMAPS, source=c0, scale ×4, draw 640×480 full screen
• Source=c1, BLEND_FUNC = DST_ALPHA, draw 640×480
• Source=mask, sample as alpha mask, draw 640×480

Три полноэкранных прохода. Каждый проход = один bitmap fetch per pixel.

Именно здесь видно правило «считать или хранить». Псевдо-DXT экономил RAM_G: вместо полноценного фона хранились endpoints и mask. Но эта экономия покупалась ценой трёх проходов по каждой строке. Для FT812 это хуже, чем просто хранить больше готовых пикселей: RAM_G занималась меньше, но драгоценные pixel-clock такты тратились на двойную/тройную отрисовку одной и той же строки, и строка не успевала дорисоваться вовремя.

Симптом на реале — «срыв строчной»

Когда фон рисовался псевдо-DXT, на ZX-Evo:

• Картинка дрожала по горизонтали (строки слегка прыгали)
• Появлялись цветные полосы непредсказуемой ширины
• При движении frog/шаров — артефакты усиливались
• На Unreal x64 эмуляторе — всё чисто, никакого тиринга

Первая гипотеза была tearing — попробовали VM_640_480_74Hz (§4.2). Не помогло. Вторая — буфер DL переполняется. Замеры через REG_CLOCK профайлер показали что DL build не превышал vblank window. То есть Z80 ничего не зашкаливает.

Реальная причина — пиксельный клок-бюджет на строку

FT812 на 800 пикс/строка имеет ровно 800 пиксельных клоков для всех операций рендера этой строки. При:

• 1 bitmap-проходе с NEAREST + paletted4444 → ~1 такт/пикс, бюджет = 800 пикс, с большим запасом.

• 1 bitmap-проходе с BILINEAR → ~2 такта/пикс, бюджет = 400 пикс ≈ половина строки.

• 3 bitmap-прохода (псевдо-DXT) → каждый берёт 1 такт/пикс минимум, итого 3 × 640 = 1920 тактов. На 1120 тактов больше чем строка содержит. FT812 не успевает закончить рендер строки до начала следующей → строка обрезается / смещается, что визуально и выглядит как срыв синхронизации.

Это аппаратное ограничение per-line, а не общий FPS-cap. Unreal x64 эмулирует DL семантически но не моделирует pixel-clock budget — поэтому там не было видно.

Решение — один полноэкранный проход

Перешли на формат 400×300 PALETTED4444 + аппаратный NEAREST upscale ×1.6:

FT_BitmapHandle  BG_HANDLE
FT_PaletteSource BG_PALETTE_RAMG
FT_BitmapSource  BG_RAMG_ADDR
FT_BitmapLayout  FT_PALETTED4444, 400, 300
FT_BitmapSize    FT_NEAREST, FT_BORDER, FT_BORDER, 640, 480
CMD_SCALE        1.6 (16.16 fixed)
Vertex2f         (0, 0)

Один bitmap fetch на пиксель. NEAREST = 1 такт/пикс. На 800-тактовую строку бюджет занят процентов на 50 — есть запас под другие операции (рамка, шары, frog).

На реале — чистая картинка, никакого дрожания.

Что потеряли по сравнению с псевдо-DXT

• Потеряли: 640×480 native + 16-bit цвет. С NEAREST upscale картинка стала слегка «пикселявой» (~1.6× больше реальных пикселей). Цвета теперь ограничены 256-цветной палитрой (раньше было до ~50K при RGB565×2).

• Получили: рабочая стабильная картинка на реальном железе.

• Стоимость по RAM_G: +40 КБ (~50% больше) — терпимо, общая RAM_G FT812 = 1 МБ.

Почему не разделили на полосы

Можно было оставить псевдо-DXT, но рисовать не 640×480 за один кадр а полосами (скажем 8×60 px каждая), переключая bitmap source/scissor между ними. Это распределило бы pixel-clock budget — каждая полоса в своём DL «окне».

Не пошли потому что:

• Требует scissor management + N draw calls = сложнее код
• Не масштабируется для уровней — каждый фон уровня = свой trick
• Бюджет всё равно >>1 такт/пикс если делать blend в одной полосе

Простой single-pass PALETTED4444 решает проблему без архитектурной сложности, ценой ~50% RAM.

Bigger picture: правило бюджета строки

Закон для FT812 на 800-тактовой строке:

sum(такты/пикс на каждый bitmap-проход) × (видимая ширина в пикс) ≤ 800

Для 640-pix экрана:

• 1 NEAREST = 640 тактов → запас 160
• 1 BILINEAR = 1280 тактов → уже переполнение для full-screen sprite
• 2 NEAREST = 1280 тактов → переполнение
• 3 NEAREST (псевдо-DXT) = 1920 → грубое переполнение

Если нужно несколько проходов — они должны быть не полноэкранными, чтобы сумма ширин × такты ≤ 800. Маленькие sprites (frog, шары, курсор) проблемы не создают потому что их совокупная ширина по любой строке << 640.

Когда стоит вернуться к псевдо-DXT

Если на реале FT812 окажется что появилась дополнительная архитектура которая решает row-pixel-clock переполнение (например split rendering на 4 параллельных engine), или будет важна экономия 40 КБ RAM_G в ущерб качеству. В текущей VDAC2 архитектуре — нет.

Уточнение модели (ground-truth через эмулятор, см. главу 25)

Модель выше («800 тактов на строку, ~1 такт/пиксель на проход») — рабочее первое приближение: она верно предсказывает, что три полноэкранных прохода рвут картинку, а один — нет. Но позже, сняв через эмулятор EveApps реальный RAM_DL (глава 25) и сверившись с аппаратной моделью FT812 от TS-Labs, мы уточнили механизм:

• Движок FT812 заново проходит весь Display List на КАЖДОЙ строке растра, тратя примерно 1 такт на DL-команду. Этот «проход по командам» — а не заливка — часто и есть доминанта нагрузки.

• Заливка пикселей дешевле, чем казалось: ~16 пикс/такт для не-палитровых форматов; палитра медленнее (lookup на пиксель); BILINEAR вдвое медленнее NEAREST.

• Реальный бюджет строки — это REG_HCYCLE (для нашего 640×480 ≈ 832 такта), а не ровно 800.

Ground truth. Дамп RAM_DL тяжёлого кадра (frame 0650) показал 439 DL-команд, из которых ~192 — матрицы разворота шаров (≈44% бюджета). Итог ≈ 104–106% от 832 → строка не успевает достроиться → tearing на верхней полосе. То есть tearing = переполнение бюджета строки, и виноват прежде всего объём DL, а не заливка как таковая.

Рычаги (без потери качества картинки):

1. Сократить число DL-команд — адаптивная группировка + предрасчётный LUT матриц шаров (§21.4) уже снижает их в разы.

2. Избегать BILINEAR/PALETTED на крупных спрайтах (§27.9 — frog).

3. Не дробить фон на полосы со scissor под полупрозрачной рамкой — фон виден сквозь неё, scissor исказил бы картинку.

⚠️ Ограничение проекта (2026-05-26): матрицы разворота шаров по касательной не убираются — они заметно улучшают восприятие (решение пользователя). Поэтому дальнейшая tearing-оптимизация отложена: режем что угодно, кроме матриц шаров и читаемости фона.

Глава 25. Bridgetek EveApps FT812 Emulator — настоящая эмуляция чипа (2026-05-19)

Зачем понадобился новый эмулятор

До сессии 2026-05-19 наша «эмуляция» Zuma выглядела так:

Проблема Unreal x64: он эмулирует FT812 семантически, выполняет DL команды и выводит картинку, но не моделирует hardware constraints:

• pixel-clock budget per line (см. Главу 24)
• BITMAP_HANDLE binding rules (см. Главу 26 ниже)
• SPI bandwidth, DMA timing, BFLB swap latency

Поэтому на Unreal x64 всё работало, а на реальном ZX-Evo + VDAC2 — глюки.

Нужен был настоящий эмулятор чипа FT812 для отладки таких багов БЕЗ необходимости загружать на реал каждый раз. Bridgetek предоставляет официальный — берём.

Что выбрали

Bridgetek EveApps MSVC Emulator — официальный эмулятор FT812 от производителя.

• GitHub: https://github.com/Bridgetek/EveApps
• Лицензия: MIT (open source)
• Точность: 100% (от FTDI/Bridgetek, той же команды что сделала чип)
• Windows + MSVC build

Альтернативы из Docs/ft812_emulator_setup_guide.md:

• EVE Screen Editor — GUI, для прототипирования, не для авто-тестов
• RudolphRiedel FT800-FT813 — кросс-платформа, требует USB-SPI bridge
• CircuitPython _eve — через железо

Выбрали EveApps MSVC Emulator потому что:

• Бесплатно + open source
• Windows native (наша платформа разработки)
• Поддержка ASTC/FT81x/BT81x — для будущих апгрейдов
• Можно интегрировать через файлы (просто и надёжно)

Установка (Codex, 2026-05-19)

Шаг 1: Visual Studio Build Tools 2022 + MSVC v143

Без полного Visual Studio — достаточно «Build Tools for Visual Studio 2022» с компонентом «Desktop development with C++». Лёгкая установка ~3 GB.

Шаг 2: Клонирование EveApps

cd C:\Users\Администратор\Desktop
git clone https://github.com/Bridgetek/EveApps.git

Шаг 3: Адаптация SampleApp

Bridgetek даёт готовое SampleApp\Bitmap — простой sample который рисует bitmap на эмулированный экран. Скопировали как заготовку:

cd EveApps\SampleApp
xcopy /E /I Bitmap ZumaPlayback

Затем переименовали проект в Visual Studio в ZumaPlayback_Emulator, выбрали target = FT812 (через EVE_GRAPHICS_TARGET define), заменили ZumaPlayback.c на наш файл (см. ниже).

Шаг 4: Build

В Visual Studio: Configuration = Debug, Platform = MSVC_Emulator (не FT9XX!), Build → Build Solution. Результат:

C:\Users\Администратор\Desktop\EveApps\SampleApp\ZumaPlayback\Project\Msvc_Emulator\Debug\ZumaPlayback_Emulator.exe

Что делает ZumaPlayback.c

Эмулятор работает как playback harness — не интерпретирует Z80, а просто проигрывает заранее снятые «кадры» (RAM_G + cmd FIFO snapshots).

int main(int argc, char* argv[]) {
    // 1. Init FT812 эмулятор
    EVE_HalContext s_halContext;
    EVE_Hal_open(&s_halContext, ...);

    // 2. Load ram_g.bin → RAM_G FT812 (1 MB полный snapshot)
    char bundle_dir[256];
    strcpy(bundle_dir, argv[1]);     // bundle path из CLI
    FILE* f = fopen(bundle_dir "/ram_g.bin", "rb");
    uint8_t ram[1024*1024];
    fread(ram, 1, sizeof(ram), f);
    fclose(f);
    EVE_Hal_wrMem(&s_halContext, 0, ram, sizeof(ram));

    // 3. Find all cmd_frame_*.bin in bundle, sorted
    // 4. For each frame: write cmd stream → EVE_Cmd_wr32, waitFlush, swap
    for (...) {
        FILE* cf = fopen("cmd_frame_XXXX.bin", "rb");
        // Read 32-bit commands one at a time
        uint32_t cmd;
        while (fread(&cmd, 4, 1, cf) == 1) {
            EVE_Cmd_wr32(&s_halContext, cmd);
        }
        EVE_Cmd_waitFlush(&s_halContext);
        EVE_Hal_wr8(&s_halContext, REG_DLSWAP, DLSWAP_FRAME);
        Sleep(500);   // подержать кадр на экране
    }

    // 5. Keep emulator window open
    while (1) Sleep(100);
}

Bundle export (Python side)

Bundle = папка с двумя видами файлов:

• ram_g.bin — полный 1 MB snapshot FT812 RAM_G (assemblят все assets в правильных адресах)
• cmd_frame_NNNN.bin — snapshot CMD FIFO для конкретного frame number

Генератор: Source/OTHER/export_ft812_bundle.py. Делает:

1. Парсит EQU константы из Source/ASM/main.asm (RAM_G addresses всех assets)
2. Собирает ram_g.bin — кладёт каждый converted asset (bg paletted, balls, frog, frame strips, dialog_frame, fonts, palettes…) в свой EQU address
3. Запускает full Z80 emulator (zuma_full_z80_emulator.py) с реальным asm кодом
4. Прогоняет N frames через emulator (вызывает Frog_Update, VDC_Update, Bullet_Update, ZL_DrawFrame)
5. На указанных frames дампит CMD FIFO buffer → cmd_frame_NNNN.bin

CLI пример:

python Source\OTHER\export_ft812_bundle.py --out _ft812_bundle_test --frames 0,240,500,650

Опциональные флаги для тестирования специфичных состояний:

python Source\OTHER\export_ft812_bundle.py --out _ft812_bundle_dialog_test --frames 100 --force-dialog 1 --force-lives 2

--force-dialog 1 — записать VDC_DialogState=1 ПЕРЕД захватом frame, чтобы триггернуть рендер game-over диалога без необходимости проиграть partию.

Запуск эмулятора

$exe='C:\Users\Администратор\Desktop\EveApps\SampleApp\ZumaPlayback\Project\Msvc_Emulator\Debug\ZumaPlayback_Emulator.exe'
$bundle='C:\Users\Администратор\Desktop\Zuma Deluxe VDAC2\_ft812_bundle_dialog_test'
Start-Process -FilePath $exe -ArgumentList "`"$bundle`"" -WorkingDirectory (Split-Path $exe)

Открывается окно «BT8XX Emulator» с эмулированным экраном FT812 640×480. Кадры из bundle проигрываются по очереди с задержкой ~0.5 сек.

Что дало в v028

Глава 25 написана после того как эмулятор нашёл нам реальный баг которого Unreal x64 не видел.

Кейс: при рендере game-over диалога текст должен показывать “2 lives left”, “GAME OVER” и т.д. В Unreal x64 текст рисовался корректно. На FT812 эмуляторе — rainbow color noise в позиции текста (Главу 26 см. ниже про сам баг).

Сценарий который сработал:

1. Написали DrawString routine, проверили в Unreal x64 — выглядит ОК.
2. Юзер запустил на реале → garbled. Не поверили — могли быть проблемы с реалом.
3. Запустили FT812 emulator → то же garbled! Стало ясно что баг в коде, не в реале.

4. Скриншот эмулятора через PowerShell CopyFromScreen → ВИДНО garbage rect ровно где должен быть текст. Position+size правильные, content = rainbow noise.

5. Гипотеза: BITMAP_SOURCE/SIZE применяются к WRONG handle. Подтверждено reading FT812 datasheet. Fix: эмитить BITMAP_HANDLE ПЕРЕД SOURCE/SIZE.

6. После fix → эмулятор показывает правильный текст. Юзер подтвердил на реале.

Без FT812 emulator мы бы либо:

• Гоняли реал каждый цикл итерации (5-10 мин на цикл)
• Или скипнули баг как «реальное hardware quirk» и оставили сломанным

С эмулятором цикл итерации ~30 сек, и баг был очевиден сразу.

Подход playback vs interactive

EveApps умеет и interactive mode — где C код напрямую обновляет DL каждый кадр через FT812 API. Это нужно для тестов с input/touch. Мы пока сделали только playback (RAM_G + cmd snapshots), потому что:

• Z80 логика — это наш asm, не C; портировать в C это дублирование
• Playback покрывает 90% случаев — рендер «застывшего» состояния
• Bundle экспорт за секунды, можно проверить любой state через --force-* флаги
• Snapshot не зависит от времени → reproducible

Interactive mode понадобится если будем тестировать timing-sensitive штуки (анимации, animations, transitions). Тогда напишем C harness который вызывает Z80 функции через ctypes или socket bridge.

Readback реального RAM_DL — ground-truth аудит Display List (доводка)

Главное, что дал этот эмулятор после первоначальной настройки, — достоверный снимок настоящего Display List. Наш Z80-код собирает кадр через копроцессор (RAM_CMD FIFO); команды FIFO (cmd_*) — это НЕ готовый DL: копроцессор сам разворачивает их в реальные DL-команды. Поэтому «сколько команд в DL» по нашему cmd-потоку посчитать нельзя — нужно прочитать то, что копроцессор реально положил в RAM_DL.

ZumaPlayback.c пропатчен так: после EVE_Cmd_waitFlush (FIFO допроигран) читаем RAM_DL (адрес 0x300000, 8 КБ) и пишем в dl_frame_NNNN.bin, затем headless-выход (без удержания окна — для пакетного прогона). Сборка — Debug|Win32 через MSBuild; в этом прогоне target эмулятора = BT817 (совместимый EVE из того же EveApps). Bundle тот же (ram_g.bin + cmd_frame_*).

Парсер (analyze_dl_*) читает dl_frame_*.bin до команды DISPLAY и считает DL-команды по типам. Так мы впервые увидели реальные цифры бюджета строки (глава 24): тяжёлый кадр = 439 DL-команд, ~192 из них — матрицы разворота шаров. Только этот путь разворачивает FIFO-копроцессорные команды в настоящий DL — Unreal x64 и наши Python-эмуляторы этого не делают.

Практический вывод

EveApps playback нужен не как отдельная ветка разработки, а как проверка того, что FT812 действительно увидит после исполнения FIFO копроцессора. Для Zuma VDAC2 он полезен в двух случаях:

• проверить, во что разворачиваются CMD_*-команды и сколько настоящих DL-команд получает кадр;

• сверить readback RAM_DL с ожиданиями, когда Unreal x64 или Python-харнесс показывают правдоподобную, но неполную картину.

Скриншотный diff и автоматический PNG-output не стали частью обязательного пайплайна проекта: для этой игры ценность дала именно проверка RAM_DL и бюджета строки FT812.

Ссылки

• Setup guide: Docs/ft812_emulator_setup_guide.md (раннее общее планирование)
• Bridgetek EveApps: https://github.com/Bridgetek/EveApps
• Bundle exporter: Source/OTHER/export_ft812_bundle.py в репозитории проекта.
• Чат.txt: [2026-05-19 13:42] Codex -> FT812 emulator playback harness ready — Codex set-up note.
• Чат.txt: [2026-05-20 02:40] VDAC2 → VDC: v028 Game Over dialog — описание bug который эмулятор нашёл.

Глава 26. BITMAP_HANDLE binding ловушка FT812 (2026-05-20)

TL;DR

BITMAP_HANDLE в FT812 это selector одного из 32 slots с per-handle bitmap state. Команды BITMAP_SOURCE, BITMAP_LAYOUT, BITMAP_SIZE записываются в текущий selected handle. Если эмитить SOURCE → HANDLE → SIZE → Vertex2f, то SOURCE попадает в OLD handle (тот что был selected до), и новый handle остаётся со старым source (garbage или previous frame leftovers). Symptom: ЯРКИЙ rainbow / multi-color noise ровно в bounding box того места где должна быть текстура.

Семантика BITMAP_HANDLE в FT812

FT812 имеет 32 "bitmap slot" (handles 0..31).
Каждый slot хранит свои:
  - BITMAP_SOURCE   (address в RAM_G)
  - BITMAP_LAYOUT   (format + stride + height)
  - BITMAP_SIZE     (filter + wrap + width + height)
  - BITMAP_TRANSFORM_* (matrix coefficients)
  - PALETTE_SOURCE  (для PALETTED формата)
  - ... остальные per-bitmap state regs

BITMAP_HANDLE(N) переключает "active slot" в N.
Все последующие BITMAP_* команды модифицируют active slot.
BEGIN(BITMAPS) + Vertex2II/Vertex2f — рисуют из active slot.

Bad pattern (rainbow noise!)

; Try to draw glyph with runtime BITMAP_SOURCE switch
LD HL, glyph_addr_lo
LD A, glyph_addr_hi
LD B, #01 : LD C, A : LD D, H : LD E, L
CALL Command_BCDE                ; ← BITMAP_SOURCE emit (но какой handle active?)
FT_BitmapHandle GLYPH_HANDLE     ; ← switch slot ПОСЛЕ source emit
FT_BitmapLayout FT_ARGB4, ...
FT_BitmapSize FT_NEAREST, ...
XOR A : CALL FT.Coprocessor.Cell
LD BC, x*16 : LD DE, y*16
CALL FT.Coprocessor.Vertex2f

Что происходит:

• Active handle = previous (e.g. FRAME_HANDLE)
• BITMAP_SOURCE записывается в previous slot (perverts state of frame!)
• FT_BitmapHandle GLYPH_HANDLE — switches active
• BITMAP_LAYOUT/SIZE записываются в GLYPH_HANDLE (правильно)
• Vertex2f читает из GLYPH_HANDLE: source = whatever было раньше (или default) = читаем garbage RAM_G как ARGB4 → rainbow noise

Good pattern

FT_BitmapHandle GLYPH_HANDLE     ; ← FIRST select slot
LD HL, glyph_addr_lo             ; теперь setup runtime addr
LD A, glyph_addr_hi
LD B, #01 : LD C, A : LD D, H : LD E, L
CALL Command_BCDE                ; ← BITMAP_SOURCE → GLYPH_HANDLE (correct)
FT_BitmapLayout FT_ARGB4, ...
FT_BitmapSize FT_NEAREST, ...
XOR A : CALL FT.Coprocessor.Cell
LD BC, x*16 : LD DE, y*16
CALL FT.Coprocessor.Vertex2f