finally

2026-03-29 18:36:48 +03:00
parent 770dd629f5
commit 64ab493037
13 changed files with 816 additions and 19 deletions
--- a/FORMAT.md
+++ b/FORMAT.md
@@ -0,0 +1,122 @@
+# Спецификация формата `.minint` (версия 1)
+
+## Общие сведения
+
+- Все многобайтовые целые числа — **little-endian**.
+- Строки — **UTF-8**, с префиксом длины 1 байт (макс. 255 байт).
+- Формат не использует сжатие — данные хранятся как есть.
+
+## Структура файла
+
+```
+┌──────────────────────────┐
+│   Container Header       │  28 байт (фиксированный)
+├──────────────────────────┤
+│   Document 1             │  (блок переменной длины)
+├──────────────────────────┤
+│   Document 2             │
+├──────────────────────────┤
+│   ...                    │
+├──────────────────────────┤
+│   Document N             │
+└──────────────────────────┘
+```
+
+## Container Header (28 байт)
+
+| Смещение | Размер | Тип    | Описание                        |
+|----------|--------|--------|---------------------------------|
+| 0        | 6      | ASCII  | Сигнатура: `MININT`             |
+| 6        | 2      | uint16 | Версия формата (текущая: `1`)   |
+| 8        | 4      | uint32 | Ширина (Width)                  |
+| 12       | 4      | uint32 | Высота (Height)                 |
+| 16       | 4      | uint32 | Количество документов           |
+| 20       | 8      | —      | Зарезервировано (нули)          |
+
+## Блок документа
+
+Повторяется `DocumentCount` раз, последовательно.
+
+### Заголовок документа
+
+| Размер              | Тип    | Описание                    |
+|---------------------|--------|-----------------------------|
+| 1                   | uint8  | Длина имени (NameLen)       |
+| NameLen             | UTF-8  | Имя документа               |
+| 4                   | uint32 | FrameDelayMs                |
+| 4                   | uint32 | Количество цветов (PalCnt)  |
+
+### Палитра
+
+`PalCnt × 4` байт. Каждый цвет: `[R, G, B, A]` (по 1 байту).
+
+Индекс 0 всегда соответствует прозрачному цвету `(0, 0, 0, 0)`.
+
+### Ширина индекса
+
+Вычисляется из `PalCnt` (не хранится в файле явно):
+
+| PalCnt              | Байт на индекс |
+|---------------------|-----------------|
+| 1 – 255             | 1               |
+| 256 – 65 535        | 2               |
+| 65 536 – 16 777 215 | 3              |
+| 16 777 216+         | 4               |
+
+### Количество слоёв
+
+| Размер | Тип    | Описание          |
+|--------|--------|-------------------|
+| 4      | uint32 | Количество слоёв  |
+
+### Блок слоя
+
+Повторяется `LayerCount` раз.
+
+| Размер                    | Тип   | Описание                           |
+|---------------------------|-------|------------------------------------|
+| 1                         | uint8 | Длина имени слоя (LayerNameLen)    |
+| LayerNameLen              | UTF-8 | Имя слоя                          |
+| 1                         | uint8 | Видимость (0 = скрыт, 1 = виден)  |
+| 1                         | uint8 | Opacity (0–255)                    |
+| Width × Height × ByteWidth | bytes | Индексы палитры, row-major, LE    |
+
+## Правила валидации
+
+1. Сигнатура — строго `MININT` (6 байт ASCII).
+2. Версия — строго `1` (неизвестные версии отклоняются).
+3. Width, Height >= 1; максимум 65 536.
+4. DocumentCount >= 1.
+5. PaletteCount >= 1.
+6. Каждый индекс пикселя < PaletteCount.
+7. IsVisible — только 0 или 1.
+8. Зарезервированные байты — допускаются ненулевые (forward compatibility).
+9. Неожиданный конец файла — ошибка с описанием контекста.
+
+## Пример
+
+Контейнер 4×4, 1 документ, 2 цвета (прозрачный + красный), 1 слой:
+
+```
+4D 49 4E 49 4E 54          — "MININT"
+01 00                       — version 1
+04 00 00 00                 — width = 4
+04 00 00 00                 — height = 4
+01 00 00 00                 — 1 document
+00 00 00 00 00 00 00 00     — reserved
+
+05                          — name length = 5
+44 6F 63 20 31              — "Doc 1"
+64 00 00 00                 — FrameDelayMs = 100
+02 00 00 00                 — palette count = 2
+00 00 00 00                 — color 0: transparent
+FF 00 00 FF                 — color 1: red (R=255, G=0, B=0, A=255)
+
+01 00 00 00                 — 1 layer
+07                          — layer name length = 7
+4C 61 79 65 72 20 31        — "Layer 1"
+01                          — visible
+FF                          — opacity = 255
+00 00 00 00 00 00 00 00     — 16 pixels, all index 0 (transparent)
+00 00 00 00 00 00 00 00
+```