Frequenza fotogrammi

L'API Frame Rate consente alle app di informare la piattaforma Android della frequenza fotogrammi prevista ed è disponibile per le app che hanno come target Android 11 (livello API 30) o versioni successive. In genere, la maggior parte dei dispositivi supporta una sola frequenza di aggiornamento del display, solitamente 60 Hz, ma la situazione sta cambiando. Molti dispositivi ora supportano frequenze di aggiornamento aggiuntive, come 90 Hz o 120 Hz. Alcuni dispositivi supportano i cambi di frequenza di aggiornamento senza interruzioni, mentre altri mostrano brevemente una schermata nera, che di solito dura un secondo.

Lo scopo principale dell'API è consentire alle app di sfruttare meglio tutte le frequenze di aggiornamento del display supportate. Ad esempio, un'app che riproduce un video a 24 Hz che chiama setFrameRate() potrebbe comportare la modifica della frequenza di aggiornamento del display da 60 Hz a 120 Hz da parte del dispositivo. Questa nuova frequenza di aggiornamento consente una riproduzione fluida e senza tremolii dei video a 24 Hz, senza la necessità di un pulldown 3:2, come sarebbe necessario per riprodurre lo stesso video su un display a 60 Hz. In questo modo, l'esperienza utente è migliore.

Utilizzo di base

Android offre diversi modi per accedere e controllare le schermate, quindi esistono diverse versioni dell'API setFrameRate(). Ogni versione dell'API accetta gli stessi parametri e funziona allo stesso modo delle altre:

L'app non deve considerare le frequenze di aggiornamento del display effettivamente supportate, che possono essere ottenute chiamando Display.getSupportedModes(), per chiamare setFrameRate() in sicurezza. Ad esempio, anche se il dispositivo supporta solo 60 Hz, chiama setFrameRate() con la frequenza fotogrammi preferita dalla tua app. I dispositivi che non hanno una corrispondenza migliore per la frequenza fotogrammi dell'app manterranno la frequenza di aggiornamento del display corrente.

Per verificare se una chiamata a setFrameRate() comporta una modifica della frequenza di aggiornamento del display, registrati per ricevere notifiche di modifica del display chiamando DisplayManager.registerDisplayListener() o AChoreographer_registerRefreshRateCallback().

Quando chiami setFrameRate(), è meglio passare la frequenza fotogrammi esatta anziché arrotondarla a un numero intero. Ad esempio, durante il rendering di un video registrato a 29,97 Hz, passa 29,97 anziché arrotondare a 30.

Per le app video, il parametro di compatibilità passato a setFrameRate() deve essere impostato su Surface.FRAME_RATE_COMPATIBILITY_FIXED_SOURCE per fornire un suggerimento aggiuntivo alla piattaforma Android che l'app utilizzerà il pulldown per adattarsi a una frequenza di aggiornamento del display non corrispondente (che comporterà un tremolio).

In alcuni scenari, la superficie video interromperà l'invio di frame, ma rimarrà visibile sullo schermo per un po' di tempo. Gli scenari più comuni includono quando la riproduzione raggiunge la fine del video o quando l'utente la mette in pausa. In questi casi, chiama setFrameRate() con il parametro della frequenza fotogrammi impostato su 0 per ripristinare il valore predefinito dell'impostazione della frequenza fotogrammi della superficie. La cancellazione dell'impostazione della frequenza fotogrammi come questa non è necessaria quando si distrugge la superficie o quando la superficie è nascosta perché l'utente passa a un'altra app. Cancella l'impostazione della frequenza fotogrammi solo quando la superficie rimane visibile senza essere utilizzata.

Cambio della frequenza fotogrammi non fluido

Su alcuni dispositivi, il passaggio alla frequenza di aggiornamento potrebbe presentare interruzioni visive, ad esempio una schermata nera per un secondo o due. In genere, questo accade su set-top box, pannelli TV e dispositivi simili. Per impostazione predefinita, il framework Android non cambia modalità quando viene chiamata l'API Surface.setFrameRate(), per evitare queste interruzioni visive.

Alcuni utenti preferiscono un'interruzione visiva all'inizio e alla fine dei video più lunghi. In questo modo, la frequenza di aggiornamento del display corrisponde alla frequenza fotogrammi del video ed evita artefatti di conversione della frequenza fotogrammi, come il judder del pulldown 3:2 per la riproduzione di film.

Per questo motivo, i cambi di frequenza di aggiornamento non fluidi possono essere attivati se sia l'utente sia le app eseguono l'attivazione:

