
Buckle up son, we're dumpster-diving into beautiful world of Android dev!
Android so exciting because of all the different vendors and implementations you have to support. And they often disagree on very basic things, such as setting surface refresh rate.
As you know, modern phones have screens going up to 120hz, and once you are used to it there's no coming back. So engineers (not to be confused with vibe sloppers) really want to make apps efficient enough to sustain 120fps load if they want them to feel good. Especially games!
Historically, since about 2014, you would set preferredRefreshRate on WindowManager's LayoutParams, which you would get from a set of predefined supported numbers. This sets refresh rate of the entire display in somewhat authoritarian way. About a year later, they also added preferredDisplayModeId, which combines refresh reate and screen resolution, similarly to how display modes work on Wayland and X11.
But recently (in 2020), a new set of APIs got introduced, that lets you set refresh rate not for entire screen, but per-surface of your app. This allows more granularity, integrates with a new fancy Android frame pacer, and is better for batter life. Even better - this family of APIs is exposed in NDK - so you can easily use it from C/Rust/Jai/Odin without having to go through Java (as you have to with preferredRefreshRate).
And an official documentation _really_ recommends you to use new API, and even says that when you use it simultaneously with an old preferredRefreshRate rate, that old one is completely ignored! Direct quote from Google's official Android dev portal: "preferredRefreshRate is ignored for Surfaces that use setFrameRate(). In general use setFrameRate() if possible."
Here's the issue though. The documentation for this new modern API says, I quote (with emphasis added): "On devices that are capable of running the display at different refresh rates, the system **MAY CHOOSE** a display refresh rate to better match this surface's frame rate."
So it's really a vote kind of API. Technically, you kindly ask the device to give you the refresh rate, but it might say NO for no visible reason.
And, in fact, many devices do. A lot of Chinese Android builds even go as far as to only allow changing refresh rate for some predefined white list of applications. Very elitistic!
But much more of them still obey good old preferredRefreshRate/preferredDisplayModeId from 2014, even though they still might refuse for legitimate reasons (such as battery efficiency mode). So it remains to be the only reliable way to get the refresh rate you actually want, and this is why most programs (knowingly, or through some underlying framework they are written it) still use it.
This is how all this technological research and advancements get completely crushed by lousy implementations, and all it does is just adding more pain for the developers.