alex/VGMPLAY.WMF
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add OPL4 playback and analyzer support

Browse Source
This commit is contained in:
alex
2026-09-15 14:59:29 +03:00
commit 1686838e03
553 changed files with 50524 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/02_Plugin_Header_Structure.md
+311
View File
@@ -0,0 +1,311 @@
# Структура заголовка плагина (512 байт)
> Источники: `inc/wc_api.h` (константы `WC_PLUGIN_*`, `WC_PCOND_*`),
> `DiskRef/WC_History.txt` (история изменений формата)
## Общая структура
Заголовок плагина имеет фиксированный размер **512 байт** и содержит всю
необходимую информацию для загрузки и запуска плагина системой WC.
**Текущая версия формата:** `#10` (`WC_PLUGIN_VERSION`), идентификатор: `WildCommanderMDL`.
Формат неоднократно менялся (WC v0.56, v1.00, v1.02, v1.06, v1.09) —
старые плагины несовместимы с новой версией.
## Детальная структура
| Offset | Размер | Описание |
|--------|--------|----------|
| +0 | 16 | Резерв (reserved) |
| +16 | 16 | Идентификатор: "WildCommanderMDL" |
| +32 | 1 | Версия формата (#10) |
| +33 | 1 | Резерв |
| +34 | 1 | Количество страниц для плагина |
| +35 | 1 | Номер страницы для #8000 (от 0) |
| +36 | 12 | Блоки данных (6 x 2 байта) |
| +48 | 15 | Резерв |
| +63 | 1 | Флаги для блока расширений |
| +64 | 96 | Блок расширений (32 x 3 байта) |
| +160 | 1 | #00 (маркер окончания расширений) |
| +161 | 4 | Максимальный размер файла |
| +165 | 32 | Имя плагина |
| +197 | 1 | Тип условий вызова плагина |
| +198 | 6 | Текст для F4 или F2 |
| +204 | 24 | Текст для меню вьювера |
| +228 | 32 | Резерв |
| +260 | 252 | Структура параметров INI |
## Детальное описание полей
### Количество страниц (+34)
Указывает, сколько 16 КБ страниц памяти будет выделено плагину.
Максимум: **64 страницы** (`WC_PLUGIN_MAX_PAGES`) = 1 МБ.
Страницы выделяются из пула `#61–#A0` (физические), плагин обращается
по логическому номеру 0..N−1 через `wc_mngc_pl()` / `wc_mng0_pl()` / `wc_mng8_pl()`.
Часть страниц может использоваться как буфер, который **сохраняется
между повторными запусками** плагина (NEXT/PREV) — код плагина WC не
перезагружает, если плагин уже загружен.
### Номер стартовой страницы (+35)
Номер страницы (от 0), которая будет включена в окно #8000 при запуске плагина. Нумерация начинается с 0.
### Блоки данных (+36, 12 байт)
Описывает до 6 блоков данных плагина:
```
Для каждого блока (2 байта):
Байт 0: Номер страницы (от 0) для размещения блока
Байт 1: Размер блока (x512 байт)
```
Блоки данных следуют сразу за заголовком плагина (512 байт).
Пример:
```asm
DB 0,16 ; Блок 0: код плагина, 16x512 = 8КБ
DB 1,32 ; Блок 1: данные плеера, 32x512 = 16КБ
DB 2,9 ; Блок 2: дополнительный плеер, 9x512 = 4.5КБ
DB 0,0 ; Остальные блоки не используются
DB 0,0
DB 0,0
```
### Флаги блока расширений (+63)
Определяет, какая клавиша запускает плагин по расширению:
```
BIT 0: Режим запуска
0 - запуск и по ENTER, и по F3
1 - см. BIT 1
BIT 1 (если BIT 0 = 1):
0 - запуск только по ENTER
1 - запуск только по F3
```
| Биты [1:0] | Поведение |
|------------|------------------------------------------|
| `00` | ENTER и F3 — оба запускают плагин |
| `01` | Только ENTER (F3 = встроенный вьювер WC) |
| `11` | Только F3 (ENTER = вход в файл как данные) |
> Разделение ENTER и F3 добавлено в WC v1.00 (октябрь 2019).
### Блок расширений (+64, 96 байт)
Содержит до 32 расширений файлов (по 3 байта каждое).
**Важно:** Расширения указываются **ТОЛЬКО БОЛЬШИМИ БУКВАМИ!**
Примеры:
```asm
DB "TXT" ; Текстовые файлы
DB "MOD" ; MOD музыка
DB "WAV" ; WAV аудио
DB "MP3" ; MP3 аудио
DB "VGM" ; VGM музыка
; ... до 32 расширений
DS 27*3 ; Остальные заполняем нулями
```
Блок можно забить нулями, если не нужна инициация по расширениям.
### Максимальный размер файла (+161, 4 байта)
Определяет максимальный размер файла, который плагин может обработать. Файлы больше этого размера плагину не передаются.
Примеры:
```asm
DW #FFFF,#FFFF ; Без ограничений
DW #6000,#0000 ; Максимум 24КБ
```
### Имя плагина (+165, 32 байта)
Текстовое имя плагина, которое показывается в меню.
```asm
DB "VGM Player for OPL3 v1.0 "
```
### Тип условий вызова (+197)
Определяет, при каких условиях плагин должен вызываться (помимо расширений):
| Код | Константа (C) | Условие вызова |
|-----|---------------|----------------|
| #00 | `WC_PCOND_EXT_ONLY` | Только по расширению |
| #01 | `WC_PCOND_ON_LOAD` | Сразу после загрузки (при ENTER) |
| #02 | `WC_PCOND_TIMER` | По таймеру скринсейвера + из меню F10 |
| #03 | `WC_PCOND_F10` | Из меню F10 |
| #04 | `WC_PCOND_VIEWER` | Из меню вьювера (SHIFT+F3) |
| #05 | `WC_PCOND_F10_VIEW` | F10 + SHIFT+F3 |
| #11 | `WC_PCOND_F10_F2` | F10 + F2 |
| #12 | `WC_PCOND_F2` | По F2 |
| #13 | `WC_PCOND_F10_F4` | F10 + F4 |
| #14 | `WC_PCOND_F4` | По F4 |
| #15 | `WC_PCOND_F10_V_F4` | F10 + SHIFT+F3 + F4 |
**Примечание:** Все плагины с указанными расширениями также вызываются
по расширению. Тип вызова расширяет набор способов запуска.
### Текст для F2/F4 (+198, 6 байт)
Если тип вызова #11/#12 - текст для подсказки F2
Если тип вызова #13/#14/#15 - текст для подсказки F4
```asm
DB "Edit " ; Для редактора
DB "Play " ; Для плеера
```
### Текст для меню вьювера (+204, 24 байта)
Текст, который выводится в меню выбора вьювера (при типах #04/#05/#15):
```asm
DB "Play VGM on OPL3 "
```
## Структура параметров INI (+260, 252 байта)
> Добавлено в WC v1.09 (31.07.2024)
Позволяет плагину принимать параметры из INI-файла WC (`wc.ini`).
Параметры отображаются в меню F9 → настройки плагина.
### Формат записи
```
+0: 1 байт - длина ПОЛНОЙ структуры (включая этот байт) или #00 (конец)
+1: 1 байт - default_option (1-based номер опции по умолчанию)
+2: N байт - "parameter_name" (ASCII, без терминатора)
+2+N: 1 байт - количество опций (1-10)
+3+N: M байт - "option1",0, "option2",0, ...
... следующая запись или #00
```
Максимум 8 параметров, каждый до 10 опций.
### Пример
```asm
PAR1:
DB PAR1END-PAR1 ; Длина структуры
DB 1 ; Опция по умолчанию = 1
DB "opl_port" ; Имя параметра
DB 2 ; Количество опций
DB "C4",0 ; Опция 1
DB "C0",0 ; Опция 2
PAR1END:
PAR2:
DB PAR2END-PAR2
DB 1
DB "freq"
DB 3
DB "683",0
DB "1367",0
DB "2734",0
PAR2END:
DB 0 ; Конец списка параметров
```
### Чтение параметров в плагине
```c
// wc_prm_pl(param_num) — param_num с 0
// Возвращает: номер опции (1-based), 0xFF если параметр не задан
uint8_t opt = wc_prm_pl(0); // прочитать 1-й параметр
if (opt == 0xFF) opt = 1; // значение по умолчанию
```
```asm
; ASM: A' = номер параметра (0-based)
EXA
LD A,0 ; Параметр #0
CALL WLD
EXA
LD A,#53 ; PRM_PL
CALL WLD
; Z=не задан, NZ: A=номер опции (1-based)
```
В INI-файле (`wc.ini`) параметры записываются по длинному имени плагина:
```ini
[VGM Player v0.5]
opl_port=C4
freq=683
```
## Пример полного заголовка
```asm
ORG #6000
; +0: Резерв
DS 16
; +16: Идентификатор
DB "WildCommanderMDL"
; +32: Версия
DB #10
; +33: Резерв
DB 0
; +34: Количество страниц
DB 2
; +35: Стартовая страница
DB 0
; +36: Блоки данных
DB 0,8 ; Код: 4КБ
DB 1,16 ; Данные: 8КБ
DB 0,0
DB 0,0
DB 0,0
DB 0,0
; +48: Резерв
DS 15
; +63: Флаги расширений
DB 0
; +64: Расширения
DB "VGM"
DB "VGZ"
DS 30*3
; +160: Конец расширений
DB 0
; +161: Максимальный размер
DW #FFFF,#FFFF
; +165: Имя плагина
DB "VGM Player v1.0 "
; +197: Тип вызова
DB #00 ; По расширению
; +198-228: Резерв/меню
DS 6
DS 24
DS 32
; +260: Параметры INI
DB 0 ; Нет параметров
ORG #8000,#6200
; Здесь начинается код плагина
```