Ti consigliamo di utilizzare sempre CHANGE_FRAME_RATE_ALWAYS per i video di lunga durata, come i film. Questo perché il vantaggio di abbinare la frequenza fotogrammi del video supera l'interruzione che si verifica quando si modifica la frequenza di aggiornamento.

Altri consigli

Segui questi consigli per gli scenari comuni.

Più piattaforme

La piattaforma Android è progettata per gestire correttamente gli scenari in cui sono presenti più piattaforme con impostazioni di frequenza fotogrammi diverse. Quando la tua app ha più superfici con frequenze fotogrammi diverse, chiama setFrameRate() con la frequenza fotogrammi corretta per ogni superficie. Anche se il dispositivo esegue più app contemporaneamente, utilizzando la modalità schermo diviso o Picture in picture, ogni app può chiamare setFrameRate() in sicurezza per le proprie piattaforme.

La piattaforma non cambia la frequenza fotogrammi dell'app

Anche se il dispositivo supporta la frequenza fotogrammi specificata dall'app in una chiamata a setFrameRate(), in alcuni casi il dispositivo non cambia la frequenza di aggiornamento del display. Ad esempio, una superficie con priorità più alta potrebbe avere un'impostazione della frequenza fotogrammi diversa oppure il dispositivo potrebbe essere in modalità di risparmio energetico (impostando una limitazione della frequenza di aggiornamento del display per preservare la batteria). L'app deve comunque funzionare correttamente quando il dispositivo non cambia la frequenza di aggiornamento del display in base all'impostazione della frequenza fotogrammi dell'app, anche se il dispositivo cambia in circostanze normali.

Spetta all'app decidere come rispondere quando la frequenza di aggiornamento del display non corrisponde alla frequenza fotogrammi dell'app. Per i video, la frequenza fotogrammi è fissa su quella del video di origine e sarà necessario il pulldown per mostrare i contenuti video. Un gioco potrebbe invece scegliere di provare a funzionare alla frequenza di aggiornamento del display anziché mantenere la frequenza fotogrammi preferita. L'app non deve modificare il valore che passa a setFrameRate() in base alle azioni della piattaforma. Deve rimanere impostata sulla frequenza fotogrammi preferita dell'app, indipendentemente da come l'app gestisce i casi in cui la piattaforma non si adatta alla richiesta dell'app. In questo modo, se le condizioni del dispositivo cambiano per consentire l'utilizzo di frequenze di aggiornamento del display aggiuntive, la piattaforma dispone delle informazioni corrette per passare alla frequenza fotogrammi preferita dell'app.

Nei casi in cui l'app non può o non vuole essere eseguita alla frequenza di aggiornamento del display, l'app deve specificare i timestamp di presentazione per ogni frame, utilizzando uno dei meccanismi della piattaforma per l'impostazione dei timestamp di presentazione:

L'utilizzo di questi timestamp impedisce alla piattaforma di presentare un frame dell'app troppo presto, il che comporterebbe un judder non necessario. L'utilizzo corretto dei timestamp di presentazione dei frame è un po' complicato. Per i giochi, consulta la nostra guida al frame pacing per saperne di più su come evitare il judder e valuta la possibilità di utilizzare la libreria Android Frame Pacing.

In alcuni casi, la piattaforma potrebbe passare a un multiplo della frequenza fotogrammi specificata dall'app in setFrameRate(). Ad esempio, un'app potrebbe chiamare setFrameRate() con 60 Hz e il dispositivo potrebbe passare il display a 120 Hz. Un motivo per cui ciò potrebbe accadere è se un'altra app ha una superficie con un'impostazione della frequenza fotogrammi di 24 Hz. In questo caso, l'esecuzione del display a 120 Hz consentirà l'esecuzione della superficie a 60 Hz e della superficie a 24 Hz senza richiedere il pulldown.

Quando il display funziona a un multiplo della frequenza fotogrammi dell'app, l'app deve specificare i timestamp di presentazione per ogni fotogramma per evitare tremolii non necessari. Per i giochi, la libreria Android Frame Pacing è utile per impostare correttamente i timestamp di presentazione dei frame.

setFrameRate() e preferredDisplayModeId

