IAudioRenderClient：：GetBuffer 方法 (audioclient.h)

项目
08/22/2023

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

语法

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	参数 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