Add Monitors, update version to 1.5 (v2)

v2: [airlied] add get_active to monitor get
interface, to allow normal vs configuration
clients to see active vs all monitors. (r-b by keithp)

Reviewed-by: Dave Airlie <airlied@redhat.com>
Signed-off-by: Keith Packard <keithp@keithp.com>

1 files changed, 178 insertions, 2 deletions

diff --git a/randrproto.txt b/randrproto.txt
index df2c712..d0481c0 100644
--- a/randrproto.txt
+++ b/randrproto.txt
@@ -1,5 +1,5 @@
 	       The X Resize, Rotate and Reflect Extension
-			     Version 1.4.1
+			     Version 1.5.0
 			       2015-03-14
 
 			      Jim Gettys
@@ -149,6 +149,37 @@ be dynamically configured to provide support for:
 
  4) multiple GPU rendering - This replaces Xinerama.
 
+1.5. Introduction to version 1.5 of the extension
+
+Version 1.5 adds monitors
+
+ • A 'Monitor' is a rectangular subset of the screen which represents
+   a coherent collection of pixels presented to the user.
+
+ • Each Monitor is be associated with a list of outputs (which may be
+   empty).
+
+ • When clients define monitors, the associated outputs are removed from
+   existing Monitors. If removing the output causes the list for that
+   monitor to become empty, that monitor will be deleted.
+
+ • For active CRTCs that have no output associated with any
+   client-defined Monitor, one server-defined monitor will
+   automatically be defined of the first Output associated with them.
+
+ • When defining a monitor, setting the geometry to all zeros will
+   cause that monitor to dynamically track the bounding box of the
+   active outputs associated with them
+
+This new object separates the physical configuration of the hardware
+from the logical subsets  the screen that applications should
+consider as single viewable areas.
+
+1.5.1. Relationship between Monitors and Xinerama
+
+Xinerama's information now comes from the Monitors instead of directly
+from the CRTCs. The Monitor marked as Primary will be listed first.
+
 1.99 Acknowledgments
 
 Our thanks to the contributors to the design found on the xpert mailing
@@ -162,7 +193,9 @@ David Dawes for XFree86 DDX integration work
 Thomas Winischhofer for the hardware-accelerated SiS rotation implementation
 Matthew Tippett and Kevin Martin for splitting outputs and CRTCs to more
 fully expose what video hardware can do
-Dave Airlie for the 1.4.0 protocol changes.
+Dave Airlie for the 1.4.0 protocol changes and for working through the
+implications of MST monitors and encouraging the introduction of the
+'Monitor' concept.
 
 			      ❧❧❧❧❧❧❧❧❧❧❧
 
@@ -365,6 +398,21 @@ PROVIDER_CAPS { SourceOutput, SinkOutput, SourceOffload, SinkOffload }
 
 			      ❧❧❧❧❧❧❧❧❧❧❧
 
+5.6. Protocol Types added in version 1.5 of the extension
+
+MONITORINFO { name: ATOM
+              primary: BOOL
+	      automatic: BOOL
+	      x: INT16
+	      y: INT16
+	      width: CARD16
+	      height: CARD16
+	      width-in-millimeters: CARD32
+	      height-in-millimeters: CARD32
+	      outputs: LISTofOUTPUT }
+
+			      ❧❧❧❧❧❧❧❧❧❧❧
+
 6. Extension Initialization
 
 The name of this extension is "RANDR".
@@ -1539,6 +1587,79 @@ dynamic changes in the display environment.
 
 
 			      ❧❧❧❧❧❧❧❧❧❧❧
