.\" $OpenBSD: xtsscale.1,v 1.15 2011/07/16 17:32:24 matthieu Exp $
.\"
.\" Copyright (c) 2007 Robert Nagy <robert@openbsd.org>
.\" Copyright (c) 2009 Matthieu Herrb <matthieu@herrb.eu>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OPENBSD PROJECT AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OPENBSD
.\" PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: July 16 2011 $
.Dt XTSSCALE 1
.Os
.Sh NAME
.Nm xtsscale
.Nd X touch screen calibration tool
.Sh SYNOPSIS
.Nm xtsscale
.Bk -words
.Op Fl c
.Op Fl D Ar display
.Op Fl d Ar device
.Op Fl o Ar output
.Op Fl v
.Ek
.Sh DESCRIPTION
.Nm
is used interactively to calculate both the scaling and offset values which
will make the pointer act at the indicated location on the screen.
.Pp
The following options can be used:
.Bl -tag -width Ds
.It Fl c
keep the X cursor visible during calibration.
Useful for indirect absolute devices like tablets.
.It Fl D Ar display
specify the X11 display to use.
.It Fl d Ar device
defines the name or numerical identifier of the X Input extension device
to calibrate.
Use
.Pp
.Dl $ xinput --list
.Pp
to figure out the actual name for the X configuration.
.Ar device
can be omitted if there is only one X extension pointer with
calibration properties in the system.
.It Fl o Ar output
specifies the XRandR output to with the touch screen is connected.
If omitted
.Nm
will use all heads in multi-head configurations, which is probably
not what is expected.
Use
.Pp
.Dl $ xrandr
.Pp
to figure out the names of the outputs.
.It Fl v
specifies that
.Nm
will be verbose, outputting various information, including the
raw coordinate values produced, mostly for debugging purposes.
.El
.Pp
When good deviations are calculated from the selections made at these
points,
.Nm
will exit and provide on standard output a result like the following:
.Pp
.Dl mouse.scale=200,3400,312,3672,0,1024,768
.Pp
This result should be placed into
.Pa /etc/wsconsctl.conf
for further use.
The new calibration is automatically used by the X server.
The calibration process can be interrupted at any time using the ESC
key.
In this case the current screen calibration data will not be modified.
.Sh NOTES
To use
.Nm
the mode of the input device should be set to raw in the
.Pa /etc/X11/xorg.conf
X configuration file. See
.Xr ws 4
for details.
.Pp
.Pa /etc/wsconsctl.conf
cannot currently be used to set the calibration data of a device
that is not the first device. (
.Pa /dev/wsmouse0
)
.Sh SEE ALSO
.Xr xinput 1 ,
.Xr xrandr 1 ,
.Xr uhts 4 ,
.Xr uts 4 ,
.Xr wscons 4 ,
.Xr ws 4 ,
.Xr wsconsctl 8 ,
.Xr X 7
.Sh HISTORY
The
.Nm
command appeared in
.Ox 4.2 .