Метод IAudioCaptureClient::GetBuffer (audioclient.h)
Извлекает указатель на следующий доступный пакет данных в буфере конечной точки отслеживания.
Синтаксис
HRESULT GetBuffer(
[out] BYTE **ppData,
[out] UINT32 *pNumFramesToRead,
[out] DWORD *pdwFlags,
[out] UINT64 *pu64DevicePosition,
[out] UINT64 *pu64QPCPosition
);
Параметры
[out] ppData
Указатель на переменную указателя, в которую метод записывает начальный адрес следующего пакета данных, доступного для чтения клиентом.
[out] pNumFramesToRead
Указатель на переменную UINT32 , в которую метод записывает количество кадров (количество звуковых кадров, доступных в пакете данных). Клиент должен прочитать весь пакет данных или ни один из них.
[out] pdwFlags
Указатель на переменную DWORD , в которую метод записывает флаги состояния буфера. Метод записывает либо 0, либо побитовую или побитовую комбинацию одного или нескольких из следующих _AUDCLNT_BUFFERFLAGS значений перечисления:
AUDCLNT_BUFFERFLAGS_SILENT
AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY
AUDCLNT_BUFFERFLAGS_TIMESTAMP_ERROR
В Windows 7 и более поздних версиях ОС этот флаг можно использовать для обнаружения сбоев. Чтобы запустить поток записи, клиентское приложение должно вызвать IAudioClient::Start , а затем вызовы GetBuffer в цикле для чтения пакетов данных, пока не будут прочитаны все доступные пакеты в буфере конечной точки. GetBuffer задает флаг AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY, указывающий на сбой в буфере, на который указывает ppData.
[out] pu64DevicePosition
Указатель на переменную UINT64 , в которую метод записывает позицию устройства первого звукового кадра в пакете данных. Положение устройства выражается в виде количества звуковых кадров от начала потока. Этот параметр может иметь значение NULL , если клиенту не требуется расположение устройства. Дополнительные сведения см. в подразделе "Примечания".
[out] pu64QPCPosition
Указатель на переменную UINT64 , в которую метод записывает значение счетчика производительности во время записи устройством конечной точки аудио позиции первого звукового кадра в пакете данных. Метод преобразует значение счетчика в 100-наносекундные единицы, прежде чем записывать его в *pu64QPCPosition. Этот параметр может иметь значение NULL , если клиенту не требуется значение счетчика производительности. Дополнительные сведения см. в подразделе "Примечания".
Возвращаемое значение
Возможные коды возврата включают, но не ограничиваются ими, значения, приведенные в следующей таблице.
| Код возврата | Описание |
|---|---|
|
Вызов выполнен успешно, и параметр *pNumFramesToRead является ненулевой, что означает, что пакет готов к чтению. |
|
Вызов выполнен успешно, и значение *pNumFramesToRead равно 0, что указывает на отсутствие доступных данных записи для чтения. |
|
Windows 7 и более поздних версий: GetBuffer не удалось получить буфер данных, а *ppData указывает на NULL. Дополнительные сведения см. в подразделе "Примечания". |
|
Предыдущий вызов IAudioCaptureClient::GetBuffer по-прежнему действует. |
|
Устройство конечной точки звука было отключено, или звуковое оборудование или связанные аппаратные ресурсы были перенастроены, отключены, удалены или иным образом стали недоступными для использования. |
|
Доступ к буферу невозможен, так как выполняется сброс потока. |
|
Аудиослужба Windows не запущена. |
|
Параметр ppData, pNumFramesToRead или pdwFlags имеет значение NULL. |
Комментарии
Этот метод извлекает следующий пакет данных из буфера конечной точки отслеживания. В определенный момент буфер может содержать ноль, один или несколько пакетов, готовых к чтению. Как правило, поток обработки буфера, который считывает данные из буфера конечной точки отслеживания, считывает все доступные пакеты при каждом выполнении потока.
Во время обработки потока аудиозахвата клиентское приложение поочередо вызывает Метод GetBuffer и метод IAudioCaptureClient::ReleaseBuffer . Клиент может считывать не более одного пакета данных при каждом вызове GetBuffer . После каждого вызова GetBuffer клиент должен вызывать ReleaseBuffer , чтобы освободить пакет, прежде чем клиент сможет снова вызвать GetBuffer , чтобы получить следующий пакет.
Два или более последовательных вызова GetBuffer или ReleaseBuffer не допускаются и завершатся сбоем с кодом ошибки AUDCLNT_E_OUT_OF_ORDER. Чтобы обеспечить правильный порядок вызовов, вызов GetBuffer и соответствующий вызов ReleaseBuffer должны выполняться в одном потоке.
Во время каждого вызова GetBuffer вызывающий объект должен получить весь пакет или ни один из них. Перед чтением пакета вызывающий объект может проверка размер пакета (доступный через параметр pNumFramesToRead), чтобы убедиться, что в нем достаточно места для хранения всего пакета.
Во время каждого вызова ReleaseBuffer вызывающий сообщает количество аудиокадров, считываемых из буфера. Это число должно иметь размер пакета (ненулевого) или 0. Если номер равен 0, при следующем вызове GetBuffer вызывающий объект получит тот же пакет, что и в предыдущем вызове GetBuffer .
После каждого вызова GetBuffer данные в пакете остаются действительными до тех пор, пока следующий вызов ReleaseBuffer не освободит буфер.
Клиент должен вызвать ReleaseBuffer после вызова GetBuffer , который успешно получает пакет любого размера, кроме 0. Клиент может вызывать или не вызывать ReleaseBuffer для выпуска пакета размером 0.
Метод выводит позицию устройства и счетчик производительности с помощью выходных параметров pu64DevicePosition и pu64QPCPosition . Эти значения предоставляют метку времени для первого звукового кадра в пакете данных. С помощью выходного параметра pdwFlags метод указывает, является ли указанная позиция устройства допустимой.
Позиция устройства, которую метод записывает в *pu64DevicePosition , — это относительное положение звукового кадра, который в настоящее время воспроизводит динамики (для потока отрисовки) или записывается через микрофон (для потока захвата). Позиция выражается как количество кадров от начала потока. Размер кадра в аудиопотоке определяется элементом nBlockAlign структуры WAVEFORMATEX (или WAVEFORMATEXTENSIBLE), задающей формат потока. Размер звукового кадра в байтах равен количеству каналов в потоке, умноженным на размер выборки на канал. Например, для стереопотока (2-канальный) с 16-разрядными выборками размер кадра составляет четыре байта.
Значение счетчика производительности, которое GetBuffer записывает в *pu64QPCPosition , не является необработанным значением счетчика, полученным из функции QueryPerformanceCounter . Если t является необработанным значением счетчика, а f — частотой, полученной из функции QueryPerformanceFrequency , GetBuffer вычисляет значение счетчика производительности следующим образом:
*pu64QPCPosition = 10 000 000.T/F
Результат выражается в 100-наносекундных единицах. Дополнительные сведения о QueryPerformanceCounter и QueryPerformanceFrequency см. в документации по Windows SDK.
Если новый пакет в настоящее время недоступен, метод устанавливает *pNumFramesToRead = 0 и возвращает код состояния AUDCLNT_S_BUFFER_EMPTY. В этом случае метод не выполняет запись в переменные, на которые указывают параметры ppData, pu64DevicePosition и pu64QPCPosition .
Клиенты должны избегать чрезмерных задержек между вызовом 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, см. в разделе Захват Stream.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows Vista [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2008 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | audioclient.h |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по