Velocidad de fotogramas

La API de velocidad de fotogramas permite que las apps informen a la plataforma de Android sobre la velocidad de fotogramas deseada y está disponible en apps segmentadas a Android 11 (nivel de API 30) o versiones posteriores. Tradicionalmente, la mayoría de los dispositivos solo admitían una frecuencia de actualización de la pantalla, que en general era de 60 Hz, pero esto cambió. Muchos dispositivos ahora admiten frecuencias de actualización adicionales, como 90 Hz o 120 Hz. Algunos dispositivos admiten cambios de frecuencia de actualización fluidos, mientras que otros muestran brevemente una pantalla negra, que suele durar un segundo.

El objetivo principal de la API es permitir que las apps aprovechen mejor todas las frecuencias de actualización de pantalla compatibles. Por ejemplo, una app que reproduce un video de 24 Hz que llama a setFrameRate() puede hacer que el dispositivo cambie la frecuencia de actualización de la pantalla de 60 Hz a 120 Hz. Esta nueva frecuencia de actualización permite una reproducción fluida y sin vibraciones de videos de 24 Hz, sin necesidad de una reducción de 3:2, como se requeriría para reproducir el mismo video en una pantalla de 60 Hz. Esto genera una mejor experiencia del usuario.

Uso básico

Android expone varias formas de acceder y controlar superficies, por lo que existen varias versiones de la API de setFrameRate(): Cada versión de la API toma los mismos parámetros y funciona de la misma manera que las demás:

• Surface.setFrameRate()
• SurfaceControl.Transaction.setFrameRate()
• ANativeWindow_setFrameRate()
• ASurfaceTransaction_setFrameRate()

La app no necesita tener en cuenta las frecuencias de actualización de pantalla compatibles reales, que se pueden obtener llamando a Display.getSupportedModes(), para llamar de forma segura a setFrameRate(). Por ejemplo, incluso si el dispositivo solo admite 60 Hz, llama a setFrameRate() con la velocidad de fotogramas que prefiera tu app. Los dispositivos que no tengan una mejor coincidencia para la velocidad de fotogramas de la app permanecerán con la frecuencia de actualización de la pantalla actual.

Para ver si una llamada a setFrameRate() genera un cambio en la frecuencia de actualización de la pantalla, regístrate para recibir notificaciones de cambio de pantalla llamando a DisplayManager.registerDisplayListener() o AChoreographer_registerRefreshRateCallback().

Cuando llames a setFrameRate(), es mejor pasar la velocidad de fotogramas exacta en lugar de redondear a un número entero. Por ejemplo, cuando renderices un video grabado a 29.97 Hz, pasa 29.97 en lugar de redondear a 30.

En el caso de las apps de video, el parámetro de compatibilidad que se pasa a setFrameRate() debe establecerse en Surface.FRAME_RATE_COMPATIBILITY_FIXED_SOURCE para dar una sugerencia adicional a la plataforma de Android de que la app usará la reducción para adaptarse a una frecuencia de actualización de la pantalla que no coincida (lo que generará vibraciones).

En algunas situaciones, la superficie de video dejará de enviar fotogramas, pero permanecerá visible en la pantalla durante un tiempo. Las situaciones comunes incluyen cuando la reproducción llega al final del video o cuando el usuario la pausa. En estos casos, llama a setFrameRate() con el parámetro de velocidad de fotogramas establecido en 0 para borrar la configuración de velocidad de fotogramas de la superficie y volver al valor predeterminado. No es necesario borrar la configuración de velocidad de fotogramas de esta manera cuando se destruye la superficie o cuando se oculta porque el usuario cambia a una app diferente. Borra la configuración de velocidad de fotogramas solo cuando la superficie permanezca visible sin usarse.

Cambio de velocidad de fotogramas no fluido

En algunos dispositivos, el cambio de frecuencia de actualización puede tener interrupciones visuales, como una pantalla negra durante uno o dos segundos. Por lo general, esto ocurre en decodificadores, paneles de TV y dispositivos similares. De forma predeterminada, el framework de Android no cambia de modo cuando se llama a la API de Surface.setFrameRate() para evitar esas interrupciones visuales.

Algunos usuarios prefieren una interrupción visual al principio y al final de los videos más largos. Esto permite que la frecuencia de actualización de la pantalla coincida con la velocidad de fotogramas del video y evita artefactos de conversión de velocidad de fotogramas, como la vibración de la reducción de 3:2 para la reproducción de películas.

Por este motivo, se pueden habilitar los cambios de frecuencia de actualización no fluidos si el usuario y las apps aceptan participar:

• Usuarios: Para participar, los usuarios pueden habilitar la configuración de usuario Coincidir con la velocidad de fotogramas del contenido.
• Apps: Para participar, las apps pueden pasar CHANGE_FRAME_RATE_ALWAYS a setFrameRate().

Te recomendamos que siempre uses CHANGE_FRAME_RATE_ALWAYS para videos de larga duración, como películas. Esto se debe a que el beneficio de hacer coincidir la velocidad de fotogramas del video supera la interrupción que se produce cuando se cambia la frecuencia de actualización.

Recomendaciones adicionales

Sigue estas recomendaciones para situaciones comunes.

Varias superficies

La plataforma de Android está diseñada para controlar correctamente las situaciones en las que hay varias superficies con diferentes configuraciones de velocidad de fotogramas. Cuando tu app tiene varias superficies con diferentes velocidades de fotogramas, llama a setFrameRate() con la velocidad de fotogramas correcta para cada superficie. Incluso si el dispositivo ejecuta varias apps a la vez, usa el modo de pantalla dividida o el modo Imagen en imagen, cada app puede llamar de forma segura a setFrameRate() para sus propias superficies.

La plataforma no cambia a la velocidad de fotogramas de la app

Incluso si el dispositivo admite la velocidad de fotogramas que especifica la app en una llamada a setFrameRate(), hay casos en los que el dispositivo no cambiará la pantalla a esa frecuencia de actualización. Por ejemplo, una superficie de mayor prioridad puede tener una configuración de velocidad de fotogramas diferente, o el dispositivo puede estar en el modo de ahorro de batería (establecer una restricción en la frecuencia de actualización de la pantalla para preservar la batería). La app debe seguir funcionando correctamente cuando el dispositivo no cambia la frecuencia de actualización de la pantalla a la configuración de velocidad de fotogramas de la app, incluso si el dispositivo cambia en circunstancias normales.

Depende de la app decidir cómo responder cuando la frecuencia de actualización de la pantalla no coincide con la velocidad de fotogramas de la app. En el caso del video, la velocidad de fotogramas se fija en la del video fuente, y se requerirá una reducción para mostrar el contenido del video. En cambio, un juego puede optar por intentar ejecutarse a la frecuencia de actualización de la pantalla en lugar de permanecer con su velocidad de fotogramas preferida. La app no debe cambiar el valor que pasa a setFrameRate() en función de lo que hace la plataforma. Debe permanecer establecida en la velocidad de fotogramas preferida de la app, independientemente de cómo la app controle los casos en los que la plataforma no se ajusta para que coincida con la solicitud de la app. De esa manera, si las condiciones del dispositivo cambian para permitir el uso de frecuencias de actualización de la pantalla adicionales, la plataforma tiene la información correcta para cambiar a la velocidad de fotogramas preferida de la app.

En los casos en los que la app no se ejecute o no pueda ejecutarse a la frecuencia de actualización de la pantalla, la app debe especificar marcas de tiempo de presentación para cada fotograma, usando uno de los mecanismos de la plataforma para establecer marcas de tiempo de presentación:

• ASurfaceTransaction_setDesiredPresentTime()
• EGL_ANDROID_presentation_time
• VK_GOOGLE_display_timing

El uso de estas marcas de tiempo impide que la plataforma presente un fotograma de la app demasiado pronto, lo que generaría vibraciones innecesarias. El uso correcto de las marcas de tiempo de presentación de fotogramas es un poco complicado. En el caso de los juegos, consulta nuestra guía de regulación de fotogramas para obtener más información sobre cómo evitar las vibraciones y considera usar la biblioteca de Frame Pacing de Android.

