Документация на АПИ к библиотеке ayfly.
Библиотека ориентирована на максимальную масштабируемость, поэтому упор был сделан проигрывание нескольких модулей одновременно. Для каждой загружаемой мелодии создается отдельный контекст со своими областями памяти z80, своими копиями музыкальных сопроцессоров и т.п.
Центральной структурой библиотеки является структура aysonginfo, которая представляется клиентским приложениям простым указателем типа void, т.е. детали реализации полей структуры доступны только в библиотеке, а на пользовательском уровне должны использоваться различные функции, которые принимают указатель на данную структуру.
Теперь список функций с описаниями:
Макрос AY_CHAR определен либо как char* для ANSI сборки, и как wchar_t* для для сборки в юникоде.
void *ay_initsong(const AY_CHAR *FilePath, unsigned long sr, AbstractAudio *player = 0);
Данная функция загружает модуль, путь к которому определяется переменной FilePath и определяет частоту дискретизации равной значению переменной sr. Если переменная player = 0, тогда дополнительно инициализируется драйвер вывода звука для данного модуля. Иначе player доложен указывать на реализацию класса, наследуемого от AbstractAudio.
Возвращаемое значение — указатель на структуру aysonginfo, который в дальнейшем используется во всех функциях управления, либо 0, если модуль не может быть инициализрован по какой-либо причине.
void *ay_initsongindirect(unsigned char *module, unsigned long sr, AY_CHAR *type, unsigned long size, AbstractAudio *player = 0);
Данная функция делает то же самое, что и предыдущая, за исключением того, что инициализирует модуль, уже загруженный в облась памяти, начиная с адреса module, имеющим длину size. Переменная type должна содержать либо путь к модулю, либо его расширение в формате «.расширение». Это нужно для правильного выбора проигрывателя.
void *ay_getsonginfo(const AY_CHAR *FilePath);
void *ay_getsonginfoindirect(unsigned char *module, AY_CHAR *type, unsigned long size);
Данные функции также возвращают указатель на структуру aysonginfo, который служит лишь для того, чтобы впоследствии получать такую информацию о модуле, как название, автор, время проигрывания, и т.п. Модуль не может быть проигран с помощью возвращаемого значения.
const AY_CHAR *ay_getsongname(void *info);
const AY_CHAR *ay_getsongauthor(void *info);
const AY_CHAR *ay_getsongpath(void *info);
Эти функции возвращают сообветственно название модуля (может отличаться от имени файла), автора и путь к модулю.
unsigned long ay_getsonglength(void *info);
unsigned long ay_getelapsedtime(void *info);
unsigned long ay_getsongloop(void *info);
Эти функции возвращают соответственно длину модуля, текущую позицию при проигрывании и позицию зацикливания модуля. Все значения имеют точность 1/50 секунды, а именно измеряются в количествах прерываний z80.
void ay_seeksong(void *info, long new_position);
Данная функция перемещает позицию проигрывания модуля на позицию new_position, измеряемую в 1/50 секунды. Новая позиция может изменяться от 0 до значения, возвращаемого функцией ay_getsonglength.
void ay_resetsong(void *info);
Перемещает указатель проигрывания на нулевую позицию.
void ay_closesong(void **info);
Останавливает проигрывание модуля(если оно в данный момент активно)освобождает все ресурсы, связанные с модулем *info, и присваивает переменной, *info значение 0.
bool ay_songstarted(void *info);
Возвращает true, если модуль находится в режиме воспроизведения.
void ay_startsong(void *info);
Запускает проигрывание указанного модуля.
void ay_stopsong(void *info);
Останавливает воспроизведение модуля.
void ay_setvolume(void *info, unsigned long chnl, float volume, unsigned char chip_num = 0);
Устанавливает громкость канала под номером chnl (от 0 до 2), чипа AY с номером chip_num (от 0 до 255) равным значению переменной volume, изменяющейся от 0 до 1.
float ay_getvolume(void *info, unsigned long chnl, unsigned char chip_num = 0);
Возвращает громкость канала chnl (от 0 до 2) чипа AY chip_num (от 0 до 255) в пределах от 0 до 1.
void ay_chnlmute(void *info, unsigned long chnl, bool mute, unsigned char chip_num = 0);
Отключает (если mute = true) или включает (если mute = false) канал под номером chnl (от 0 до 2) чипа AY с номером chip_num (от 0 до 255).
bool ay_chnlmuted(void *info, unsigned long chnl, unsigned char chip_num = 0);
Возвращает true, если канал под номером chnl (от 0 до 2) чипа AY под номером chip_num (от 0 до 255) выключен.
void ay_setelapsedcallback(void *info, ELAPSED_CALLBACK callback, void *callback_arg);
Устанавливает функцию обратного вызова типа bool (void *arg), которая вызывается при достижении конца мелодии (даже если причутствует цикл). Если функцию обратного вызова возвращает true, тогда воспроизведение мелодии приостанавливается и вызывается функция обратного вызова stoppedcallback (если задана).
void ay_setstoppedcallback(void *info, STOPPED_CALLBACK callback, void *callback_arg);
Устанавливает функцию обратного вызова типа void (void *arg), которая вызывается при достижении конца мелодии, если функция обратного вызова elapsedcallback возвращает true.
const unsigned char *ay_getregs(void *info, unsigned char chip_num = 0);
Возвращает указатель на струкруру из 16-ти байт, которая содержит текущий снимок регистров чипа AY под номером chip_num. ВОзвращаемая структура доступна только для чтения.
void ay_rendersongbuffer(void *info, unsigned char *buffer, unsigned long buffer_length, unsigned char chip_num);
Заполняет участок памяти по адресу buffer длиной buffer_length оцифровкой мелодии с чипа AY chip_num (от 0 до 255). Записываемые данные имеют формат 16 бит 44100 кГц стерео. buffer_length - длина буфера в байтах. для записи одного стерео-сэмпла в данном режиме требуется 4 байта.
unsigned long ay_getz80freq(void *info);
Возвращает текущую частоту z80.
void ay_setz80freq(void *info, unsigned long z80_freq);
Устанавливает частоту z80, равную переменной z80_freq.
unsigned long ay_getayfreq(void *info);
Возвращает текущую частоту чипов AY.
void ay_setayfreq(void *info, unsigned long ay_freq);
Устанавливает частоту чипов AY, равную переменной ay_freq.
unsigned long ay_getintfreq(void *info);
Возвращает текущую частоту прерываний z80.
void ay_setintfreq(void *info, unsigned long int_freq);
Устанавливает частоту прерываний z80, равную переменной int_freq.
unsigned long ay_getsamplerate(void *info);
Возвращает текущую частоту дискретизации.
void ay_setsamplerate(void *info, unsigned long sr);
Устанавливает частоту дискретизации, равную переменной sr.
void ay_setsongplayer(void *info, void * /* class AbstractAudio */ player);
Устанавливает проигрыватель для песни. player должен быть реализацией класса, базовым для которого является класс AbstractAudio.
void *ay_getsongplayer(void *info);
Возвращает ссылку на проигрыватель для мелодии.
void ay_setchiptype(void *info, unsigned char chip_type);
Устанавливает тип чипа AY (0 = AY, 1 = YM), равным переменной chip_type.
unsigned char ay_getchiptype(void *info);
Возвращает тип чипа AY. 0 = AY, 1 = YM.
void ay_writeay(void *info, unsigned char reg, unsigned char val, unsigned char chip_num = 0);
Устанавливает значение рагистра куп чипа AY под номером chip_num равным переменной val.
unsigned char ay_readay(void *info, unsigned char reg, unsigned char chip_num = 0);
Возвращает значение регистра reg чипа AY под номером chip_num.
bool ay_format_supported(AY_TXT_TYPE filePath);
Возвращает true, если формат файла filePath поддерживается текущей версией библиотеки. filePath должен содержать либо расширение файла в формате ".расширение", либо полнуй путь к файлу, включая расширение.
void ay_sethwnd(void *info, HWND hWnd);
Устанавливает дестриптор окна для текущего плеера, равному переменной hWnd.