xrandr: add more information about the transform option in the manpage

Add information about the transformation, stating it's a homogeneous
coordinate transformation and adding the (simplified) pixel calculation
formula. Also and an example of keystone shaping generated using the algorithm
found in xkeystone.

Based on a patch by Eric Piel <eric.piel@tremplin-utc.net>

Signed-off-by: Matthias Hopf <mhopf@suse.de>

1 files changed, 34 insertions, 10 deletions

diff --git a/xrandr.man b/xrandr.man
index 1fceeb6..d1a767e 100644
--- a/xrandr.man
+++ b/xrandr.man
@@ -150,22 +150,40 @@ size with \fI--fb\fP simultaneously.
 .IP "\-\-transform \fIa\fP,\fIb\fP,\fIc\fP,\fId\fP,\fIe\fP,\fIf\fP,\fIg\fP,\fIh\fP,\fIi\fP"
 Specifies a transformation matrix to apply on the output. Automatically a bilinear filter is selected.
 The mathematical form corresponds to:
-.RS 
-.RS 
+.RS
+.RS
 a b c
 .br
 d e f
 .br
 g h i
 .RE
-The transformation matrix multiplied by a coordinate vector of a pixel of the
-output (extended to 3 values) gives the approximate coordinate vector of a pixel
-in the graphic buffer. Typically, \fIa\fP and
+The transformation is based on homogeneous coordinates. The matrix multiplied
+by the coordinate vector of a pixel of the output gives the transformed
+coordinate vector of a pixel in the graphic buffer.  More precisely, the vector
+.RI "(x y)"
+of the output pixel is extended to 3 values
+.RI "(x y w),"
+with 1 as the w coordinate and multiplied against the matrix. The final device
+coordinates of the pixel are then calculated with the so-called homogenic
+division by the transformed w coordinate.  In other words, the device
+coordinates
+.RI "(x' y')"
+of the transformed pixel are:
+.RS
+x' = (ax + by + c) / w'   and
+.br
+y' = (dx + ey + f) / w'   ,
+.br
+with  w' = (gx + hy + i)  .
+.RE
+Typically, \fIa\fP and
 \fIe\fP corresponds to the scaling on the X and Y axes, \fIc\fP and \fIf\fP
-corresponds to the tranlastion on those axes, and \fIg\fP, \fIh\fP, and \fIi\fP
-are respectively 0, 0 and 1. It also allows to express a rotation of an angle T
-with:
-.RS 
+corresponds to the translation on those axes, and \fIg\fP, \fIh\fP, and \fIi\fP
+are respectively 0, 0 and 1. The matrix can also be used to express more
+complex transformations such as keystone shaping, or rotation.  For a
+rotation of an angle T, this formula can be used:
+.RS
 cos T  -sin T   0
 .br
 sin T   cos T   0
@@ -313,8 +331,14 @@ big VGA screen display the surrounding of the mouse at normal size.
 .RS 
 xrandr --fb 3200x2000 --output LVDS --scale 2.5x2.5 --output VGA --pos 0x0 --panning 3200x2000+0+0/3200x2000+0+0/64/64/64/64
 .RE
+.PP
+Displays the VGA output in keystone shape so that it is projected correctly
+when the beamer is slightly above the screen:
+.RS 
+xrandr --fb 1024x768 --output VGA --transform 1.24,0.16,-124,0,1.24,0,0,0.000316,1
+.RE
 .SH "SEE ALSO"
-Xrandr(3), cvt(1)
+Xrandr(3), cvt(1), xkeystone(1)
 .SH AUTHORS
 Keith Packard,
 Open Source Technology Center, Intel Corporation.