Implementing top-level collections in multi-touch devices
This topic describes how to implement top-level collections in multi-touch devices. It also includes sample report descriptors for a mouse collection, a two finger parallel/hybrid mode multi-touch device, and a single finger hybrid mode multi-touch device.
Overview
The report descriptor for a multiple input device must include at least one top-level collection for the primary device and a separate top-level collection for the mouse.The Two finger parallel/hybrid mode multi-touch device sample report descriptor contains two logical collections (one for each finger). Be aware that this descriptor can still support more than two concurrent contacts by using Hybrid mode.
Important In previous versions of windows, some devices used a configuration top level collection to allow their devices to adapt to the capabilities of the host operating system. This functionality is available in Windows 8 and Windows 8.1 for backwards compatibility but it is strongly recommended not to use the configuration collection when designing a new digitizer for Windows. This feature is deprecated in Windows 8 and Windows 8.1. It will be removed in a future version of Windows, and is not available in Windows RT.
The Single finger hybrid mode multi-touch device sample report descriptor contains a single logical collection. For many categories of devices, end users may operate with a single finger in most scenarios. For this type of device, this mode is the most optimal.
I2C connected digitizers are required to implement Single Finger Hybrid Mode or Two Finger Parallel Mode.
Report descriptors for touch devices should use Finger (0x22) CL (Collection Logical) to group the data and control usages in the top-level collections, whereas the Stylus (0x20) CL should be used to group pen-related control and data usages.
Rules for global items
A logical range must be provided for all usages.
The minimum physical size of a digitizer is one square inch.
The recommended (and minimum) time stamp usage report size is 16 bits.
Reported values must always be within the logical range. The only exception is when the usage includes support for NULL values.
Sample: mouse collection
This is a sample report descriptor for a mouse collection.
//
// Dummy mouse collection starts here
//
0x05, 0x01, // USAGE_PAGE (Generic Desktop) 0
0x09, 0x02, // USAGE (Mouse) 2
0xa1, 0x01, // COLLECTION (Application) 4
0x85, REPORTID_MOUSE, // REPORT_ID (Mouse) 6
0x09, 0x01, // USAGE (Pointer) 8
0xa1, 0x00, // COLLECTION (Physical) 10
0x05, 0x09, // USAGE_PAGE (Button) 12
0x19, 0x01, // USAGE_MINIMUM (Button 1) 14
0x29, 0x02, // USAGE_MAXIMUM (Button 2) 16
0x15, 0x00, // LOGICAL_MINIMUM (0) 18
0x25, 0x01, // LOGICAL_MAXIMUM (1) 20
0x75, 0x01, // REPORT_SIZE (1) 22
0x95, 0x02, // REPORT_COUNT (2) 24
0x81, 0x02, // INPUT (Data,Var,Abs) 26
0x95, 0x06, // REPORT_COUNT (6) 28
0x81, 0x03, // INPUT (Cnst,Var,Abs) 30
0x05, 0x01, // USAGE_PAGE (Generic Desktop) 32
0x09, 0x30, // USAGE (X) 34
0x09, 0x31, // USAGE (Y) 36
0x15, 0x81, // LOGICAL_MINIMUM (-127) 38
0x25, 0x7f, // LOGICAL_MAXIMUM (127) 40
0x75, 0x08, // REPORT_SIZE (8) 42
0x95, 0x02, // REPORT_COUNT (2) 44
0x81, 0x06, // INPUT (Data,Var,Rel) 46
0xc0, // END_COLLECTION 48
0xc0 // END_COLLECTION 49/50
Sample: two finger parallel/hybrid mode multi-touch device
This is a sample report descriptor for a two finger parallel/hybrid mode multi-touch device.
0x05, 0x0d, // USAGE_PAGE (Digitizers)
0x09, 0x04, // USAGE (Touch Screen)
0xa1, 0x01, // COLLECTION (Application)
0x85, 0x01, // REPORT_ID (Touch)
0x09, 0x22, // USAGE (Finger)
0xa1, 0x02, // COLLECTION (Logical)
0x09, 0x42, // USAGE (Tip Switch)
0x15, 0x00, // LOGICAL_MINIMUM (0)
0x25, 0x01, // LOGICAL_MAXIMUM (1)
0x75, 0x01, // REPORT_SIZE (1)
0x95, 0x01, // REPORT_COUNT (1)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x95, 0x07, // REPORT_COUNT (7)
0x81, 0x03, // INPUT (Cnst,Ary,Abs)
0x75, 0x08, // REPORT_SIZE (8)
0x09, 0x51, // USAGE (Contact Identifier)
0x95, 0x01, // REPORT_COUNT (1)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x05, 0x01, // USAGE_PAGE (Generic Desk..
0x26, 0xff, 0x0f, // LOGICAL_MAXIMUM (4095)
0x75, 0x10, // REPORT_SIZE (16)
0x55, 0x0e, // UNIT_EXPONENT (-2)
0x65, 0x13, // UNIT(Inch,EngLinear)
0x09, 0x30, // USAGE (X)
0x35, 0x00, // PHYSICAL_MINIMUM (0)
0x46, 0xb5, 0x04, // PHYSICAL_MAXIMUM (1205)
0x95, 0x02, // REPORT_COUNT (2)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x46, 0x8a, 0x03, // PHYSICAL_MAXIMUM (906)
0x09, 0x31, // USAGE (Y)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x05, 0x0d, // USAGE_PAGE (Digitizers)
0x09, 0x48, // USAGE (Width)
0x09, 0x49, // USAGE (Height)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x95, 0x01, // REPORT_COUNT (1)
0x55, 0x0C, // UNIT_EXPONENT (-4)
0x65, 0x12, // UNIT (Radians,SIROtation)
0x35, 0x00, // PHYSICAL_MINIMUM (0)
0x47, 0x6f, 0xf5, 0x00, 0x00, // PHYSICAL_MAXIMUM (62831)
0x15, 0x00, // LOGICAL_MINIMUM (0)
0x27, 0x6f, 0xf5, 0x00, 0x00, // LOGICAL_MAXIMUM (62831)
0x09, 0x3f, // USAGE (Azimuth[Orientation])
0x81, 0x02, // INPUT (Data,Var,Abs)
0xc0, // END_COLLECTION
0x09, 0x22, // USAGE (Finger)
0xa1, 0x02, // COLLECTION (Logical)
0x09, 0x42, // USAGE (Tip Switch)
0x15, 0x00, // LOGICAL_MINIMUM (0)
0x25, 0x01, // LOGICAL_MAXIMUM (1)
0x75, 0x01, // REPORT_SIZE (1)
0x95, 0x01, // REPORT_COUNT (1)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x95, 0x07, // REPORT_COUNT (7)
0x81, 0x03, // INPUT (Cnst,Ary,Abs)
0x75, 0x08, // REPORT_SIZE (8)
0x09, 0x51, // USAGE (Contact Identifier)
0x95, 0x01, // REPORT_COUNT (1)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x05, 0x01, // USAGE_PAGE (Generic Desk..
0x26, 0xff, 0x0f, // LOGICAL_MAXIMUM (4095)
0x75, 0x10, // REPORT_SIZE (16)
0x55, 0x0e, // UNIT_EXPONENT (-2)
0x65, 0x13, // UNIT(Inch,EngLinear)
0x09, 0x30, // USAGE (X)
0x35, 0x00, // PHYSICAL_MINIMUM (0)
0x46, 0xb5, 0x04, // PHYSICAL_MAXIMUM (1205)
0x95, 0x02, // REPORT_COUNT (2)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x46, 0x8a, 0x03, // PHYSICAL_MAXIMUM (906)
0x09, 0x31, // USAGE (Y)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x05, 0x0d, // USAGE_PAGE (Digitizers)
0x09, 0x48, // USAGE (Width)
0x09, 0x49, // USAGE (Height)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x95, 0x01, // REPORT_COUNT (1)
0x55, 0x0C, // UNIT_EXPONENT (-4)
0x65, 0x12, // UNIT (Radians,SIROtation)
0x35, 0x00, // PHYSICAL_MINIMUM (0)
0x47, 0x6f, 0xf5, 0x00, 0x00, // PHYSICAL_MAXIMUM (62831)
0x15, 0x00, // LOGICAL_MINIMUM (0)
0x27, 0x6f, 0xf5, 0x00, 0x00, // LOGICAL_MAXIMUM (62831)
0x09, 0x3f, // USAGE (Azimuth[Orientation])
0x81, 0x02, // INPUT (Data,Var,Abs)
0xc0, // END_COLLECTION
0x05, 0x0d, // USAGE_PAGE (Digitizers)
0x55, 0x0C, // UNIT_EXPONENT (-4)
0x66, 0x01, 0x10, // UNIT (Seconds)
0x47, 0xff, 0xff, 0x00, 0x00, // PHYSICAL_MAXIMUM (65535)
0x27, 0xff, 0xff, 0x00, 0x00, // LOGICAL_MAXIMUM (65535)
0x75, 0x10, // REPORT_SIZE (16)
0x95, 0x01, // REPORT_COUNT (1)
0x09, 0x56, // USAGE (Scan Time)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x09, 0x54, // USAGE (Contact count)
0x25, 0x7f, // LOGICAL_MAXIMUM (127)
0x95, 0x01, // REPORT_COUNT (1)
0x75, 0x08, // REPORT_SIZE (8)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x85, REPORTID_MAX_COUNT, // REPORT_ID (Feature)
0x09, 0x55, // USAGE(Contact Count Maximum)
0x95, 0x01, // REPORT_COUNT (1)
0x25, 0x02, // LOGICAL_MAXIMUM (2)
0xb1, 0x02, // FEATURE (Data,Var,Abs)
0x85, 0x44, // REPORT_ID (Feature)
0x06, 0x00, 0xff, // USAGE_PAGE (Vendor Defined)
0x09, 0xC5, // USAGE (Vendor Usage 0xC5)
0x15, 0x00, // LOGICAL_MINIMUM (0)
0x26, 0xff, 0x00, // LOGICAL_MAXIMUM (0xff)
0x75, 0x08, // REPORT_SIZE (8)
0x96, 0x00, 0x01, // REPORT_COUNT (0x100 (256))
0xb1, 0x02, // FEATURE (Data,Var,Abs)
0xc0, // END_COLLECTIONÂ Â Â
Sample: single finger hybrid mode multi-touch device
This is a sample report descriptor for a single finger hybrid mode multi-touch device.
Note The REPORTID_MAX_COUNT and REPORTID_MOUSE referenced in this example don't signify any particular value. Report identifiers are optional and should be assigned according to the needs of every report descriptor. Please see the Device Class Definition for Human Interface Devices (HID) Version 1.11 document for more information about report identifiers
0x05, 0x0d, // USAGE_PAGE (Digitizers)
0x09, 0x04, // USAGE (Touch Screen)
0xa1, 0x01, // COLLECTION (Application)
0x85, 0x01, // REPORT_ID (Touch)
0x09, 0x22, // USAGE (Finger)
0xa1, 0x02, // COLLECTION (Logical)
0x09, 0x42, // USAGE (Tip Switch)
0x15, 0x00, // LOGICAL_MINIMUM (0)
0x25, 0x01, // LOGICAL_MAXIMUM (1)
0x75, 0x01, // REPORT_SIZE (1)
0x95, 0x01, // REPORT_COUNT (1)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x95, 0x07, // REPORT_COUNT (7)
0x81, 0x03, // INPUT (Cnst,Ary,Abs)
0x75, 0x08, // REPORT_SIZE (8)
0x09, 0x51, // USAGE (Contact Identifier)
0x95, 0x01, // REPORT_COUNT (1)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x05, 0x01, // USAGE_PAGE (Generic Desk..
0x26, 0xff, 0x0f, // LOGICAL_MAXIMUM (4095)
0x75, 0x10, // REPORT_SIZE (16)
0x55, 0x0e, // UNIT_EXPONENT (-2)
0x65, 0x13, // UNIT(Inch,EngLinear)
0x09, 0x30, // USAGE (X)
0x35, 0x00, // PHYSICAL_MINIMUM (0)
0x46, 0xb5, 0x04, // PHYSICAL_MAXIMUM (1205)
0x95, 0x02, // REPORT_COUNT (2)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x46, 0x8a, 0x03, // PHYSICAL_MAXIMUM (906)
0x09, 0x31, // USAGE (Y)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x05, 0x0d, // USAGE_PAGE (Digitizers)
0x09, 0x48, // USAGE (Width)
0x09, 0x49, // USAGE (Height)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x95, 0x01, // REPORT_COUNT (1)
0x55, 0x0C, // UNIT_EXPONENT (-4)
0x65, 0x12, // UNIT (Radians,SIROtation)
0x35, 0x00, // PHYSICAL_MINIMUM (0)
0x47, 0x6f, 0xf5, 0x00, 0x00, // PHYSICAL_MAXIMUM (62831)
0x15, 0x00, // LOGICAL_MINIMUM (0)
0x27, 0x6f, 0xf5, 0x00, 0x00, // LOGICAL_MAXIMUM (62831)
0x09, 0x3f, // USAGE (Azimuth[Orientation])
0x81, 0x02, // INPUT (Data,Var,Abs)
0xc0, // END_COLLECTION
0x05, 0x0d, // USAGE_PAGE (Digitizers)
0x55, 0x0C, // UNIT_EXPONENT (-4)
0x66, 0x01, 0x10, // UNIT (Seconds)
0x47, 0xff, 0xff, 0x00, 0x00, // PHYSICAL_MAXIMUM (65535)
0x27, 0xff, 0xff, 0x00, 0x00, // LOGICAL_MAXIMUM (65535)
0x75, 0x10, // REPORT_SIZE (16)
0x95, 0x01, // REPORT_COUNT (1)
0x09, 0x56, // USAGE (Scan Time)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x09, 0x54, // USAGE (Contact count)
0x25, 0x7f, // LOGICAL_MAXIMUM (127)
0x95, 0x01, // REPORT_COUNT (1)
0x75, 0x08, // REPORT_SIZE (8)
0x81, 0x02, // INPUT (Data,Var,Abs)
0x85, REPORTID_MAX_COUNT, // REPORT_ID (Feature)
0x09, 0x55, // USAGE(Contact Count Maximum)
0x95, 0x01, // REPORT_COUNT (1)
0x25, 0x02, // LOGICAL_MAXIMUM (2)
0xb1, 0x02, // FEATURE (Data,Var,Abs)
0x85, 0x44, // REPORT_ID (Feature)
0x06, 0x00, 0xff, // USAGE_PAGE (Vendor Defined)
0x09, 0xC5, // USAGE (Vendor Usage 0xC5)
0x15, 0x00, // LOGICAL_MINIMUM (0)
0x26, 0xff, 0x00, // LOGICAL_MAXIMUM (0xff)
0x75, 0x08, // REPORT_SIZE (8)
0x96, 0x00, 0x01, // REPORT_COUNT (0x100 (256))
0xb1, 0x02, // FEATURE (Data,Var,Abs)
0xc0, // END_COLLECTION
The following example shows two frames of five reports each for single-finger hybrid device representing 5 counts:
| X | Y | Tip | Scan Time | Contact ID | Contact Count |
|---|---|---|---|---|---|
517 |
350 |
TRUE |
3472 |
0 |
5 |
706 |
217 |
TRUE |
3472 |
1 |
0 |
510 |
640 |
TRUE |
3472 |
2 |
0 |
1113 |
317 |
TRUE |
3472 |
3 |
0 |
866 |
218 |
TRUE |
3472 |
4 |
0 |
517 |
350 |
TRUE |
3561 |
0 |
5 |
706 |
217 |
TRUE |
3561 |
1 |
0 |
510 |
640 |
TRUE |
3561 |
2 |
0 |
1113 |
317 |
TRUE |
3561 |
3 |
0 |
866 |
218 |
TRUE |
3561 |
4 |
0 |