Configurable Report Parser

[X9VoiD]

Description

We have way too many classes that essentially does the same parsing but in different indices.

If we encounter such tablet that only needs "regular" parsing, we should be able to define its report structure in the configuration itself.

Proposed Schema (intentionally incomplete)

We add ReportStructure as a field of the tablet configuration.

ReportStructure

It is a field that contains an array of Report.

Report

Field	Data Type	Description
Tag	string (optional)	A user-defined tag to describe this specific identified report.
Type	enum	The general type of the report.
Identifier	Identifier	This defines how this specific report will be identified.

Type Enum

Enum Value	Description
Data	This report contains parseable data.
StylusOutOfRange	This report means that the stylus just went out of range.

Report (Type = Data)

Field	Data Type	Description
Values	ReportValue	The values contained in this report.

Identifier

Field	Data Type	Description
Index	uint	The byte index to look for to identify this report.
Mask	hex string	Specifies the mask of what bits are important for identification.
Value	hex string	The byte should match this value after masking for a successful match to this report.

ReportValue

TODO: cba to write this one for now, should be self-explanatory with the example down below.

Example (XP-Pen G640S)

{
  "Name": "XP-Pen Star G640S",

  // -- snip --

  "ReportParser": "OpenTabletDriver.Tablet.ConfigurableReportParser",
  "ReportStructure": [
    {
      "Tag": "Digitizer",
      "Type": "Data"
      "Identifier": {
        "Index": 1,
        "Mask": "0xf0",
        "Value": "0xa0",
      },
      "Values": [
        {
          "Data": "StylusPositionX",
          "DataType": "ushort",
          "Index": 2,
          "ExtensionIndex": null
        },
        {
          "Data": "StylusPositionY",
          "DataType": "ushort",
          "Index": 4,
          "ExtensionIndex": null
        },
        {
          "Data": "StylusPressure",
          "DataType": "ushort",
          "Index": 6,
          "ExtensionIndex": null
        },
        {
          "Data": "StylusEraser",
          "DataType": "BitField",
          "Index": 1,
          "Mask": "0x08"
        },
        {
          "Data": "StylusButtons",
          "DataType": "BitField",
          "Index": 1,
          "Mask": "0x06"
        },
        {
          "Data": "StylusTiltX",
          "DataType": "sbyte",
          "Index": 8,
          "ReverseSign": false
        },
        {
          "Data": "StylusTiltY",
          "DataType": "sbyte",
          "Index": 9,
          "ReverseSign": false
        }
      ]
    },
    {
      "Tag": "Auxiliary",
      "Identifier": {
        "Index": 1,
        "Mask": "0xf0",
        "Value": "0xf0",
      },
      "Values": [
        {
          "Data": "TabletButton",
          "DataType": "BitfieldArray",
          "BitFields": [
            {
              "Index": 2,
              "Mask": "0xff",
            },
            {
              "Index": 3,
              "Mask": "0x03"
            }
          ]
        }
      ]
    },
    {
      "Type": "StylusOutOfRange",
      "Identifier": {
        "Index": 1,
        "Mask": "0xf0",
        "Value": "0xc0"
      }
    }
  ]
}

ExtensionIndex is when an encoded value is to be extended via another byte in the report.

It handles cases like this:

            Position = new Vector2
            {
                X = Unsafe.ReadUnaligned<ushort>(ref report[2]) | report[10] << 16,
                Y = Unsafe.ReadUnaligned<ushort>(ref report[4]) | report[11] << 16
            };

Other stuff

Dealing with redundancy

It's gonna be too redundant if we have to add the entire thing per tablet config that can be handled by the configurable parser, so what I thought of is to have another file.

report_structure_definitions.json

which contains named structures, much like named parsers.

[
  {
    "Name": "XP_Pen.BasicReport",
    "ReportStructure": [
      // -- snip --
    ]
  },
  // ...
]

and then when a ReportStructure in a tablet configuration is a string, it should be considered a name of a report structure.

Possibility of checking for inconsistencies/conflicts within the structure/parser itself

We could write a test that does exactly that, and also checking for too similar structures/parsers.

Better documentation of the reports from tablets

Acknowledgements

• I have searched the existing issues and this new issue is not a duplicate of any.
• I have written a concise and meaningful title.
• I am on the latest version of OpenTabletDriver.