Kare hızı

Kare hızı API'si, uygulamaların Android platformunu amaçlanan kare hızı hakkında bilgilendirmesine olanak tanır ve Android 11 (API düzeyi 30) veya sonraki sürümleri hedefleyen uygulamalarda kullanılabilir. Geleneksel olarak çoğu cihaz yalnızca tek bir ekran yenileme hızını (genellikle 60 Hz) destekler ancak bu durum değişmektedir. Birçok cihaz artık 90 Hz veya 120 Hz gibi ek yenileme hızlarını destekliyor. Bazı cihazlar kesintisiz yenileme hızı geçişlerini desteklerken diğerleri genellikle bir saniye süren siyah bir ekran gösterir.

API'nin asıl amacı, uygulamaların desteklenen tüm ekran yenileme hızlarından daha iyi yararlanmasını sağlamaktır. Örneğin, 24 Hz video oynatan bir uygulama setFrameRate() yöntemini çağırırsa cihaz, ekran yenileme hızını 60 Hz'den 120 Hz'e değiştirebilir. Bu yeni yenileme hızı, 24 Hz videonun 60 Hz ekranda oynatılması için gereken 3:2 pulldown işlemine gerek kalmadan sorunsuz ve sarsıntısız bir şekilde oynatılmasını sağlar. Bu sayede daha iyi bir kullanıcı deneyimi sunulur.

Temel kullanım

Android, yüzeylere erişmek ve bunları kontrol etmek için çeşitli yöntemler sunar. Bu nedenle, setFrameRate() API'nin birkaç sürümü vardır. API'nin her sürümü aynı parametreleri alır ve diğerleriyle aynı şekilde çalışır:

Uygulamanın, setFrameRate() yöntemini güvenli bir şekilde çağırabilmek için desteklenen gerçek ekran yenileme hızlarını dikkate alması gerekmez. Bu hızlar, Display.getSupportedModes() yöntemi çağrılarak elde edilebilir. Örneğin, cihaz yalnızca 60 Hz'yi desteklese bile uygulamanızın tercih ettiği kare hızıyla setFrameRate() yöntemini çağırın. Uygulamanın kare hızıyla daha iyi eşleşmeyen cihazlar, mevcut ekran yenileme hızını kullanmaya devam eder.

setFrameRate() çağrısının ekran yenileme hızında değişikliğe neden olup olmadığını görmek için DisplayManager.registerDisplayListener() veya AChoreographer_registerRefreshRateCallback() çağrısı yaparak ekran değişikliği bildirimlerine kaydolun.

setFrameRate() çağrılırken kare hızını tam sayıya yuvarlamak yerine tam kare hızını iletmek en iyisidir. Örneğin, 29,97 Hz'de kaydedilen bir videoyu oluştururken 30'a yuvarlamak yerine 29,97 değerini iletin.

Video uygulamalarında, setFrameRate() öğesine iletilen uyumluluk parametresi Surface.FRAME_RATE_COMPATIBILITY_FIXED_SOURCE olarak ayarlanmalıdır. Bu sayede Android platformuna, uygulamanın eşleşmeyen bir ekran yenileme hızına uyum sağlamak için pulldown kullanacağı (bu da titremeye neden olur) konusunda ek bir ipucu verilir.

Bazı senaryolarda, video yüzeyi kare göndermeyi durdurur ancak bir süre ekranda görünür kalır. Oynatmanın videonun sonuna ulaşması veya kullanıcının oynatmayı duraklatması, yaygın senaryolar arasındadır. Bu durumlarda, yüzeyin kare hızı ayarını varsayılan değere geri döndürmek için kare hızı parametresi 0 olarak ayarlanmış şekilde setFrameRate() yöntemini çağırın. Yüzey yok edildiğinde veya kullanıcı farklı bir uygulamaya geçtiği için yüzey gizlendiğinde kare hızı ayarını bu şekilde temizlemek gerekmez. Kare hızı ayarını yalnızca yüzey kullanılmadan görünür kaldığında temizleyin.

Kesintisiz olmayan kare hızı geçişi

Bazı cihazlarda yenileme hızı değiştirilirken bir veya iki saniyeliğine siyah ekran gibi görsel kesintiler yaşanabilir. Bu durum genellikle set üstü kutularda, TV panellerinde ve benzer cihazlarda görülür. Android çerçevesi, bu tür görsel kesintileri önlemek için Surface.setFrameRate() API'si çağrıldığında varsayılan olarak mod değiştirmez.