En algunos casos, la plataforma puede cambiar a un múltiplo de la velocidad de fotogramas que especificó la app en setFrameRate(). Por ejemplo, una app puede llamar a setFrameRate() con 60 Hz y el dispositivo puede cambiar la pantalla a 120 Hz. Una de las razones por las que esto podría suceder es si otra app tiene una superficie con una configuración de velocidad de fotogramas de 24 Hz. En ese caso, ejecutar la pantalla a 120 Hz permitirá que la superficie de 60 Hz y la de 24 Hz se ejecuten sin necesidad de reducción.

Cuando la pantalla se ejecuta a un múltiplo de la velocidad de fotogramas de la app, esta debe especificar marcas de tiempo de presentación para cada fotograma para evitar vibraciones innecesarias. En el caso de los juegos, la biblioteca de Frame Pacing de Android es útil para configurar correctamente las marcas de tiempo de presentación de fotogramas.

Comparación entre setFrameRate() y preferredDisplayModeId

WindowManager.LayoutParams.preferredDisplayModeId es otra forma en que las apps pueden indicar su velocidad de fotogramas a la plataforma. Algunas apps solo quieren cambiar la frecuencia de actualización de la pantalla en lugar de cambiar otros parámetros de configuración del modo de visualización, como la resolución de la pantalla. En general, usa setFrameRate() en lugar de preferredDisplayModeId. La función setFrameRate() es más fácil de usar porque la app no necesita buscar en la lista de modos de visualización para encontrar un modo con una velocidad de fotogramas específica.

setFrameRate() le brinda a la plataforma más oportunidades para elegir una velocidad de fotogramas compatible en situaciones en las que hay varias superficies que se ejecutan a diferentes velocidades de fotogramas. Por ejemplo, considera una situación en la que dos apps se ejecutan en el modo de pantalla dividida en un Pixel 4, en la que una app reproduce un video de 24 Hz y la otra le muestra al usuario una lista desplazable. El Pixel 4 admite dos frecuencias de actualización de la pantalla: 60 Hz y 90 Hz. Con la API de preferredDisplayModeId, la superficie de video se ve obligada a elegir 60 Hz o 90 Hz. Cuando se llama a setFrameRate() con 24 Hz, la superficie de video le brinda a la plataforma más información sobre la velocidad de fotogramas del video fuente, lo que permite que la plataforma elija 90 Hz para la frecuencia de actualización de la pantalla, que es mejor que 60 Hz en esta situación.

Sin embargo, hay situaciones en las que se debe usar preferredDisplayModeId en lugar de setFrameRate(), como las siguientes:

• Si la app quiere cambiar la resolución o la configuración de otro modo de visualización, usa preferredDisplayModeId.
• La plataforma solo cambiará los modos de visualización en respuesta a una llamada a setFrameRate() si el cambio de modo es ligero y es poco probable que el usuario lo note. Si la app prefiere cambiar la frecuencia de actualización de la pantalla, incluso si requiere un cambio de modo pesado (por ejemplo, en un dispositivo Android TV), usa preferredDisplayModeId.
• Las apps que no pueden controlar la pantalla que se ejecuta a un múltiplo de la velocidad de fotogramas de la app, lo que requiere configurar marcas de tiempo de presentación en cada fotograma, deben usar preferredDisplayModeId.

Comparación entre setFrameRate() y preferredRefreshRate

WindowManager.LayoutParams#preferredRefreshRate establece una velocidad de fotogramas preferida en la ventana de la app, y la velocidad se aplica a todas las superficies dentro de la ventana. La app debe especificar su velocidad de fotogramas preferida, independientemente de las frecuencias de actualización compatibles del dispositivo, de manera similar a setFrameRate(), para darle al programador una mejor sugerencia de la velocidad de fotogramas deseada de la app.

Se ignora preferredRefreshRate para las superficies que usan setFrameRate(). En general, usa setFrameRate() si es posible.

Comparación entre preferredRefreshRate y preferredDisplayModeId

Si las apps solo quieren cambiar la frecuencia de actualización preferida, es mejor usar preferredRefreshRate en lugar de preferredDisplayModeId.

Evita llamar a setFrameRate() con demasiada frecuencia

Aunque la llamada a setFrameRate() no es muy costosa en términos de rendimiento, las apps deben evitar llamar a setFrameRate() cada fotograma o varias veces por segundo. Es probable que las llamadas a setFrameRate() generen un cambio en la frecuencia de actualización de la pantalla, lo que puede provocar una caída de fotogramas durante la transición. Debes determinar la velocidad de fotogramas correcta con anticipación y llamar a setFrameRate() una vez.

Uso para juegos o cualquier otra app que no sea de video

Aunque el video es el caso de uso principal de la API de setFrameRate(), se puede usar para otras apps. Por ejemplo, un juego que no pretende ejecutarse a más de 60 Hz (para reducir el uso de energía y lograr sesiones de juego más largas) puede llamar a Surface.setFrameRate(60, Surface.FRAME_RATE_COMPATIBILITY_DEFAULT). De esta manera, un dispositivo que se ejecuta a 90 Hz de forma predeterminada se ejecutará a 60 Hz mientras el juego esté activo, lo que evitará la vibración que, de lo contrario, se produciría si el juego se ejecutara a 60 Hz mientras la pantalla se ejecutara a 90 Hz.

Uso de FRAME_RATE_COMPATIBILITY_FIXED_SOURCE

FRAME_RATE_COMPATIBILITY_FIXED_SOURCE está diseñado solo para apps de video. Para el uso que no sea de video, usa FRAME_RATE_COMPATIBILITY_DEFAULT.

Cómo elegir una estrategia para cambiar la velocidad de fotogramas

• Te recomendamos que las apps, cuando muestren videos de larga duración, como películas, llamen a setFrameRate(fps, FRAME_RATE_COMPATIBILITY_FIXED_SOURCE, CHANGE_FRAME_RATE_ALWAYS), donde fps es la velocidad de fotogramas del video.
• Te recomendamos que las apps no llamen a setFrameRate() con CHANGE_FRAME_RATE_ALWAYS cuando esperes que la reproducción de video dure varios minutos o menos.

Ejemplo de integración para apps de reproducción de video

Recomendamos los siguientes pasos para integrar los cambios de frecuencia de actualización en las apps de reproducción de video:

1. Decide la changeFrameRateStrategy:
   1. Si reproduces un video de larga duración, como una película, usa MATCH_CONTENT_FRAMERATE_ALWAYS
   2. Si reproduces un video corto, como un tráiler de película, usa CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS.
2. Si el changeFrameRateStrategy es CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS , ve al paso 4.
3. Para detectar si está a punto de ocurrir un cambio de frecuencia de actualización no fluido, verifica que se cumplan ambos hechos:
   1. No es posible cambiar de modo fluido de la frecuencia de actualización actual (llamémosla C) a la velocidad de fotogramas del video (llamémosla V). Este será el caso si C y V son diferentes y Display.getMode().getAlternativeRefreshRates no contiene un múltiplo de V.
   2. El usuario aceptó los cambios de frecuencia de actualización no fluidos. Para detectarlo, verifica si DisplayManager.getMatchContentFrameRateUserPreference muestra MATCH_CONTENT_FRAMERATE_ALWAYS.
4. Si el cambio va a ser fluido, haz lo siguiente:
   1. Llama a setFrameRate y pásale fps, FRAME_RATE_COMPATIBILITY_FIXED_SOURCE, y changeFrameRateStrategy, donde fps es la velocidad de fotogramas del video.
   2. Comienza la reproducción de video.
5. Si está a punto de ocurrir un cambio de modo no fluido, haz lo siguiente:
   1. Muestra la UX para notificar al usuario. Ten en cuenta que te recomendamos que implementes una forma para que el usuario descarte esta UX y omita la demora adicional en el paso 5.d. Esto se debe a que nuestra demora recomendada es mayor de lo necesario en pantallas que muestran tiempos de cambio más rápidos.
   2. Llama a setFrameRate y pásale fps, FRAME_RATE_COMPATIBILITY_FIXED_SOURCE, y CHANGE_FRAME_RATE_ALWAYS, donde fps es la velocidad de fotogramas del video.
   3. Espera la onDisplayChanged devolución de llamada.
   4. Espera 2 segundos para que se complete el cambio de modo.
   5. Comienza la reproducción de video.

El pseudocódigo para admitir solo el cambio fluido es el siguiente:

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

El pseudocódigo para admitir el cambio fluido y no fluido como se describió anteriormente es el siguiente:

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();
}