312 lines
11 KiB
Markdown
312 lines
11 KiB
Markdown
# Структура заголовка плагина (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
|
||
; Здесь начинается код плагина
|
||
```
|