Bazı kullanıcılar, daha uzun videoların başında ve sonunda görsel bir kesinti olmasını tercih eder. Bu sayede ekranın yenileme hızı, video kare hızıyla eşleşir ve film oynatırken 3:2 pulldown titremesi gibi kare hızı dönüştürme kusurları önlenir.

Bu nedenle, hem kullanıcı hem de uygulamalar etkinleştirirse kesintisiz olmayan yenileme hızı geçişleri etkinleştirilebilir:

Film gibi uzun süreli videolar için her zaman CHANGE_FRAME_RATE_ALWAYS kullanmanızı öneririz. Bunun nedeni, video kare hızını eşleştirmenin avantajının, yenileme hızı değiştirilirken meydana gelen kesintiden daha ağır basmasıdır.

Ek öneriler

Sık karşılaşılan senaryolar için aşağıdaki önerileri uygulayın.

Birden çok yüzey

Android platformu, farklı kare hızı ayarlarına sahip birden fazla yüzeyin bulunduğu senaryoları doğru şekilde işleyecek şekilde tasarlanmıştır. Uygulamanızda farklı kare hızlarına sahip birden fazla yüzey varsa her yüzey için doğru kare hızıyla setFrameRate() yöntemini çağırın. Cihaz, bölünmüş ekran veya pencere içinde pencere modunu kullanarak aynı anda birden fazla uygulama çalıştırsa bile her uygulama kendi yüzeyleri için setFrameRate() yöntemini güvenli bir şekilde çağırabilir.

Platform, uygulamanın kare hızına geçmez.

Cihaz, uygulamanın setFrameRate() çağrısında belirttiği kare hızını desteklese bile ekranı bu yenileme hızına geçirmeyebilir. Örneğin, daha yüksek öncelikli bir yüzeyin kare hızı ayarı farklı olabilir veya cihaz, pil tasarrufu modunda olabilir (pili korumak için ekran yenileme hızına kısıtlama getirilir). Cihaz, ekran yenileme hızını uygulamanın kare hızı ayarına geçirmese bile uygulama doğru şekilde çalışmaya devam etmelidir. Bu durum, cihazın normal koşullarda geçiş yaptığı durumlarda da geçerlidir.

Ekran yenileme hızı, uygulama kare hızıyla eşleşmediğinde nasıl yanıt verileceğine uygulama karar verir. Video için kare hızı, kaynak videonun kare hızına sabitlenir ve video içeriğini göstermek için pulldown gerekir. Bir oyun, tercih ettiği kare hızında kalmak yerine ekran yenileme hızında çalışmayı deneyebilir. Uygulama, platformun yaptığı işleme göre setFrameRate() parametresine ilettiği değeri değiştirmemelidir. Platformun, uygulamanın isteğine uymadığı durumları uygulamanın nasıl ele aldığına bakılmaksızın, uygulamanın tercih ettiği kare hızına ayarlanmış olarak kalmalıdır. Böylece, cihaz koşulları ek ekran yenileme hızlarının kullanılmasına izin verecek şekilde değişirse platform, uygulamanın tercih edilen kare hızına geçmek için doğru bilgilere sahip olur.

Uygulamanın ekran yenileme hızında çalışmayacağı veya çalışamayacağı durumlarda uygulama, platformun sunum zaman damgalarını ayarlama mekanizmalarından birini kullanarak her kare için sunum zaman damgalarını belirtmelidir:

Bu zaman damgalarının kullanılması, platformun uygulama karesini çok erken sunmasını engeller. Bu da gereksiz titremeye neden olur. Kare sunumu zaman damgalarının doğru kullanımı biraz karmaşıktır. Oyunlarda titremeyi önleme hakkında daha fazla bilgi için kare hızı kılavuzumuzu inceleyin ve Android Kare Hızı kitaplığını kullanmayı düşünün.

Bazı durumlarda platform, uygulamanın setFrameRate() içinde belirttiği kare hızının katına geçebilir. Örneğin, bir uygulama 60 Hz ile setFrameRate() çağrısı yapabilir ve cihaz, ekranı 120 Hz'e geçirebilir. Bunun bir nedeni, başka bir uygulamanın 24 Hz kare hızı ayarına sahip bir yüzeyi olması olabilir. Bu durumda, ekranı 120 Hz'de çalıştırmak, hem 60 Hz hem de 24 Hz yüzeyin pulldown işlemi gerekmeden çalışmasını sağlar.

