IAudioRenderClient::GetBuffer-Methode (audioclient.h)

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

Syntax

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

Die 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

Zeigen Sie 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, enthalten mögliche Rückgabecodes, sind jedoch nicht beschränkt auf die in der folgenden Tabelle gezeigten Werte.

Bemerkungen

Der Aufrufer kann eine Paketgröße anfordern, die kleiner oder gleich der Menge des verfügbaren Speicherplatzes im Puffer ist (mit Ausnahme eines Exklusivmodusdatenstroms, 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 bereits für die Wiedergabe in die Warteschlange eingereiht ist. Wenn der Aufrufer einen NumFramesRequested-Wert angibt, der den verfügbaren Speicherplatz im Puffer überschreitet, schlägt der Aufruf fehl und gibt fehlercode AUDCLNT_E_BUFFER_TOO_LARGE zurück.

Der Client ist dafür verantwortlich, eine ausreichende Datenmenge in den Puffer zu schreiben, um zu verhindern, dass Im Audiodatenstrom Störungen auftreten. 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 das Audiomodul aus, indem die IAudioRenderClient::ReleaseBuffer-Methode aufgerufen wird.

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.

Bei Nichtzero-Paketgrößen muss der Client aufrufe von GetBuffer und ReleaseBuffer wechseln. Jedem GetBuffer-Aufruf muss ein entsprechender ReleaseBuffer-Aufruf folgen. Nachdem der Client GetBuffer zum Abrufen eines Datenpakets aufgerufen hat, kann der Client das nächste Datenpaket erst abrufen, wenn es ReleaseBuffer aufgerufen hat, um das vorherige Paket freizugeben. 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.

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

Wenn der Aufrufer NumFramesRequested = 0 festlegt, gibt die Methode den Statuscode 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 vermeiden, der einen Puffer abruft, und dem ReleaseBuffer-Aufruf , der den Puffer 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 Puffers für mehrere Perioden verzögern, riskant sind, dass Beispieldaten verloren gehen.

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, 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

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

• Rendern eines Datenstroms
• Exclusive-Mode Streams

Anforderungen

Siehe auch

IAudioClient::GetBufferSize

IAudioClient::GetCurrentPadding

IAudioClient::Initialize

IAudioRenderClient-Schnittstelle

IAudioRenderClient::ReleaseBuffer