IAudioCaptureClient::GetBuffer-Methode (audioclient.h)

Ruft einen Zeiger auf das nächste verfügbare Datenpaket im Aufnahmeendpunktpuffer ab.

Syntax

HRESULT GetBuffer(
  [out] BYTE   **ppData,
  [out] UINT32 *pNumFramesToRead,
  [out] DWORD  *pdwFlags,
  [out] UINT64 *pu64DevicePosition,
  [out] UINT64 *pu64QPCPosition
);

Die Parameter

[out] ppData

Zeigen Sie 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 Frameanzahl geschrieben wird (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 Pufferstatuskennzeichnungen 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

[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 Die 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 zum 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 Leistungsindikatorwert nicht erfordert. Weitere Informationen finden Sie in den Hinweisen.

Rückgabewert

Mögliche Rückgabecodes umfassen, sind jedoch nicht beschränkt auf die in der folgenden Tabelle gezeigten Werte.

Bemerkungen

Diese Methode ruft das nächste Datenpaket aus dem Aufnahmeendpunktpuffer ab. Zu einem bestimmten Zeitpunkt kann der Puffer null, ein oder mehrere Pakete enthalten, die zum Lesen bereit sind. In der Regel liest ein Pufferverarbeitungsthread, der Daten aus einem Erfassungsendpunktpuffer liest, alle verfügbaren Pakete jedes Mal, wenn der Thread ausgeführt wird.

Während der Verarbeitung eines Audioaufnahmedatenstroms ruft die Clientanwendung alternativ 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 abzurufen.

Mindestens zwei aufeinander folgende Aufrufe von GetBuffer oder ReleaseBuffer sind nicht zulässig und schlagen mit fehlercode AUDCLNT_E_OUT_OF_ORDER fehl. Um die richtige Reihenfolge von Anrufen sicherzustellen, muss ein GetBuffer-Aufruf und sein entsprechender ReleaseBuffer-Aufruf im selben Thread auftreten.

Bei jedem GetBuffer-Aufruf 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.

Während jedes ReleaseBuffer-Aufrufs meldet der Aufrufer die Anzahl der Audioframes, die er aus dem Puffer liest. Diese Zahl muss entweder die Paketgröße (nonzero) oder 0 sein. Wenn die Nummer 0 ist, zeigt der nächste GetBuffer-Aufruf den Anrufer mit demselben Paket wie im vorherigen GetBuffer-Aufruf an.

Nach jedem GetBuffer-Aufruf bleiben die Daten im Paket gültig, bis der nächste ReleaseBuffer-Aufruf den Puffer loslässt.

Der Client muss ReleaseBuffer nach einem GetBuffer-Aufruf aufrufen, der erfolgreich ein Paket mit 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 den Gerätepositions- und Leistungsindikator über die Ausgabeparameter pu64DevicePosition und pu64QPCPosition aus. Diese Werte stellen einen Zeitstempel für den ersten Audioframe im Datenpaket bereit. Über den pdwFlags-Ausgabeparameter 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 Renderingdatenstrom) wiedergegeben wird oder über das Mikrofon aufgezeichnet wird (für einen Aufnahmedatenstrom). Die Position wird als Die Anzahl der Frames vom Anfang des Datenstroms ausgedrückt. Die Größe eines Frames in einem Audiodatenstrom wird durch das nBlockAlign-Element der WAVEFORMATEX -Struktur (oder WAVEFORMATEXTENSIBLE) angegeben, die das Datenstromformat angibt. Die Größe eines Audioframes in Bytes entspricht der Anzahl der Kanäle im Datenstrom, die mit der Beispielgröße pro Kanal multipliziert werden. For example, for a stereo (2-channel) stream with 16-bit samples, the frame size is four bytes.

Der Leistungsindikatorwert, den GetBuffer in *pu64QPCPosition schreibt, ist nicht der rohe Leistungsindikatorwert, 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 wird, berechnet GetBuffer den Wert des Leistungsindikators 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 statuscode AUDCLNT_S_BUFFER_EMPTY zurück. In diesem Fall schreibt die Methode nicht in die Variablen, auf die durch die Parameter "ppData", "pu64DevicePosition" und "pu64QPCPosition" verwiesen wird.

Clients sollten übermäßige Verzögerungen zwischen dem GetBuffer-Aufruf vermeiden, der ein Paket abruft, und dem ReleaseBuffer-Aufruf , der das Paket freigibt. Bei der Implementierung des Audiomoduls wird davon ausgegangen, dass der GetBuffer-Aufruf und der entsprechende ReleaseBuffer-Aufruf innerhalb desselben Pufferverarbeitungszeitraums erfolgen. Clients, die das Freigeben eines Pakets für mehrere Perioden verzögern, riskant sind, dass Beispieldaten verloren gehen.

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, da ein Datenpaket nicht verfügbar war (*ppData received NULL).

Wenn GetBufferAUDCLNT_E_BUFFER_ERROR zurückgibt, muss der Thread, der die Audiobeispiele verwendet, 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 eine neue Verarbeitungsschleife starten, nachdem er den aktuellen Client beendet hat, indem er IAudioClient::Stop, IAudioClient::Reset aufruft und den Audioclient freigibt.

Examples

Ein Codebeispiel, das die GetBuffer-Methode aufruft, finden Sie unter Erfassen eines Datenstroms.

Anforderungen

Siehe auch

IAudioCaptureClient-Schnittstelle

IAudioCaptureClient::ReleaseBuffer

IAudioClient::GetMixFormat

IAudioClock::GetPosition