Ekran, uygulamanın kare hızının katı olan bir hızda çalışırken uygulamanın, gereksiz titremeyi önlemek için her kare için sunum zaman damgalarını belirtmesi gerekir. Oyunlar için Android Frame Pacing kitaplığı, kare sunumu zaman damgalarını doğru şekilde ayarlamak açısından faydalıdır.

setFrameRate() ve preferredDisplayModeId karşılaştırması

WindowManager.LayoutParams.preferredDisplayModeId, uygulamaların kare hızlarını platforma bildirmesinin başka bir yoludur. Bazı uygulamalar, ekran çözünürlüğü gibi diğer ekran modu ayarlarını değiştirmek yerine yalnızca ekran yenileme hızını değiştirmek ister. Genel olarak preferredDisplayModeId yerine setFrameRate() kullanın. setFrameRate() işlevinin kullanımı daha kolaydır çünkü uygulamanın, belirli bir kare hızına sahip bir mod bulmak için görüntüleme modları listesinde arama yapması gerekmez.

setFrameRate(), farklı kare hızlarında çalışan birden fazla yüzeyin bulunduğu senaryolarda platformun uyumlu bir kare hızı seçmesi için daha fazla fırsat sunar. Örneğin, Pixel 4'te bölünmüş ekran modunda çalışan iki uygulama olduğunu varsayalım. Bu uygulamalardan biri 24 Hz video oynatırken diğeri kullanıcıya kaydırılabilir bir liste gösteriyor. Pixel 4, iki ekran yenileme hızını destekler: 60 Hz ve 90 Hz. preferredDisplayModeId API'si kullanıldığında video yüzeyi 60 Hz veya 90 Hz'yi seçmeye zorlanır. Video yüzeyi, 24 Hz ile setFrameRate() yöntemini çağırarak platforma kaynak videonun kare hızı hakkında daha fazla bilgi verir. Böylece platform, ekran yenileme hızı için 90 Hz'i seçebilir. Bu senaryoda 90 Hz, 60 Hz'den daha iyidir.

Ancak setFrameRate() yerine preferredDisplayModeId kullanılması gereken durumlar da vardır. Örneğin:

  • Uygulama, çözünürlüğü veya diğer görüntü modu ayarlarını değiştirmek istiyorsa preferredDisplayModeId tuşunu kullanın.
  • Platform, yalnızca mod geçişi basitse ve kullanıcı tarafından fark edilme olasılığı düşükse setFrameRate() çağrısına yanıt olarak görüntüleme modlarını değiştirir. Uygulama, ağır bir mod geçişi gerektirse bile ekran yenileme hızını değiştirmeyi tercih ediyorsa (ör. Android TV cihazda) preferredDisplayModeId kullanın.
  • Ekranın, uygulamanın kare hızının katı olan bir hızda çalışmasını işleyemeyen uygulamalar (her karede sunum zaman damgalarının ayarlanmasını gerektirir) preferredDisplayModeId kullanmalıdır.

setFrameRate() ve preferredRefreshRate karşılaştırması

WindowManager.LayoutParams#preferredRefreshRate, uygulamanın penceresinde tercih edilen bir kare hızı ayarlar ve bu hız, penceredeki tüm yüzeyler için geçerlidir. Uygulama, cihazın desteklediği yenileme hızlarından bağımsız olarak tercih ettiği kare hızını belirtmelidir. Bu, setFrameRate() yöntemine benzer şekilde, zamanlayıcıya uygulamanın amaçlanan kare hızı hakkında daha iyi bir ipucu verir.

preferredRefreshRate, setFrameRate() kullanan yüzeyler için yoksayılır. Genel olarak mümkünse setFrameRate() kullanın.

preferredRefreshRate ve preferredDisplayModeId karşılaştırması

Uygulamalar yalnızca tercih edilen yenileme hızını değiştirmek istiyorsa preferredDisplayModeId yerine preferredRefreshRate kullanılması tercih edilir.

setFrameRate() yöntemini çok sık çağırmaktan kaçınma

setFrameRate() çağrısı performans açısından çok maliyetli olmasa da uygulamalar her karede veya saniyede birden fazla kez setFrameRate() çağrısı yapmaktan kaçınmalıdır. setFrameRate() çağrıları, ekran yenileme hızında değişikliğe neden olabilir. Bu da geçiş sırasında kare düşüşüne yol açabilir. Doğru kare hızını önceden belirlemeniz ve setFrameRate() yöntemini bir kez çağırmanız gerekir.

Oyunlar veya video dışı diğer uygulamalar için kullanım

