简介

SDK API 提供向声音引擎发送 MIDI 事件的功能。可能发送的 MIDI 事件的类型有：

• Note-On（音符开启）事件。
• Note-Off（音符关闭）事件。
• 以及 CC（持续控制器）事件。

要 MIDI 事件产生声音，则这些事件必须有目标合成器。合成器是声音设计师在项目的 Actor-Mixer hierarchy（角色混音器层级结构）中创建的 Wwise 对象的集合。 Note-On 事件通常播放目标 Actor-Mixer 对象或它的后代之一。开始播放之后，Actor-Mixer 对象一旦遇到以下情况将停止：

• 如果没有设置循环，在播放到对象源的末尾时，
• 或者相应 Note-Off 事件（相同音符和通道）发送到同一目标。

把 MIDI 事件集成到游戏中

AK::SoundEngine::PostMIDIOnEvent "PostMIDIOnEvent" 函数对声音引擎中的 MIDI 事件排队。此函数使用以下项目作为变量：

• MIDI 事件。
• 事件发生的时间（相对于当前帧）。
• Wwise 事件 ID。
• 游戏对象 ID。

声音引擎将已发送的 MIDI 事件分组成序列。每个序列通过以下项目标识：

• 游戏对象 ID；函数参数，
• Wwise 对象 ID；从对应于事件 ID 的事件中的播放动作的目标对象获取。 请参阅 集成 Event 了解有关事件的更多详情。

因此，可同时向多个目标发送相同 MIDI 事件。例如，假设我们有：

• 事件 EV1，它有针对 Wwise 对象 W0 和 W1 的播放动作，
• 事件 EV2，它有针对 Wwise 对象 W0 的播放动作。

如果我们将 MIDI 事件 ME1 发送给游戏对象 GO 上的 Wwise 事件 EV1，声音引擎则将把 MIDI 事件 ME1 添加到 MIDI 序列 W0-GO 和 W1-GO。 如果我们再把 MIDI 事件 ME2 发送到 Wwise 事件 EV2，声音引擎则将把 MIDI 事件 ME2 添加到 MIDI 序列 W0-GO。

调用 AK::SoundEngine::PostMIDIOnEvent 将把 MIDI 事件添加到 MIDI 序列中。 然而，在调用 AK::SoundEngine::RenderAudio 函数之前不会执行任何处理。每次调用 AK::SoundEngine::RenderAudio 都会处理消息队列，可能产生任意数量的音频帧；具体帧数量取决于距上次调用 RenderAudio 以来已走过的时间。RenderAudio 每处理一帧，声音引擎就会使所有 MIDI 序列前进一帧。

更新 MIDI 序列

声音引擎在应用程序设定的时间播放 MIDI 序列非常重要。有两种方式向声音引擎发送 MIDI 序列。

如果整个 MIDI 序列为已知，并且知道 MIDI 序列的时序不会改变，则调用一次 AK::SoundEngine::PostMIDIOnEvent 可发送整个 MIDI 序列。

然而，如果不是这样，则必须每帧更新一次 MIDI 序列。在应用程序中可随时随地调用 AK::SoundEngine::PostMIDIOnEvent 函数。 然而，在除主音频线程之外的线程中调用此函数可能会导致同步问题。调用 AK::SoundEngine::PostMIDIOnEvent 只会发送声音引擎消息队列中的事件。消息队列在调用 AK::SoundEngine::RenderAudio 期间处理，此类调用中可能会处理任意数量的音频帧。 为了确保正确同步，建议应用程序按照以下方式注册一个全局回调函数：

• AK::SoundEngine::RegisterGlobalCallback( &MyCallbackFunction, AkGlobalCallbackLocation_PreProcessMessageQueueForRender );

声音引擎将在每个音频帧上调用这个注册了的函数。应用程序可使用回调函数跟踪声音引擎处理的音频帧。 因此，在回调函数中发送 MIDI 事件将确保正确同步。

停止 MIDI 序列

调用 AK::SoundEngine::StopMIDIOnEvent "StopMIDIOnEvent" 函数可停止 MIDI 序列。此函数接受 Event ID 和游戏对象 ID 作为参数。 它们任一参数都可设置为无效值来充当通配符。因此，如果事件 ID 和游戏对象 ID 均设为无效，则所有 MIDI 序列都会停止。

调用此函数将清空 MIDI 序列，并停止任何正在播放的声音。

有关集成 MIDI 的示例，请参阅 快速入门示例集成——MIDI 。