Panning protocol description

1 files changed, 110 insertions, 0 deletions

diff --git a/randrproto.txt b/randrproto.txt
index b23e415..5ebbcd9 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.
 	
@@ -1061,6 +1074,103 @@ dynamic changes in the display environment.
 	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