setFrameRate() API'sinin birincil kullanım alanı video olsa da diğer uygulamalar için de kullanılabilir. Örneğin, 60 Hz'den yüksek hızda çalıştırılmak istenmeyen bir oyun (güç kullanımını azaltmak ve daha uzun oyun oturumları elde etmek için) Surface.setFrameRate(60, Surface.FRAME_RATE_COMPATIBILITY_DEFAULT) yöntemini çağırabilir. Bu sayede, varsayılan olarak 90 Hz'de çalışan bir cihaz, oyun etkinken 60 Hz'de çalışır. Böylece, oyun 60 Hz'de çalışırken ekran 90 Hz'de çalışsaydı oluşacak titreme önlenir.

FRAME_RATE_COMPATIBILITY_FIXED_SOURCE kullanımı

FRAME_RATE_COMPATIBILITY_FIXED_SOURCE yalnızca video uygulamaları için tasarlanmıştır. Video dışı kullanım için FRAME_RATE_COMPATIBILITY_DEFAULT kullanın.

Kare hızını değiştirmek için strateji seçme

  • Uygulamaların, film gibi uzun videoları gösterirken setFrameRate(fps, FRAME_RATE_COMPATIBILITY_FIXED_SOURCE, CHANGE_FRAME_RATE_ALWAYS) değerini çağırmasını önemle tavsiye ederiz. Burada fps, videonun kare hızıdır.
  • Video oynatmanın birkaç dakika veya daha kısa sürmesini beklediğinizde uygulamaların CHANGE_FRAME_RATE_ALWAYS ile setFrameRate() yöntemini çağırmasını kesinlikle önermiyoruz.

Video oynatma uygulamaları için örnek entegrasyon

Video oynatma uygulamalarında yenileme hızı anahtarlarını entegre etmek için aşağıdaki adımları uygulamanızı öneririz:

  1. changeFrameRateStrategy belirleyin:
    1. Film gibi uzun bir video oynatıyorsanız MATCH_CONTENT_FRAMERATE_ALWAYS kullanın.
    2. Film fragmanı gibi kısa bir video oynatıyorsanız CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS kullanın.
  2. changeFrameRateStrategy CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS ise 4. adıma gidin.
  3. Aşağıdaki iki durumun da geçerli olup olmadığını kontrol ederek kesintisiz olmayan bir yenileme hızı geçişinin gerçekleşmek üzere olup olmadığını tespit edin:
    1. Mevcut yenileme hızından (C diyelim) videonun kare hızına (V diyelim) sorunsuz mod geçişi mümkün değildir. C ve V farklıysa ve Display.getMode().getAlternativeRefreshRates, V'nin katını içermiyorsa bu durum geçerli olur.
    2. Kullanıcı, kesintisiz olmayan yenileme hızı değişikliklerini etkinleştirmiştir. Bunu, DisplayManager.getMatchContentFrameRateUserPreference işlevinin MATCH_CONTENT_FRAMERATE_ALWAYS döndürüp döndürmediğini kontrol ederek tespit edebilirsiniz.
  4. Geçiş sorunsuz olacaksa aşağıdakileri yapın:
    1. setFrameRate yöntemini çağırın ve fps, FRAME_RATE_COMPATIBILITY_FIXED_SOURCE ve changeFrameRateStrategy değerlerini iletin. Burada fps, videonun kare hızıdır.
    2. Video oynatmayı başlatma
  5. Sorunsuz olmayan bir mod değişikliği gerçekleşmek üzereyse aşağıdakileri yapın:
    1. Kullanıcıyı bilgilendirmek için kullanıcı deneyimini gösterin. Kullanıcının bu kullanıcı deneyimini kapatması ve 5.d adımındaki ek gecikmeyi atlaması için bir yöntem uygulamanızı öneririz. Bunun nedeni, önerilen gecikme süremizin, daha hızlı geçiş süreleri sergileyen ekranlarda gerekenden daha uzun olmasıdır.
    2. setFrameRate işlevini çağırın ve fps, FRAME_RATE_COMPATIBILITY_FIXED_SOURCE ve CHANGE_FRAME_RATE_ALWAYS değerlerini iletin. Burada fps, videonun kare hızıdır.
    3. onDisplayChanged geri çağırma işlevini bekleyin.
    4. Mod geçişinin tamamlanması için 2 saniye bekleyin.
    5. Video oynatmayı başlatma

Yalnızca otomatik geçişi destekleyen sözde kod aşağıdaki gibidir:

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

Yukarıda açıklandığı gibi sorunsuz ve sorunlu geçişi destekleyen sözde kod aşağıdaki gibidir:

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