IAudioRenderClient::GetBuffer 方法 (audioclient.h)
检索指向呈现终结点缓冲区中下一个可用空间的指针,调用方可以在其中写入数据包。
语法
HRESULT GetBuffer(
[in] UINT32 NumFramesRequested,
[out] BYTE **ppData
);
参数
[in] NumFramesRequested
调用方计划写入缓冲区中请求空间的数据包中的音频帧数。 如果调用成功,则 *ppData 指向的缓冲区大小与 NumFramesRequested 中指定的大小匹配。
[out] ppData
指向指针变量的指针,方法将缓冲区的起始地址写入调用方将数据包写入其中。
返回值
如果该方法成功,则它会返回 S_OK。 如果失败,可能的返回代码包括但不限于下表中显示的值。
返回代码 | 说明 |
---|---|
|
GetBuffer 未能检索数据缓冲区,并且 *ppData 指向 NULL。 有关详细信息,请参阅“备注”。 |
|
NumFramesRequested 值超出可用缓冲区空间 (缓冲区大小减去填充大小) 。 |
|
流是独占模式,使用事件驱动的缓冲,但客户端尝试获取的数据包不是缓冲区的大小。 |
|
以前的 IAudioRenderClient::GetBuffer 调用仍然有效。 |
|
音频终结点设备已拔出,或者音频硬件或关联的硬件资源已重新配置、禁用、删除或以其他方式不可用。 |
|
无法访问缓冲区,因为正在进行流重置。 |
|
Windows 音频服务未运行。 |
|
参数 ppData 为 NULL。 |
注解
调用方可以请求小于或等于缓冲区 (可用空间量的数据包大小,但使用事件驱动缓冲的独占模式流除外;有关详细信息,请参阅 IAudioClient::Initialize) 。 可用空间只是缓冲区大小减去缓冲区中已排队等待播放的数据量。 如果调用方指定的 NumFramesRequested 值超过了缓冲区中的可用空间,则调用将失败并返回错误代码AUDCLNT_E_BUFFER_TOO_LARGE。
客户端负责将足够的数据写入缓冲区,以防止音频流中出现故障。 有关缓冲要求的详细信息,请参阅 IAudioClient::Initialize。
通过调用 GetBuffer 获取数据包后,客户端使用呈现数据填充数据包,并通过调用 IAudioRenderClient::ReleaseBuffer 方法将数据包发布到音频引擎。
在成功获取除 0 以外的任何大小的数据包的 GetBuffer 调用后,客户端必须调用 ReleaseBuffer。 客户端可以选择调用或不调用 ReleaseBuffer 来释放大小为 0 的数据包。
对于非零数据包大小,客户端必须交替调用 GetBuffer 和 ReleaseBuffer。 每个 GetBuffer 调用都必须后跟相应的 ReleaseBuffer 调用。 在客户端调用 GetBuffer 来获取数据包后,在调用 ReleaseBuffer 释放上一个数据包之前,客户端无法获取下一个数据包。 不允许对 GetBuffer 或 ReleaseBuffer 进行两次或多次连续调用,并且将失败并AUDCLNT_E_OUT_OF_ORDER错误代码。
为了确保调用顺序正确, GetBuffer 调用及其相应的 ReleaseBuffer 调用必须在同一线程中发生。
音频帧的大小由客户端通过调用 IAudioClient::GetMixFormat 方法获取的 WAVEFORMATEX 结构的 nBlockAlign 成员指定。
如果调用方设置 NumFramesRequested = 0,该方法将返回状态代码S_OK但不写入 ppData 参数指向的变量。
客户端应避免获取缓冲区的 GetBuffer 调用与释放缓冲区的 ReleaseBuffer 调用之间的过度延迟。 音频引擎的实现假定 GetBuffer 调用和相应的 ReleaseBuffer 调用发生在同一缓冲区处理周期内。 延迟释放缓冲区超过一个时间段的客户端可能会丢失示例数据。
在 Windows 7 中, GetBuffer 可以为在独占模式下使用终结点缓冲区的音频客户端返回 AUDCLNT_E_BUFFER_ERROR 错误代码。 此错误表示未检索数据缓冲区,因为数据包不可用 (*ppData 收到 NULL) 。
如果 GetBuffer 返回 AUDCLNT_E_BUFFER_ERROR,则使用音频样本的线程必须等待下一个处理阶段。 客户端可能会受益于保留失败的 GetBuffer 调用计数。 如果 GetBuffer 重复返回此错误,则客户端可以在关闭当前客户端后启动新的处理循环,方法是调用 IAudioClient::Stop、 IAudioClient::Reset 并释放音频客户端。
示例
有关调用 GetBuffer 方法的代码示例,请参阅以下主题:
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows Vista [桌面应用 | UWP 应用] |
最低受支持的服务器 | Windows Server 2008 [桌面应用 | UWP 应用] |
目标平台 | Windows |
标头 | audioclient.h |