Формат Pro Tracker 2 (PT2) — Сводное описание

1. Общая структура файла​

Порядок секций в файле:​

+0x00:    Заголовок (Tempo, Length, Loop, таблицы смещений, название)
+0x83:    Position List (список номеров паттернов, заканчивается 0xFF)
+?:       Pattern Pointers Table (6 байт на паттерн, заканчивается 0x0000)
+?:       Pattern Data (потоки команд для каналов)
+?:       Samples (описания кварков)
+?:       Ornaments (таблицы отклонений нот)

2. Заголовок модуля​

3. Position List​

4. Pattern Pointers Table​

PatternPtr[PatternIndex * 6 + 0] = смещение канала A (LE)
PatternPtr[PatternIndex * 6 + 2] = смещение канала B (LE)
PatternPtr[PatternIndex * 6 + 4] = смещение канала C (LE)

5. Команды каналов (Pattern Data)​

Таблица команд:​

6. Сэмплы (Samples)​

Структура:​

+0: Size   — количество кварков (1 байт)
+1: Loop   — точка зацикливания (1 байт)
+2: Quarks[Size] — кварки по 3 байта каждый

Кварк (3 байта):​

Byte 0 — NoiseAndFlags:  nnnnnsTN
  bits 7-3: n — частота шума (0-31)
  bit 2:    s — знак вибрато
  bit 1:    T — маска тона (1=выключен)
  bit 0:    N — маска шума (1=выключен)

Byte 1 — LevelHiVibrato: aaaaHHHH
  bits 7-4: a — амплитуда/уровень (0-15)
  bits 3-0: H — старшие 4 бита вибрато

Byte 2 — LoVibrato: LLLLLLLL
  bits 7-0: L — младшие 8 бит вибрато

Vibrato = ((H << 8) | L) × (sign)

7. Орнаменты (Ornaments)​

Структура:​

+0: Size   — количество элементов (1 байт)
+1: Loop   — точка зацикливания (1 байт)
+2: Values[Size] — знаковые байты (-128..+127)

8. Механизм воспроизведения​

1. Инициализация: Загружается заголовок, устанавливаются адреса каналов для первой позиции
2. Главный цикл (вызывается каждый тик):
   • Декремент общего счётчика задержки
   • Если задержка истекла — обработка каналов
   • Для каждого канала: декремент счётчика пропуска, если 0 — декодирование команд
   • Вычисление AY-регистров (частота, амплитуда, шум, микшер)
   • Вывод в порты AY-чипа

9. AY-3-8910 Регистры​

R0-R1:  Тон канала A (12 бит)
R2-R3:  Тон канала B
R4-R5:  Тон канала C
R6:     Частота шума (5 бит)
R7:     Микшер (биты 0-2: тон, биты 3-5: шум; 1=выкл, 0=вкл)
R8:     Амплитуда канала A (биты 0-3: громкость 0-15, бит 4: 1=огибающая)
R9:     Амплитуда канала B
R10:    Амплитуда канала C
R11-12: Период огибающей (16 бит)
R13:    Форма огибающей (0-15, 255=выкл)

10. Сравнение трёх версий​

10.1. VfNG/NEW (оригинальная документация)​

• Счётчики каналов: 3 раздельных (LF748, LF749, LF74A), декрементируются каждый в своём тике по очереди (A→B→C)
• 0x00 = отключение канала (L11)
• 0xE0-0xFF → SAMPLE: A = (op + 0x20), индекс = A/2
• 0x80-0xDF → NOTE: A = (op + 0x20 + 0x60), нота = A
• 0x70-0x7F → ENVELOPE: 0x70 = выход
• 0x0D → PORTAMENTO: 3 байта (шаг, дельта_lo, дельта_hi)
• 0x0E → GLISSADE: 1 байт (signed)
• 0x0F → DELAY: 1 байт
• 0x01-0x0B → ADD NOISE: 1 байт
• Знак вибрато: 0 = "+", 1 = "-"
• Volume Table: генерируется процедурой INITVOL (256 байт)
• Проверка конца паттерна: 0x00 в начале данных канала A

