IAudioClock::GetPosition-Methode (audioclient.h)

Artikel
02/26/2024

Die GetPosition-Methode ruft die aktuelle Geräteposition ab.

Syntax

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

Parameter

[out] pu64Position

Zeiger auf eine UINT64-Variable , in die die -Methode die Geräteposition schreibt. Die Geräteposition ist der Offset vom Anfang des Datenstroms bis zur aktuellen Position im Stream. Die Einheiten, in denen dieser Offset ausgedrückt wird, sind jedoch nicht definiert. Der Wert der Geräteposition hat eine Bedeutung nur im Verhältnis zur Häufigkeit, die von der IAudioClock::GetFrequency-Methode gemeldet wird. Weitere Informationen finden Sie in den Hinweisen.

[out] pu64QPCPosition

Zeiger auf eine UINT64-Variable , in die die Methode den Wert des Leistungsindikators schreibt, wenn das Audioendpunktgerät die Geräteposition (*pu64Position) als Reaktion auf den GetPosition-Aufruf liest. Die Methode konvertiert den Zählerwert in 100 Nanosekunden-Zeiteinheiten, bevor er in *pu64QPCPosition geschrieben wird. Dieser Parameter kann NULL sein, wenn der Client den Leistungsindikatorwert nicht erfordert.

Rückgabewert

Wenn die Methode erfolgreich ist und einen genauen Wert der Position erhält, gibt sie S_OK zurück. Wenn die Methode erfolgreich ist, aber die Dauer des Aufrufs lang genug ist, um die Genauigkeit des Positionslesevorgangs zu beeinträchtigen, gibt die Methode S_FALSE zurück. Wenn ein Fehler auftritt, können mögliche Rückgabecodes die in der folgenden Tabelle gezeigten Werte umfassen, sind jedoch nicht darauf beschränkt.

Rückgabecode	Beschreibung
E_POINTER	Der Parameter pu64Position ist NULL.
AUDCLNT_E_DEVICE_INVALIDATED	Das Audioendpunktgerät wurde getrennt, oder die Audiohardware oder die zugehörigen Hardwareressourcen wurden neu konfiguriert, deaktiviert, entfernt oder anderweitig für die Verwendung nicht verfügbar gemacht.
AUDCLNT_E_SERVICE_NOT_RUNNING	Der Windows-Audiodienst wird nicht ausgeführt.

Hinweise

Render- oder Aufzeichnungsclients, die eine Uhr basierend auf der aktuellen Wiedergabe- oder Aufzeichnungsposition des Datenstroms verfügbar machen müssen, können diese Methode verwenden, um diese Uhr abzuleiten.

Diese Methode ruft zwei korrelierte Datenstrompositionswerte ab:

Geräteposition. Der Client ruft die Geräteposition über den Ausgabeparameter pu64Position ab. Dies ist die Streamposition des Beispiels, das derzeit über die Lautsprecher (für einen Renderingstream) wiedergegeben wird oder über das Mikrofon (für einen Aufzeichnungsstream) aufgezeichnet wird.
Leistungsindikator. Der Client ruft den Leistungsindikator über den Ausgabeparameter pu64QPCPosition ab. Dies ist der Zählerwert, den die Methode durch Aufrufen der QueryPerformanceCounter-Funktion zu dem Zeitpunkt abgerufen hat, zu dem das Audioendpunktgerät die Streamposition (*pu64Position) aufgezeichnet hat. Beachten Sie, dass GetPosition den Zählerwert in Zeiteinheiten von 100 Nanosekunden konvertiert.

Die Geräteposition ist bedeutungslos, es sei denn, sie wird mit der Gerätehäufigkeit kombiniert, die von der IAudioClock::GetFrequency-Methode gemeldet wird. Der Grund ist, dass die Einheiten, in denen die Gerätepositionen für verschiedene Streams ausgedrückt werden, je nach Faktoren variieren können, z. B. ob der Stream im freigegebenen Modus oder im exklusiven Modus geöffnet wurde. Die von GetFrequency erhaltene Häufigkeit f wird jedoch immer in Einheiten ausgedrückt, die mit denen der Geräteposition p kompatibel sind. Daher kann der streamrelative Offset in Sekunden immer als p/f berechnet werden.

