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

  1. A logical range must be provided for all usages.

  2. The minimum physical size of a digitizer is one square inch.

  3. The recommended (and minimum) time stamp usage report size is 16 bits.

  4. 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

 

 

 

Send comments about this topic to Microsoft