protocol: warn clients about some wl_output properties
All wl_output properties don't always make sense for all
compositors.
Some compositors might not implement a "global compositor space",
(e.g. 3D compositors) in which case properties like x and y don't
make sense.
Some compositors might expose virtual outputs, in which case modes,
make and model are not relevant.
In a lot of these situations, information from xdg_output is better
suited.
Compositors also expose output refresh rate, which shouldn't be used
for synchronization purposes.
Signed-off-by: Simon Ser <contact@emersion.fr>
Reviewed-by: Daniel Stone <daniels@collabora.com>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Derek Foreman <derek.foreman.wayland@gmail.com>
Simon Ser authored 5 years ago
Derek Foreman committed 5 years ago
| 2406 | 2406 | |
| 2407 | 2407 | The physical size can be set to zero if it doesn't make sense for this |
| 2408 | 2408 | output (e.g. for projectors or virtual outputs). |
| 2409 | ||
| 2410 | Note: wl_output only advertises partial information about the output | |
| 2411 | position and identification. Some compositors, for instance those not | |
| 2412 | implementing a desktop-style output layout or those exposing virtual | |
| 2413 | outputs, might fake this information. Instead of using x and y, clients | |
| 2414 | should use xdg_output.logical_position. Instead of using make and model, | |
| 2415 | clients should use xdg_output.name and xdg_output.description. | |
| 2409 | 2416 | </description> |
| 2410 | 2417 | <arg name="x" type="int" |
| 2411 | 2418 | summary="x position within the global compositor space"/> |
| 2450 | 2457 | the output device. This is not necessarily the same as |
| 2451 | 2458 | the output size in the global compositor space. For instance, |
| 2452 | 2459 | the output may be scaled, as described in wl_output.scale, |
| 2453 | or transformed, as described in wl_output.transform. | |
| 2460 | or transformed, as described in wl_output.transform. Clients | |
| 2461 | willing to retrieve the output size in the global compositor | |
| 2462 | space should use xdg_output.logical_size instead. | |
| 2463 | ||
| 2464 | Clients should not use the refresh rate to schedule frames. Instead, | |
| 2465 | they should use the wl_surface.frame event or the presentation-time | |
| 2466 | protocol. | |
| 2467 | ||
| 2468 | Note: this information is not always meaningful for all outputs. Some | |
| 2469 | compositors, such as those exposing virtual outputs, might fake the | |
| 2470 | refresh rate or the size. | |
| 2454 | 2471 | </description> |
| 2455 | 2472 | <arg name="flags" type="uint" enum="mode" summary="bitfield of mode flags"/> |
| 2456 | 2473 | <arg name="width" type="int" summary="width of the mode in hardware units"/> |