parse_descriptor()

TabletLayout MayaFlux::Core::TabletBackend::parse_descriptor ( std::span< const uint8_t >  descriptor )

static

Parse a HID report descriptor into a tablet layout.

Free of device state and of HIDAPI, so captured descriptor bytes can be parsed and asserted against with no hardware present.

Parameters

descriptor

Raw report descriptor bytes.

Returns

Parsed layout. No fields means no digitizer usages were found.

Definition at line 249 of file TabletBackend.cpp.

{
 
    TabletLayout layout;
 
    GlobalState global;
    std::vector<GlobalState> global_stack;
 
    std::vector<LocalUsage> local_usages;
    uint32_t usage_min = 0;
    uint32_t usage_max = 0;
    bool has_usage_range = false;
 
    std::unordered_map<uint8_t, uint32_t> bit_cursor;
    bool digitizer_seen = false;
 
    const auto clear_locals = [&]() {
        local_usages.clear();
        usage_min = 0;
        usage_max = 0;
        has_usage_range = false;
    };
 
    size_t i = 0;
    while (i < descriptor.size()) {
        const uint8_t prefix = descriptor[i];
 
        if (prefix == 0xFE) {
            if (i + 1 >= descriptor.size())
                break;
            i += 2U + descriptor[i + 1];
            continue;
        }
 
        size_t size = prefix & 0x03U;
        if (size == 3)
            size = 4;
        const uint8_t type = (prefix >> 2U) & 0x03U;
        const uint8_t tag = (prefix >> 4U) & 0x0FU;
 
        ++i;
        if (i + size > descriptor.size())
            break;
 
        const uint8_t* payload = descriptor.data() + i;
        i += size;
 
        if (type == 1) {
            switch (tag) {
            case 0x0:
                global.usage_page = static_cast<uint16_t>(item_unsigned(payload, size));
                if (global.usage_page == k_page_digitizer)
                    digitizer_seen = true;
                break;
 
            case 0x1:
                global.logical_min = item_signed(payload, size);
                break;
 
            case 0x2: {
                const int32_t as_signed = item_signed(payload, size);
                global.logical_max = (global.logical_min >= 0 && as_signed < 0)
                    ? static_cast<int32_t>(item_unsigned(payload, size))
                    : as_signed;
                break;
            }
 
            case 0x7:
                global.report_size = item_unsigned(payload, size);
                break;
 
            case 0x8:
                global.report_id = static_cast<uint8_t>(item_unsigned(payload, size));
                layout.uses_report_ids = true;
                break;
 
            case 0x9:
                global.report_count = item_unsigned(payload, size);
                break;
 
            case 0xA:
                global_stack.push_back(global);
                break;
 
            case 0xB:
                if (!global_stack.empty()) {
                    global = global_stack.back();
                    global_stack.pop_back();
                }
                break;
 
            default:
                break;
            }
            continue;
        }
 
        if (type == 2) {
            switch (tag) {
            case 0x0:
                if (size == 4) {
                    const uint32_t full = item_unsigned(payload, size);
                    const auto page = static_cast<uint16_t>(full >> 16U);
                    local_usages.push_back({ .page = page, .usage = static_cast<uint16_t>(full & 0xFFFFU) });
                    if (page == k_page_digitizer)
                        digitizer_seen = true;
                } else {
                    local_usages.push_back({ .page = global.usage_page,
                        .usage = static_cast<uint16_t>(item_unsigned(payload, size)) });
                }
                break;
 
            case 0x1:
                usage_min = item_unsigned(payload, size);
                has_usage_range = true;
                break;
 
            case 0x2:
                usage_max = item_unsigned(payload, size);
                has_usage_range = true;
                break;
 
            default:
                break;
            }
            continue;
        }
 
        if (type != 0) {
            continue;
        }
 
        if (tag != 0x8) {
            clear_locals();
            continue;
        }
 
        const uint32_t flags = item_unsigned(payload, size);
        const bool is_constant = (flags & 0x01U) != 0U;
 
        if (global.report_size == 0 || global.report_count == 0) {
            clear_locals();
            continue;
        }
 
        uint32_t& cursor = bit_cursor[global.report_id];
 
        for (uint32_t index = 0; index < global.report_count; ++index) {
            LocalUsage current { .page = global.usage_page, .usage = 0 };
 
            if (!is_constant) {
                if (index < local_usages.size()) {
                    current = local_usages[index];
                } else if (!local_usages.empty()) {
                    current = local_usages.back();
                } else if (has_usage_range) {
                    current.usage = static_cast<uint16_t>(
                        std::min(usage_min + index, usage_max));
                }
            }
 
            const size_t slot = is_constant
                ? k_slot_none
                : slot_for_usage(current.page, current.usage);
 
            if (slot != k_slot_none) {
                TabletField field;
                field.report_id = global.report_id;
                field.usage_page = current.page;
                field.usage = current.usage;
                field.bit_offset = cursor;
                field.bit_size = global.report_size;
                field.logical_min = global.logical_min;
                field.logical_max = global.logical_max;
                field.slot = slot;
                layout.fields.push_back(field);
 
                if (slot < TabletFrame::SLOT_COUNT)
                    layout.axes |= axis_for_slot(slot);
                if (slot == k_pseudo_invert)
                    layout.has_invert = true;
                if (slot == k_pseudo_serial)
                    layout.has_serial = true;
            }
 
            cursor += global.report_size;
        }
 
        clear_locals();
    }
 
    if (!digitizer_seen)
        layout.fields.clear();
 
    return layout;
}

References MayaFlux::Core::TabletLayout::axes, MayaFlux::Core::TabletField::bit_offset, MayaFlux::Core::TabletField::bit_size, current, MayaFlux::Core::TabletLayout::fields, MayaFlux::Core::TabletLayout::has_invert, MayaFlux::Core::TabletLayout::has_serial, MayaFlux::Core::TabletField::logical_max, MayaFlux::Core::TabletField::logical_min, page, MayaFlux::Core::TabletField::report_id, MayaFlux::Core::TabletField::slot, MayaFlux::Core::TabletFrame::SLOT_COUNT, MayaFlux::Core::TabletField::usage, MayaFlux::Core::TabletField::usage_page, and MayaFlux::Core::TabletLayout::uses_report_ids.

Referenced by adopt_device().

Here is the caller graph for this function: