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

[out] pu64DevicePosition

Указатель на переменную UINT64 , в которую метод записывает положение устройства первого звукового кадра в пакете данных. Позиция устройства выражается как количество аудиокадров с начала потока. Этот параметр может иметь значение NULL , если клиенту не требуется положение устройства. Дополнительные сведения см. в разделе "Примечания".

[out] pu64QPCPosition

Указатель на переменную UINT64 , в которую метод записывает значение счетчика производительности в то время, когда устройство аудиоконечной точки записало положение устройства первого звукового кадра в пакете данных. Метод преобразует значение счетчика в 100-nanosecond единиц перед записью в *pu64QPCPosition. Этот параметр может иметь значение 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 . Если значение счетчика не является необработанным, и если значение f является частотой, полученной из функции QueryPerformanceFrequency , GetBuffer вычисляет значение счетчика производительности следующим образом:

*pu64QPCPosition = 10 000 000^.t/f

Результат выражается в 100-наносекундных единицах. Дополнительные сведения о QueryPerformanceCounter и QueryPerformanceFrequency см. в документации по пакету SDK для Windows.

Если новый пакет в настоящее время недоступен, метод задает *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 , см. в разделе "Запись потока".

Требования

См. также

Интерфейс IAudioCaptureClient

IAudioCaptureClient::ReleaseBuffer

IAudioClient::GetMixFormat

IAudioClock::GetPosition