Metodo IAudioClock::GetPosition (audioclient.h)

Articolo
02/26/2024

Il metodo GetPosition ottiene la posizione corrente del dispositivo.

Sintassi

HRESULT GetPosition(
  [out] UINT64 *pu64Position,
  [out] UINT64 *pu64QPCPosition
);

Parametri

[out] pu64Position

Puntatore a una variabile UINT64 in cui il metodo scrive la posizione del dispositivo. La posizione del dispositivo è l'offset dall'inizio del flusso alla posizione corrente nel flusso. Tuttavia, le unità in cui questo offset viene espresso non sono definite: il valore della posizione del dispositivo ha significato solo in relazione alla frequenza segnalata dal metodo IAudioClock::GetFrequency . 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 dell'endpoint audio legge la posizione del dispositivo (*pu64Position) in risposta alla chiamata GetPosition . Il metodo converte il valore del contatore in 100-nanosecondi prima di scriverlo in *pu64QPCPosition. Questo parametro può essere NULL se il client non richiede il valore del contatore delle prestazioni.

Valore restituito

Se il metodo ha esito positivo e ottiene una lettura accurata della posizione, restituisce S_OK. Se il metodo ha esito positivo, ma la durata della chiamata è abbastanza lunga per sottrarre l'accuratezza della lettura della posizione, il metodo restituisce S_FALSE. Se ha esito negativo, i codici restituiti possibili includono, ma non sono limitati a, i valori visualizzati nella tabella seguente.

Codice restituito	Descrizione
E_POINTER	Il parametro pu64Position è NULL.
AUDCLNT_E_DEVICE_INVALIDATED	Il dispositivo endpoint audio è stato scollegato o l'hardware audio o le risorse hardware associate sono state riconfigurate, disabilitate, rimosse o altrimenti non disponibili per l'uso.
AUDCLNT_E_SERVICE_NOT_RUNNING	Il servizio audio Di Windows non è in esecuzione.

Commenti

Il rendering o l'acquisizione dei client che devono esporre un orologio in base alla riproduzione o alla posizione del record corrente del flusso possono usare questo metodo per derivare tale orologio.

Questo metodo recupera due valori di posizione del flusso correlati:

Posizione del dispositivo. Il client ottiene la posizione del dispositivo tramite il parametro di output pu64Position. Si tratta della posizione del flusso dell'esempio attualmente riprodotto attraverso gli altoparlanti (per un flusso di rendering) o registrato tramite il microfono (per un flusso di acquisizione).
Contatore delle prestazioni. Il client ottiene il contatore delle prestazioni tramite il parametro di output pu64QPCPosition. Questo è il valore del contatore ottenuto chiamando la funzione QueryPerformanceCounter al momento in cui il dispositivo dell'endpoint audio ha registrato la posizione del flusso (*pu64Position). Si noti che GetPosition converte il valore del contatore in 100-nanosecondi.

La posizione del dispositivo non significa se non viene combinata con la frequenza del dispositivo segnalata dal metodo IAudioClock::GetFrequency . Il motivo è che le unità in cui le posizioni del dispositivo per flussi diversi possono variare in base a fattori come se il flusso è stato aperto in modalità condivisa o in modalità esclusiva. Tuttavia, la frequenza f ottenuta da GetFrequency è sempre espressa in unità compatibili con quelle della posizione del dispositivo p. Pertanto, l'offset relativo del flusso in secondi può sempre essere calcolato come p/f.

La posizione del dispositivo è un offset relativo al flusso. Ovvero, viene specificato come offset dall'inizio del flusso. La posizione del dispositivo può essere considerata come offset in un buffer idealizzato che contiene l'intero flusso ed è contiguo dall'inizio alla fine.

Dato la posizione del dispositivo e il contatore delle prestazioni al momento della chiamata GetPosition , il client può fornire una stima più tempestiva della posizione del dispositivo in un secondo momento chiamando QueryPerformanceCounter per ottenere il contatore delle prestazioni corrente ed estrapolando la posizione del dispositivo in base alla distanza avanzata del contatore dal momento in cui è stata registrata la posizione del dispositivo originale. Il client può chiamare la funzione QueryPerformanceFrequency per determinare la frequenza dell'orologio che incrementa il contatore. Prima di confrontare il valore del contatore non elaborato ottenuto da QueryPerformanceCounter al valore scritto in *pu64QPCPosition by GetPosition, convertire il valore del contatore non elaborato in unità di tempo a 100 nanosecondi come indicato di seguito:

Moltiplicare il valore del contatore non elaborato per 10.000.000.
Dividere il risultato in base alla frequenza del contatore ottenuta da QueryPerformanceFrequency.

Per altre informazioni su QueryPerformanceCounter e QueryPerformanceFrequency, vedere la documentazione di Windows SDK.

Immediatamente dopo la creazione di un nuovo flusso, la posizione del dispositivo è 0. Dopo una chiamata al metodo IAudioClient::Start , la posizione del dispositivo aumenta a una frequenza uniforme. Il metodo IAudioClient::Stop blocca la posizione del dispositivo e una chiamata Start successiva causa la ripresa della posizione del dispositivo dal relativo valore al momento della chiamata Stop . Una chiamata a IAudioClient::Reset, che deve verificarsi solo mentre il flusso viene arrestato, reimposta la posizione del dispositivo su 0.

Quando un flusso di rendering nuovo o reimpostato inizia inizialmente l'esecuzione, la posizione del dispositivo potrebbe rimanere 0 per alcuni millisecondi fino a quando i dati audio non hanno avuto il tempo di propagare dal buffer dell'endpoint al dispositivo dell'endpoint di rendering. La posizione del dispositivo cambia da 0 a un valore diverso da zero quando i dati iniziano a giocare attraverso il dispositivo.

Le letture successive del dispositivo aumentano monotonicamente. Anche se la posizione del dispositivo potrebbe non cambiare tra due letture successive, la posizione del dispositivo non diminuisce mai da una lettura alla successiva.

Il parametro pu64Position deve essere un puntatore non NULL valido o il metodo avrà esito negativo e restituirà il codice di errore E_POINTER.

Le misurazioni delle posizioni possono essere occasionalmente ritardate da eventi intermittenti e con priorità elevata. Questi eventi potrebbero non essere correlati all'audio. Nel caso di un flusso in modalità esclusiva, il metodo può restituire S_FALSE anziché S_OK se il metodo ha esito positivo, ma la durata della chiamata è abbastanza lunga per sottrarre l'accuratezza della posizione segnalata. In questo caso, il chiamante ha la possibilità di chiamare di nuovo il metodo per tentare di recuperare una posizione più accurata , come indicato dal valore restituito S_OK. Tuttavia, il chiamante deve evitare di eseguire questo test in un ciclo infinito nel caso in cui il metodo restituisce in modo coerente S_FALSE.

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