home | help 
WACOM(4)		    Kernel Interfaces Manual			WACOM(4)

NAME
     wacom - Wacom input driver

SYNOPSIS
     Section "InputClass"
       Identifier "idevname"
       MatchIsTablet "on"
       MatchDevicePath "devpath"
       Driver "wacom"
       Option "..." " ..."
       ...
     EndSection

DESCRIPTION
     wacom is an X input driver for Wacom devices.

     The wacom driver functions as a pointer input device.

SUPPORTED HARDWARE
     This driver supports virtually all tablet devices that are supported by the
     Linux kernel.

     Please  check  https://github.com/linuxwacom  for latest updates of Wacom X
     and kernel drivers.

DRIVER-INTERNAL DEVICE HOTPLUGGING
     Configuration via Section "InputDevice" is discouraged as such devices can-
     not be hotplugged at runtime. Instead users should use Section "InputClass"
     as in the example above. The InputClass section  (see  xorg.conf.d(5))  as-
     signs  this  driver for the device, the wacom driver creates multiple X de-
     vices for each 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 au-
     tomatically 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.

CONFIGURATION DETAILS
     Please refer to xorg.conf(5) or xorg.conf.d(5)  for  general  configuration
     details and for options that can be used with all input drivers.  This sec-
     tion 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 unnec-
	 essary 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 Ex-
	 pressKeys/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 sup-
	 port.	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 only if using  Section  "InputDevice"
	 for static configuration.

     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 pre-
	 vious 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 dri-
	 ver-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  rota-
	 tion.	Rotation  must be applied to the parent device (usually the sty-
	 lus), rotation settings on in-driver hotplugged devices (see DRIVER-IN-
	 TERNAL 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 con-
	 trol 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 com-
	 patibility  with applications that have this range hardcoded.	See sec-
	 tion 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 mes-
	 sages with a level less than or equal to the "number"	will  be  logged
	 into  the  XLibre 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 inte-
	 gers between 1 and 12. All debug messages with a  level  less	than  or
	 equal to the "number" will be logged into the XLibre log file. This op-
	 tion 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  (In-
	 tuos/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  de-
	 vices	which are capable of reporting a serial number. To see if a con-
	 nected 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 air-
	 brush+eraser, art pen, extra pen, etc.

     Option "Threshold" "number"
	 sets the pressure threshold used to generate a button 1 events of  sty-
	 lus.	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  dis-
	 abling  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 move-
	 ment distance before a zoom gesture is recognized.

     Option "ScrollDistance" "number"
	 If Option "Gesture" is enabled, this option specifies the minimum move-
	 ment 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 ini-
	 tial 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 consecu-
	 tive 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 de-
	 pending on tablet resolution (corresponds to 13 mm of distance).

     Option "SmoothPanscrollingEnabled" "bool"
	 Allows  to  disable  smooth  panscrolling. Default: true.  If disabled,
	 panscrolling sends legacy button events instead.   This  option  exists
	 for  backwards  compatibility with applications that have the number of
	 axes on a device limited to 6.  See section BUGS for more details. This
	 option should not be used unless the user runs one or more applications
	 that do not support more than six axes.

TOUCH GESTURES
   Single finger (1FG)
     Left click: tap, actual click happens after TapTime period elapses.

     Left click drag: tap to select, quickly (within TapTime period)  touch  se-
     lection  again.   Then  drag.   Available	on touchpads, e.g. BambooPT, not
     touchscreens.

   Two finger (2FG)
     Right click: one finger down + tap second finger

     Vertical scroll: two fingers side by side (in any orientation) moving  ver-
     tically  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.

BUGS
   Pressure range increase leads to unexpected behavior
     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 Pro-
     tocol  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.

   Smooth panscrolling exceeds the axis limits
     In  version  1.2.0,  the driver's support for smooth panscrolling added two
     axes to the stylus device, bringing the total axis count to eight. The num-
     ber of axes is advertised through the X Input Protocol  but  some	applica-
     tions  (notably GIMP 2.xx) cannot handle more than six axes. This is an ap-
     plication bug but for backwards-compatibility with such applications,  this
     driver  provides  the SmoothPanscrollingEnabled option to disable this fea-
     ture and thus limit the axis count to six. Note that this	setting  applies
     to  the  device.  Once  applied,  the driver will not send smooth panscroll
     events at all. It is not possible to provide this setting on a per-applica-
     tion basis.

SEE ALSO
     Xorg(1), xorg.conf(5), xorg.conf.d(5), X(7)

     More information is available at  https://github.com/linuxwacom/xf86-input-
     wacom

AUTHORS
     Peter  Hutterer  <peter.hutterer@who-t.net>,  Ping Cheng <pingc@wacom.com>,
     Frederic Lepied <lepied@xfree86.org>, John E. Joganic  <jej@j-arkadia.com>,
     Magnus VigerlA<paragraph>f <Magnus.Vigerlof@ipbo.se>

X Version 11		     xf86-input-wacom 25.0.0			WACOM(4)
home | help