WindowManager.LayoutParams.preferredDisplayModeId è un altro modo in cui le app possono indicare la frequenza fotogrammi alla piattaforma. Alcune app vogliono solo modificare la frequenza di aggiornamento del display anziché altre impostazioni della modalità di visualizzazione, come la risoluzione del display. In generale, utilizza setFrameRate() anziché preferredDisplayModeId. La funzione setFrameRate() è più facile da usare perché l'app non deve cercare nell'elenco delle modalità di visualizzazione per trovare una modalità con una frequenza fotogrammi specifica.

setFrameRate() offre alla piattaforma maggiori opportunità di scegliere una frequenza fotogrammi compatibile in scenari in cui sono presenti più piattaforme che funzionano con frequenze fotogrammi diverse. Ad esempio, considera uno scenario in cui due app sono in esecuzione in modalità schermo diviso su un Pixel 4, dove un'app riproduce un video a 24 Hz e l'altra mostra all'utente un elenco scorrevole. Pixel 4 supporta due frequenze di aggiornamento del display: 60 Hz e 90 Hz. Utilizzando l'API preferredDisplayModeId, la superficie video è costretta a scegliere 60 Hz o 90 Hz. Chiamando setFrameRate() con 24 Hz, la superficie video fornisce alla piattaforma maggiori informazioni sulla frequenza fotogrammi del video di origine, consentendo alla piattaforma di scegliere 90 Hz per la frequenza di aggiornamento del display, che è migliore di 60 Hz in questo scenario.

Tuttavia, esistono scenari in cui è necessario utilizzare preferredDisplayModeId anziché setFrameRate(), ad esempio:

  • Se l'app vuole modificare la risoluzione o altre impostazioni della modalità di visualizzazione, utilizza preferredDisplayModeId.
  • La piattaforma cambierà le modalità di visualizzazione in risposta a una chiamata a setFrameRate() solo se il cambio di modalità è leggero e difficilmente percepibile dall'utente. Se l'app preferisce cambiare la frequenza di aggiornamento del display anche se richiede un cambio di modalità pesante (ad esempio su un dispositivo Android TV), utilizza preferredDisplayModeId.
  • Le app che non sono in grado di gestire il display in esecuzione a un multiplo della frequenza fotogrammi dell'app, che richiede l'impostazione di timestamp di presentazione su ogni frame, devono utilizzare preferredDisplayModeId.

setFrameRate() e preferredRefreshRate

WindowManager.LayoutParams#preferredRefreshRate imposta una frequenza fotogrammi preferita nella finestra dell'app, che è applicabile a tutte le piattaforme all'interno della finestra. L'app deve specificare la frequenza fotogrammi preferita indipendentemente dalle frequenze di aggiornamento supportate dal dispositivo, in modo simile a setFrameRate(), per fornire allo scheduler un'indicazione migliore della frequenza fotogrammi prevista dell'app.

preferredRefreshRate viene ignorato per le piattaforme che utilizzano setFrameRate(). In generale, utilizza setFrameRate() se possibile.

preferredRefreshRate e preferredDisplayModeId

Se le app vogliono solo modificare la frequenza di aggiornamento preferita, è preferibile utilizzare preferredRefreshRate anziché preferredDisplayModeId.

Evita di chiamare setFrameRate() troppo di frequente

Sebbene la chiamata setFrameRate() non sia molto costosa in termini di prestazioni, le app dovrebbero evitare di chiamare setFrameRate() ogni frame o più volte al secondo. Le chiamate a setFrameRate() probabilmente comporteranno una modifica della frequenza di aggiornamento del display, che potrebbe causare un calo dei frame durante la transizione. Devi determinare la frequenza fotogrammi corretta in anticipo e chiamare setFrameRate() una volta.

Utilizzo per giochi o altre app non video

Sebbene i video siano il caso d'uso principale dell'API setFrameRate(), questa può essere utilizzata per altre app. Ad esempio, un gioco che non deve essere eseguito a una frequenza superiore a 60 Hz (per ridurre il consumo energetico e ottenere sessioni di gioco più lunghe) può chiamare Surface.setFrameRate(60, Surface.FRAME_RATE_COMPATIBILITY_DEFAULT). In questo modo, un dispositivo che funziona a 90 Hz per impostazione predefinita funzionerà a 60 Hz mentre il gioco è attivo, evitando così il tremolio che si verificherebbe se il gioco funzionasse a 60 Hz mentre il display funzionasse a 90 Hz.

Utilizzo di FRAME_RATE_COMPATIBILITY_FIXED_SOURCE

FRAME_RATE_COMPATIBILITY_FIXED_SOURCE è destinato solo alle app video. Per l'utilizzo non video, utilizza FRAME_RATE_COMPATIBILITY_DEFAULT.

