Метод IAudioRenderClient::ReleaseBuffer (audioclient.h)

Статья
02/23/2024

Метод ReleaseBuffer освобождает буферное пространство, полученное при предыдущем вызове метода IAudioRenderClient::GetBuffer .

Синтаксис

HRESULT ReleaseBuffer(
  [in] UINT32 NumFramesWritten,
  [in] DWORD  dwFlags
);

Параметры

[in] NumFramesWritten

Количество аудиокадров, записанных клиентом в пакет данных. Значение этого параметра должно быть меньше или равно размеру пакета данных, как указано в параметре NumFramesRequested, передаваемом методу IAudioRenderClient::GetBuffer .

[in] dwFlags

Флаги конфигурации буфера. Вызывающий объект может задать для этого параметра значение 0 или следующее значение перечисления _AUDCLNT_BUFFERFLAGS (бит флага):

AUDCLNT_BUFFERFLAGS_SILENT

Если этот бит флага задан, звуковой модуль обрабатывает пакет данных так, как если бы он содержал тишину независимо от значений данных, содержащихся в пакете. Этот флаг избавляет клиента от необходимости явно записывать данные о тишине в буфер отрисовки.

Возвращаемое значение

Если метод завершается успешно, возвращает значение S_OK. В случае сбоя возможные коды возврата включают, но не ограничиваются ими, значения, показанные в следующей таблице.

Код возврата	Описание
AUDCLNT_E_INVALID_SIZE	Значение NumFramesWritten превышает значение NumFramesRequested , указанное в предыдущем вызове IAudioRenderClient::GetBuffer .
AUDCLNT_E_BUFFER_SIZE_ERROR	Поток является монопольным режимом и использует буферизацию на основе событий, но клиент пытался освободить пакет, который не был размером буфера.
AUDCLNT_E_OUT_OF_ORDER	Этому вызову не предшествовал соответствующий вызов IAudioRenderClient::GetBuffer.
AUDCLNT_E_DEVICE_INVALIDATED	Устройство конечной точки звука было отключено, или звуковое оборудование или связанные аппаратные ресурсы были перенастроены, отключены, удалены или иным образом стали недоступными для использования.
AUDCLNT_E_SERVICE_NOT_RUNNING	Аудиослужба Windows не запущена.
E_INVALIDARG	Параметр dwFlags не является допустимым значением.

Клиент должен освободить то же количество кадров, которое было запрошено в предыдущем вызове метода IAudioRenderClient::GetBuffer . Единственным исключением из этого правила является то, что клиент всегда может вызывать ReleaseBuffer для освобождения 0 кадров (если поток не находится в монопольном режиме и не использует буферизацию на основе событий).

Это позволяет клиенту "освободить" ранее запрошенный пакет длиной 0. В этом случае вызов ReleaseBuffer необязателен. После вызова GetBuffer для получения пакета длиной 0 клиент может не вызывать ReleaseBuffer перед повторным вызовом GetBuffer .

Кроме того, если предыдущий вызов GetBuffer получил пакет ненулевого размера, вызов ReleaseBuffer с параметром NumFramesRequested , равным 0, будет выполнен успешно (если поток не является монопольным режимом и не использует буферизацию на основе событий). Смысл вызова заключается в том, что клиент не записал данные в пакет перед его освобождением. Таким образом, метод рассматривает часть буфера, представленную пакетом, как неиспользуемую, и сделает эту часть буфера снова доступной для клиента в следующем вызове GetBuffer .

Клиентам следует избегать чрезмерных задержек между вызовом GetBuffer , который получает буфер, и вызовом ReleaseBuffer , который освобождает буфер. Реализация обработчика звука предполагает, что вызов GetBuffer и соответствующий вызов ReleaseBuffer происходят в течение одного периода обработки буфера. Клиенты, которые задерживают освобождение буфера более чем на один период, рискуют потерять образцы данных.

Примеры кода, вызывающие метод ReleaseBuffer , см. в следующих разделах:

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	audioclient.h

См. также раздел

IAudioClient::Initialize

Интерфейс IAudioRenderClient

IAudioRenderClient::GetBuffer

Поделиться через