RandR 1.2 output properties and options

[Dirk Thierbach]

On Fri, Nov 17, 2006 at 10:45:41AM -0800, Keith Packard wrote:
> Output devices occasionally need more information than is provided in
> the mode line to correctly program the hardware. LVDS panels need
> scaling information, TV outputs need all kinds of data. Most of these
> options don't affect whether the modeline can be supported by the
> hardware, rather they affect what the hardware will do with a specific
> modeline. 

I'd again like to point out that for TV encoders, this view doesn't
reflect reality very well. A substantial part of the data needed is
intimately coupled to the modeline (and cannot be calculated from the
modeline). Another part of the data (that determines the TV system,
e.g. NTSC or PAL) is more loosely coupled (the total number of 
625 resp. 525 TV lines affects the overall timing). A third, small
part is really independent (various forms of filters or enhancements,
controls like contrast, brightness, saturation).

Examples:

- (Older) Chrontel encoders have a fixed number of modes, with 
  fixed timings. For each mode, they need a particular modeline. 
  There is some limited flexibility to adjust for the horizontal sync, 
  and one can play some games by not using the full resolution (say,
  720 out of 800 pixels for modes to display DVD images), but that's
  about all.
- Conexant encoders are quite flexible, but because they don't use a
  horizontal scaler, they are limited by the size of the internal FIFO.
  So the desired TV image size and resolution determines the modeline
  (and not the other way round).
- Philips encoders do have a horizontal scaler, so they can adapt to
  a wider range of modelines. But for best image quality, it's 
  desireable not to do any horizontal scaling. Also, vertical scaling
  and the flicker filter are coupled in this encoder, and both are
  again restricted by the size of internal FIFOs (unfortunately, the
  documentation doesn't have enough details on this). The result is
  that especially for some flicker filter settings, the range of 
  modeline/encoder timing data that works is quite narrow, and they
  have to determined by trial and error.

And it gets worse, because graphic cards also require additional timing
information that's different from the usual modeline/CRTC association:

- NVidia GPUs seem to use the sync values differently when slaved to
  a TV encoder in master mode. The corresponding modelines would be 
  rejected by X, because some sync values are out of range.
- At least some NVidia GPUs require a second set of additional 
  modeline-like values in special registers when the encoder is used in 
  slave mode.
- The Voodoo3 GPU also requires additional values (blanking) when
  using the TV.
- The Intel i810 will store the modeline in registers different from
  the CRTC when using a TV (it doesn't use the more general design
  in later Intels).

> As such, they need to be separate from the modeline and associated
> only with the output.

So again, I'd like to advocate to switch (at least in the long run)
to a more general design of having "functional blocks" of data,
of which the modeline is just one particular block. This would make
transition simple and smooth, drivers which are not affected could
just go on using the old modeline infrastructure.

The (small) number of values which *are* separate from the modeline
(i.e., brightness, contrast, hue, gamma, filters, etc.), and which
should be freely adjustable by the user, could then be associated to
each "functional block" similar to the way it's done for the video
port attributes.

And that isn't restricted to the outputs. For example, the NVidia GPU
has a "color saturation boost" feature which would fit perfectly into
this scheme. And of course the gamma correction I already mentioned.
These are tied to the CRTC, not to the output. So it really makes sense
to have these attributes for each "functional block".

> In addition, outputs have options (like color controls) which can be
> adjusted while the modeline is active. It doesn't make sense to reset
> the configuration just to adjust simple output parameters like this.
> 
> Independently, we created this notion of 'output properties' which were
> designed communicate information about the hardware to (and potentially
> from) applications. A simple example here is the EDID data -- the output
> device will set the EDID property to report to applications the data
> provided by the monitor about its capabilities. Taking that the other
> direction, an application may decided to override that EDID data and
> supply its own. In doing so, the X server will recalculate the list of
> supported modes and present that in the other parts of the RandR
> protocol. 

I am not sure if it is wise to mix "simple" controls like color
adjustments (which are independent from the modeline) with more
complex controls that completely change the modes (and hence the
modelines) that are available.

That will at least confuse clients that are not aware that the list
of available modes can be changed through a "backdoor". And EDID
data is not the only way to construct a list of modes (when using a TV,
it would make sense for an application to ask the driver "give me a mode
with that resolution and about that TV image size/overscan", and
the driver could calculate a list of modes that come close).

So if the goal is to have more flexibility in this area, this should
really be part of an overhaul of the modesetting, to make it somewhat
more consistent.

> One problem with the property mechanism is that, unlike options, there
> was no explicit time at which the property would take effect. Options
> were provided as a part of the mode setting operation, properties were
> set separately.

Yes. That's another indication they should be treated differently:

There's data which is part of the modesetting (what you call "options",
and I called "functional blocks"), which is somewhat heavyweight,
can be calculated from EDID, from the config file, or on request.
Then this data can be used to switch modes.

And there's data like the color adjustments, (what you call
"properties", and I called "attributes"), which is lightweight and can
be changed immediately, independent of any mode.

Mixing those would just cause confusion IMHO.

> In addition, the valid range of property settings isn't explictly
> provided in the protocol while the valid option settings were. Not
> knowing what possible values a property might take makes it impossible
> for applications to accurately present them to the user.

Yes. So provide two different interfaces: For the attributes
("properties"), just list the possible ranges or values. Then the
application can present those to the user, and the user can change
them as he likes.

For the modesetting, invent some general mechanism to let the user
specify what he kind of mode he wants (maybe again using well-known
attributes with defined ranges/values, like resolution, image size,
image overscan, dpi, etc.), and then ask the driver to find a list of
modes (i.e., groups of "functional blocks"), which come close.

> So, I think properties need to contain several fields:
> 
>       * Current value. This is what the hardware is currently using.
>       * Pending value. This is what the hardware will use the next time
>         it is configured.
>       * Range of valid values. For ordered sets, this can just be a
>         simple pair of minimum/maximum limits for the value. For
>         unordered sets, we need a list of valid values.

This won't work if validity of values cannot be determined by looking at
a single value. And this will be almost certainly the case for all
of the timing data needed for the TV encoders, for example. So again,
it's probably not a good idea to express that data in this way. 

>       * Type. Just like window properties, the representation and type
>         are separate, permitting some more accurate type checking.
>       * Name. An atom representing the intended use for the property.

> This raises some interesting questions -- who gets to set the range of
> valid values? Can you set and query the pending value separately from
> the current value?

> I suggest that values controlled by the X server should have a read-only
> range of values. Values created by applications may have a range of
> valid values as well, but the range can be set by applications.
> 
> For properties which have no pending/current split, they will report
> only the current value. I think I will mix the notion of pending/current
> with the range setting request so applications can create new properties
> that work like the built-in properties.

Why don't just go for KISS? Maybe it's just me, but I really don't
understand why keeping the modeline as it is (which was a good
abstraction many years back, but now isn't just general enough) and
adding an overly complicated system of properties is better than
generalizing the modeline a bit (with the option of legacy support),
and keeping the properties/attributes simple and efficient. 

IMHO, the first way will make implementing TV support just
unnecessarily difficult, and it will it also make difficult for
applications to interact with different drivers, if there's no
standardized interface.

- Dirk