The MirAL API should support more options for display configuration

[AlanGriffiths]

While the mirclient API (mir_toolkit/mir_display_configuration.h) provides for configuring the display we have no corresponding Wayland extension. (E.g. for setting the gamma ramp).

Within the MirAL API there is inadequate support for many options: miral::DisplayConfiguration only offers the option to select some basic screen layout choices from a configuration file.

To configure the display within the server currently requires use of the mirserver and mirplatform APIs (mir/graphics/display_configuration.h & mir::Server::wrap_display_configuration_policy()).

We should expose more of these features.

[wmww]

Related to #1831

[programizer]

Would you be able to give some more guidance to someone new trying to fix this? Because right now while I'd like to fix this, I'm not sure that I can...

[RAOF]

So, the broad outline of the problem to solve is: miral only exposes a small subset of the possible configuration options. We don't want to directly expose the underlying Mir types from mir/graphics/display_configuration.h and mir::Server, both because they include implementation details that are uninteresting to the shell, and because those types are subject to change, and MirAL is intended to provide a stable base.

There are a bunch of things that are needed: There needs to be a miral structure describing the relevant aspects of display configuration, there needs to be a miral API for changing that configuration, and there needs to be a miral API for choosing a display configuration when some display event happens (like plugging/unplugging a monitor).

miral::StaticDisplayConfig::apply_to() is an example of how to implement the “choosing a display configuration” bit, and demonstrates some of the internal Mir APIs needed to do the other things.

Fortunately, this could be done a bit at a time - start with a class describing the available connectors, which connectors have displays plugged in, and which displays are active, and the ability to enable/disable a display. That could then be expanded to list the available modes of the plugged in displays, and select the mode, then expanded again to describe/set the orientation, and again to describe/set the gamma ramps, and so on.

[AlanGriffiths]

@programizer as RAOF says, this is something of an epic issue to remind us of the wider considerations. Do you have a specific problem you want to solve that could be a step along the way?

[programizer]

@AlanGriffiths Yes, setting the gamma ramp.

[AlanGriffiths]

Perhaps you could start with adding gamma curves to the static display configuration?

I realise you probably want to change them dynamically, but this would introduce you to the internal APIs you need for that. Once you gain that familiarity, you'll have a better understanding of the options.

[programizer]

To be honest I was simply thinking in terms of reducing the brightness of RGB components by, say, a factor. I'm not so familiar with the term "gamma curve" itself, although I just looked it up. Would one gamma curve correspond to, for example, R=100%, G=98%, B=2%?
What I would need this for as a user is making the display color warmer over all (or plainly lowering just blue, which includes a UV part as I understand), so the display hurts my eyes less, when I look into it for a longer amount of time.
But yes, if I'm able to add a feature where I can activate just a fixed warmer color profile, that would be great.

[AlanGriffiths]

I'm a bit hazy on the details myself and don't want to confuse you. But each colour has a "curve" indicating the correction at different brightnesses (e.g. there may be a bigger adjustment at lower light levels than at higher levels). Each curve is represented as a vector (and the three vectors need to be the same length).

[RAOF]

So, what we're describing as the “gamma curve” is the hardware LUT (lookup table) that the output hardware uses to translate between pixel values in video memory and the actual values sent to the display hardware.

The lookup tables are typically 256 elements per colour channel, but can be smaller (with intermediate values interpolated) or larger (for higher precision with 10bpc displays).

There's an additional quirk in that I believe HDR support requires changes here, but I don't yet have a good understanding of what. You can probably just ignore it for now.

[AlanGriffiths]

To clarify, the config could say "R=100%, G=98%, B=2%" and the correspondin curves would be 0...max, 0..0.98*max, 0..0.02*max.

[programizer]

I'm having trouble finding mir_toolkit/mir_display_configuration.h.
Did it move to a new location?
I also tried modifying a function called "make_linear_ramp()" or similar just to see some quick first results, but apparently it's never called anywhere by default, because it didn't change anything?

[AlanGriffiths]

Happy New Year!

I'm having trouble finding mir_toolkit/mir_display_configuration.h.
Did it move to a new location?

No, the mirclient API to which it belonged was deprecated with Mir 2.0 and eventually deleted. It has gone, forget it.

I also tried modifying a function called "make_linear_ramp()" or similar just to see some quick first results, but apparently it's never called anywhere by default, because it didn't change anything?

As I recall (am not at computer) it is called by the gbm-kms platform when reporting the current LUT. You need to be using that platform (e.g. running in a VT) for it to be called, but I don't think it actually sets the hardware LUT.

HTH