10.2. Bulba Universal PT2 Player​

• Счётчики: 3 раздельных (SkpCnt для каждого канала), декрементируются все при DelyCnt==0
• 0xE0 → PD_REL (установка флагов канала)
• 0xE1-0xFF → PD_SAM: A = ((op + 0x20) & 0xFF) << 1, индекс = A/2
• 0x80-0xDF → PD_NOTE: нота через цепочку сложений (аналогично VfNG)
• 0x7F → PD_EOff (отключить огибающую)
• 0x71-0x7E → PD_ENV (установить огибающую)
• 0x70 → PD_QUIT
• 0x0D → PD_PORT: 3 байта, но пропускает предрассчитанную дельту (INC BC / INC BC)
• 0x0E → PD_GLIS
• 0x0C → PD_STOP (остановить глиссандо/портаменто)
• 0x01-0x0B → добавка к шуму
• PD_SKIP: Skip = adjusted + 1 (INC A перед сохранением)
• Volume Table: ((Level << 4) | Volume) >> 4 — инвертированный индекс относительно VfNG!
• Проверка 0x00: только в канале A, каналы B/C декодируются без проверки
• Глобальный пропуск линий: через GetMinCounter() (все каналы вместе)
• Знак вибрато: как в VfNG (0="-", 1="+")
• Таблица частот: генерируется динамически (NTBL → NT_)
• PT2.4PF: поддержка относительных смещений (коррекция через MODADDR)

10.3. ZXTune (витамин/vitamin.​

• SAMPLE: cmd - 0xE0 (прямой индекс) — отличается от VfNG/Bulba!
  • VfNG/Bulba: индекс = ((op + 0x20) & 0xFF) / 2
  • ZXTune: индекс = op - 0xE0
  • Это даёт РАЗНЫЕ индексы для нечётных op!
• NOTE: cmd - 0x80 — отличается от VfNG/Bulba!
  • VfNG/Bulba: нота через цепочку сложений
  • ZXTune: нота = cmd - 0x80
  • Разница в 16 полутонов для одного и того же байта!
• SKIP: cmd - 0x20 — отличается от Bulba!
  • Bulba: cmd - 0x1F (INC A)
  • ZXTune: cmd - 0x20
• ENVELOPE: 0x71-0x7E (тип 1-14), 0x70 = QUIT
• GLISS: 0x0D = NOTE GLISS (портаменто с лимитом), 0x0E = простой GLISS
• Счётчики: глобальный пропуск через GetMinCounter() (как Bulba)
• Конец паттерна: 0x00 только для канала A в HasLine()
• Знак вибрато: ИНВЕРТИРОВАН! 1 = "+", 0 = "-" (противоположно VfNG/Bulba!)
• Sample Loop: std::min(Loop, Size) — всегда валидный
• Проверка смещений: minOffset = PatternsOffset + MaxPattern * sizeof(RawPattern)

11. Сводная таблица различий​

12. Рекомендации по реализации​

1. Для максимальной совместимости используйте алгоритм Bulba (наиболее распространённый в плеерах ZX Spectrum)
2. Индекс сэмпла: используйте ((op + 0x20) & 0xFF) / 2 (VfNG/Bulba) — ZXTune-метод несовместим
3. Ноту: используйте цепочку сложений (VfNG/Bulba) — ZXTune-метод даёт другие ноты
4. SKIP: cmd - 0x1F (Bulba) — добавляет 1 относительно ZXTune
5. Знак вибрато: 0 = отрицательный, 1 = положительный (VfNG/Bulba) — ZXTune инвертирован
6. Volume Table: ((Level << 4) | Volume) >> 4 (Bulba) — инвертированный индекс
7. Проверка 0x00: только для канала A (все версии)
8. Счётчики: декремент всех трёх каналов при DelyCnt==0 (Bulba)
9. 0x0C: PD_STOP (Bulba) или GLISS OFF (ZXTune) — не NOISE ADD (VfNG)