Программирование игр для Windows. Советы профессионала

API пакета программ MIDPAK


Драйвер MIDI, MIDPAK использует вектор прерывания 66h, что обеспечивает прозрачный программный интерфейс. Ниже.описываются два способа воспроизведения MIDI-музыки. Первый способ основан на прерываниях. Второй — на использовании библиотеки функций на Си или ассемблере, которые позволяют не только осуществлять доступ к драйверам звука, но и предоставляют другие полезные функции. Эти функции находятся в исходном файле MIDPACK.ASM.

MIDPAK использует тот же вектор прерывания, что и DIGPAK. Пакет DIGPAK описывает полный набор драйверов оцифрованного звука, поставляемый фирмой Audio Solution. MIDPAK полностью совместим с DIGPAK. Если ваша программа должна воспроизводить как MIDI-музыку, так и оцифрованный звук, надо вначале загрузить требуемый драйвер оцифрованного звука, и затем поверх него загрузить MIDI-драйвер MIDPAK. Драйвер MIDPAK обнаруживает присутствие драйвера DIGPAK и перенаправляет через него все вызовы. Если аппаратное обеспечение не в состоянии независимо воспроизводить оцифрованный звук (поддержка прямого доступа в память: Sound Blaster и ProAudio Spectrum), тогда во время воспроизведения оцифрованного звука исполнение MIDI-музыки будет выключено. Воспроизведение MIDI-музыки возобновится сразу же после окончания проигрывания оцифрованного звукового фрагмента. Для прикладной программы этот процесс полностью прозрачен.

Пакет программ MIDPAK использует набор звуковых драйверов MIDI, разработанных Miles Design Inc. Эти драйверы различаются по своему размеру и имеют расширение .ADV. При старте MIDPAK всегда загружает драйвер MUSIC.ADV. Поэтому прикладная программа перед загрузкой MIDPAK должна переименовать необходимый драйвер в MUSIC.ADV.

MIDPAK не исполняет непосредственно файлы MIDI. Вы должны конвертировать файлы MIDI (с расширением .MID) в файлы обобщенного MIDI (-XMI), используя программу MIDIFORM или утилиту MENU. Драйверы Расширенного MIDI фирмы Miles Design Incorporated поддерживают каналы 2-9 для мелодических инструментов и канал 10 для ударных.

Замечание




Любой не указанный номер функции является устаревшим или не используется.

Функция № 1: UnloadMidPak

Эта функция освобождает память, занятую резидентной частью MIDPAK, и на должна использоваться прикладной программой! Используется MIDPAK для внутренних целей и приведена здесь только для полноты картины.

ВХОД:  AX=700h Номер команды.

ВЫХОД: Ничего                             

Функция № 2: DigPakAvailable



Функция определяет доступность драйвера DIGPAK под драйвером MIDPAK.

ВХОД:  AX=701h    Номер команды.

ВЫХОД: АХ=0       DIGPAK не доступен.

                АХ=1       DIGPAK доступен.

Функция № 3 PlaySequence

Функция исполняет последовательность из текущего зарегистрированного XMIDI-файла.                       

ВХОД:  AX=702h    Номер команды,                  

              BX=SEQ     Номер последовательности, начиная с нуля,

ВЫХОД: АХ=1        Последовательность проигрывается.  

                АХ=0        Последовательность не доступна.      

Функция № 4: SegueSequence

Функция регистрирует с указанием кода активации новую последовательность Для исполнения по триггерному событию. Если значение кода активации -1, то переход к данной последовательности будет осуществлен по ближайшему триггеру. Триггер с указанием кода события помещается в поток данных MIDI с помощью Контроллера 119. Контроллеры 119 могут быть помещены в любое место потока данных MIDI для передачи программе информации о текуацей позиций в MIDI-последовательности.

ВХОД:  AX=703h     Номер команды.

              ВХ = SEQ    Номер регистрируемой последовательности.

              СХ= ACT    Код активации события, -1 означает следующий триггер.

Функция № 5: RegisterXmidi

Функция регистрирует адрес файла XMIDI для исполнения.

ВХОД:  AX=704h     Номер команды,

              BX=Offset   Смещение в дальнем адресе данных XMIDI.

              CX=Segment Сегмент в дальнем адресе данных XMIDI.

              SI=Low len   Младшее слово значения длины данных XMIDI.

              DI=High len Старшее слово значения длины данных XMIDI.



