randr: Add non-desktop output property and behaviors [v3]

non-desktop devices are those to which the normal desktop environment
should not be extended. Examples are Head-mounted displays and the
Apple Touch Bar.

How an output device is set to non-desktop is not part of this
proposal; it is expected that the underlying operating system will
provide this information and have it reflected to X applications
through this extension.

v2: fix puncutation and duplicated 'the'.
v3: switch to 32-bit property named non-desktop to match Linux

Signed-off-by: Keith Packard <keithp@keithp.com>

include/X11/extensions/randr.h

@@ -196,6 +196,7 @@ typedef unsigned long	XRandrModeFlags;
 #define RR_PROPERTY_BORDER_DIMENSIONS	"BorderDimensions"
 #define RR_PROPERTY_GUID		"GUID"
 #define RR_PROPERTY_RANDR_TILE		"TILE"
+#define RR_PROPERTY_NON_DESKTOP		"non-desktop"
 
 /* roles this device can carry out */
 #define RR_Capability_None 0

randrproto.txt

@@ -194,14 +194,23 @@ just mark them as disconnected.
 
 1.6. Introduction to version 1.6 of the extension
 
-Version 1.6 adds resource leasing.
+Version 1.6 adds resource leasing and non desktop output management.
 
- • A 'Lease' is a collection of crtcs and outputs which are made
+ • A “Lease” is a collection of crtcs and outputs which are made
    available to a client for direct access via kernel KMS and DRM
    APIs. This is done by passing a suitable file descriptor back to
    the client which has access to those resources. While leased, those
    resources aren't used by the X server.
 
+ • A “non-desktop” output is a device which should not normally be
+   considered as part of the desktop environment. Head-mounted
+   displays and the Apple "Touch Bar" are examples of such
+   devices. A desktop environment should be able to discover which
+   outputs are connected to such devices and, by default, not present
+   normal desktop applications on them. This is done by having
+   RRGetOutputInfo report such devices as Disconnected while reporting
+   all other information about the device correctly.
+
 1.99 Acknowledgments
 
 Our thanks to the contributors to the design found on the xpert mailing
@@ -772,6 +781,12 @@ dynamic changes in the display environment.
 	monitor in some way; for fixed-pixel devices, this would generally
 	indicate which modes match the resolution of the output device.
 
+	Changes in version 1.6 of the protocol:
+
+	When a “non-desktop” device is connected, the 'connection'
+	field will report Disconnected but the remaining fields will
+	report information about the connected device.
+
 ┌───
     RRListOutputProperties
 	output:OUTPUT
@@ -783,6 +798,12 @@ dynamic changes in the display environment.
 	This request returns the atoms of properties currently defined on
 	the output.
 
+	Changes in version 1.6 of the protocol:
+
+	When a “non-desktop” device is connected, the property list
+	will be correct for the device, even though RRGetOutputInfo
+	reports the device as disconnected.
+
 ┌───
     RRQueryOutputProperty
 	output: OUTPUT
@@ -814,6 +835,12 @@ dynamic changes in the display environment.
 	changed by clients. Immutable properties are interpreted by the X
 	server.
 
+	Changes in version 1.6 of the protocol:
+
+	When a “non-desktop” device is connected, the property information
+	will be correct for the device, even though RRGetOutputInfo
+	reports the device as disconnected.
+
 ┌───
     RRConfigureOutputProperty
 	output: OUTPUT
@@ -932,6 +959,12 @@ dynamic changes in the display environment.
 	is True and the bytes-after is zero, the property is also deleted
 	from the output, and a RROutputPropertyNotify event is generated.
 
+	Changes in version 1.6 of the protocol:
+
+	When a “non-desktop” device is connected, the property value
+	will be correct for the device, even though RRGetOutputInfo
+	reports the device as disconnected.
+
 ┌───
     RRCreateMode
 	window: WINDOW
@@ -1821,6 +1854,12 @@ factors, such as re-cabling a monitor, etc.
 	precise change can be detected by examining the new state of the
 	system.
 
+	Changes in version 1.6 of the protocol:
+
+	When a “non-desktop” device is connected, this event will be
+	delivered when the connection status of the output changes,
+	however the 'connection' value will be set to 'Disconnected'.
+
 ┌───
     RROutputPropertyNotify:
 	window: WINDOW			window requesting notification
@@ -1960,6 +1999,13 @@ as long as the semantics are not altered.  Clients SHOULD fall back
 gracefully to lower version functionality, though, if the driver
 doesn't handle a mandatory property correctly.
 
+Changes in version 1.6 of the protocol:
+
+When a “non-desktop” device is connected, the property information
+will be correct for the device, even though RRGetOutputInfo
+reports the device as disconnected. The “non-desktop” property will be
+set to 1 for such devices and not present on other devices.
+
 9.1 Known properties
 
     "Backlight"			aka RR_PROPERTY_BACKLIGHT
@@ -2060,6 +2106,29 @@ doesn't handle a mandatory property correctly.
 	output. Should include main EDID data and all extension
 	blocks. Previously known as EdidData.
 
+    “non-desktop”	aka RR_PROPERTY_NON_DESKTOP
+	Type:			INTEGER
+	Format:			32
+	Num items:		1
+	Flags			Immutable
+	Range/List:		0-1
+
+	Indicates whether the device attached to this output should not
+	be considered part of the normal desktop. When set to 0 or not
+	present, the output should be presented as part of the
+	desktop.
+
+	When set to 1, the output should not be presented as part of
+	the desktop. To not present an output as part of the desktop,
+	the normal desktop environment should not be shown on this
+	output, nor should desktop applications be positioned on it.
+
+	When set to 1, RRGetOutputInfo will always report connection status
+	Disconnected, but RROutputChangeNotify events will still be
+	delivered when the connection status changes and all other
+	information about the output and connected device will be
+	reported correctly.
+
     "SignalFormat"		aka RR_PROPERTY_SIGNAL_FORMAT
 	Type:			ATOM
 	Format:			32
@@ -2250,6 +2319,13 @@ GUID				yes		not mandatory
 Property			Immutable	Mandatory since
 ────────			─────────	───────────────
 TILE				yes		not mandatory
+
+9.8 Properties introduced with version 1.6 of the RandR extension
+
+Property			Immutable	Mandatory since
+────────			─────────	───────────────
+non-desktop			yes		not mandatory
+
 			      ❧❧❧❧❧❧❧❧❧❧❧
 
 10. Extension Versioning
@@ -2288,6 +2364,8 @@ list of what each version provided:
 
 	1.5: Added Monitors
 
+	1.6: Added Leases and non-desktop output information.
+
 Compatibility between 0.0 and 1.0 was *NOT* preserved, and 0.0 clients
 will fail against 1.0 servers. The wire encoding op-codes were
 changed for GetScreenInfo to ensure this failure in a relatively
@@ -2296,7 +2374,7 @@ graceful way. Version 1.1 servers and clients are cross compatible with
 compatibility from this point. Version 1.2 offers an extended model of the
 system with multiple output support. Version 1.3 adds a cheap version of
 GetScreenResources to avoid expensive DDC operations, CRTC transformations,
-panning, and the primary output concept. Versions 1.2 through 1.4 are
+panning, and the primary output concept. Versions 1.2 through 1.6 are
 backward-compatible with 1.1.
 
 			      ❧❧❧❧❧❧❧❧❧❧❧