Метод IAudioClient::GetCurrentPadding (audioclient.h)

Статья
02/26/2024

Метод GetCurrentPadding извлекает количество кадров заполнения в буфере конечной точки.

Синтаксис

HRESULT GetCurrentPadding(
  [out] UINT32 *pNumPaddingFrames
);

Параметры

[out] pNumPaddingFrames

Указатель на переменную UINT32 , в которую метод записывает число кадров (количество звуковых кадров заполнения в буфере).

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

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

Код возврата	Описание
AUDCLNT_E_NOT_INITIALIZED	Аудиопоток не инициализирован.
AUDCLNT_E_DEVICE_INVALIDATED	Устройство конечной точки аудио отключено, звуковое оборудование или связанные аппаратные ресурсы были перенастроены, отключены, удалены или иным образом недоступны для использования.
AUDCLNT_E_SERVICE_NOT_RUNNING	Служба звука Windows не запущена.
E_POINTER	Параметр pNumPaddingFrames имеет значение NULL.

Этот метод требует предварительной инициализации интерфейса IAudioClient . Все вызовы этого метода будут завершаться ошибкой AUDCLNT_E_NOT_INITIALIZED до тех пор, пока клиент не инициализирует аудиопоток, вызвав метод IAudioClient::Initialize .

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

Значение заполнения выражается в виде нескольких звуковых кадров. Размер звукового кадра определяется элементом nBlockAlign структуры WAVEFORMATEX (или WAVEFORMATEXTENSIBLE), переданной клиентом методу IAudioClient::Initialize . Размер звукового кадра в байтах равен количеству каналов в потоке, умноженном на размер выборки для каждого канала. Например, размер кадра составляет четыре байта для стереопотока (2-канальный) с 16-разрядными выборками.

Для потока отрисовки общего режима значение заполнения, сообщаемое Командлетом GetCurrentPadding , указывает количество аудиокадров, которые помещаются в очередь для воспроизведения в буфере конечной точки. Перед записью в буфер конечной точки клиент может вычислить объем доступного пространства в буфере, вычитая значение заполнения из длины буфера. Чтобы обеспечить успешное выполнение последующего вызова метода IAudioRenderClient::GetBuffer , клиент должен запросить длину пакета, которая не превышает доступного пространства в буфере. Чтобы получить длину буфера, вызовите метод IAudioClient::GetBufferSize .

Для потока захвата общего режима значение заполнения, сообщаемое Командлетом GetCurrentPadding , указывает количество кадров данных записи, доступных в следующем пакете в буфере конечной точки. В определенный момент ноль, один или несколько пакетов данных записи могут быть готовы для клиента для чтения из буфера. Если пакеты в настоящее время недоступны, метод сообщает значение заполнения, равное 0. После вызова GetCurrentPadding вызов метода IAudioCaptureClient::GetBuffer извлекает пакет, длина которого точно равна значению заполнения, предоставленному GetCurrentPadding. Каждый вызов GetBuffer извлекает целый пакет. Пакет всегда содержит целое количество аудиокадров.

Для потока захвата общего режима вызов GetCurrentPadding эквивалентен вызову метода IAudioCaptureClient::GetNextPacketSize . То есть значение заполнения, сообщаемое Командлетом GetCurrentPadding , равно длине пакета, сообщаемой Командлетом GetNextPacketSize.

Для потока отрисовки или захвата в монопольном режиме, который был инициализирован с флагом AUDCLNT_STREAMFLAGS_EVENTCALLBACK, клиент обычно не использует значение заполнения, сообщаемое GetCurrentPadding. Вместо этого клиент обращается ко всему буферу во время каждого прохода обработки. Каждый раз, когда буфер становится доступным для обработки, звуковой модуль уведомляет клиента, сигнализируя дескриптор события клиента. Дополнительные сведения об этом флаге см. в разделе IAudioClient::Initialize.

Для потока отрисовки или захвата в монопольном режиме, который не был инициализирован с флагом AUDCLNT_STREAMFLAGS_EVENTCALLBACK, клиент может использовать значение заполнения, полученное из GetCurrentPadding , таким образом, как описано выше для потока общего режима. Ниже приведены подробные сведения.

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

Во-вторых, для потока захвата в монопольном режиме значение заполнения, сообщаемое GetCurrentPadding , указывает текущую длину следующего пакета. Однако это значение заполнения является snapshot длины пакета, которая может увеличиться, прежде чем клиент вызовет метод IAudioCaptureClient::GetBuffer. Таким образом, длина пакета, полученного GetBuffer , по крайней мере равна значению заполнения, полученному методом GetCurrentPadding , который предшествовал вызову GetBuffer . В отличие от этого, для потока захвата общего режима длина пакета, полученного из GetBuffer , всегда равна значению заполнения, сообщаемом предыдущим вызовом GetCurrentPadding .

Пример кода, который вызывает метод GetCurrentPadding, см. в разделе Отрисовка Stream.

Требования

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