Die Geräteposition ist ein streamrelativer Offset. Das heißt, es wird vom Anfang des Datenstroms als Offset angegeben. Die Geräteposition kann als Offset in einen idealisierten Puffer betrachtet werden, der den gesamten Datenstrom enthält und von Anfang bis Ende zusammenhängend ist.

Angesichts der Geräteposition und des Leistungsindikators zum Zeitpunkt des GetPosition-Aufrufs kann der Client eine zeitnahere Schätzung der Geräteposition zu einem etwas späteren Zeitpunkt bereitstellen, indem QueryPerformanceCounter aufgerufen wird, um den aktuellen Leistungsindikator abzurufen, und die Geräteposition basierend darauf extrapoliert, wie weit der Zähler seit der Aufzeichnung der ursprünglichen Geräteposition fortgeschritten ist. Der Client kann die QueryPerformanceFrequency-Funktion aufrufen, um die Häufigkeit der Uhr zu bestimmen, die den Zähler inkrementiert. Bevor Sie den rohen Zählerwert aus QueryPerformanceCounter mit dem wert vergleichen, der von GetPosition in *pu64QPCPosition geschrieben wurde, konvertieren Sie den rohen Zählerwert wie folgt in 100 Nanosekunden-Zeiteinheiten:

Multiplizieren Sie den Rohindikatorwert mit 10.000.000.
Dividieren Sie das Ergebnis durch die von QueryPerformanceFrequency abgerufene Zählerhäufigkeit.

Weitere Informationen zu QueryPerformanceCounter und QueryPerformanceFrequency finden Sie in der Dokumentation zum Windows SDK.

Unmittelbar nach der Erstellung eines neuen Datenstroms ist die Geräteposition 0. Nach einem Aufruf der IAudioClient::Start-Methode erhöht sich die Geräteposition mit einer gleichmäßigen Rate. Die IAudioClient::Stop-Methode friert die Geräteposition ein, und ein nachfolgender Start-Aufruf bewirkt, dass die Geräteposition zum Zeitpunkt des Beenden-Aufrufs die Inkrementierung des Werts fortsetzen kann. Ein Aufruf von IAudioClient::Reset, der nur erfolgen sollte, wenn der Stream beendet wird, setzt die Geräteposition auf 0 zurück.

Wenn ein neuer oder zurückgesetzter Renderingdatenstrom zunächst ausgeführt wird, kann seine Geräteposition für einige Millisekunden 0 bleiben, bis die Audiodaten Zeit hatten, vom Endpunktpuffer an das Renderingendpunktgerät zu verteilen. Die Geräteposition ändert sich von 0 in einen wert ohne Zero, wenn die Daten über das Gerät wiedergegeben werden.

Die aufeinanderfolgenden Gerätemessungen nehmen monoton zu. Obwohl sich die Geräteposition zwischen zwei aufeinanderfolgenden Messwerten möglicherweise nicht ändert, nimmt die Geräteposition nie von einem Lesevorgang zum nächsten ab.

Der pu64Position-Parameter muss ein gültiger Nicht-NULL-Zeiger sein, andernfalls schlägt die Methode fehl und gibt Fehlercode E_POINTER zurück.

Positionsmessungen können gelegentlich durch zeitweilige Ereignisse mit hoher Priorität verzögert werden. Diese Ereignisse haben möglicherweise nichts mit Audio zu tun. Im Fall eines Datenstroms im exklusiven Modus kann die Methode S_FALSE anstelle von S_OK zurückgeben, wenn die Methode erfolgreich ist, die Dauer des Aufrufs jedoch lang genug ist, um die Genauigkeit der gemeldeten Position zu beeinträchtigen. In diesem Fall hat der Aufrufer die Möglichkeit, die -Methode erneut aufzurufen, um zu versuchen, eine genauere Position abzurufen (wie durch den Rückgabewert S_OK angegeben). Der Aufrufer sollte jedoch vermeiden, diesen Test in einer Endlosschleife durchzuführen, falls die Methode konsistent S_FALSE zurückgibt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	audioclient.h