IAudioRenderClient::GetBuffer-Methode (audioclient.h)

Artikel
08/22/2023

Ruft einen Zeiger auf den nächsten verfügbaren Speicherplatz im Renderingendpunktpuffer ab, in den der Aufrufer ein Datenpaket schreiben kann.

Syntax

HRESULT GetBuffer(
  [in]  UINT32 NumFramesRequested,
  [out] BYTE   **ppData
);

Parameter

[in] NumFramesRequested

Die Anzahl der Audioframes im Datenpaket, die der Aufrufer in den angeforderten Speicherplatz im Puffer schreiben möchte. Wenn der Aufruf erfolgreich ist, entspricht die Größe des Pufferbereichs, auf den *ppData verweist, der in NumFramesRequested angegebenen Größe.

[out] ppData

Zeiger auf eine Zeigervariable, in die die -Methode die Startadresse des Pufferbereichs schreibt, in den der Aufrufer das Datenpaket schreibt.

Rückgabewert

Wenn die Methode erfolgreich ist, wird S_OK zurückgegeben. 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
AUDCLNT_E_BUFFER_ERROR	GetBuffer konnte keinen Datenpuffer abrufen und *ppData zeigt auf NULL. Weitere Informationen finden Sie in den Hinweisen.
AUDCLNT_E_BUFFER_TOO_LARGE	Der NumFramesRequested-Wert überschreitet den verfügbaren Pufferraum (Puffergröße minus Auffüllungsgröße).
AUDCLNT_E_BUFFER_SIZE_ERROR	Der Stream ist exklusiver Modus und verwendet ereignisgesteuerte Pufferung, aber der Client hat versucht, ein Paket abzurufen, das nicht die Größe des Puffers hatte.
AUDCLNT_E_OUT_OF_ORDER	Ein vorheriger IAudioRenderClient::GetBuffer-Aufruf ist weiterhin in Kraft.
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_BUFFER_OPERATION_PENDING	Auf Puffer kann nicht zugegriffen werden, da eine Streamzurücksetzung ausgeführt wird.
AUDCLNT_E_SERVICE_NOT_RUNNING	Der Windows-Audiodienst wird nicht ausgeführt.
E_POINTER	Der Parameter ppData ist NULL.

Hinweise

Der Aufrufer kann eine Paketgröße anfordern, die kleiner oder gleich dem verfügbaren Speicherplatz im Puffer ist (mit Ausnahme eines Datenstroms im exklusiven Modus, der ereignisgesteuerte Pufferung verwendet; weitere Informationen finden Sie unter IAudioClient::Initialize). Der verfügbare Speicherplatz ist einfach die Puffergröße abzüglich der Datenmenge im Puffer, die sich bereits in der Warteschlange befindet, um wiedergegeben zu werden. Wenn der Aufrufer einen NumFramesRequested-Wert angibt, der den verfügbaren Speicherplatz im Puffer überschreitet, schlägt der Aufruf fehl und gibt den Fehlercode AUDCLNT_E_BUFFER_TOO_LARGE zurück.

Der Client ist dafür verantwortlich, eine ausreichende Menge an Daten in den Puffer zu schreiben, um Störungen im Audiostream zu verhindern. Weitere Informationen zu Pufferanforderungen finden Sie unter IAudioClient::Initialize.

Nach dem Abrufen eines Datenpakets durch Aufrufen von GetBuffer füllt der Client das Paket mit Renderingdaten und gibt das Paket an die Audio-Engine aus, indem er die IAudioRenderClient::ReleaseBuffer-Methode aufruft.

Der Client muss ReleaseBuffer aufrufen, nachdem ein GetBuffer-Aufruf erfolgreich ein Paket einer anderen Größe als 0 abgerufen hat. Der Client kann ReleaseBuffer aufrufen oder nicht aufrufen, um ein Paket der Größe 0 freizugeben.

Bei nichtzero-Paketgrößen muss der Client getBuffer - und ReleaseBuffer-Aufrufe wechseln. Jedem GetBuffer-Aufruf muss ein entsprechender ReleaseBuffer-Aufruf folgen. Nachdem der Client GetBuffer aufgerufen hat, um ein Datenpaket abzurufen, kann der Client das nächste Datenpaket erst abrufen, wenn er ReleaseBuffer aufgerufen hat, um das vorherige Paket zu veröffentlichen. Zwei oder mehr 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 der Aufrufe sicherzustellen, müssen ein GetBuffer-Aufruf und der zugehörige ReleaseBuffer-Aufruf im selben Thread erfolgen.

Die Größe eines Audioframes wird durch das nBlockAlign-Element der WAVEFORMATEX-Struktur angegeben, das der Client durch Aufrufen der IAudioClient::GetMixFormat-Methode erhält.

Wenn der Aufrufer NumFramesRequested = 0 festlegt, gibt die Methode status Code S_OK zurück, schreibt aber nicht in die Variable, auf die der ppData-Parameter verweist.

Clients sollten übermäßige Verzögerungen zwischen dem GetBuffer-Aufruf , der einen Puffer abruft, und dem ReleaseBuffer-Aufruf vermeiden, der den Puffer 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 das Freigeben eines Puffers um mehr als einen Zeitraum verzögern, riskieren den Verlust von Beispieldaten.

In Windows 7 kann GetBuffer den AUDCLNT_E_BUFFER_ERROR Fehlercode für einen Audioclient zurückgeben, der den Endpunktpuffer im exklusiven Modus verwendet. Dieser Fehler weist darauf hin, 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, dass die Anzahl der fehlgeschlagenen GetBuffer-Aufrufe beibehalten wird. 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

Codebeispiele, die die GetBuffer-Methode aufrufen, finden Sie in den folgenden Themen:

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