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

Artículo
03/14/2023

El método GetPosition obtiene la posición actual del dispositivo.

Sintaxis

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

Parámetros

[out] pu64Position

Puntero a una variable UINT64 en la que el método escribe la posición del dispositivo. La posición del dispositivo es el desplazamiento desde el inicio de la secuencia hasta la posición actual de la secuencia. Sin embargo, las unidades en las que se expresa este desplazamiento no están definidas; el valor de posición del dispositivo solo tiene significado en relación con la frecuencia notificada por el método IAudioClock::GetFrequency . Para obtener más información, vea la sección Comentarios.

[out] pu64QPCPosition

Puntero a una variable UINT64 en la que el método escribe el valor del contador de rendimiento en el momento en que el dispositivo de punto de conexión de audio lee la posición del dispositivo (*pu64Position) en respuesta a la llamada GetPosition . El método convierte el valor del contador en unidades de tiempo de 100 nanosegundos antes de escribirlo en *pu64QPCPosition. Este parámetro puede ser NULL si el cliente no requiere el valor del contador de rendimiento.

Valor devuelto

Si el método se realiza correctamente y obtiene una lectura precisa de la posición, devuelve S_OK. Si el método se realiza correctamente, pero la duración de la llamada es lo suficientemente larga como para impedir la precisión de la lectura de la posición, el método devuelve S_FALSE. Si se produce un error, los códigos de retorno posibles incluyen, entre otros, los valores que se muestran en la tabla siguiente.

Código devuelto	Descripción
E_POINTER	El parámetro pu64Position es NULL.
AUDCLNT_E_DEVICE_INVALIDATED	El dispositivo de punto de conexión de audio se ha desconectado o el hardware de audio o los recursos de hardware asociados se han reconfigurado, deshabilitado, quitado o dejado de estar disponible para su uso.
AUDCLNT_E_SERVICE_NOT_RUNNING	El servicio de audio de Windows no se está ejecutando.

Comentarios

La representación o captura de clientes que necesitan exponer un reloj basado en la reproducción o posición de registro actual de la secuencia pueden usar este método para derivar ese reloj.

Este método recupera dos valores de posición de secuencia correlacionados:

Posición del dispositivo. El cliente obtiene la posición del dispositivo mediante el parámetro de salida pu64Position. Esta es la posición de secuencia del ejemplo que se está reproduciendo actualmente a través de los altavoces (para una secuencia de representación) o que se graba a través del micrófono (para una secuencia de captura).
Contador de rendimiento. El cliente obtiene el contador de rendimiento mediante el parámetro de salida pu64QPCPosition. Este es el valor del contador que obtuvo el método llamando a la función QueryPerformanceCounter en el momento en que el dispositivo de punto de conexión de audio grabó la posición de la secuencia (*pu64Position). Tenga en cuenta que GetPosition convierte el valor del contador en unidades de tiempo de 100 nanosegundos.

La posición del dispositivo es a menos que se combine con la frecuencia del dispositivo notificada por el método IAudioClock::GetFrequency . La razón es que las unidades en las que se expresan las posiciones del dispositivo para diferentes secuencias pueden variar según factores como si la secuencia se abrió en modo compartido o en modo exclusivo. Sin embargo, la frecuencia f obtenida de GetFrequency siempre se expresa en unidades que son compatibles con las de la posición del dispositivo p. Por lo tanto, el desplazamiento relativo a la secuencia en segundos siempre se puede calcular como p/f.

La posición del dispositivo es un desplazamiento relativo a la secuencia. Es decir, se especifica como un desplazamiento desde el principio de la secuencia. La posición del dispositivo se puede considerar como un desplazamiento en un búfer idealizado que contiene toda la secuencia y es contiguo de principio a fin.

Dado la posición del dispositivo y el contador de rendimiento en el momento de la llamada a GetPosition , el cliente puede proporcionar una estimación más oportuna de la posición del dispositivo en un momento ligeramente posterior llamando a QueryPerformanceCounter para obtener el contador de rendimiento actual y extrapolar la posición del dispositivo en función de la distancia que ha avanzado el contador desde que se registró la posición del dispositivo original. El cliente puede llamar a la función QueryPerformanceFrequency para determinar la frecuencia del reloj que incrementa el contador. Antes de comparar el valor del contador sin procesar obtenido de QueryPerformanceCounter con el valor escrito en *pu64QPCPosition por GetPosition, convierta el valor del contador sin formato en unidades de tiempo de 100 nanosegundos de la siguiente manera:

Multiplique el valor del contador sin formato en 10 000 000.
Divida el resultado por la frecuencia de contador obtenida de QueryPerformanceFrequency.

Para obtener más información sobre QueryPerformanceCounter y QueryPerformanceFrequency, consulte la documentación de Windows SDK.

Inmediatamente después de la creación de una nueva secuencia, la posición del dispositivo es 0. Después de una llamada al método IAudioClient::Start , la posición del dispositivo se incrementa a una velocidad uniforme. El método IAudioClient::Stop bloquea la posición del dispositivo y una llamada Start posterior hace que la posición del dispositivo reanude el incremento de su valor en el momento de la llamada Stop . Una llamada a IAudioClient::Reset, que solo debe producirse mientras se detiene la secuencia, restablece la posición del dispositivo a 0.

Cuando un flujo de representación nuevo o restablecido comienza a ejecutarse inicialmente, su posición del dispositivo puede permanecer 0 durante unos milisegundos hasta que los datos de audio han tenido tiempo de propagarse desde el búfer del punto de conexión al dispositivo de punto de conexión de representación. La posición del dispositivo cambia de 0 a un valor distinto de cero cuando los datos comienzan a reproducirse a través del dispositivo.

Las lecturas sucesivas de dispositivos aumentan de forma monotónica. Aunque es posible que la posición del dispositivo no cambie entre dos lecturas sucesivas, la posición del dispositivo nunca disminuye de una lectura a la siguiente.

El parámetro pu64Position debe ser un puntero válido que no sea NULL o el método producirá un error y devolverá el código de error E_POINTER.

Las medidas de posición pueden retrasarse ocasionalmente por eventos intermitentes de alta prioridad. Estos eventos pueden no estar relacionados con el audio. En el caso de una secuencia en modo exclusivo, el método puede devolver S_FALSE en lugar de S_OK si el método se realiza correctamente, pero la duración de la llamada es lo suficientemente larga como para impedir la precisión de la posición notificada. Cuando esto ocurre, el autor de la llamada tiene la opción de volver a llamar al método para intentar recuperar una posición más precisa (como se indica mediante el valor devuelto S_OK). Sin embargo, el autor de la llamada debe evitar realizar esta prueba en un bucle infinito en caso de que el método devuelva de forma coherente S_FALSE.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	audioclient.h