Método IAudioCaptureClient::GetBuffer (audioclient.h)
Recupera um ponteiro para o próximo pacote de dados disponível no buffer do ponto de extremidade de captura.
Sintaxe
HRESULT GetBuffer(
[out] BYTE **ppData,
[out] UINT32 *pNumFramesToRead,
[out] DWORD *pdwFlags,
[out] UINT64 *pu64DevicePosition,
[out] UINT64 *pu64QPCPosition
);
Parâmetros
[out] ppData
Ponteiro para uma variável de ponteiro na qual o método grava o endereço inicial do próximo pacote de dados que está disponível para o cliente ler.
[out] pNumFramesToRead
Ponteiro para uma variável UINT32 na qual o método grava a contagem de quadros (o número de quadros de áudio disponíveis no pacote de dados). O cliente deve ler o pacote de dados inteiro ou nenhum deles.
[out] pdwFlags
Ponteiro para uma variável DWORD na qual o método grava os sinalizadores de status buffer. O método grava 0 ou a combinação bit a bit-OR de um ou mais dos seguintes valores de enumeração _AUDCLNT_BUFFERFLAGS :
AUDCLNT_BUFFERFLAGS_SILENT
AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY
AUDCLNT_BUFFERFLAGS_TIMESTAMP_ERROR
No Windows 7 e versões posteriores do sistema operacional, esse sinalizador pode ser usado para detecção de falhas. Para iniciar o fluxo de captura, o aplicativo cliente deve chamar IAudioClient::Start seguido de chamadas para GetBuffer em um loop para ler pacotes de dados até que todos os pacotes disponíveis no buffer do ponto de extremidade sejam lidos. GetBuffer define o sinalizador AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY para indicar uma falha no buffer apontado por ppData.
[out] pu64DevicePosition
Ponteiro para uma variável UINT64 na qual o método grava a posição do dispositivo do primeiro quadro de áudio no pacote de dados. A posição do dispositivo é expressa como o número de quadros de áudio desde o início do fluxo. Esse parâmetro poderá ser NULL se o cliente não exigir a posição do dispositivo. Para obter mais informações, consulte Comentários.
[out] pu64QPCPosition
Ponteiro para uma variável UINT64 na qual o método grava o valor do contador de desempenho no momento em que o dispositivo de ponto de extremidade de áudio registrou a posição do dispositivo do primeiro quadro de áudio no pacote de dados. O método converte o valor do contador em unidades de 100 nanossegundos antes de escrevê-lo em *pu64QPCPosition. Esse parâmetro poderá ser NULL se o cliente não exigir o valor do contador de desempenho. Para obter mais informações, consulte Comentários.
Retornar valor
Os possíveis códigos de retorno incluem, mas não se limitam a, os valores mostrados na tabela a seguir.
| Código de retorno | Descrição |
|---|---|
|
A chamada foi bem-sucedida e *pNumFramesToRead não é zero, indicando que um pacote está pronto para ser lido. |
|
A chamada foi bem-sucedida e *pNumFramesToRead é 0, indicando que nenhum dado de captura está disponível para leitura. |
|
Windows 7 e posteriores: o GetBuffer não conseguiu recuperar um buffer de dados e *ppData aponta para NULL. Para obter mais informações, consulte Comentários. |
|
Uma chamada anterior de IAudioCaptureClient::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 não estão disponí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, pNumFramesToRead ou pdwFlags é NULL. |
Comentários
Esse método recupera o próximo pacote de dados do buffer de ponto de extremidade de captura. Em um determinado momento, o buffer pode conter zero, um ou mais pacotes prontos para leitura. Normalmente, um thread de processamento de buffer que lê dados de um buffer de ponto de extremidade de captura lê todos os pacotes disponíveis sempre que o thread é executado.
Durante o processamento de um fluxo de captura de áudio, o aplicativo cliente alternadamente chama GetBuffer e o método IAudioCaptureClient::ReleaseBuffer . O cliente não pode ler mais do que um único pacote de dados com cada chamada getBuffer . Após cada chamada de GetBuffer , o cliente deve chamar ReleaseBuffer para liberar o pacote antes que o cliente possa chamar GetBuffer novamente para obter o próximo pacote.
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 de ReleaseBuffer correspondente devem ocorrer no mesmo thread.
Durante cada chamada do GetBuffer , o chamador deve obter o pacote inteiro ou nenhum deles. Antes de ler o pacote, o chamador pode marcar o tamanho do pacote (disponível por meio do parâmetro pNumFramesToRead) para garantir que ele tenha espaço suficiente para armazenar todo o pacote.
Durante cada chamada do ReleaseBuffer , o chamador relata o número de quadros de áudio que leu do buffer. Esse número deve ser o tamanho do pacote (diferente de zero) ou 0. Se o número for 0, a próxima chamada getbuffer apresentará ao chamador o mesmo pacote que na chamada getbuffer anterior.
Após cada chamada de GetBuffer , os dados no pacote permanecem válidos até que a próxima chamada releaseBuffer libere o buffer.
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.
O método gera a posição do dispositivo e o contador de desempenho por meio dos parâmetros de saída pu64DevicePosition e pu64QPCPosition . Esses valores fornecem um carimbo de data/hora para o primeiro quadro de áudio no pacote de dados. Por meio do parâmetro de saída pdwFlags , o método indica se a posição do dispositivo relatada é válida.
A posição do dispositivo que o método grava em *pu64DevicePosition é a posição relativa ao fluxo do quadro de áudio que está sendo reproduzido atualmente pelos alto-falantes (para um fluxo de renderização) ou sendo gravado por meio do microfone (para um fluxo de captura). A posição é expressa como o número de quadros desde o início do fluxo. O tamanho de um quadro em um fluxo de áudio é especificado pelo membro nBlockAlign da estrutura WAVEFORMATEX (ou WAVEFORMATEXTENSIBLE) que especifica o formato de fluxo. O tamanho, em bytes, de um quadro de áudio é igual ao número de canais no fluxo multiplicado pelo tamanho da amostra por canal. Por exemplo, para um fluxo estéreo (2 canais) com amostras de 16 bits, o tamanho do quadro é de quatro bytes.
O valor do contador de desempenho que GetBuffer grava em *pu64QPCPosition não é o valor bruto do contador obtido da função QueryPerformanceCounter . Se t for o valor bruto do contador e se f for a frequência obtida da função QueryPerformanceFrequency , GetBuffer calculará o valor do contador de desempenho da seguinte maneira:
*pu64QPCPosition = 10.000.000.T/F
O resultado é expresso em unidades de 100 nanossegundos. Para obter mais informações sobre QueryPerformanceCounter e QueryPerformanceFrequency, consulte a documentação do SDK do Windows.
Se nenhum novo pacote estiver disponível no momento, o método definirá *pNumFramesToRead = 0 e retornará status código AUDCLNT_S_BUFFER_EMPTY. Nesse caso, o método não grava nas variáveis apontadas pelos parâmetros ppData, pu64DevicePosition e pu64QPCPosition .
Os clientes devem evitar atrasos excessivos entre a chamada GetBuffer que adquire um pacote e a chamada ReleaseBuffer que libera o pacote. A implementação do mecanismo de áudio pressupõe que a chamada GetBuffer e a chamada de ReleaseBuffer correspondente ocorram no mesmo período de processamento de buffer. Os clientes que atrasam a liberação de um pacote por mais de um período correm o risco de perder dados de exemplo.
No Windows 7 e posteriores, 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 um exemplo de código que chama o método GetBuffer, consulte Capturando um Stream.
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 |