MIDI *load_midi(char *filename);
载入一个 MIDI 文件, (可以是格式 0 和格式 1), 返回一个
MIDI 结构指针, 发生错误就返回 NULL.
void destroy_midi(MIDI *midi);
当你调用它则撤销一个 MIDI 结构. 即使在 MIDI 文件正在播放
中执行此函数也很安全, 因为函数将检查是否正在播放音
乐并将它关掉。
int play_midi(MIDI *midi, int loop);
先停止调用此函数前播放的音乐并开始播放指定的
MIDI 文件, 如果设定循环参数为真, 将反复播放音乐,
直到它被其他的东东重置, 否则音乐到达文件尾部时就会停止.
传入一个 NULL 指针将停止目前播放的任何音乐.
如果发生任何错误将返回一非零值.(如果 patch-caching 波表驱动程序
不能载入采样声音时错误就会发生,
要么至少发生在以后有人写的一些 patch-caching 波表驱动程序里了 :-)
int play_looped_midi(MIDI *midi, int loop_start, int loop_end);
以用户设定循环位置方式播放一个 MIDI 文件, 当播放器到
达音乐结束点或文件尾部时(如只设定到达文件尾部时
loop_end值可以是-1), 播放器将返回到音乐的起始点.
结束点和起始点都以相同音乐节拍数的格式在
midi_pos 变量中定义.
void stop_midi();
停止当前正在播放的所有音乐, 此函数与调用
play_midi (NULL, FALSE) 函数功能相同.
void midi_pause();
暂停 MIDI 播放器.
void midi_resume();
重新开始播放被暂停的 MIDI 文件.
int midi_seek(int target);
定位当前 MIDI 文件到用户指定的位置, 如目标地址
早于当前 midi_pos, 函数将从文件开始处定位;
否则将从当前位置开始定位. 如果成功, 如果到达文件尾部就返回非零
( 1 表示已停止播放, 2 表示返回到音乐开头).
如果这个函数由于到达文件末尾的原因而停止,
midi_pos 将设置为 MIDI 文件长度的负值.
void midi_out(unsigned char *data, int length);
即时将 MIDI 数据块输入播放器, 允许你触发音符,
叮当声等, 将放在任何正在播放的 MIDI 文件之上.
int load_midi_patches();
强制 MIDI 驱动程序装载全部准备使用的 Patch,
一般你不需要调用此函数, 因为 Allegro 自动装载当前 MIDI 文件需
要的数据, 但在你通过调用 midi_out() 命令发送任何程序变更信息之前你
必须调用此函数. 如发生错误将返回非零值.
extern volatile long midi_pos;
储存当前 MIDI 文件里的位置 (节拍数),
或者是一个负值, 这时当前当前没有音乐播放. 此函数对使用音乐同步动画显示
和检查 MIDI 文件是否播放完毕很有用.
extern long midi_loop_start;
extern long midi_loop_end;
循环开始点和结束点, 由 play_looped_midi( ) 函数设置.
这些值在音乐播放中可以安全地改变, 但你必须保
证改变这些值的有效性 ( start < end). 如你同时改变
这两个值, 你一定要注意使用正确的次序, 因为你的两次设定
将导致 MIDI 中断!
设置成 -1 将分别将它们置向文件的开头和末尾.
extern void (*midi_msg_callback)(int msg, int byte1, int byte2);
extern void (*midi_meta_callback)(int type, unsigned char *data, int length);
extern void (*midi_sysex_callback)(unsigned char *data, int length);
以上函数允许你截取 MIDI 播放器事件. 如果设置为 NULL
之外的任何值, 这些程序将为每个 MIDI 信息,
meta-事件, 系统各自独特的数据块调用.
它们将在每个中断上下文句柄处执行, 因此它们使用的所有代码和数据都要锁定,
且不能调用任何系统功能. 一般你只是用这些函数设置
一些标志以备今后在你的主线代码中调用中使用.
int load_ibk(char *filename, int drums);
读入一个 .IBK patch 定义文件给 Adlib 驱动程序使用.
如果 drums 参数被设定, 装载此函数将激发 patch set, 否则
它将替代普通 MIDI 乐器集合. 你可以在初始化声音代码前
或后调用此函数, 也可以简单地将 ibk_file 和 ibk_drum_file
变量在配置件中设定来使数据自动装载.
注意此函数除了 Adlib 驱动程序对其它均无效!