Metodo IAudioRenderClient::GetBuffer (audioclient.h)

Articolo
02/26/2024

Recupera un puntatore allo spazio disponibile successivo nel buffer dell'endpoint di rendering in cui il chiamante può scrivere un pacchetto di dati.

Sintassi

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

Parametri

[in] NumFramesRequested

Numero di fotogrammi audio nel pacchetto di dati che il chiamante prevede di scrivere nello spazio richiesto nel buffer. Se la chiamata ha esito positivo, la dimensione dell'area del buffer a cui punta *ppData corrisponde alla dimensione specificata in NumFramesRequested.

[out] ppData

Puntatore a una variabile puntatore in cui il metodo scrive l'indirizzo iniziale dell'area del buffer in cui il chiamante scriverà il pacchetto di dati.

Valore restituito

Se il metodo ha esito positivo, viene restituito S_OK. Se ha esito negativo, i possibili codici restituiti includono, ma non sono limitati, i valori illustrati nella tabella seguente.

Codice restituito	Descrizione
AUDCLNT_E_BUFFER_ERROR	GetBuffer non è riuscito a recuperare un buffer di dati e *ppData punta a NULL. Per altre informazioni, vedere la sezione Osservazioni.
AUDCLNT_E_BUFFER_TOO_LARGE	Il valore NumFramesRequested supera lo spazio disponibile del buffer (dimensioni del buffer meno dimensioni di riempimento).
AUDCLNT_E_BUFFER_SIZE_ERROR	Il flusso è in modalità esclusiva e usa il buffering basato su eventi, ma il client ha tentato di ottenere un pacchetto che non era la dimensione del buffer.
AUDCLNT_E_OUT_OF_ORDER	Una chiamata IAudioRenderClient::GetBuffer precedente è ancora attiva.
AUDCLNT_E_DEVICE_INVALIDATED	Il dispositivo endpoint audio è stato scollegato oppure l'hardware audio o le risorse hardware associate sono state riconfigurate, disabilitate, rimosse o altrimenti non disponibili per l'uso.
AUDCLNT_E_BUFFER_OPERATION_PENDING	Impossibile accedere al buffer perché è in corso una reimpostazione del flusso.
AUDCLNT_E_SERVICE_NOT_RUNNING	Il servizio audio di Windows non è in esecuzione.
E_POINTER	Il parametro ppData è NULL.

Commenti

Il chiamante può richiedere una dimensione del pacchetto minore o uguale alla quantità di spazio disponibile nel buffer (tranne nel caso di un flusso in modalità esclusiva che usa il buffer basato su eventi. Per altre informazioni, vedere IAudioClient::Initialize). Lo spazio disponibile è semplicemente la dimensione del buffer meno la quantità di dati nel buffer già accodati fino a essere riprodotti. Se il chiamante specifica un valore NumFramesRequested che supera lo spazio disponibile nel buffer, la chiamata ha esito negativo e restituisce il codice di errore AUDCLNT_E_BUFFER_TOO_LARGE.

Il client è responsabile della scrittura di una quantità sufficiente di dati nel buffer per evitare che si verifichino errori nel flusso audio. Per altre informazioni sui requisiti di buffering, vedere IAudioClient::Initialize.

Dopo aver ottenuto un pacchetto di dati chiamando GetBuffer, il client riempie il pacchetto con i dati di rendering e rilascia il pacchetto al motore audio chiamando il metodo IAudioRenderClient::ReleaseBuffer .

Il client deve chiamare ReleaseBuffer dopo una chiamata GetBuffer che ottiene correttamente un pacchetto di qualsiasi dimensione diversa da 0. Il client ha la possibilità di chiamare o non chiamare ReleaseBuffer per rilasciare un pacchetto di dimensioni 0.

Per le dimensioni dei pacchetti diversi da zero, il client deve alternare le chiamate a GetBuffer e ReleaseBuffer. Ogni chiamata GetBuffer deve essere seguita da una chiamata ReleaseBuffer corrispondente. Dopo che il client ha chiamato GetBuffer per acquisire un pacchetto di dati, il client non può acquisire il pacchetto di dati successivo finché non ha chiamato ReleaseBuffer per rilasciare il pacchetto precedente. Due o più chiamate consecutive a GetBuffer o a ReleaseBuffer non sono consentite e avranno esito negativo con codice di errore AUDCLNT_E_OUT_OF_ORDER.

Per garantire l'ordinamento corretto delle chiamate, è necessario che venga eseguita una chiamata GetBuffer e la chiamata ReleaseBuffer corrispondente nello stesso thread.

Le dimensioni di un frame audio vengono specificate dal membro nBlockAlign della struttura WAVEFORMATEX ottenuta dal client chiamando il metodo IAudioClient::GetMixFormat .

Se il chiamante imposta NumFramesRequested = 0, il metodo restituisce il codice di stato S_OK ma non scrive nella variabile a cui punta il parametro ppData .

I client devono evitare ritardi eccessivi tra la chiamata GetBuffer che acquisisce un buffer e la chiamata ReleaseBuffer che rilascia il buffer. L'implementazione del motore audio presuppone che la chiamata GetBuffer e la chiamata ReleaseBuffer corrispondente vengano eseguite entro lo stesso periodo di elaborazione del buffer. I client che ritardano il rilascio di un buffer per più di un periodo rischiano di perdere i dati di esempio.

In Windows 7 GetBuffer può restituire il codice di errore AUDCLNT_E_BUFFER_ERROR per un client audio che usa il buffer dell'endpoint in modalità esclusiva. Questo errore indica che il buffer dei dati non è stato recuperato perché un pacchetto di dati non era disponibile (*ppData ha ricevuto NULL).

Se GetBuffer restituisce AUDCLNT_E_BUFFER_ERROR, il thread che utilizza gli esempi audio deve attendere il passaggio di elaborazione successivo. Il client potrebbe trarre vantaggio dalla conservazione di un conteggio delle chiamate GetBuffer non riuscite. Se GetBuffer restituisce ripetutamente questo errore, il client può avviare un nuovo ciclo di elaborazione dopo l'arresto del client corrente chiamando IAudioClient::Stop, IAudioClient::Reset e rilasciando il client audio.

Esempio

Per esempi di codice che chiamano il metodo GetBuffer , vedere gli argomenti seguenti:

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	audioclient.h