IAudioRenderClient::GetBuffer 方法 (audioclient.h)

检索指向呈现终结点缓冲区中下一个可用空间的指针,调用方可以在其中写入数据包。

语法

HRESULT GetBuffer(
  [in]  UINT32 NumFramesRequested,
  [out] BYTE   **ppData
);

参数

[in] NumFramesRequested

调用方计划写入缓冲区中请求空间的数据包中的音频帧数。 如果调用成功,则 *ppData 指向的缓冲区大小与 NumFramesRequested 中指定的大小匹配。

[out] ppData

指向指针变量的指针,方法将缓冲区的起始地址写入调用方将数据包写入其中。

返回值

如果该方法成功,则它会返回 S_OK。 如果失败,可能的返回代码包括但不限于下表中显示的值。

返回代码 说明
AUDCLNT_E_BUFFER_ERROR

GetBuffer 未能检索数据缓冲区,并且 *ppData 指向 NULL。 有关详细信息,请参阅“备注”。

AUDCLNT_E_BUFFER_TOO_LARGE
NumFramesRequested 值超出可用缓冲区空间 (缓冲区大小减去填充大小) 。
AUDCLNT_E_BUFFER_SIZE_ERROR
流是独占模式,使用事件驱动的缓冲,但客户端尝试获取的数据包不是缓冲区的大小。
AUDCLNT_E_OUT_OF_ORDER
以前的 IAudioRenderClient::GetBuffer 调用仍然有效。
AUDCLNT_E_DEVICE_INVALIDATED
音频终结点设备已拔出,或者音频硬件或关联的硬件资源已重新配置、禁用、删除或以其他方式不可用。
AUDCLNT_E_BUFFER_OPERATION_PENDING
无法访问缓冲区,因为正在进行流重置。
AUDCLNT_E_SERVICE_NOT_RUNNING
Windows 音频服务未运行。
E_POINTER
参数 ppDataNULL

注解

调用方可以请求小于或等于缓冲区 (可用空间量的数据包大小,但使用事件驱动缓冲的独占模式流除外;有关详细信息,请参阅 IAudioClient::Initialize) 。 可用空间只是缓冲区大小减去缓冲区中已排队等待播放的数据量。 如果调用方指定的 NumFramesRequested 值超过了缓冲区中的可用空间,则调用将失败并返回错误代码AUDCLNT_E_BUFFER_TOO_LARGE。

客户端负责将足够的数据写入缓冲区,以防止音频流中出现故障。 有关缓冲要求的详细信息,请参阅 IAudioClient::Initialize

通过调用 GetBuffer 获取数据包后,客户端使用呈现数据填充数据包,并通过调用 IAudioRenderClient::ReleaseBuffer 方法将数据包发布到音频引擎。

在成功获取除 0 以外的任何大小的数据包的 GetBuffer 调用后,客户端必须调用 ReleaseBuffer。 客户端可以选择调用或不调用 ReleaseBuffer 来释放大小为 0 的数据包。

对于非零数据包大小,客户端必须交替调用 GetBufferReleaseBuffer。 每个 GetBuffer 调用都必须后跟相应的 ReleaseBuffer 调用。 在客户端调用 GetBuffer 来获取数据包后,在调用 ReleaseBuffer 释放上一个数据包之前,客户端无法获取下一个数据包。 不允许对 GetBufferReleaseBuffer 进行两次或多次连续调用,并且将失败并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::StopIAudioClient::Reset 并释放音频客户端。

示例

有关调用 GetBuffer 方法的代码示例,请参阅以下主题:

要求

要求
最低受支持的客户端 Windows Vista [桌面应用 | UWP 应用]
最低受支持的服务器 Windows Server 2008 [桌面应用 | UWP 应用]
目标平台 Windows
标头 audioclient.h

另请参阅

IAudioClient::GetBufferSize

IAudioClient::GetCurrentPadding

IAudioClient::Initialize

IAudioRenderClient 接口

IAudioRenderClient::ReleaseBuffer