Velocidad de fotogramas

La API de velocidad de fotogramas permite que las apps informen a la plataforma de Android su velocidad de fotogramas prevista 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 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 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 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 la reproducción fluida y sin interrupciones de videos de 24 Hz, sin necesidad de una reducción 3:2, como sería necesario 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 varios 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 igual 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 prefiera tu app. Los dispositivos que no tengan una mejor coincidencia para la velocidad de fotogramas de la app se quedará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 cambios en la pantalla llamando a DisplayManager.registerDisplayListener() o AChoreographer_registerRefreshRateCallback().

Cuando llames a setFrameRate(), es mejor pasar la velocidad de fotogramas exacta en lugar de redondearla 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. Las situaciones comunes incluyen cuando 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.

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. 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 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 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, se pueden habilitar los interruptores de frecuencia de actualización no fluida si el usuario y las apps aceptan 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 funció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 está diseñada para controlar correctamente situaciones en las que hay varias plataformas con diferentes parámetros de configuración 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 de forma segura a setFrameRate() 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 prioridad más alta puede tener una configuración de velocidad de fotogramas diferente, o el dispositivo puede estar en modo de ahorro de batería (establece una restricción en la frecuencia de actualización de la pantalla para conservar la 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 intentar ejecutarse a la frecuencia de actualización de la pantalla en lugar de mantener su velocidad de fotogramas preferida. La app no debe cambiar el valor que le 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 esta 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 se ejecute o no pueda ejecutarse a la frecuencia de actualización de la pantalla, esta debe 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 temprano, lo que generaría un parpadeo innecesario. 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 regulación de fotogramas para obtener más información sobre cómo evitar el parpadeo y considera usar la biblioteca de regulación de fotogramas de Android.

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 la superficie de 60 Hz y la de 24 Hz se ejecuten sin necesidad de una bajada.

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 Frame Pacing de Android es útil para configurar correctamente las marcas de tiempo de presentación de fotogramas.

setFrameRate() en comparación con 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 plataformas que se ejecutan a diferentes velocidades de fotogramas. Por ejemplo, imagina una situación en la que se ejecutan dos apps en 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 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 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.

setFrameRate() en comparación con 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 las plataformas que usan setFrameRate(). En general, usa setFrameRate() si es posible.

preferredRefreshRate en comparación con preferredDisplayModeId

Si las apps solo quieren cambiar la frecuencia de actualización preferida, es preferible 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() 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 pérdida 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 usar para otras apps. Por ejemplo, un juego que no tiene la intención de 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 solo está diseñado 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

• Cuando las apps muestran videos de larga duración, como películas, recomendamos que llamen a setFrameRate(fps, FRAME_RATE_COMPATIBILITY_FIXED_SOURCE, CHANGE_FRAME_RATE_ALWAYS), donde fps es 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

Te recomendamos que sigas los siguientes pasos para integrar interruptores de frecuencia de actualización en las 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 estas dos condiciones:
   1. No es posible cambiar del modo fluido a 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 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. Cómo comenzar a reproducir un video
5. Si se va a producir un cambio de modo no 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 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 devolución de llamada de onDisplayChanged.
   4. Espera 2 segundos a que se complete el cambio de modo.
   5. Cómo comenzar a reproducir un video

El pseudocódigo para solo admitir el cambio sin problemas 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();
}