+
+7.5. Extension Requests added in version 1.5 of the extension.
+
+┌───
+    RRGetMonitors
+	window : WINDOW
+	get_active : BOOL
+     ▶
+	timestamp: TIMESTAMP
+	monitors: LISTofMONITORINFO
+└───
+	Errors: Window
+
+	Returns the list of Monitors for the screen containing
+	'window'. If 'get_active' is set it returns only active
+	monitors (non-0x0 monitors).  'get_active' should always
+	be set by toolkits, and not by configuration clients.
+
+	'timestamp' indicates the server time when the list of
+	monitors last changed.
+
+┌───
+    RRSetMonitor
+	window : WINDOW
+	info: MONITORINFO
+└───
+	Errors: Window, Output, Atom, Value
+
+	Create a new monitor. Any existing Monitor of the same name is deleted.
+
+	'name' must be a valid atom or an Atom error results.
+
+	'name' must not match the name of any Output on the screen, or
+	a Value error results.
+
+	If 'info.outputs' is non-empty, and if x, y, width, height are all
+	zero, then the Monitor geometry will be dynamically defined to
+	be the bounding box of the geometry of the active CRTCs
+	associated with them.
+
+	If 'name' matches an existing Monitor on the screen, the
+	existing one will be deleted as if RRDeleteMonitor were called.
+
+	For each output in 'info.outputs, each one is removed from all
+	pre-existing Monitors. If removing the output causes the list of
+	outputs for that Monitor to become empty, then that Monitor will
+	be deleted as if RRDeleteMonitor were called.
+
+	Only one monitor per screen may be primary. If 'info.primary'
+	is true, then the primary value will be set to false on all
+	other monitors on the screen.
+
+	RRSetMonitor generates a ConfigureNotify event on the root
+	window of the screen.
+
+┌───
+    RRDeleteMonitor
+	window : WINDOW
+	name: ATOM
+└───
+	Errors: Window, Atom, Value
+
+	Deletes the named Monitor.
+
+	'name' must be a valid atom or an Atom error results.
+
+	'name' must match the name of a Monitor on the screen, or a
+	Value error results.
+
+	RRDeleteMonitor generates a ConfigureNotify event on the root
+	window of the screen.
+
+			      ❧❧❧❧❧❧❧❧❧❧❧
 8. Extension Events
 
 Clients MAY select for ConfigureNotify on the root window to be
@@ -2044,6 +2165,8 @@ list of what each version provided:
 
         1.4: Added provider objects for handling multi-GPU systems.
 
+	1.5: Added Monitors
+
 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
@@ -2194,6 +2317,23 @@ A.1 Common Types
 	0x00000008	SinkOffload
 └───
 
+A.1.1 Common Types added in version 1.5 of the protocol
+
+┌───
+    MONITORINFO (16 + 4*n)
+	4	ATOM		name
+	1	BOOL		primary
+	1	BOOL		automatic
+	2	CARD16		ncrtcs
+	2	INT16		x
+	2	INT16		y
+	2	CARD16		width in pixels
+	2	CARD16		height in pixels
+	4	CARD32		width in millimeters
+	4	CARD32		height in millimeters
+	4*n	CRTC		crtcs
+└───
+
 A.2 Protocol Requests
 
 Opcodes 1 and 3 were used in the 0.0 protocols, and will return
@@ -2932,6 +3072,42 @@ A.2.3 Protocol Requests added with version 1.4
 	p				unused, p=pad(n)
 └───
 
+A.2.4 Protocol Requests added with version 1.5
+
+┌───
+    RRGetMonitors
+	1	CARD8			major opcode
+	1	42			RandR opcode
+	2	2			request length
+	4	WINDOW			window
+     ▶
+	1	1			Reply
+	1				unused
+	2	CARD16			sequence number
+	4	6*n + o			reply length
+	4	TIMESTAMP		timestamp
+	4	n			nmonitors
+	4	o			noutputs
+	12				unused
+	n*24+o*4 LISTofMONITORINFO	monitors
+└───
+┌───
+    RRSetMonitor
+	1	CARD8			major opcode
+	1	43			RandR opcode
+	2	6 + o			request length
+	4	WINDOW			window
+	24+o	MONITORINFO		monitorinfo
+└───
+┌───
+    RRDeleteMonitor
+	1	CARD8			major opcode
+	1	44			RandR opcode
+	2	3			request length
+	4	WINDOW			window
+	4	ATOM			name
+└───
+
 A.3 Protocol Events
 
 ┌───