/*
 * gfx.h — Sprinter graphics: mode-agnostic API (BGI_GFX).
 *
 * Рисование (putpixel/line/bar/circle/…) вынесено в BGI — см.
 * <graphics.h> и driver-библиотеки bgi256.lib / bgi16.lib (выбор режима
 * линковкой: sprinter-cc --gfx 256 | --gfx 16).  Здесь остались только
 * функции БЕЗ BGI-аналога: вход/выход в режим, страницы, банк, vsync,
 * палитра, шрифт.  Они mode-agnostic и живут в libbgi/common/ (один
 * исходник, .rel в обеих driver-библиотеках).
 *
 * Адресация (для не-BGI программ, использующих эти примитивы напрямую: 
 * пиксель (x,y) — CPU 0xC000 + (x или x/2) с Port_Y (0x89) = y; 
 * gfx-код мапит 16 КБ VRAM-страницу в W3 при записи.
 * Для double-buffering страница 1 начинается на 320 байт дальше (0xC140).
 *
 * Палитра: BIOS $A4 (RST 8); 4 байта на запись — B, G, R, pad.
 */
#ifndef GFX_H
#define GFX_H

#include <stdint.h>

/* ESTEX SETVMOD codes — same values as the SETVMOD `A` register. */
#define GFX_MODE_TEXT_40x32       0x02
#define GFX_MODE_TEXT_80x32       0x03
#define GFX_MODE_320x256x256      0x81
#define GFX_MODE_640x256x16       0x82

/* Pixel dimensions of mode 0x81 (320×256, 256 colours). */
#define GFX_WIDTH   320
#define GFX_HEIGHT  256

/* Pixel dimensions of mode 0x82 (640×256, 16 colours).  Each byte at
 * 0xC000+x_byte holds two pixels: high nibble = LEFT (even-x), low
 * nibble = RIGHT (odd-x) — see memory/sprinter_graphics.md. */
#define GFX_WIDTH_16   640
#define GFX_HEIGHT_16  256
#define GFX_COLORS_16  16

/* ---- Page selection (double-buffering) and bank control ---------- */
void    gfx_set_visible_page(uint8_t page);   /* 0 or 1 */
uint8_t gfx_get_visible_page(void);
void    gfx_set_draw_page(uint8_t page);      /* 0 or 1 */
uint8_t gfx_get_draw_page(void);
void    gfx_set_bank(uint8_t bank);           /* 0x50..0x5F */
uint8_t gfx_get_bank(void);

/* Block until the next frame (50 Hz).  Типичный double-buffer:
 *   gfx_set_draw_page(hidden); draw_frame(); gfx_wait_vsync();
 *   gfx_set_visible_page(hidden);   // tear-free flip */
void    gfx_wait_vsync(void);

/* ---- Bitmap-font text -------------------------------------------- *
 * Шрифт 256 глифов × 8 рядов × 1 байт (ZX-Spectrum формат), 2 КБ.
 * Грузится лениво при первом использовании BGI-текста; gfx_set_font
 * подменяет указатель (storage должен жить, пока шрифт активен). */
void    gfx_load_default_font(void);
void    gfx_set_font(const uint8_t *font);

/* ---- Palette ----------------------------------------------------- *
 * Каждая графическая страница имеет свою палитру (page 0 → palette 0,
 * page 1 → palette 1).  Для seamless double-buffering грузить одну
 * палитру в обе. */
void    gfx_pal_load(uint8_t pal_num, uint8_t start, uint8_t count,
                     const uint8_t *data);
void    gfx_pal_set (uint8_t pal_num, uint8_t idx,
                     uint8_t r, uint8_t g, uint8_t b);
void    gfx_pal_get (uint8_t pal_num, uint8_t start, uint8_t count,
                     uint8_t *data);
void    gfx_pal_get_color(uint8_t pal_num, uint8_t idx,
                          uint8_t *r, uint8_t *g, uint8_t *b);
void    gfx_pal_reset(void);

#endif