ВЫХОД: АХ=0       Ошибка регистрации данных XMIDI.

                 АХ=1        Файл XMIDI зарегистрирован резидентно. Это означает, что файл полностью поместился во внутренний буфер MIDPAK. Ваша программа может освободить память, связанную с файлом XMIDI, так как MIDPAK создал для себя его, копию. Это очень полезно в средах с виртуальной памятью, где прикладная программа не всегда имеет фиксированный адрес в памяти. Это также позволяет MIDPAK исполнять музыку в фоновом режиме под DOS.

                 АХ=2        Файл XMIDI зарегистрирован. Прикладная программа ответственна за то, чтобы указанный фиксированный адрес в памяти всегда содержал соответствующие данные XMIDI.

Функция № 6: MidiStop

Функция, останавливает воспроизведение текущей последовательности MIDI.

ВХОД:  AX=705h     Номер команды.

ВЫХОД: Ничего

Функция № 8: ReportTriggerCount

Функция возвращает счетчик триггерных событий и код последнего события.

ВХОД:  AX=707h     Номер команды.

ВЫХОД: AX=COUNT Количество событий со времени последнего сброса счетчика.

                 DX=ID      Код последнего события. Коды событий вы можете найти в спецификации XMIDI..

Функция № 9: ResetTriggerCount

Функция сбрасывает счетчик событий в ноль.

ВХОД:  AX=708h     Номер команды.

ВЫХОД: Ничего

Функция № 12: ResumePlaying

Функция продолжает исполнение остановленной последовательности.

ВХОД:  АХ-70Вh    Номер команды.

Функция № 13: SequenceStatus                                  

Функция возвращает состояние последовательности.

ВХОД: АХ=70Сh              Номер команды.

ВЫХОД: АХ=Статус

                        SEQ_STOPPED 0        Воспроизведение последовательности остановлено.

                        SEQ_PLAYING 1        Последовательность исполняется в настоящий момент.

                        SEQ_DONE 2           Исполнение последовательности завершено.

Функция № 14: RegisterXmidiFile

Функция регистрирует файл по его имени.

ВХОД:  AX=70Dh  Номер команды.

BX=Offset   Смещение адреса имени файла.



CX=Segment Сегмент адреса имени файла.

Функция № 15: RelativeVolume

Функция возвращает относительную громкость музыки в процентах.

ВХОД:  АХ=70Еh    Номер команды.

ВЫХОД: АХ= VOL    Текущая относительная громкость в процентах 0-100.

Функция № 16: SetRelativeVolume

Функция устанавливает относительную громкость в процентах.

ВХОД:  AX=70Fh    Номер команды.

Функция № 17: BootstrapMidPak

Функция позволяет приложению устанавливать драйвер MIDPAK.

ВХОД:  АХ-710h     Номер команды.

ВХ:СХ      СЕГМЕНТ:СМЕЩЕНИЕ драйвера ADV.

DX:SI       СЕГМЕНТ:СМЕЩЕНИЕ файла AD.

Функция № 18: PollMidPak

ВХОД;  AX=710h

Функция используется в сочетании с PMIDPAK.COM. Это версия MIDPAK, работающая по опросу. Обычный MIDPAK перехватывает прерывание либо от таймера, либо от часов реального времени и обслуживает его с частотой 120 раз в минуту. Однако некоторые сложные прикладные программы сами обслуживают аппаратные прерывания и требуют исполнения фоновой музыки с иной частотой дискретизации, или синхронизируют по таймеру графические функции, чтобы избежать возможного прерывания музыкой графических процедур.

После того как MIDPAK установлен, он восстанавливает вектор прерывания таймера и не проявляет себя до- тех пор, пока программа, не выполнит прерывание 66h с командой 0711h. Вы должны вызывать это прерывание с частотой 120 раз в минуту или с частотой дискретизации, указанной при запуске MIDIFORM. При запуске MIDIFORM вы можете указать частоту дискретизации для вашей музыки, отличную от принятого по умолчанию значения 120. При снижении частоты дискретизации вы услышите ухудшение качества музыки, так как ASDR не будет реагировать достаточно быстро. Снижение ее,  например, до 60 раз в минуту не будет сильно заметным, однако уменьшение частоты до 30 или 15 вызовет значительное ухудшение качества звучания. Очевидно, что исполнение многоканальной MIDI-музыки на таком частотном синтезаторе, как Adiib, потребует определенных ресурсов процессора. Переквантовывая свою музыку и задавая MIDPAK удобные для вас частоты, вы можете добиться хорошего баланса использования ресурсов компьютера.



Функция № 19: MidpakClock

Функция возвращает текущее значение счетчика MIDPAK.

ВХОД:  AX=7l2h

ВЫХОД: AX:DX      Текущее значение счетчика с момента старта MIDPAK. Счетчик обновляется 120 раз в минуту, и ваше приложение может использовать его как таймер.

ВХ:СХ       Образует дальний указатель на счетчик.

