IAudioCaptureClient::GetBuffer-Methode (audioclient.h)
Ruft einen Zeiger auf das nächste verfügbare Datenpaket im Erfassungsendpunktpuffer ab.
Syntax
HRESULT GetBuffer(
[out] BYTE **ppData,
[out] UINT32 *pNumFramesToRead,
[out] DWORD *pdwFlags,
[out] UINT64 *pu64DevicePosition,
[out] UINT64 *pu64QPCPosition
);
Parameter
[out] ppData
Zeiger auf eine Zeigervariable, in die die -Methode die Startadresse des nächsten Datenpakets schreibt, das für den Client zum Lesen verfügbar ist.
[out] pNumFramesToRead
Zeiger auf eine UINT32-Variable , in die die -Methode die Frameanzahl schreibt (die Anzahl der im Datenpaket verfügbaren Audioframes). Der Client sollte entweder das gesamte Datenpaket oder keines davon lesen.
[out] pdwFlags
Zeiger auf eine DWORD-Variable, in die die Methode die pufferbasierten status-Flags schreibt. Die -Methode schreibt entweder 0 oder die bitweise OR-Kombination aus einem oder mehreren der folgenden _AUDCLNT_BUFFERFLAGS Enumerationswerte:
AUDCLNT_BUFFERFLAGS_SILENT
AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY
AUDCLNT_BUFFERFLAGS_TIMESTAMP_ERROR
In Windows 7 und höheren Betriebssystemversionen kann dieses Flag für die Erkennung von Störungen verwendet werden. Um den Erfassungsdatenstrom zu starten, muss die Clientanwendung IAudioClient::Start aufrufen, gefolgt von Aufrufen von GetBuffer in einer Schleife, um Datenpakete zu lesen, bis alle verfügbaren Pakete im Endpunktpuffer gelesen wurden. GetBuffer legt das AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY-Flag fest, um einen Fehler im Puffer anzuzeigen, der von ppData zeigt.
[out] pu64DevicePosition
Zeiger auf eine UINT64-Variable , in die die -Methode die Geräteposition des ersten Audioframes im Datenpaket schreibt. Die Geräteposition wird als Anzahl der Audioframes vom Anfang des Datenstroms ausgedrückt. Dieser Parameter kann NULL sein, wenn der Client die Geräteposition nicht erfordert. Weitere Informationen finden Sie in den Hinweisen.
[out] pu64QPCPosition
Zeiger auf eine UINT64-Variable , in die die Methode den Wert des Leistungsindikators zu dem Zeitpunkt schreibt, zu dem das Audioendpunktgerät die Geräteposition des ersten Audioframes im Datenpaket aufgezeichnet hat. Die -Methode konvertiert den Zählerwert in 100 Nanosekundeneinheiten, bevor er in *pu64QPCPosition geschrieben wird. Dieser Parameter kann NULL sein, wenn der Client den Wert des Leistungsindikators nicht benötigt. Weitere Informationen finden Sie in den Hinweisen.
Rückgabewert
Mögliche Rückgabecodes sind unter anderem die in der folgenden Tabelle aufgeführten Werte.
| Rückgabecode | BESCHREIBUNG |
|---|---|
|
Der Aufruf war erfolgreich, und *pNumFramesToRead ist ungleich null, was angibt, dass ein Paket zum Lesen bereit ist. |
|
Der Aufruf war erfolgreich, und *pNumFramesToRead ist 0, was angibt, dass keine Erfassungsdaten zum Lesen verfügbar sind. |
|
Windows 7 und höher: GetBuffer konnte keinen Datenpuffer abrufen, und *ppData zeigt auf NULL. Weitere Informationen finden Sie in den Hinweisen. |
|
Ein vorheriger IAudioCaptureClient::GetBuffer-Aufruf ist weiterhin aktiv. |
|
Das Audioendpunktgerät wurde nicht angeschlossen, oder die Audiohardware oder die zugehörigen Hardwareressourcen wurden neu konfiguriert, deaktiviert, entfernt oder anderweitig nicht mehr verfügbar gemacht. |
|
Auf den Puffer kann nicht zugegriffen werden, da eine Datenstromzurücksetzung ausgeführt wird. |
|
Der Windows-Audiodienst wird nicht ausgeführt. |
|
Der Parameter ppData, pNumFramesToRead oder pdwFlags ist NULL. |
Hinweise
Diese Methode ruft das nächste Datenpaket aus dem Erfassungsendpunktpuffer ab. Zu einem bestimmten Zeitpunkt kann der Puffer 0, ein oder mehrere Pakete enthalten, die gelesen werden können. In der Regel liest ein Pufferverarbeitungsthread, der Daten aus einem Erfassungsendpunktpuffer liest, bei jeder Ausführung des Threads alle verfügbaren Pakete.
Während der Verarbeitung eines Audioaufnahmedatenstroms ruft die Clientanwendung abwechselnd GetBuffer und die IAudioCaptureClient::ReleaseBuffer-Methode auf. Der Client kann nicht mehr als ein einzelnes Datenpaket mit jedem GetBuffer-Aufruf lesen. Nach jedem GetBuffer-Aufruf muss der Client ReleaseBuffer aufrufen, um das Paket freizugeben, bevor der Client GetBuffer erneut aufrufen kann, um das nächste Paket zu erhalten.
Zwei oder mehr aufeinander folgende Aufrufe von GetBuffer oder ReleaseBuffer sind nicht zulässig und schlagen mit einem Fehlercode AUDCLNT_E_OUT_OF_ORDER fehl. Um die richtige Reihenfolge der Aufrufe sicherzustellen, müssen ein GetBuffer-Aufruf und der zugehörige ReleaseBuffer-Aufruf im selben Thread erfolgen.
Während jedes GetBuffer-Aufrufs muss der Aufrufer entweder das gesamte Paket oder keines davon abrufen. Vor dem Lesen des Pakets kann der Aufrufer die Paketgröße (verfügbar über den pNumFramesToRead-Parameter ) überprüfen, um sicherzustellen, dass genügend Platz zum Speichern des gesamten Pakets vorhanden ist.
Bei jedem ReleaseBuffer-Aufruf meldet der Aufrufer die Anzahl der Audioframes, die er aus dem Puffer liest. Diese Zahl muss entweder die Paketgröße (ungleich 0) oder 0 sein. Wenn die Zahl 0 ist, wird der Aufrufer beim nächsten GetBuffer-Aufruf mit demselben Paket wie im vorherigen GetBuffer-Aufruf angezeigt.
Nach jedem GetBuffer-Aufruf bleiben die Daten im Paket gültig, bis der nächste ReleaseBuffer-Aufruf den Puffer freigibt.
Der Client muss ReleaseBuffer nach einem GetBuffer-Aufruf aufrufen, der erfolgreich ein Paket einer anderen Größe als 0 abruft. Der Client hat die Möglichkeit, ReleaseBuffer aufzurufen oder nicht aufzurufen, um ein Paket der Größe 0 freizugeben.
Die -Methode gibt die Geräteposition und den Leistungsindikator über die Ausgabeparameter pu64DevicePosition und pu64QPCPosition aus. Diese Werte stellen einen Zeitstempel für den ersten Audioframe im Datenpaket bereit. Über den ausgabeparameter pdwFlags gibt die -Methode an, ob die gemeldete Geräteposition gültig ist.
Die Geräteposition, die die Methode in *pu64DevicePosition schreibt, ist die streamrelative Position des Audioframes, der derzeit über die Lautsprecher (für einen Renderingstream) wiedergegeben wird oder über das Mikrofon (für einen Aufnahmedatenstrom) aufgezeichnet wird. Die Position wird als Anzahl von Frames vom Anfang des Datenstroms ausgedrückt. Die Größe eines Frames in einem Audiostream wird durch den nBlockAlign-Member der WAVEFORMATEX-Struktur (oder WAVEFORMATEXTENSIBLE) angegeben, die das Streamformat angibt. Die Größe eines Audioframes in Byte entspricht der Anzahl von Kanälen im Stream multipliziert mit der Beispielgröße pro Kanal. Für einen Stereodatenstrom (2-Kanal) mit 16-Bit-Beispielen beträgt die Framegröße beispielsweise vier Bytes.
Der Leistungsindikatorwert, den GetBuffer in *pu64QPCPosition schreibt, ist nicht der unformatierte Zählerwert, der von der QueryPerformanceCounter-Funktion abgerufen wird. Wenn t der unformatierte Zählerwert ist und f die Häufigkeit ist, die von der QueryPerformanceFrequency-Funktion abgerufen wurde, berechnet GetBuffer den Leistungsindikatorwert wie folgt:
*pu64QPCPosition = 10.000.000.T/F
Das Ergebnis wird in 100 Nanosekundeneinheiten ausgedrückt. Weitere Informationen zu QueryPerformanceCounter und QueryPerformanceFrequency finden Sie in der Windows SDK-Dokumentation.
Wenn derzeit kein neues Paket verfügbar ist, legt die Methode *pNumFramesToRead = 0 fest und gibt status Code AUDCLNT_S_BUFFER_EMPTY zurück. In diesem Fall schreibt die -Methode nicht in die Variablen, auf die von den Parametern ppData, pu64DevicePosition und pu64QPCPosition verwiesen wird.
Clients sollten übermäßige Verzögerungen zwischen dem GetBuffer-Aufruf , der ein Paket abruft, und dem ReleaseBuffer-Aufruf vermeiden, der das Paket freigibt. Bei der Implementierung der Audio-Engine wird davon ausgegangen, dass der GetBuffer-Aufruf und der entsprechende ReleaseBuffer-Aufruf innerhalb desselben Pufferverarbeitungszeitraums erfolgen. Clients, die die Freigabe eines Pakets um mehr als einen Zeitraum verzögern, riskieren den Verlust von Beispieldaten.
In Windows 7 und höher kann GetBuffer den AUDCLNT_E_BUFFER_ERROR Fehlercode für einen Audioclient zurückgeben, der den Endpunktpuffer im exklusiven Modus verwendet. Dieser Fehler gibt an, dass der Datenpuffer nicht abgerufen wurde, weil ein Datenpaket nicht verfügbar war (*ppData hat NULL empfangen).
Wenn GetBufferAUDCLNT_E_BUFFER_ERROR zurückgibt, muss der Thread, der die Audiobeispiele nutzt, auf den nächsten Verarbeitungsdurchlauf warten. Der Client kann davon profitieren, die Anzahl der fehlgeschlagenen GetBuffer-Aufrufe beizubehalten. Wenn GetBuffer diesen Fehler wiederholt zurückgibt, kann der Client nach dem Herunterfahren des aktuellen Clients eine neue Verarbeitungsschleife starten, indem er IAudioClient::Stop, IAudioClient::Reset aufruft und den Audioclient freigibt.
Beispiele
Ein Codebeispiel, das die GetBuffer-Methode aufruft, finden Sie unter Erfassen einer Stream.
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 |
Weitere Informationen
IAudioCaptureClient-Schnittstelle