Método IAudioRenderClient::GetBuffer (audioclient.h)
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 |
|---|---|
|
Falha de GetBuffer ao recuperar um buffer de dados e *ppData aponta para NULL. Para obter mais informações, consulte Comentários. |
|
O valor NumFramesRequested excede o espaço de buffer disponível (tamanho do buffer menos o tamanho do preenchimento). |
|
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. |
|
Uma chamada anterior de IAudioRenderClient::GetBuffer ainda está em vigor. |
|
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. |
|
O buffer não pode ser acessado porque uma redefinição de fluxo está em andamento. |
|
O serviço de áudio do Windows não está em execução. |
|
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 |