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 (normalmente 60 Hz), pero esto está cambiando. 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 una reproducción fluida y sin sacudidas de videos de 24 Hz, sin necesidad de obtener una bajada de 3:2, como se requeriría para reproducir el mismo video en una pantalla de 60 Hz. Esto da como resultado 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 igual que las demás:

La app no necesita tener en cuenta las frecuencias de actualización de pantalla admitidas, 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 prefiere tu app. Los dispositivos que no tengan una mejor coincidencia con la velocidad de fotogramas de la app permanecerán con la frecuencia de actualización de 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 de pantalla llamando a DisplayManager.registerDisplayListener() o a AChoreographer_registerRefreshRateCallback().

Cuando se llama 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 brindar a la plataforma de Android una sugerencia adicional de que la app usará la herramienta desplegable para adaptarse a una frecuencia de actualización de pantalla no coincidente (lo que generará un movimiento).

En algunos casos, la superficie de video dejará de enviar fotogramas, pero seguirá 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 restablecer la configuración de velocidad de fotogramas de la superficie al valor predeterminado. No es necesario borrar la configuración de la velocidad de fotogramas cuando se destruye la superficie ni cuando esta está oculta porque el usuario cambia a otra app. Borra la configuración de la velocidad de fotogramas solo cuando la superficie permanezca visible sin usarse.

Interruptor de velocidad de fotogramas fluida

En algunos dispositivos, el cambio de frecuencia de actualización puede presentar 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 tales 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 evita artefactos de conversión de velocidad de fotogramas, como una sacudida de 3:2 para la reproducción de películas.

Por este motivo, se pueden habilitar los interruptores de frecuencia de actualización flexibles si tanto el usuario como las apps aceptan lo siguiente:

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 manejar correctamente situaciones en las que hay varias superficies con diferentes configuraciones de velocidad de fotogramas. Cuando tu app tenga varias plataformas 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 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 cambiará la pantalla a esa frecuencia de actualización. Por ejemplo, una superficie con prioridad más alta puede tener una configuración de velocidad de fotogramas diferente, o bien el dispositivo puede estar en modo de ahorro de batería (es posible que se establezca una restricción en la frecuencia de actualización de la pantalla para conservar la batería). La app debe funcionar correctamente cuando el dispositivo no cambie la frecuencia de actualización de la pantalla a la configuración de velocidad de fotogramas de la app, incluso si cambia en circunstancias normales.

La app debe 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 se fija a la del video de origen, y se requerirá una pantalla desplegable para mostrar el contenido del video. En su lugar, un juego puede optar por intentar ejecutarse a la frecuencia de actualización de 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 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 el uso de 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 a la frecuencia de actualización de pantalla o no pueda hacerlo, debe especificar marcas de tiempo de presentación para cada fotograma usando uno de los mecanismos de la plataforma para configurar marcas de tiempo de presentación:

El uso de estas marcas de tiempo evita que la plataforma presente un fotograma de app demasiado pronto, lo que generaría un sacudón innecesario. 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 ritmo de fotogramas para obtener más información sobre cómo evitar la vibración 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 especificó la app en setFrameRate(). Por ejemplo, una app podría llamar a setFrameRate() con 60 Hz y el dispositivo podría 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 se ejecuten tanto la superficie de 60 Hz como la de 24 Hz sin necesidad de reducir la presió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 a fin de evitar una sacudida innecesaria. 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 pantalla en lugar de cambiar otras opciones del modo de visualización, como la resolución. 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, 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 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 permite que la plataforma elija 90 Hz para la frecuencia de actualización de 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 desea cambiar la resolución o cualquier otra 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 cambio de modo es liviano y no es 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 ejecutándose 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() 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 que admita el dispositivo, de manera similar a setFrameRate(), para brindar al programador una mejor idea de la velocidad de fotogramas prevista de la app.

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

PreferredRefreshRate vs. PreferredDisplayModeId

Si las apps solo desean 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() cada fotograma o varias veces por segundo. Es probable que las llamadas a setFrameRate() generen un cambio en la frecuencia de actualización de pantalla, lo que puede provocar la disminución 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 y otras apps que no son de video

Si bien el video es el caso de uso principal para la API de setFrameRate(), se puede utilizar para otras apps. Por ejemplo, un juego que pretende no 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 lo hará a 60 Hz mientras el juego esté activo, lo que evitará el sacudón que, de lo contrario, ocurriría si el juego se ejecutara a 60 Hz y la pantalla lo hiciera a 90 Hz.

Uso de frame_RATE_COMPATIBILITY_FIXED_SOURCE

FRAME_RATE_COMPATIBILITY_FIXED_SOURCE está diseñado solo 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 es la velocidad de fotogramas del video.
  • Te recomendamos que evites las apps que 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

Te recomendamos que sigas estos pasos para integrar los cambios de frecuencia de actualización en apps de reproducción de video:

  1. Decide el changeFrameRateStrategy:
    1. Si estás reproduciendo un video de larga duración, como una película, usa MATCH_CONTENT_FRAMERATE_ALWAYS
    2. Si reproduces un video corto, como un avance en movimiento, usa CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS.
  2. Si changeFrameRateStrategy es CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS, ve al paso 4.
  3. Detecta si está por suceder un cambio de frecuencia de actualización no fluido verificando que se cumplan estas dos condiciones:
    1. El cambio de Modo sin interrupciones no es posible desde la frecuencia de actualización actual (podemos llamarla C) a la velocidad de fotogramas del video (que llamaremos V). Esto será así si C y V son diferentes y Display.getMode().getAlternativeRefreshRates no contiene un múltiplo de V.
    2. El usuario habilitó los cambios constantes en la frecuencia de actualización. Para detectarlo, verifica si DisplayManager.getMatchContentFrameRateUserPreference muestra MATCH_CONTENT_FRAMERATE_ALWAYS.
  4. Si vas a realizar el cambio sin problemas, 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 no fluido, haz lo siguiente:
    1. Muestra la UX para notificar al usuario. Ten en cuenta que recomendamos que implementes una manera para que el usuario descarte esta UX y omita el retraso adicional en el paso 5.d. Esto se debe a que la demora recomendada es mayor que el 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, donde fps es la velocidad de fotogramas del video.
    3. Espera la devolución de llamada onDisplayChanged.
    4. Espera 2 segundos para que se complete el cambio de modo.
    5. Iniciar reproducción de video

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