IAudioRenderClient：：GetBuffer 方法（audioclient.h）

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

Syntax

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

参数

[in] NumFramesRequested

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

[out] ppData

指向指针变量的指针变量，该方法会将调用方写入数据包的缓冲区区域的起始地址。

返回值

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

注解

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

客户端负责将足够多的数据写入缓冲区，以防止故障发生在音频流中。 有关缓冲要求的详细信息，请参阅 IAudioClient：：Initialize。

通过调用 GetBuffer 获取数据包后，客户端通过呈现数据填充数据包，并通过调用 IAudioRenderClient：：ReleaseBuffer 方法向音频引擎发出数据包。

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

对于非零数据包大小，客户端必须备用调用 GetBuffer 和 ReleaseBuffer。 每个 GetBuffer 调用都必须后跟相应的 ReleaseBuffer 调用。 客户端调用 GetBuffer 以获取数据包后，客户端将无法获取下一个数据包，直到它调用 ReleaseBuffer 释放以前的数据包。 不允许对 GetBuffer 或 ReleaseBuffer 进行两次或更多连续调用，并且错误代码AUDCLNT_E_OUT_OF_ORDER失败。

若要确保调用的顺序正确， GetBuffer 调用及其相应的 ReleaseBuffer 调用必须在同一线程中发生。

音频帧的大小由客户端通过调用 IAudioClient：：GetMixFormat 方法获得的波形图X 结构的 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 方法的代码示例，请参阅以下主题：

• 呈现流
• Exclusive-Mode 流

要求

另请参阅

IAudioClient：：GetBufferSize

IAudioClient：：GetCurrentPadding

IAudioClient：：Initialize

IAudioRenderClient 接口

IAudioRenderClient：：ReleaseBuffer