Метод 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 .

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

Для ненулевых размеров пакетов клиент должен чередовать вызовы GetBuffer и ReleaseBuffer. За каждым вызовом GetBuffer должен следовать соответствующий вызов ReleaseBuffer . После того как клиент вызовет GetBuffer для получения пакета данных, клиент не сможет получить следующий пакет данных, пока не вызовет ReleaseBuffer , чтобы освободить предыдущий пакет. Два или более последовательных вызова GetBuffer или ReleaseBuffer не допускаются и завершатся сбоем с кодом ошибки AUDCLNT_E_OUT_OF_ORDER.

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

Размер звукового кадра определяется элементом nBlockAlign структуры WAVEFORMATEX , которую клиент получает путем вызова метода IAudioClient::GetMixFormat .

Если вызывающий объект задает 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
Header	audioclient.h