Metodo IAudioCaptureClient::GetBuffer (audioclient.h)
Recupera un puntatore al successivo pacchetto di dati disponibile nel buffer dell'endpoint di acquisizione.
Sintassi
HRESULT GetBuffer(
[out] BYTE **ppData,
[out] UINT32 *pNumFramesToRead,
[out] DWORD *pdwFlags,
[out] UINT64 *pu64DevicePosition,
[out] UINT64 *pu64QPCPosition
);
Parametri
[out] ppData
Puntatore a una variabile puntatore in cui il metodo scrive l'indirizzo iniziale del pacchetto di dati successivo disponibile per la lettura del client.
[out] pNumFramesToRead
Puntatore a una variabile UINT32 in cui il metodo scrive il numero di fotogrammi (il numero di fotogrammi audio disponibili nel pacchetto di dati). Il client deve leggere l'intero pacchetto di dati o nessuno di esso.
[out] pdwFlags
Puntatore a una variabile DWORD in cui il metodo scrive i flag di stato del buffer. Il metodo scrive 0 o la combinazione OR bit per bit di uno o più dei valori di enumerazione seguenti _AUDCLNT_BUFFERFLAGS :
AUDCLNT_BUFFERFLAGS_SILENT
AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY
AUDCLNT_BUFFERFLAGS_TIMESTAMP_ERROR
Nelle versioni di Windows 7 e versioni successive del sistema operativo questo flag può essere usato per il rilevamento degli errori. Per avviare il flusso di acquisizione, l'applicazione client deve chiamare IAudioClient::Start seguita da chiamate a GetBuffer in un ciclo per leggere i pacchetti di dati fino a quando non sono stati letti tutti i pacchetti disponibili nel buffer dell'endpoint. GetBuffer imposta il flag AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY per indicare un problema nel buffer a cui punta ppData.
[out] pu64DevicePosition
Puntatore a una variabile UINT64 in cui il metodo scrive la posizione del dispositivo del primo frame audio nel pacchetto di dati. La posizione del dispositivo viene espressa come numero di fotogrammi audio dall'inizio del flusso. Questo parametro può essere NULL se il client non richiede la posizione del dispositivo. Per altre informazioni, vedere la sezione Osservazioni.
[out] pu64QPCPosition
Puntatore a una variabile UINT64 in cui il metodo scrive il valore del contatore delle prestazioni al momento in cui il dispositivo endpoint audio ha registrato la posizione del dispositivo del primo fotogramma audio nel pacchetto di dati. Il metodo converte il valore del contatore in unità da 100 nanosecondi prima di scriverlo in *pu64QPCPosition. Questo parametro può essere NULL se il client non richiede il valore del contatore delle prestazioni. Per altre informazioni, vedere la sezione Osservazioni.
Valore restituito
I codici restituiti possibili includono, ma non sono limitati, i valori illustrati nella tabella seguente.
| Codice restituito | Descrizione |
|---|---|
|
La chiamata è riuscita e *pNumFramesToRead è diverso da zero, a indicare che un pacchetto è pronto per la lettura. |
|
La chiamata è riuscita e *pNumFramesToRead è 0, a indicare che non sono disponibili dati di acquisizione da leggere. |
|
Windows 7 e versioni successive: GetBuffer non è riuscito a recuperare un buffer di dati e *ppData punta a NULL. Per altre informazioni, vedere la sezione Osservazioni. |
|
Una chiamata IAudioCaptureClient::GetBuffer precedente è ancora attiva. |
|
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. |
|
Impossibile accedere al buffer perché è in corso una reimpostazione del flusso. |
|
Il servizio audio di Windows non è in esecuzione. |
|
Il parametro ppData, pNumFramesToRead o pdwFlags è NULL. |
Commenti
Questo metodo recupera il pacchetto di dati successivo dal buffer dell'endpoint di acquisizione. In un determinato momento, il buffer potrebbe contenere zero, uno o più pacchetti pronti per la lettura. In genere, un thread di elaborazione del buffer che legge i dati da un buffer dell'endpoint di acquisizione legge tutti i pacchetti disponibili ogni volta che viene eseguito il thread.
Durante l'elaborazione di un flusso di acquisizione audio, l'applicazione client chiama in alternativa GetBuffer e il metodo IAudioCaptureClient::ReleaseBuffer . Il client non può leggere più di un singolo pacchetto di dati con ogni chiamata GetBuffer . Dopo ogni chiamata GetBuffer , il client deve chiamare ReleaseBuffer per rilasciare il pacchetto prima che il client possa chiamare nuovamente GetBuffer per ottenere il pacchetto successivo.
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.
Durante ogni chiamata GetBuffer , il chiamante deve ottenere l'intero pacchetto o nessuno di esso. Prima di leggere il pacchetto, il chiamante può controllare le dimensioni del pacchetto (disponibili tramite il parametro pNumFramesToRead ) per assicurarsi che abbia spazio sufficiente per archiviare l'intero pacchetto.
Durante ogni chiamata ReleaseBuffer , il chiamante segnala il numero di fotogrammi audio letti dal buffer. Questo numero deve essere la dimensione del pacchetto (diverso da zero) o 0. Se il numero è 0, la chiamata GetBuffer successiva presenterà al chiamante lo stesso pacchetto della chiamata GetBuffer precedente.
Dopo ogni chiamata GetBuffer , i dati nel pacchetto rimangono validi fino a quando la chiamata ReleaseBuffer successiva rilascia il buffer.
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.
Il metodo restituisce la posizione del dispositivo e il contatore delle prestazioni tramite i parametri di output pu64DevicePosition e pu64QPCPosition . Questi valori forniscono un timestamp per il primo fotogramma audio nel pacchetto di dati. Tramite il parametro di output pdwFlags , il metodo indica se la posizione del dispositivo segnalata è valida.
La posizione del dispositivo che il metodo scrive in *pu64DevicePosition è la posizione relativa del flusso del fotogramma audio attualmente in riproduzione tramite gli altoparlanti (per un flusso di rendering) o registrata tramite il microfono (per un flusso di acquisizione). La posizione viene espressa come numero di fotogrammi dall'inizio del flusso. Le dimensioni di un frame in un flusso audio vengono specificate dal membro nBlockAlign della struttura WAVEFORMATEX (o WAVEFORMATEXTENSIBLE) che specifica il formato del flusso. Le dimensioni, in byte, di un frame audio equivalgono al numero di canali nel flusso moltiplicato per le dimensioni del campione per canale. Ad esempio, per un flusso stereo (a 2 canali) con campioni a 16 bit, le dimensioni dei fotogrammi sono quattro byte.
Il valore del contatore delle prestazioni scritto da GetBuffer in *pu64QPCPosition non è il valore del contatore non elaborato ottenuto dalla funzione QueryPerformanceCounter . Se t è il valore del contatore non elaborato e se f è la frequenza ottenuta dalla funzione QueryPerformanceFrequency , GetBuffer calcola il valore del contatore delle prestazioni come indicato di seguito:
*pu64QPCPosition = 10.000.000.T/F
Il risultato è espresso in unità di 100 nanosecondi. Per altre informazioni su QueryPerformanceCounter e QueryPerformanceFrequency, vedere la documentazione di Windows SDK.
Se non è attualmente disponibile alcun nuovo pacchetto, il metodo imposta *pNumFramesToRead = 0 e restituisce il codice di stato AUDCLNT_S_BUFFER_EMPTY. In questo caso, il metodo non scrive nelle variabili a cui puntano i parametri ppData, pu64DevicePosition e pu64QPCPosition .
I client devono evitare ritardi eccessivi tra la chiamata GetBuffer che acquisisce un pacchetto e la chiamata ReleaseBuffer che rilascia il pacchetto. 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 pacchetto per più di un periodo rischiano di perdere i dati di esempio.
In Windows 7 e versioni successive 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 di 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 un esempio di codice che chiama il metodo GetBuffer, vedere Acquisizione di un Stream.
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 |
Vedi anche
Interfaccia IAudioCaptureClient