Skip to content

SDL_report_descriptor: Parse and store Usage attached to Collection items to enable detecting Gamepads - #16006

Draft
ao2 wants to merge 2 commits into
libsdl-org:mainfrom
ao2:wip/ao2/task957
Draft

ao2 wants to merge 2 commits into
libsdl-org:mainfrom
ao2:wip/ao2/task957

Conversation

@ao2

@ao2 ao2 commented Jul 15, 2026

Copy link
Copy Markdown
Contributor
  • I confirm that I am the author of this code and release it to the SDL project under the Zlib license. This contribution does not contain code from other sources, including code generated by a Large Language Model ("AI").

For the sake of transparency, an LLM helped me to explore the problem, but the code has been hand-crafted (given also the AGENTS.md file in the SDL project).

This is a prototype of how Gamepads could be detected by parsing the HID report descriptor

Description

We are investigating how to detect gamepads starting from their HID report descriptor, mainly because we would like to give hidraw uaccess ot all gamepdas, but only to gamepads.

The changes are for exploration only at the current stage.

The proposed changes seem to work for a restricted set of devices:

$ find ../HID-report-descriptor/data -name "*.rdesc" |
    while read file;
    do
        ./build/test/testdescriptor "$file"
    done 2>&1 \
        | grep gamepad | sort
Is device "../HID-report-descriptor/data/fanatec_handbrake_hid_report_descriptor.rdesc" a gamepad? YES
Is device "../HID-report-descriptor/data/heusinkveld_pedals_hid_report_descriptor.rdesc" a gamepad? YES
Is device "../HID-report-descriptor/data/ps3_hid_report_descriptor.rdesc" a gamepad? YES
Is device "../HID-report-descriptor/data/steam_deck_kb_hid_report_descriptor.rdesc" a gamepad? NO
Is device "../HID-report-descriptor/data/steam_deck_lcd_js_hid_report_descriptor.rdesc" a gamepad? NO
Is device "../HID-report-descriptor/data/steam_deck_mouse_hid_report_descriptor.rdesc" a gamepad? NO
Is device "../HID-report-descriptor/data/steam_deck_oled_js_hid_report_descriptor.rdesc" a gamepad? NO
Is device "../HID-report-descriptor/data/thinkpad_usb_keyboard_hid_report_descriptor.rdesc" a gamepad? NO
Is device "../HID-report-descriptor/data/thinkpad_usb_trackpoint_hid_report_descriptor.rdesc" a gamepad? NO
Is device "../HID-report-descriptor/data/vrs_pedals_hid_report_descriptor.rdesc" a gamepad? YES
Is device "../HID-report-descriptor/data/xbox_one_elite_2_hid_report_descriptor.rdesc" a gamepad? YES
Is device "../HID-report-descriptor/data/xpadneo09_xb1s_hid_report_descriptor.rdesc" a gamepad? YES

However the parsing might be incomplete and detection could fail for other devices.

ao2 added 2 commits July 16, 2026 09:49
…tems

The parser only keeps track of Usages attached to fields, and those are
the one that can be found by SDL_DescriptorHasUsage().

However the HID Usage Tables spec (section 3.4) states that there are
three basic types of information that are described by Usages: controls,
collections, and data.

A Usage such as Joystick or Game Pad on the Generic Desktop page is
a Collection Application Usage: it is applied directly to a top-level
Collection(Application) item via the Usage item that precedes it, and
never appears on any data field.

The parser discarded this kind of Usages entirely, only tracking
collection nesting for debug logging.

Add a growable list of collections to DescriptorContext, and store each
Collection item's Usage (the first Usage local item seen before it) with
AddCollection(), following the same reallocation mechanism as
AddInputFields() for fields.

Expose the list through SDL_ReportDescriptor and add a new function
SDL_DescriptorHasCollectionUsage(), a collection-scoped counterpart of
SDL_DescriptorHasUsage(), so callers can distinguish "this usage is on
a collection" from "this usage is on a field" and query for
device-identifying Usages like Joystick or Game Pad that only ever
appear on collections.

This only stores each collection's own Usage; it does not yet track
which fields belong to which collection. That refinement can be
implemented  in a follow-up if needed.

Signed-off-by: Antonio Ospite <antonio.ospite@collabora.com>
Signed-off-by: Antonio Ospite <antonio.ospite@collabora.com>
@ao2
ao2 force-pushed the wip/ao2/task957 branch from 5daa419 to a1fc3ff Compare July 16, 2026 07:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant