Velocidad de fotogramas

La API de velocidad de fotogramas permite que las apps informen a la plataforma de Android la velocidad de fotogramas deseada y está disponible en apps orientadas 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 pantalla, por lo general, 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 sin interrupciones, 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 y llama a setFrameRate() podría provocar 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 sacudidas de video de 24 Hz, sin necesidad de una función desplegable de 3:2, como se requiere para reproducir el mismo video en una pantalla de 60 Hz. De esta manera, se mejora la experiencia del usuario.

Importante: El programador tiene en cuenta una serie de factores cuando decide la frecuencia de actualización de la pantalla, por lo que no hay garantía de que tu app obtenga la velocidad de fotogramas que solicitas con setFrameRate().

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 considerar las tasas de actualización de pantalla compatibles reales, que se pueden obtener llamando a Display.getSupportedModes(), para llamar a setFrameRate() de forma segura. Por ejemplo, incluso si el dispositivo solo admite 60 Hz, llama a setFrameRate() con la velocidad de fotogramas que prefiere tu app. Los dispositivos que no tienen una mejor coincidencia con la velocidad de fotogramas de la app conservarán la frecuencia de actualización de la pantalla actual.

Para ver si una llamada a setFrameRate() cambia la frecuencia de actualización de la pantalla, llama a DisplayManager.registerDisplayListener() o AChoreographer_registerRefreshRateCallback() a fin de registrarte para recibir notificaciones de cambios de pantalla.

Cuando llamas 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á el menú desplegable para adaptarse a una frecuencia de actualización de la pantalla que no coincide (lo que provocará un parpadeo).

En algunos casos, la plataforma de video dejará de enviar fotogramas, pero permanecerá visible en la pantalla durante un tiempo. Algunas situaciones comunes son los casos en que la reproducción llega al final del video o cuando el usuario pausa la reproducción. 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 restablecer el valor predeterminado. No es necesario borrar la configuración de la velocidad de fotogramas de esta manera cuando se destruye la superficie o cuando esta se oculta porque el usuario cambia a una app diferente. Borra la configuración de la velocidad de fotogramas solo cuando la superficie permanezca visible sin usarse.

Interruptor de velocidad de fotogramas ininterrumpido

En algunos dispositivos, el cambio de frecuencia de actualización puede tener interrupciones visuales, como una pantalla negra, durante uno o dos segundos. Esto suele ocurrir 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 comienzo 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 evite artefactos de conversión de velocidad de fotogramas, como el parpadeo de la bajada de 3:2 para la reproducción de películas.

Por este motivo, los interruptores de frecuencia de actualización que no sean fluidos se pueden habilitar si el usuario y las apps habilitan lo siguiente:

• Usuarios: Para habilitar esta función, los usuarios pueden activar la configuración Ajustar la velocidad de fotogramas del contenido.
• Apps: Para habilitar esta opción, 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 se diseñó para manejar correctamente situaciones en las que hay varias plataformas con diferentes configuraciones de velocidad de fotogramas. Cuando tu app tenga 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, con el modo de pantalla dividida o de pantalla en pantalla, cada app puede llamar a setFrameRate() de forma segura para sus propias plataformas.

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 cambia 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 modo de ahorro de batería (estableciendo una restricción en la frecuencia de actualización de la pantalla para ahorrar batería). La app aún debe funcionar correctamente cuando el dispositivo no cambia la frecuencia de actualización de la pantalla al parámetro de configuración de la 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 de los videos, la velocidad de fotogramas es fija y se corresponde con la del video de origen. Para mostrar el contenido de video, se requerirá un menú desplegable. 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() según lo que hace la plataforma. Debe permanecer configurada en la velocidad de fotogramas preferida de la app, independientemente de cómo la app maneje los casos en los que la plataforma no se ajusta para coincidir con la solicitud de la app. De esa manera, si las condiciones del dispositivo cambian para permitir que se usen frecuencias de actualización de pantalla adicionales, la plataforma tiene la información correcta para cambiar a la velocidad de fotogramas preferida de la app.

En los casos en que la app no pueda ejecutarse a la frecuencia de actualización de la pantalla, esta debería especificar marcas de tiempo de presentación para cada fotograma con 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 evita que la plataforma presente un fotograma de la app demasiado pronto, lo que generaría una sacudida innecesaria. El uso correcto de las marcas de tiempo de presentación de tramas es un poco complicado. En el caso de los juegos, consulta nuestra guía de ritmo de fotogramas para obtener más información sobre cómo evitar sacudidas y considera usar la biblioteca de Android Frame Pacing.

En algunos casos, la plataforma puede cambiar a un múltiplo de la velocidad de fotogramas que la app especifica en setFrameRate(). Por ejemplo, una app puede llamar a setFrameRate() con 60 Hz, y el dispositivo puede cambiar la pantalla a 120 Hz. Una razón por la 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 se ejecuten tanto la superficie de 60 Hz como la de 24 Hz sin que sea necesario retroceder.

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 un parpadeo innecesario. En el caso de los juegos, la biblioteca de Android Frame Pacing es útil para configurar correctamente las marcas de tiempo de presentación de fotogramas.

setFrameRate() frente a 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 de elegir una velocidad de fotogramas compatible en situaciones en las que hay varias superficies que se ejecutan con diferentes velocidades de fotogramas. Por ejemplo, imagina una situación en la que dos apps se ejecutan en el modo de pantalla dividida en un Pixel 4, donde una app reproduce un video de 24 Hz y la otra muestra al usuario una lista desplazable. El Pixel 4 admite dos frecuencias de actualización de pantalla: 60 Hz y 90 Hz. Con la API de preferredDisplayModeId, la superficie de video se fuerza 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 de origen, lo que le permite elegir 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 cualquier otro parámetro de configuración del modo de visualización, usa preferredDisplayModeId.
• La plataforma solo cambiará los modos de visualización en respuesta a una llamada a setFrameRate() si el interruptor 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 interruptor de modo pesado (por ejemplo, en un dispositivo Android TV), usa preferredDisplayModeId.
• Las apps que no pueden controlar la ejecución de la pantalla a un múltiplo de su velocidad de fotogramas, lo que requiere configurar marcas de tiempo de presentación en cada fotograma, deben usar preferredDisplayModeId.

setFrameRate() frente a 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 prevista de la app.

preferredRefreshRate se ignora para plataformas que usan setFrameRate(). En general, usa setFrameRate() si es posible.

PreferredRefreshRate frente a PreferredDisplayModeId

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

Cómo evitar 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() en 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 de juegos y otras apps que no son de video

Si bien el video es el caso de uso principal de la API de setFrameRate(), se puede utilizar para otras apps. Por ejemplo, un juego que intenta no ejecutarse a más de 60 Hz (para reducir el consumo 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á el parpadeo que se produciría si el juego se ejecutara a 60 Hz mientras la pantalla se ejecuta a 90 Hz.

Uso de FRAME_RATE_COMPATIBILITY_FIXED_SOURCE

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

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

• 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), en el que FPS corresponde a la velocidad de fotogramas del video.
• No recomendamos que las apps llamen a setFrameRate() con CHANGE_FRAME_RATE_ALWAYS cuando esperas 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 interruptores de frecuencia de actualización en apps de reproducción de video:

1. Decide el 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 avance 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 los siguientes dos aspectos:
   1. El cambio de modo fluido no es posible desde la frecuencia de actualización actual (llamémoslo C) a la velocidad de fotogramas del video (llamémoslo 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 detectar esto, verifica si DisplayManager.getMatchContentFrameRateUserPreference muestra MATCH_CONTENT_FRAMERATE_ALWAYS.
4. Si el cambio será sin interrupciones, 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. Iniciar reproducción de video
5. Si está por ocurrir un cambio de modo que no sea fluido, haz lo siguiente:
   1. Muestra la UX para notificar al usuario. Ten en cuenta que te recomendamos implementar una forma para que el usuario descarte esta UX y omita la demora adicional en el paso 5.d. Esto se debe a que el retraso recomendado es mayor de lo necesario en pantallas que exhiben 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, en los que fps es la velocidad de fotogramas del video.
   3. Espera la devolución de llamada de onDisplayChanged.
   4. Espera 2 segundos para que se complete el cambio de modo.
   5. Cómo comenzar a reproducir un video

El seudocódigo que solo admite 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 seudocódigo para admitir el cambio sin interrupciones y sin interrupciones, 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();
}