wacom - Wacom input driver
Section "InputDevice"
Identifier "idevname"
Driver "wacom"
Option "Device" "devpath"
...
EndSection
wacom is an X input driver for Wacom devices.
The
wacom driver functions as a pointer input device.
This driver supports the Wacom IV and Wacom V protocols. Serial tablets only
need this driver. USB tablet support is available on some Linux platforms and
requires the wacom kernel driver being loaded before this driver starts.
Please check
https://github.com/linuxwacom for latest updates of Wacom X and
kernel drivers.
When input device hotplugging in the X server is enabled and no
InputDevice section exists for a compatible tablet device and an
InputClass section (see
xorg.conf.d(5x)) assigns this driver for the
device, the
wacom driver creates multiple X devices for each a physical
device, one X device for each available tool. The list of tools is
hardware-dependent. See
Option Type as outlined in the
CONFIGURATION
DETAILS section.
These tool-specific devices are referred to as parent device and dependent
device. The parent device is the one presented by the system and the one that
causes the X server to load the
wacom driver. This parent device then
causes the automatic addition of several dependent devices. If the parent
device is unplugged or otherwise removed, the dependent devices will be
automatically removed as well.
Dependent devices may be assigned tool-specific options through additional
InputClass sections. We recommend that a
MatchDriver wacom line
is used in these sections in addition to the user-specific pattern.
Match directives are applied by the X server before the driver is selected. The
type name of the parent device is appended by the driver. It is not possible
to use a
MatchProduct directive to match against this appended type
name.
Please refer to
xorg.conf(5x) or
xorg.conf.d(5x) for general configuration
details and for options that can be used with all input drivers. This section
only covers configuration details specific to this driver.
Multiple instances of the Wacom devices can cohabit. Each device supports the
following entries:
- Option "Type"
"stylus"|"eraser"|"cursor"|"pad"|"touch"
- sets the type of tool the device represents. This option is
mandatory. The core options, such as "SendCoreEvents" or
"AlwaysCore", are unnecessary in Gimp if you don't need to move
system cursor outside of Gimp drawing area. "pad" is for Intuos
3 or Cintiq 21UX tablet ExpressKeys/menu strips, and Graphire 4 or Bamboo
tablet buttons, wheel, and/or ring. It is required for Intuos3, CintiqV5,
Graphire 4, and Bamboo if you want to use keystroke features.
"pad" is reported as a second tool in the driver.
"touch" is for the tablet with touch support. Right now only a
few Tablet PCs have this feature.
- Option "Device"
"path"
- sets the path to the special file which represents serial
line where the tablet is plugged. You have to specify it for each
subsection with the same value if you want to have multiple devices with
the same tablet. This option is mandatory.
- Option "Suppress"
"number"
- sets the position increment under which not to transmit
coordinates. This entry must be specified only in the first Wacom
subsection if you have multiple devices for one tablet. If you don't
specify this entry, the default value, which is 2, will be used. To
disable suppression, the entry should be specified as 0. When suppress is
defined, an event will be sent only when at least one of the following
conditions is met:
the change between the current X coordinate and the previous one is greater
than suppress;
the change between the current Y coordinate and the previous one is greater
than suppress;
the change between the current pressure and the previous one is greater
than suppress;
the change between the current degree of rotation and the previous one of
the transducer is greater than suppress;
the change between the current absolute wheel value and the previous one is
equal to or greater than suppress;
the change between the current tilt value and the previous one is equal to
or greater than suppress (if tilt is supported);
relative wheel value has changed;
button value has changed;
proximity has changed.
- Option "Mode"
"Relative"|"Absolute"
- sets the mode of the device. The default value for stylus,
pad and eraser is Absolute; cursor is Relative; touch defaults to Relative
for tablets with touch pads and Absolute for touch screens.
- Option "TopX"
"number"
- X coordinate of the top corner of the active zone. Default
to 0.
- Option "TopY"
"number"
- Y coordinate of the top corner of the active zone. Default
to 0.
- Option "BottomX"
"number"
- X coordinate of the bottom corner of the active zone.
Default to width of the tablet.
- Option "BottomY"
"number"
- Y coordinate of the bottom corner of the active zone.
Default to height of the tablet.
- Option "ButtonsOnly"
"on"|"off"
- disables the device's motion events. Default to off.
- Option "ButtonM"
"AC"
- reports an action AC when button M is pressed, where M is
one of the device supported button numbers, it can be 1 to 32. Wacom uses
a driver-internal button mapping, where any physical button appears to the
X server as the button specified by the ButtonM mapping. Hence, if two
physical buttons have the same ButtonM mapping, the server will think they
are the same physical button. The default action reported to the X server
is mouse button M click. Because X uses buttons 4, 5, 6, and 7 as the four
scrolling directions, physical buttons 4 and higher are mapped to 8 and
higher by default. Only simple button presses can be configured here; for
more complex actions, use xsetwacom(1). To ignore the button click, i.e.,
to not report any button click event to the X server, use "0" or
"button 0".
- Option "TPCButton"
"on"|"off"
- enables the stylus buttons as Tablet PC buttons. If
enabled, the stylus reports button events only when its tip is pressed. If
any button is down, pressing the tip reports a button event for the
button. Otherwise if no button is down, the tip reports as usual. Default
to "on" for Tablet PCs; "off" for all other models.
Only available on the stylus tool.
- Option "Touch"
"on"|"off"
- enables touch events for touch devices, i.e., system cursor
moves when user touches the tablet. Default to "on" for devices
that support touch; "off" for all other models.
- Option "Rotate"
"CW"|"CCW"|"HALF"|"NONE"
- rotates the tablet orientation counterclockwise (CCW) or
clockwise (CW) or 180 degrees (HALF). If you have specific tablet
mappings, i.e. TopX/Y or BottomX/Y were set, the mapping will be applied
before rotation. Rotation must be applied to the parent device (usually
the stylus), rotation settings on in-driver hotplugged devices (see
DRIVER-INTERNAL DEVICE HOTPLUGGING ) will be ignored. The default
is "NONE".
- Option "PressCurve"
"x1,y1,x2,y2"
- sets pressure curve by control points x1, y1, x2, and y2.
Their values are in range from 0..100. The pressure curve is interpreted
as Bezier curve with 4 control points, the first and the last control
point being fixed on the coordinates 0/0 and 100/100, respectively. The
middle control points are adjustible by this setting and thus define the
shape of the curve. The input for linear curve (default) is
"0,0,100,100"; slightly depressed curve (firmer) might be
"5,0,100,95"; slightly raised curve (softer) might be
"0,5,95,100". The pressure curve is only applicable to devices
of type stylus or eraser, other devices do not honor this setting.
- Option "Pressure2K"
"bool"
- reduces the pressure range to the range of 0 to 2048 for
backwards compatibility with applications that have this range hardcoded.
See section BUGS. This option should not be used unless the user
runs one or more applications that rely on a hardcoded pressure
range.
- Option "DebugLevel"
"number"
- sets the level of debugging info for tool-specific
messages. There are 12 levels, specified by the integers between 1 and 12.
All debug messages with a level less than or equal to the
"number" will be logged into the Xorg log file. This option is
only available if the driver was built with debugging support.
- Option "CommonDBG"
"number"
- sets the level of debugging info for common (i.e. not
tool-specific) code paths on the tablet. There are 12 levels, specified by
the integers between 1 and 12. All debug messages with a level less than
or equal to the "number" will be logged into the Xorg log file.
This option is only available if the driver was built with debugging
support.
- Option "GrabDevice"
"bool"
- sets whether the underlying event device will be grabbed by
the driver to prevent the data from leaking to /dev/input/mice. When
enabled, while the X server is running, no other programs will be able to
read the event stream. Default: "false".
- Option "CursorProx"
"number"
- sets the distance at which a relative tool is treated as
being out of proximity. Beyond this distance the cursor will stop
responding to tool motion. The default value for pucks is 10 (Intuos Pro)
or 42 (Intuos/Bamboo). The default value for pens is 30.
- Option "RawSample"
"number"
- Set the sample window size (a sliding average sampling
window) for incoming input tool raw data points. Default: 4, range of 1 to
20.
- Option "Serial"
"number"
- sets the serial number associated with the physical device.
This allows to have multiple devices of the same type (i.e. multiple
pens). This option is only available on wacom V devices (Intuos series and
Cintiq 21U). To see which serial number belongs to a device, you need to
run the utility program, xsetwacom, which comes with linuxwacom
package.
- Option "ToolSerials"
"number[,type[,label]][;...]"
- sets the list of serial numbered devices that need to be
hotplugged for a physical device. The 'type' option may be any of
"pen", "airbrush", "artpen", or
"cursor". This option is only available on wacom V devices which
are capable of reporting a serial number. To see if a connected device is
supported, or to identify which serial number belongs to a device, you
need to run the utility program, xsetwacom, that comes with this driver.
In layman's terms, this option will add additional X devices for this
specific tool's tip (and eraser, if applicable). This is useful for
programs like gimp (which remembers tools based on the X device) to recall
additional drawing tool selections for an airbrush+eraser, art pen, extra
pen, etc.
- Option "Threshold"
"number"
- sets the pressure threshold used to generate a button 1
events of stylus. The threshold applies to the normalised pressure range
of [0..2048]. The default is 27.
- Option "Gesture"
"bool"
- Enable or disable multi-finger in-driver gesture support on
the device. Default: off unless the tablet supports multi-touch. Note that
disabling this option may allow the desktop environment to detect
multi-finger gestures instead.
- Option "ZoomDistance"
"number"
- If Option "Gesture" is enabled,
this option specifies the minimum movement distance before a zoom gesture
is recognized.
- Option "ScrollDistance"
"number"
- If Option "Gesture" is enabled,
this option specifies the minimum movement distance before a scroll
gesture is recognized.
- Option "TapTime"
"number"
- If Option "Gesture" is enabled,
this option determines the maximum time of a touch event to be recognized
as tap. A press and release event shorter than TapTime generates
button press and release events. Presses longer than TapTime do not
generate button events, only motion events.
- Option "PressureRecalibration"
"bool"
- Allows to disable pressure recalibration. Default: true. If
the initial pressure of a device is != 0 the driver recalibrates the
pressure range. This is to account for worn out devices. The downside is
that when the user hits the tablet very hard the initial pressure reading
may be unequal to zero even for a perfectly good pen. If the consecutive
pressure readings are not higher than the initial pressure by a threshold
no button event will be generated. This option allows to disable the
recalibration.
- Option "PanScrollThreshold"
"number"
- Specifies the distance the pen must move (in tablet units)
before a scroll event is generated when using the "pan" action.
Smaller values will require less distance and be more sensitive. Larger
values will require more distance and be less sensitive. Default: 1300 or
2600 depending on tablet resolution (corresponds to 13 mm of
distance).
Left click: tap, actual click happens after TapTime period elapses.
Left click drag: tap to select, quickly (within TapTime period) touch
selection again. Then drag. Available on touchpads, e.g. BambooPT, not
touchscreens.
Right click: one finger down + tap second finger
Vertical scroll: two fingers side by side (in any orientation) moving
vertically with constant separation initiates a vertical scroll. By driver
default a gesture up results in a scroll down event (the document moves up)
and a gesture down results in a scroll up event (moving the document down).
Horizontal scroll: two fingers side by side held at a constant distance
moving horizontally initiates a horizontal scroll. A gesture to the left
results in a scroll right event (the document moves left) and a gesture right
results in a scroll left event (moving the document right).
Zoom in: two separated fingers side by side, bring together i.e. pinch.
Zoom out: two fingers side by side, spread. Not all applications support
zoom.
In version 0.34, the driver's pressure range increased from 2048 steps to 65536
steps. The pressure axis range is advertised through the X Input Protocol but
some applications have the previous pressure range hardcoded and cannot handle
pressure values above 2048. This is an application bug but for
backwards-compatibility with such applications, this driver provides the
Pressure2K option to reduce the range to 2048 steps. Note that this
setting applies to the device. Once applied, all applications will see the
reduced pressure range. It is not possible to provide this setting on a
per-application basis.
Xorg(1),
xorg.conf(5),
xorg.conf.d(5),
X(7)
More information is available at
https://github.com/linuxwacom/xf86-input-wacom
Peter Hutterer <
[email protected]>, Ping Cheng
<
[email protected]>, Frederic Lepied <
[email protected]>, John E.
Joganic <
[email protected]>, Magnus Vigerlöf
<
[email protected]>