ВХ          Смещение, СХ          Сегмент.

Функция возвращает значение внутреннего счетчика MIDPAK. При старте счетчик, представляющий собой двойное слово, имеет нулевое значение, которое увеличивается каждую минуту на 120, и ваше приложение может использовать его как таймер, просто опрашивая эту функцию.

Функция № 20: TriggerCountAddress

Функция возвращает адрес размещения счетчика триггеров.

ВХОД:  АХ=713h                                              

ВЫХОД: AX:DX       Образует адрес целого значения счетчика триггеров. Значение этого счетчика увеличивается на единицу при каждом появлении Контроллера 119 в файле MIDI.

Функция № 21: EventIDAddress

Функция возвращает адрес размещения кода события.

ВХОД: AX=714h

ВЫХОД: AX:DX       Образует адрес целого значения кода события. В этой ячейке памяти хранится код последнего события вызванного Контроллером 119.

Функция № 23: ReportSequenceNumber

Функция возвращает номер исполняемой в данный момент последовательности.

ВХОД:  AX=716h

ВЫХОД:              Возвращает номер исполняемой в данный момент последовательности.

extern short cdecl CheckMidiIn (void);

// Возвращает 1, если MIDPAK

установлен, 0 - если нет.

extern short cdecl DigpakAvailable (void) ;

// Возвращает 1, если DIGPAK

установлен, 0 - если нет. /****************************•*************************************

/**    Эти флаги возвращает функция регистрации данных XMIDI   ***

/****************************************************************/

#define FAILURE_TO_REGISTER   0 // Ошибка

регистрации

XMIDI файла.

#define REGISTERED RESIDENT   1 // Резидентный драйвер полностью

// содержит данные XMIDI. Приложение

// может освободить память, которую



// они занимали.

#define REGISTERED_APPLICATION

1 //Драйвер не имеет настолько

// большого буфера, чтобы полностью

// загрузить в него данные XMIDI.

// Приложение обязано обеспечить

// сохранение в памяти по указанному

// адресу данные XMIDI.

extern short cdecl PlaySequence (short seqnum);

// исполняет последовательность с данным номером

// из зарегистрированного файла XMIDI

#define NEXT_CALLBACK

- 1 // активизация по ближайшему событию

extern short cdecl SegueSequence (short seqnum, short activate) ;

// Переключает исполнение последовательности на

// указанную последовательность по наступлению

// события с кодом, равным указанному коду активации.

// Если код активации равен -1, переключение

// произойдет по ближайшему событию.

extern short cdecl RegisterXmidi (char *xmidi, long int size) ;

// Регистрирует XMIDI файл для воспроизведения.

// Этот вызов зарегистрирует все последовательности.

extern short cdecl MidiStop (void);

// остановка воспроизведения текущей последовательности

extern long int cdecl ReportCallbackTrigger (void);

// младшее слово - счетчик триггеров

// старшее слово - идентификатор последнего события

extern void cdecl ResetCallbackCounter (void);

// сбрасывает счетчик триггеров в ноль

extern void cdecl ResumePlaying (void) ;

// продолжает воспроизведение прерванной последовательности

#define SEQ_STOPPED  0  // возвращаемые значения

#define SEQ_PLAYING  1  // функции SequenceStatus()

#define SEQ_DONE     2

extern short cdecl SequenceStatus (void) ;

// возвращает состояние текущей последовательности

extern short cdecl RelativeVolume (short vol);

// возвращает текущую громкость

extern void cdecl SetRelativeVolume (short vol, short time);

// устанавливает громкость на заданный период времени

#define NOBUFFER          1  // нет резидентного буфера

#define FILENOTFOUND      2  // файл не найден

#define FILETOBIG         3  // файл превышает размер

// зарезервированного буфера

#define REGISTRATIONERROR 4  // ошибка регистрации файла XMI

extern short cdecl RegisterXmidiFile (char *fname);

// регистрирует файл по имени

extern void cdecl PollMidPak (void);

           // запрос MIDPAK на исполнение музыки

extern long int cdecl MidPakClock (void);

// возвращает значение внутреннего счетчика MIDPAK

extern long int * cdecl MidPakClockAddress (void);

// возвращает адрес таймера MIDPAK

extern short * cdecl TriggerCountAddress (void) ;

// возвращает адрес счетчика триггеров

extern short * cdecl EventIDAddress (void);

// возвращает адрес идентификатора события

extern short cdecl ReportSequenceNumber (void) ;

extern short cdecl InitMP (char *midpak, char *adv, char *ad) ;

// инициализирует драйвер MIDPAK

extern void cdecl DeInitMP (char *midpak);

// выгружает драйвер MIDPAK


Содержание раздела