Método IAudioClock::GetPosition (audioclient.h)

  • Artigo

O método GetPosition obtém a posição atual do dispositivo.

Sintaxe

HRESULT GetPosition(
  [out] UINT64 *pu64Position,
  [out] UINT64 *pu64QPCPosition
);

Parâmetros

[out] pu64Position

Ponteiro para uma variável UINT64 na qual o método grava a posição do dispositivo. A posição do dispositivo é o deslocamento do início do fluxo para a posição atual no fluxo. No entanto, as unidades nas quais esse deslocamento é expresso são indefinidas— o valor da posição do dispositivo tem significado apenas em relação à frequência relatada pelo método IAudioClock::GetFrequency . 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 lê a posição do dispositivo (*pu64Position) em resposta à chamada GetPosition . O método converte o valor do contador em unidades de tempo 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.

Retornar valor

Se o método for bem-sucedido e obtiver uma leitura precisa da posição, ele retornará S_OK. Se o método for bem-sucedido, mas a duração da chamada for longa o suficiente para prejudicar a precisão da leitura da posição, o método retornará S_FALSE. 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
E_POINTER
 O parâmetro pu64Position é NULL.
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_SERVICE_NOT_RUNNING
 O serviço de áudio do Windows não está em execução.

Comentários

Renderizar ou capturar clientes que precisam expor um relógio com base na posição atual de reprodução ou registro do fluxo pode usar esse método para derivar esse relógio.

Esse método recupera dois valores de posição de fluxo correlacionados:

  • Posição do dispositivo. O cliente obtém a posição do dispositivo por meio do parâmetro de saída pu64Position. Essa é a posição de fluxo do exemplo que está sendo reproduzido nos alto-falantes (para um fluxo de renderização) ou sendo gravado por meio do microfone (para um fluxo de captura).
  • Contador de desempenho. O cliente obtém o contador de desempenho por meio do parâmetro de saída pu64QPCPosition. Esse é o valor do contador obtido pelo método chamando a função QueryPerformanceCounter no momento em que o dispositivo de ponto de extremidade de áudio registrou a posição do fluxo (*pu64Position). Observe que GetPosition converte o valor do contador em unidades de tempo de 100 nanossegundos.
A posição do dispositivo não tem sentido, a menos que seja combinada com a frequência do dispositivo relatada pelo método IAudioClock::GetFrequency . O motivo é que as unidades nas quais as posições do dispositivo para fluxos diferentes são expressas podem variar de acordo com fatores como se o fluxo foi aberto no modo compartilhado ou exclusivo. No entanto, a frequência f obtida de GetFrequency é sempre expressa em unidades compatíveis com as da posição do dispositivo p. Portanto, o deslocamento relativo do fluxo em segundos sempre pode ser calculado como p/f.

A posição do dispositivo é um deslocamento relativo ao fluxo. Ou seja, ele é especificado como um deslocamento do início do fluxo. A posição do dispositivo pode ser considerada como um deslocamento para um buffer idealizado que contém todo o fluxo e é contíguo do início ao fim.

Dada a posição do dispositivo e o contador de desempenho no momento da chamada getPosition , o cliente pode fornecer uma estimativa mais oportuna da posição do dispositivo em um momento ligeiramente posterior chamando QueryPerformanceCounter para obter o contador de desempenho atual e extrapolando a posição do dispositivo com base na distância que o contador avançou desde que a posição original do dispositivo foi registrada. O cliente pode chamar a função QueryPerformanceFrequency para determinar a frequência do relógio que incrementa o contador. Antes de comparar o valor bruto do contador obtido de QueryPerformanceCounter com o valor gravado em *pu64QPCPosition por GetPosition, converta o valor bruto do contador em unidades de tempo de 100 nanossegundos da seguinte maneira:

  1. Multiplique o valor bruto do contador por 10.000.000.
  2. Divida o resultado pela frequência de contador obtida de QueryPerformanceFrequency.
Para obter mais informações sobre QueryPerformanceCounter e QueryPerformanceFrequency, consulte a documentação do SDK do Windows.

Imediatamente após a criação de um novo fluxo, a posição do dispositivo é 0. Após uma chamada para o método IAudioClient::Start , a posição do dispositivo é incrementada a uma taxa uniforme. O método IAudioClient::Stop congela a posição do dispositivo e uma chamada Inicial subsequente faz com que a posição do dispositivo retome o incremento de seu valor no momento da chamada Parar . Uma chamada para IAudioClient::Reset, que só deve ocorrer enquanto o fluxo é interrompido, redefine a posição do dispositivo como 0.

Quando um fluxo de renderização novo ou redefinido começa a ser executado inicialmente, sua posição do dispositivo pode permanecer 0 por alguns milissegundos até que os dados de áudio tiveram tempo de propagar do buffer do ponto de extremidade para o dispositivo de ponto de extremidade de renderização. A posição do dispositivo muda de 0 para um valor diferente de zero quando os dados começam a ser reproduzidos pelo dispositivo.

Leituras sucessivas de dispositivos estão aumentando monotonicamente. Embora a posição do dispositivo possa não mudar entre duas leituras sucessivas, a posição do dispositivo nunca diminui de uma leitura para a outra.

O parâmetro pu64Position deve ser um ponteiro válido, não NULL ou o método falhará e retornará o código de erro E_POINTER.

As medidas de posição podem ocasionalmente ser atrasadas por eventos intermitentes de alta prioridade. Esses eventos podem não estar relacionados ao áudio. No caso de um fluxo de modo exclusivo, o método pode retornar S_FALSE em vez de S_OK se o método for bem-sucedido, mas a duração da chamada for longa o suficiente para prejudicar a precisão da posição relatada. Quando isso ocorre, o chamador tem a opção de chamar o método novamente para tentar recuperar uma posição mais precisa (conforme indicado pelo valor retornado S_OK). No entanto, o chamador deve evitar executar esse teste em um loop infinito caso o método retorne consistentemente S_FALSE.

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

Confira também

IAudioClient::Reset

IAudioClient::Start

IAudioClient::Stop

IAudioClock Interface

IAudioClock::GetFrequency