虚拟Voice的动作

示例目录

/cri/pc/samples/criatomex/virtual_voice

示例描述

Atom运行库使用 “Voice” 执行波形数据的播放。
Voice是执行数据读取、音频解码、发声处理的对象。
原则上使用一个Voice播放一个波形数据, 应用程序中可同时播放的波形数据数量受Voice数量限制。

［备注］
可以在创建Voice池时指定Voice数量， 能够在应用程序端自由控制最大同时发声数。
但由于内存大小和CPU负荷也会与使用的Voice数量成比例增加， 因此必须将Voice数量压缩到应用程序允许的范围。
此外，在Voice使用硬件Voice的平台中， 创建的Voice数量不能超出硬件限制。

除Voice外，Atom运行库还使用名为 “虚拟Voice” 的虚拟Voice对象。
虚拟Voice执行参数管理和播放时间管理，是管理用于音频输出的Voice的对象。
通常，虚拟Voice与Voice成对运行，用户不需要知道虚拟Voice存在， 但其实也可以通过更改Voice分配方式，使用虚拟Voice作为没有Voice的虚拟声源。

虚拟Voice的预设动作

预设状态下，Atom运行库将虚拟Voice和Voice设为一组执行播放。

例如，为AtomExPlayer设置音频数据，执行::criAtomExPlayer_Start函数时， AtomExPlayer只分配需要的数量的虚拟Voice和Voice。
此时，如果可以分配虚拟Voice和Voice，则播放音频， 而只要其中一个不能分配，则设置的数据不会发声。

［备注］
初始化程序库时可以以任意数量分配虚拟Voice， 只要不发出超出初始化程序库时指定数量的播放请求， 虚拟Voice就不会获取失败。
此外，即使分配Voice失败时也会返回残存的播放ID， 因此无需根据可否播放来更改之后的处理。

如何将虚拟Voice用作虚拟声源

创建AtomExPlayer时，如果为::CriAtomExPlayerConfig 的 voice_allocation_method 指定CRIATOMEXPLAYER_RETRY_VOICE_ALLOCATION， 则即使AtomExPlayer在播放开始时无法分配Voice, 也可以只使用虚拟Voice开始播放音频。

由于无法分配Voice，因此不会执行发声处理， 而会通过虚拟Voice执行参数更改记录和播放位置管理。
（与返回存根的播放ID的情况不同，可以使用::criAtomExPlayback_GetTime函数获取播放时间。）

此外，虚拟Voice在播放期间依次监控Voice有无空闲，并在有空闲Voice时重新获取Voice。
因此， 关于用指定CRIATOMEXPLAYER_RETRY_VOICE_ALLOCATION创建的AtomExPlayer播放的音频， 即使在播放开始时无法分配Voice或在播放期间Voice因优先级控制被抢占， 只要之后有空闲Voice，就能够恢复播放。

［备注］
当虚拟Voice成功重新获取Voice时，会尽可能从播放开始的经过时间位置起恢复发声处理。
但对于不支持搜索播放的编解码以及在开始发声前（ CRIATOMEXPLAYBACK_STATUS_PREP 状态时）Voice被抢占时， 将从音频数据的开头位置开始播放。
此外，由于流播放的声音会发生缓冲延迟， 经过时间与恢复位置可能会出现较大偏差。

更改Voice分配方式的代码如下。

CriAtomExPlayerConfig player_config;
 
/* 为用于创建Player的配置构件设置预设值 */
criAtomExPlayer_SetDefaultConfig(&player_config);
 
/* 更改Voice分配方式 */
/* 备注）即使在播放过程中Voice被抢占，     */
/*       指定CRIATOMEXPLAYER_RETRY_VOICE_ALLOCATION创建的Player */   */
/*       也会在Voice有空闲时恢复播放。              */
player_config.voice_allocation_method = CRIATOMEXPLAYER_RETRY_VOICE_ALLOCATION;
 
/* 创建Player */
app_obj->player = criAtomExPlayer_Create(&player_config, NULL, 0);

在示例中，虽然只分配一个用于发声的Voice， 但操作着循环用BGM、Voice、SE三个声音。

循环BGM在示例启动的同时开始播放。
通过按钮操作播放Voice和SE时，播放循环BGM的Voice会被抢占， 继而播放Voice和SE，而播放结束后，将恢复播放循环BGM。

注意

连续按太多次按钮，将导致虚拟Voice本身耗尽， 在调试器中会输出警告并停止循环BGM。

示例使用的数据中AtomCraft项目的目录

/cri/tools/criatomex/examples/tutorial_data_for_runtime