[PATCH 02/13] randrproto: Panning protocol description

[Matthias Hopf]

---
 randrproto.txt |  110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 110 insertions(+), 0 deletions(-)

diff --git a/randrproto.txt b/randrproto.txt
index 58c9e40..458c5f9 100644
--- a/randrproto.txt
+++ b/randrproto.txt
@@ -508,6 +508,13 @@ dynamic changes in the display environment.
 	extension and the core protocol. They must be non-zero, or Value
 	error results.
 
+	Note that changes to the screen size might invalidate panning
+	parameters.  In these cases panning might be silently disabled, or the
+	panning parameters are updated automatically as necessary.  The exact
+	behavior of the implementation is undefined.  If the panning parameters
+	do not conflict with new screen size, panning remains enabled
+	unchanged.
+
 ┌───
     RRGetScreenResources
 	window: WINDOW
@@ -938,6 +945,12 @@ dynamic changes in the display environment.
 	then re-enabling the CRTC at the new configuration to avoid an
 	invalid intermediate configuration.
 
+	Note that changes to the CRTC might invalidate panning parameters.  In
+	these cases panning might be silently disabled, or the panning
+	parameters are updated automatically as necessary.  The exact behavior
+	of the implementation is undefined.  If the panning parameters do not
+	conflict with new CRTC parameters, panning remains enabled unchanged.
+
 	When this request succeeds, 'status' contains Success and the
 	requested changes to configuration will have been made.
 	
@@ -1059,6 +1072,103 @@ This request returns the pending and current transforms for the specified
 CRTC. The pending transform will be the same as the current transform if no
 new pending transform has been set since the last call to RRSetCrtcConfig.
 
+┌───
+    RRGetPanning
+	crtc: CRTC
+	config-timestamp: TIMESTAMP
+      â–¶
+	status: RRCONFIGSTATUS
+	timestamp: TIMESTAMP
+	left, top, width, height: CARD16
+	track_left, track_top, track_width, track_height: CARD16
+	border_left, border_top, border_right, border_bottom: INT16
+└───
+
+	Errors: Crtc
+
+	Version 1.3 adds panning support again. If multiple crtcs are active
+	the panning behavior can be defined per crtc individually.
+	RRGetPanning returns information about the currently set panning
+	configuration for the specified crtc.
+
+	If 'config-timestamp' does not match the current configuration
+	timestamp (as returned by RRGetScreenResources), 'status' is set to
+	InvalidConfigTime and the remaining reply data is empty. Otherwise,
+	'status' is set to Success.
+
+	'timestamp' indicates when the configuration was last set.
+
+	All other entries are explained for RRSetPanning.
+
+┌───
+    RRSetPanning
+	crtc: CRTC
+	timestamp: TIMESTAMP
+	config-timestamp: TIMESTAMP
+	left, top, width, height: CARD16
+	track_left, track_top, track_width, track_height: CARD16
+	border_left, border_top, border_right, border_bottom: INT16
+      â–¶
+	status: RRCONFIGSTATUS
+	new-timestamp: TIMESTAMP
+└───
+	Errors: Crtc, Match
+
+	If 'timestamp' is less than the time when the configuration was last
+	successfully set, the request is ignored and InvalidTime returned in
+	status.
+	
+	If 'config-timestamp' is not equal to when the CRTC's configuration
+	last changed, the request is ignored and InvalidConfigTime returned in
+	status. This could occur if the CRTC changed since you last made a
+	RRGetCrtcInfo request, perhaps by setting a different mode.  Rather
+	than allowing an incorrect call to be executed based on stale data,
+	the server will ignore the request.
+
+	'left', 'top', 'width', and 'height' contain the total panning area
+	for this CRTC.  'width' has to be larger than the CRTC's width, and
+	'left'+'width' must be within the screen size, else a Match error
+	results.  Equivalent restrictions for the height exist.  The exception
+	is 'width' == 'height' == 0 which indicates that panning should be
+	disabled.
+
+	'track_left', 'track_top', 'track_width', and 'track_height' contain
+	the pointer area for which the panning region is updated.  For normal
+	use cases it should enclose the panning area minus borders, and is
+	typically set to either the panning area minus borders, or to the
+	total screen size. If set to the total screen size, the CRTC will pan
+	in the remaining axis even if the pointer is outside the panning area
+	on a different CRTC.
+
+	'border_left', 'border_top', 'border_right', and 'border_bottom'
+	define the distances from the CRTC borders that will activate panning
+	if the pointer hits them.  If the borders are 0, the screen will pan
+	when the pointer hits the CRTC borders (behavior of pre-RandR Xserver
+	panning).  If the borders are positive, the screen will pan when the
+	pointer gets close to the CRTC borders, if they are negative, the
+	screen will only pan when the pointer is already way past the CRTC 
+	borders.  Negative values might confuse users and are discouraged.
+	border_left + border_right has to be lower or equal than the CRTC's
+	width, else a Match error results.  An equivalent restriction for the
+	height exists.
+
+	This request sets the panning parameters.  As soon as panning is
+	enabled, the CRTC position can change with every pointer move.
+	RRCrtcChangeNotify events are sent to the clients requesting those.
+
+	Note that changes to the CRTC or screen might invalidate panning
+	parameters.  In these cases panning might be silently disabled, or the
+	panning parameters are updated automatically as necessary.  The exact
+	behavior of the implementation is undefined.  If the panning parameters
+	do not conflict with new CRTC parameters or screen size, panning
+	remains enabled unchanged.
+
+	When this request succeeds, 'status' contains Success and the
+	requested changes to configuration will have been made.
+
+	'new-time-stamp' contains the time at which this request was
+	executed.
+
                               ❧❧❧❧❧❧❧❧❧❧❧
 
 8. Extension Events
-- 
1.5.6