Método IAudioRenderClient::GetBuffer (audioclient.h)

Artigo
08/22/2023

Recupera um ponteiro para o próximo espaço disponível no buffer de ponto de extremidade de renderização no qual o chamador pode gravar um pacote de dados.

Sintaxe

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

Parâmetros

[in] NumFramesRequested

O número de quadros de áudio no pacote de dados que o chamador planeja gravar no espaço solicitado no buffer. Se a chamada for bem-sucedida, o tamanho da área de buffer apontada por *ppData corresponderá ao tamanho especificado em NumFramesRequested.

[out] ppData

Ponteiro para uma variável de ponteiro na qual o método grava o endereço inicial da área de buffer na qual o chamador gravará o pacote de dados.

Retornar valor

Se o método for bem-sucedido, retornará S_OK. Se falhar, os códigos de retorno possíveis incluem, mas não se limitam a, os valores mostrados na tabela a seguir.

Código de retorno	Descrição
AUDCLNT_E_BUFFER_ERROR	Falha de GetBuffer ao recuperar um buffer de dados e *ppData aponta para NULL. Para obter mais informações, consulte Comentários.
AUDCLNT_E_BUFFER_TOO_LARGE	O valor NumFramesRequested excede o espaço de buffer disponível (tamanho do buffer menos o tamanho do preenchimento).
AUDCLNT_E_BUFFER_SIZE_ERROR	O fluxo é um modo exclusivo e usa buffer controlado por eventos, mas o cliente tentou obter um pacote que não era do tamanho do buffer.
AUDCLNT_E_OUT_OF_ORDER	Uma chamada anterior de IAudioRenderClient::GetBuffer ainda está em vigor.
AUDCLNT_E_DEVICE_INVALIDATED	O dispositivo de ponto de extremidade de áudio foi desconectado ou o hardware de áudio ou os recursos de hardware associados foram reconfigurados, desabilitados, removidos ou indisponíveis para uso.
AUDCLNT_E_BUFFER_OPERATION_PENDING	O buffer não pode ser acessado porque uma redefinição de fluxo está em andamento.
AUDCLNT_E_SERVICE_NOT_RUNNING	O serviço de áudio do Windows não está em execução.
E_POINTER	O parâmetro ppData é NULL.

Comentários

O chamador pode solicitar um tamanho de pacote menor ou igual à quantidade de espaço disponível no buffer (exceto no caso de um fluxo de modo exclusivo que usa buffer controlado por eventos; para obter mais informações, consulte IAudioClient::Initialize). O espaço disponível é simplesmente o tamanho do buffer menos a quantidade de dados no buffer que já está enfileirado para ser reproduzido. Se o chamador especificar um valor NumFramesRequested que exceda o espaço disponível no buffer, a chamada falhará e retornará o código de erro AUDCLNT_E_BUFFER_TOO_LARGE.

O cliente é responsável por gravar uma quantidade suficiente de dados no buffer para evitar que falhas ocorram no fluxo de áudio. Para obter mais informações sobre os requisitos de buffer, consulte IAudioClient::Initialize.

Depois de obter um pacote de dados chamando GetBuffer, o cliente preenche o pacote com dados de renderização e emite o pacote para o mecanismo de áudio chamando o método IAudioRenderClient::ReleaseBuffer .

O cliente deve chamar ReleaseBuffer após uma chamada getBuffer que obtém com êxito um pacote de qualquer tamanho diferente de 0. O cliente tem a opção de chamar ou não chamar ReleaseBuffer para liberar um pacote de tamanho 0.

Para tamanhos de pacotes diferentes de zero, o cliente deve alternar chamadas para GetBuffer e ReleaseBuffer. Cada chamada getBuffer deve ser seguida por uma chamada releasebuffer correspondente. Depois que o cliente tiver chamado GetBuffer para adquirir um pacote de dados, o cliente não poderá adquirir o próximo pacote de dados até que tenha chamado ReleaseBuffer para liberar o pacote anterior. Duas ou mais chamadas consecutivas para GetBuffer ou releaseBuffer não são permitidas e falharão com o código de erro AUDCLNT_E_OUT_OF_ORDER.

Para garantir a ordenação correta de chamadas, uma chamada GetBuffer e sua chamada ReleaseBuffer correspondente devem ocorrer no mesmo thread.

O tamanho de um quadro de áudio é especificado pelo membro nBlockAlign da estrutura WAVEFORMATEX que o cliente obtém chamando o método IAudioClient::GetMixFormat .

Se o chamador definir NumFramesRequested = 0, o método retornará status código S_OK mas não gravará na variável para a qual o parâmetro ppData aponta.

Os clientes devem evitar atrasos excessivos entre a chamada GetBuffer que adquire um buffer e a chamada ReleaseBuffer que libera o buffer. A implementação do mecanismo de áudio pressupõe que a chamada getBuffer e a chamada releasebuffer correspondente ocorram dentro do mesmo período de processamento de buffer. Clientes que atrasam a liberação de um buffer por mais de um período correm o risco de perder dados de exemplo.

No Windows 7, o GetBuffer pode retornar o código de erro AUDCLNT_E_BUFFER_ERROR para um cliente de áudio que usa o buffer de ponto de extremidade no modo exclusivo. Esse erro indica que o buffer de dados não foi recuperado porque um pacote de dados não estava disponível (*ppData recebeu NULL).

Se GetBuffer retornar AUDCLNT_E_BUFFER_ERROR, o thread que consome os exemplos de áudio deverá aguardar a próxima passagem de processamento. O cliente pode se beneficiar de manter uma contagem das chamadas GetBuffer com falha. Se GetBuffer retornar esse erro repetidamente, o cliente poderá iniciar um novo loop de processamento depois de desligar o cliente atual chamando IAudioClient::Stop, IAudioClient::Reset e liberando o cliente de áudio.

Exemplos

Para obter exemplos de código que chamam o método GetBuffer , consulte os seguintes tópicos:

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	audioclient.h