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

Article
02/23/2024

La méthode GetPosition obtient la position actuelle de l’appareil.

Syntaxe

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

Paramètres

[out] pu64Position

Pointeur vers une variable UINT64 dans laquelle la méthode écrit la position de l’appareil. La position de l’appareil est le décalage entre le début du flux et la position actuelle dans le flux. Toutefois, les unités dans lesquelles ce décalage est exprimé ne sont pas définies : la valeur de position de l’appareil a une signification uniquement par rapport à la fréquence signalée par la méthode IAudioClock ::GetFrequency . Pour plus d'informations, consultez la section Notes.

[out] pu64QPCPosition

Pointeur vers une variable UINT64 dans laquelle la méthode écrit la valeur du compteur de performances au moment où le périphérique de point de terminaison audio a lu la position de l’appareil (*pu64Position) en réponse à l’appel GetPosition . La méthode convertit la valeur du compteur en unités de temps de 100 nanosecondes avant de l’écrire dans *pu64QPCPosition. Ce paramètre peut être NULL si le client n’a pas besoin de la valeur du compteur de performances.

Valeur retournée

Si la méthode réussit et obtient une lecture précise de la position, elle retourne S_OK. Si la méthode réussit mais que la durée de l’appel est suffisamment longue pour nuire à la précision de la lecture de la position, la méthode retourne S_FALSE. En cas d’échec, les codes de retour possibles incluent, sans s’y limiter, les valeurs indiquées dans le tableau suivant.

Code de retour	Description
E_POINTER	Le paramètre pu64Position a la valeur NULL.
AUDCLNT_E_DEVICE_INVALIDATED	Le périphérique de point de terminaison audio a été débranché, ou le matériel audio ou les ressources matérielles associées ont été reconfigurés, désactivés, supprimés ou autrement rendus indisponibles.
AUDCLNT_E_SERVICE_NOT_RUNNING	Le service audio Windows n’est pas en cours d’exécution.

Remarques

Les clients de rendu ou de capture qui doivent exposer une horloge en fonction de la position actuelle de lecture ou d’enregistrement du flux peuvent utiliser cette méthode pour dériver cette horloge.

Cette méthode récupère deux valeurs corrélées de position de flux :

Position de l’appareil. Le client obtient la position de l’appareil via le paramètre de sortie pu64Position. Il s’agit de la position de flux de l’exemple qui est en cours de lecture sur les haut-parleurs (pour un flux de rendu) ou en cours d’enregistrement via le microphone (pour un flux de capture).
Compteur de performances. Le client obtient le compteur de performances via le paramètre de sortie pu64QPCPosition. Il s’agit de la valeur de compteur obtenue par la méthode en appelant la fonction QueryPerformanceCounter au moment où le périphérique de point de terminaison audio a enregistré la position du flux (*pu64Position). Notez que GetPosition convertit la valeur du compteur en unités de temps de 100 nanosecondes.

La position de l’appareil n’a aucun sens, sauf si elle est combinée avec la fréquence de l’appareil signalée par la méthode IAudioClock ::GetFrequency . La raison en est que les unités dans lesquelles les positions d’appareil pour différents flux sont exprimées peuvent varier en fonction de facteurs tels que l’ouverture du flux en mode partagé ou exclusif. Toutefois, la fréquence f obtenue à partir de GetFrequency est toujours exprimée en unités compatibles avec celles de la position de l’appareil p. Ainsi, le décalage relatif du flux en secondes peut toujours être calculé comme p/f.

La position de l’appareil est un décalage relatif de flux. Autrement dit, il est spécifié en tant que décalage par rapport au début du flux. La position de l’appareil peut être considérée comme un décalage dans une mémoire tampon idéalisée qui contient l’intégralité du flux et est contiguë du début à la fin.

Étant donné la position de l’appareil et le compteur de performances au moment de l’appel GetPosition , le client peut fournir une estimation plus rapide de la position de l’appareil un peu plus tard en appelant QueryPerformanceCounter pour obtenir le compteur de performances actuel et en extrapolant la position de l’appareil en fonction de l’avancée du compteur depuis l’enregistrement de la position d’origine de l’appareil. Le client peut appeler la fonction QueryPerformanceFrequency pour déterminer la fréquence de l’horloge qui incrémente le compteur. Avant de comparer la valeur de compteur brute obtenue à partir de QueryPerformanceCounter à la valeur écrite dans *pu64QPCPosition par GetPosition, convertissez la valeur du compteur brut en unités de temps de 100 nanosecondes comme suit :

Multipliez la valeur du compteur brut par 10 000 000.
Divisez le résultat par la fréquence de compteur obtenue à partir de QueryPerformanceFrequency.

Pour plus d’informations sur QueryPerformanceCounter et QueryPerformanceFrequency, consultez la documentation du Kit de développement logiciel (SDK) Windows.

Immédiatement après la création d’un flux, la position de l’appareil est 0. Après un appel à la méthode IAudioClient ::Start , la position de l’appareil s’incrémente à un taux uniforme. La méthode IAudioClient ::Stop fige la position de l’appareil, et un appel start suivant entraîne la reprise de l’incrémentation de la position de l’appareil par rapport à sa valeur au moment de l’appel Stop . Un appel à IAudioClient ::Reset, qui ne doit se produire que lorsque le flux est arrêté, réinitialise la position de l’appareil à 0.

Lorsqu’un flux de rendu nouveau ou réinitialisé commence à s’exécuter initialement, sa position de l’appareil peut rester 0 pendant quelques millisecondes jusqu’à ce que les données audio ont eu le temps de se propager de la mémoire tampon du point de terminaison vers le périphérique de point de terminaison de rendu. La position de l’appareil passe de 0 à une valeur différente de zéro lorsque les données commencent à être lues via l’appareil.

Les lectures successives des appareils augmentent de façon monotone. Bien que la position de l’appareil ne change pas entre deux lectures successives, la position de l’appareil ne diminue jamais d’une lecture à l’autre.

Le paramètre pu64Position doit être un pointeur non NULL valide, sinon la méthode échoue et retourne le code d’erreur E_POINTER.

Les mesures de position peuvent parfois être retardées par des événements intermittents de haute priorité. Ces événements peuvent ne pas être liés à l’audio. Dans le cas d’un flux en mode exclusif, la méthode peut retourner S_FALSE au lieu de S_OK si la méthode réussit, mais que la durée de l’appel est suffisamment longue pour nuire à la précision de la position signalée. Dans ce cas, l’appelant a la possibilité d’appeler à nouveau la méthode pour tenter de récupérer une position plus précise (comme indiqué par la valeur de retour S_OK). Toutefois, l’appelant doit éviter d’effectuer ce test dans une boucle infinie dans le cas où la méthode retourne systématiquement S_FALSE.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	audioclient.h