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

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

Синтаксис

HRESULT GetBuffer(
  [in]  UINT32 NumFramesRequested,
  [out] BYTE   **ppData
);

Параметры

[in] NumFramesRequested

Количество звуковых кадров в пакете данных, которое вызывающий планирует записать в запрошенное пространство в буфере. Если вызов выполнен успешно, размер буферной области, на которую указывает *ppData , соответствует размеру, указанному в NumFramesRequested.

[out] ppData

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

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

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

Замечания

Вызывающий объект может запрашивать размер пакета, который меньше или равен объему доступного пространства в буфере (за исключением случаев потока монопольного режима, использующего буферизацию на основе событий; дополнительные сведения см. в разделе 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 , см. в следующих разделах:

• Отрисовка потока
• потокиExclusive-Mode

Требования

См. также

IAudioClient::GetBufferSize

IAudioClient::GetCurrentPadding

IAudioClient::Initialize

Интерфейс IAudioRenderClient

IAudioRenderClient::ReleaseBuffer