Método IAudioClient::GetCurrentPadding (audioclient.h)

Artigo
08/22/2023

O método GetCurrentPadding recupera o número de quadros de preenchimento no buffer do ponto de extremidade.

Sintaxe

HRESULT GetCurrentPadding(
  [out] UINT32 *pNumPaddingFrames
);

Parâmetros

[out] pNumPaddingFrames

Ponteiro para uma variável UINT32 na qual o método grava a contagem de quadros (o número de quadros de áudio do preenchimento no buffer).

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_NOT_INITIALIZED	O fluxo de áudio não foi inicializado com êxito.
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 não estão disponíveis para uso.
AUDCLNT_E_SERVICE_NOT_RUNNING	O serviço de áudio do Windows não está em execução.
E_POINTER	O parâmetro pNumPaddingFrames é NULL.

Comentários

Esse método requer a inicialização prévia da interface IAudioClient . Todas as chamadas para esse método falharão com o erro AUDCLNT_E_NOT_INITIALIZED até que o cliente inicialize o fluxo de áudio chamando com êxito o método IAudioClient::Initialize .

Esse método recupera um valor de preenchimento que indica a quantidade de dados válidos e não lidos que o buffer de ponto de extremidade contém atualmente. Um aplicativo de renderização pode usar o valor de preenchimento para determinar quantos novos dados ele pode gravar com segurança no buffer do ponto de extremidade sem substituir dados gravados anteriormente que o mecanismo de áudio ainda não leu do buffer. Um aplicativo de captura pode usar o valor de preenchimento para determinar quantos novos dados ele pode ler com segurança do buffer do ponto de extremidade sem ler dados inválidos de uma região do buffer na qual o mecanismo de áudio ainda não gravou dados válidos.

O valor de preenchimento é expresso como uma série de quadros de áudio. O tamanho de um quadro de áudio é especificado pelo membro nBlockAlign da estrutura WAVEFORMATEX (ou WAVEFORMATEXTENSIBLE) que o cliente passou para o método IAudioClient::Initialize . O tamanho em bytes de um quadro de áudio é igual ao número de canais no fluxo multiplicado pelo tamanho de exemplo por canal. Por exemplo, o tamanho do quadro é de quatro bytes para um fluxo estéreo (2 canais) com amostras de 16 bits.

Para um fluxo de renderização de modo compartilhado, o valor de preenchimento relatado por GetCurrentPadding especifica o número de quadros de áudio enfileirados para reprodução no buffer do ponto de extremidade. Antes de gravar no buffer do ponto de extremidade, o cliente pode calcular a quantidade de espaço disponível no buffer subtraindo o valor de preenchimento do comprimento do buffer. Para garantir que uma chamada subsequente para o método IAudioRenderClient::GetBuffer seja bem-sucedida, o cliente deve solicitar um comprimento de pacote que não exceda o espaço disponível no buffer. Para obter o comprimento do buffer, chame o método IAudioClient::GetBufferSize .

Para um fluxo de captura de modo compartilhado, o valor de preenchimento relatado por GetCurrentPadding especifica o número de quadros de dados de captura disponíveis no próximo pacote no buffer do ponto de extremidade. Em um momento específico, zero, um ou mais pacotes de dados de captura podem estar prontos para o cliente ler do buffer. Se nenhum pacote estiver disponível no momento, o método relatará um valor de preenchimento igual a 0. Após a chamada GetCurrentPadding , uma chamada de método IAudioCaptureClient::GetBuffer recuperará um pacote cujo comprimento é exatamente igual ao valor de preenchimento relatado por GetCurrentPadding. Cada chamada para GetBuffer recupera um pacote inteiro. Um pacote sempre contém um número integral de quadros de áudio.

Para um fluxo de captura de modo compartilhado, chamar GetCurrentPadding é equivalente a chamar o método IAudioCaptureClient::GetNextPacketSize . Ou seja, o valor de preenchimento relatado por GetCurrentPadding é igual ao comprimento do pacote relatado por GetNextPacketSize.

Para um fluxo de renderização ou captura de modo exclusivo que foi inicializado com o sinalizador AUDCLNT_STREAMFLAGS_EVENTCALLBACK, o cliente normalmente não tem uso para o valor de preenchimento relatado por GetCurrentPadding. Em vez disso, o cliente acessa um buffer inteiro durante cada passagem de processamento. Sempre que um buffer fica disponível para processamento, o mecanismo de áudio notifica o cliente sinalizando o identificador de evento do cliente. Para obter mais informações sobre esse sinalizador, consulte IAudioClient::Initialize.

Para um fluxo de renderização ou captura de modo exclusivo que não foi inicializado com o sinalizador AUDCLNT_STREAMFLAGS_EVENTCALLBACK, o cliente pode usar o valor de preenchimento obtido de GetCurrentPadding de uma maneira semelhante à descrita anteriormente para um fluxo de modo compartilhado. Os detalhes são os seguintes.

Primeiro, para um fluxo de renderização de modo exclusivo, o valor de preenchimento especifica o número de quadros de áudio enfileirados para reprodução no buffer do ponto de extremidade. Como antes, o cliente pode calcular a quantidade de espaço disponível no buffer subtraindo o valor de preenchimento do comprimento do buffer.

Em segundo lugar, para um fluxo de captura de modo exclusivo, o valor de preenchimento relatado por GetCurrentPadding especifica o comprimento atual do próximo pacote. No entanto, esse valor de preenchimento é um instantâneo do comprimento do pacote, o que pode aumentar antes que o cliente chame o método IAudioCaptureClient::GetBuffer. Assim, o comprimento do pacote recuperado por GetBuffer é pelo menos tão grande quanto, mas pode ser maior do que o valor de preenchimento relatado pela chamada GetCurrentPadding que precedeu a chamada GetBuffer . Por outro lado, para um fluxo de captura de modo compartilhado, o comprimento do pacote obtido de GetBuffer sempre é igual ao valor de preenchimento relatado pela chamada GetCurrentPadding anterior.

Para obter um exemplo de código que chama o método GetCurrentPadding, consulte Renderizando 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