IAudioRenderClient::ReleaseBuffer-Methode (audioclient.h)

  • Artikel

Die ReleaseBuffer-Methode gibt den Pufferspeicher frei, der beim vorherigen Aufruf der IAudioRenderClient::GetBuffer-Methode abgerufen wurde.

Syntax

HRESULT ReleaseBuffer(
  [in] UINT32 NumFramesWritten,
  [in] DWORD  dwFlags
);

Parameter

[in] NumFramesWritten

Die Anzahl der Audioframes, die vom Client in das Datenpaket geschrieben werden. Der Wert dieses Parameters muss kleiner oder gleich der Größe des Datenpakets sein, wie im NumFramesRequested-Parameter angegeben, der an die IAudioRenderClient::GetBuffer-Methode übergeben wird.

[in] dwFlags

Die Pufferkonfigurationsflags. Der Aufrufer kann diesen Parameter entweder auf 0 oder auf den folgenden _AUDCLNT_BUFFERFLAGS Enumerationswert (ein Flagbit) festlegen:

AUDCLNT_BUFFERFLAGS_SILENT

Wenn dieses Flagbit festgelegt ist, behandelt die Audio-Engine das Datenpaket unabhängig von den im Paket enthaltenen Datenwerten so, als ob es Stille enthält. Durch dieses Flag muss der Client keine Stilledaten explizit in den Renderingpuffer schreiben.

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_INVALID_SIZE
 Der NumFramesWritten-Wert überschreitet den NumFramesRequested-Wert , der im vorherigen IAudioRenderClient::GetBuffer-Aufruf angegeben wurde.
AUDCLNT_E_BUFFER_SIZE_ERROR
 Der Stream ist exklusiver Modus und verwendet ereignisgesteuerte Pufferung, aber der Client hat versucht, ein Paket freizugeben, das nicht die Größe des Puffers hatte.
AUDCLNT_E_OUT_OF_ORDER
 Diesem Aufruf war kein entsprechender Aufruf von IAudioRenderClient::GetBuffer vorangestellt.
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.
E_INVALIDARG
 Der Parameter dwFlags ist kein gültiger Wert.

Hinweise

Der Client muss die gleiche Anzahl von Frames freigeben, die er beim vorherigen Aufruf der IAudioRenderClient::GetBuffer-Methode angefordert hat. Die einzige Ausnahme von dieser Regel besteht darin, dass der Client Immer ReleaseBuffer aufrufen kann, um 0 Frames freizugeben (es sei denn, der Stream ist exklusiver Modus und verwendet ereignisgesteuerte Pufferung).

Dieses Verhalten bietet dem Client eine bequeme Möglichkeit, ein zuvor angefordertes Paket der Länge 0 zu "freigeben". In diesem Fall ist der Aufruf von ReleaseBuffer optional. Nach dem Aufrufen von GetBuffer zum Abrufen eines Pakets der Länge 0 hat der Client die Möglichkeit , ReleaseBuffer nicht aufzurufen, bevor GetBuffer erneut aufgerufen wird.

Wenn der vorherige GetBuffer-Aufruf ein Paket mit nichtzero-Größe abgerufen hat, wird außerdem der Aufruf von ReleaseBuffer mit NumFramesRequested auf 0 erfolgreich ausgeführt (es sei denn, der Stream ist im exklusiven Modus und verwendet ereignisgesteuerte Pufferung). Die Bedeutung des Aufrufs besteht darin, dass der Client keine Daten in das Paket geschrieben hat, bevor es freigegeben wird. Daher behandelt die Methode den Teil des Puffers, der durch das Paket dargestellt wird, als nicht verwendet und stellt diesen Teil des Puffers beim nächsten GetBuffer-Aufruf wieder für den Client zur Verfügung.

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.

Codebeispiele, die die ReleaseBuffer-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

Weitere Informationen

IAudioClient::Initialize

IAudioRenderClient-Schnittstelle

IAudioRenderClient::GetBuffer