Scelta di una strategia per modificare la frequenza fotogrammi

  • Consigliamo vivamente alle app, quando mostrano video di lunga durata come i film, di chiamare setFrameRate(fps, FRAME_RATE_COMPATIBILITY_FIXED_SOURCE, CHANGE_FRAME_RATE_ALWAYS), dove fps è la frequenza fotogrammi del video.
  • Sconsigliamo vivamente alle app di chiamare setFrameRate() con CHANGE_FRAME_RATE_ALWAYS quando prevedi che la riproduzione del video duri diversi minuti o meno.

Esempio di integrazione per le app di riproduzione video

Per l'integrazione dei cambi di frequenza di aggiornamento nelle app di riproduzione video, consigliamo i seguenti passaggi:

  1. Decidi il changeFrameRateStrategy:
    1. Se riproduci un video di lunga durata, ad esempio un film, utilizza MATCH_CONTENT_FRAMERATE_ALWAYS
    2. Se riproduci un video breve, ad esempio un trailer di un film, utilizza CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS
  2. Se il changeFrameRateStrategy è CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS, vai al passaggio 4.
  3. Rileva se sta per verificarsi un cambio di frequenza di aggiornamento non fluido controllando che entrambi i seguenti fatti siano veri:
    1. Il passaggio alla modalità senza interruzioni non è possibile dalla frequenza di aggiornamento corrente (chiamiamola C) alla frequenza fotogrammi del video (chiamiamola V). Questo accade se C e V sono diversi e Display.getMode().getAlternativeRefreshRates non contiene un multiplo di V.
    2. L'utente ha attivato le modifiche della frequenza di aggiornamento non continue. Puoi rilevare questo problema controllando se DisplayManager.getMatchContentFrameRateUserPreference restituisce MATCH_CONTENT_FRAMERATE_ALWAYS.
  4. Se il passaggio sarà fluido, procedi nel seguente modo:
    1. Chiama setFrameRate e passa fps, FRAME_RATE_COMPATIBILITY_FIXED_SOURCE e changeFrameRateStrategy, dove fps è la frequenza fotogrammi del video.
    2. Inizia la riproduzione del video
  5. Se sta per verificarsi un cambio di modalità non fluido, procedi nel seguente modo:
    1. Mostra la UX per informare l'utente. Tieni presente che ti consigliamo di implementare un modo per consentire all'utente di ignorare questa UX e saltare il ritardo aggiuntivo nel passaggio 5.d. Questo perché il ritardo consigliato è maggiore del necessario sui display che presentano tempi di commutazione più rapidi.
    2. Chiama setFrameRate e passa fps, FRAME_RATE_COMPATIBILITY_FIXED_SOURCE e CHANGE_FRAME_RATE_ALWAYS, dove fps è la frequenza fotogrammi del video.
    3. Attendi il callback onDisplayChanged.
    4. Attendi 2 secondi per il completamento del cambio di modalità.
    5. Inizia la riproduzione del video

Di seguito è riportato lo pseudocodice per supportare solo il Cambio fluido:

SurfaceControl.Transaction transaction = new SurfaceControl.Transaction();
transaction.setFrameRate(surfaceControl,
    contentFrameRate,
    FRAME_RATE_COMPATIBILITY_FIXED_SOURCE,
    CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS);
transaction.apply();
beginPlayback();

Il pseudocodice per supportare il cambio fluido e non fluido come descritto sopra è il seguente:

SurfaceControl.Transaction transaction = new SurfaceControl.Transaction();
if (isSeamlessSwitch(contentFrameRate)) {
  transaction.setFrameRate(surfaceControl,
      contentFrameRate,
      FRAME_RATE_COMPATIBILITY_FIXED_SOURCE,
      CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS);
  transaction.apply();
  beginPlayback();
} else if (displayManager.getMatchContentFrameRateUserPreference()
      == MATCH_CONTENT_FRAMERATE_ALWAYS) {
  showRefreshRateSwitchUI();
  sleep(shortDelaySoUserSeesUi);
  displayManager.registerDisplayListener(…);
  transaction.setFrameRate(surfaceControl,
      contentFrameRate,
      FRAME_RATE_COMPATIBILITY_FIXED_SOURCE,
      CHANGE_FRAME_RATE_ALWAYS);
  transaction.apply();
  waitForOnDisplayChanged();
  sleep(twoSeconds);
  hideRefreshRateSwitchUI();
  beginPlayback();
}