mtouch_driver_funcs_t

Updated: May 06, 2022

Functions to be implemented by the mtouch driver

Synopsis:

#include <input/>
typedef struct mtouch_driver_funcs_t {
    int (*get_contact_id)(void *packet,
                                                uint8_t digit_idx,
                                                uint32_t *contact_id,
                                                void *arg);
    int (*is_contact_down)(void *packet,
                                                uint8_t digit_idx,
                                                int *valid,
                                                void *arg);
    int (*get_coords)(void *packet,
                                                uint8_t digit_idx,
                                                int32_t *x,
                                                int32_t *y,
                                                void *arg);
    int (*get_down_count)(void *packet,
                                                uint32_t *down_count,
                                                void *arg);
    int (*get_touch_width)(void *packet,
                                                uint8_t digit_idx,
                                                uint32_t *touch_width,
                                                void *arg);
    int (*get_touch_height)(void *packet,
                                                uint8_t digit_idx,
                                                uint32_t *touch_height,
                                                void *arg);
    int (*get_touch_orientation)(void *packet,
                                                uint8_t digit_idx,
                                                uint32_t *touch_orientation,
                                                void *arg);
    int (*get_touch_pressure)(void *packet,
                                                uint8_t digit_idx,
                                                uint32_t *touch_pressure,
                                                void *arg);
    void (*get_seq_id)(void *packet,
                                                uint32_t *seq_id,
                                                void *arg);
    int (*get_contact_type)(void *packet,
                                                uint8_t digit_idx,
                                                uint32_t *contact_type,
                                                void *arg);
    int (*get_select)(void *packet,
                                                uint8_t digit_idx,
                                                uint32_t *select,
                                                void *arg);
    int (*set_event_rate)(void *dev,
                                                uint32_t min_event_interval);
} mtouch_driver_funcs_t;

Data:

int (*get_contact_id)(void *packet, uint8_t digit_idx, uint32_t *contact_id, void *arg)
Retrieve the contact ID for the specified digit from packet.

This callback function is called for each of the touchpoints. The maximum number of touchpoints is max_touchpoints, as specified in mtouch_driver_params_t (mtouch_params.h).

Arguments
  • packet Data packet that contains information on the touch-related event. This data packet is the same packet that was passed into mtouch_driver_process_packet(). This data can be used to retrieve information about all digits, regardless of whether or not they are touching.
  • digit_idx Digit (finger) index that the Input Events library is requesting. It is a zero based index whose maximum is (max_touchpoints - 1). There is no requirement for any correlation between digit_idx and contact_id.
  • contact_id Pointer to contact ID of the touch-related event for the specified digit_idx. This function updates contact_id upon its successful execution.
  • arg User information.
Returns
  • 0 if successful; otherwise non-zero if an error occurred.
int (*is_contact_down)(void *packet, uint8_t digit_idx, int *valid, void *arg)
Retrieve the touch status for the specified digit from packet.

This callback function is called for each of the touchpoints. The maximum number of touchpoints is max_touchpoints, as specified in mtouch_driver_params_t (mtouch_params.h).

Arguments
  • packet Data packet that contains information on the touch-related event. This data packet is the same packet that was passed into mtouch_driver_process_packet(). This data can be used to retrieve information about all digits, regardless of whether or not they are touching.
  • digit_idx Digit (finger) index that the Input Events library is requesting. It is a zero based index whose maximum is (max_touchpoints - 1). There is no requirement for any correlation between digit_idx and contact_id.
  • valid Pointer to touch status (e.g., 1 = Down and 0 = Up) of the touch-related event for the specified digit_idx. This function updates valid upon its successful execution.
  • arg User information.
Returns
  • 0 if successful; otherwise non-zero if an error occurred.
int (*get_coords)(void *packet, uint8_t digit_idx, int32_t *x, int32_t *y, void *arg)
Retrieve the coordinates for the specified digit from packet.

This callback function is called for each of the touchpoints. The maximum number of touchpoints is max_touchpoints, as specified in mtouch_driver_params_t (mtouch_params.h).

Arguments
  • packet Data packet that contains information on the touch-related event. This data packet is the same packet that was passed into mtouch_driver_process_packet(). This data can be used to retrieve information about all digits, regardless of whether or not they are touching.
  • digit_idx Digit (finger) index that the Input Events library is requesting. It is a zero based index whose maximum is (max_touchpoints - 1). There is no requirement for any correlation between digit_idx and contact_id.
  • x Pointer to the x coordinate of the touch-related event for the specified digit_idx. This function updates x upon its successful execution.
  • y Pointer to the y coordinate of the touch-related event for the specified digit_idx. This function updates y upon its successful execution.
  • arg User information.
Returns
  • 0 if successful; otherwise non-zero if an error occurred.
int (*get_down_count)(void *packet, uint32_t *down_count, void *arg)
Retrieve the number of touchpoints currently in contact with the screen.

This callback function is called for each of the touchpoints. The maximum number of touchpoints is max_touchpoints, as specified in mtouch_driver_params_t (mtouch_params.h).

Arguments
  • packet Data packet that contains information on the touch-related event. This data packet is the same packet that was passed into mtouch_driver_process_packet(). This data can be used to retrieve information about all digits, regardless of whether or not they are touching.
  • down_count Pointer to the number of rouchpoints currently in contact with the screen. This function updates down_count upon its successful execution.
  • arg User information.
Returns
  • 0 if successful; otherwise non-zero if an error occurred.
int (*get_touch_width)(void *packet, uint8_t digit_idx, uint32_t *touch_width, void *arg)
Retrieve the width information for the specified digit from packet.

This callback function is called for each of the touchpoints. The maximum number of touchpoints is max_touchpoints, as specified in mtouch_driver_params_t (mtouch_params.h).

Arguments
  • packet Data packet that contains information on the touch-related event. This data packet is the same packet that was passed into mtouch_driver_process_packet(). This data can be used to retrieve information about all digits, regardless of whether or not they are touching.
  • digit_idx Digit (finger) index that the Input Events library is requesting. It is a zero based index whose maximum is (max_touchpoints - 1). There is no requirement for any correlation between digit_idx and contact_id.
  • touch_width Pointer to the width of the touch-related event for the specified digit_idx. This function updates touch_width upon its successful execution.
  • arg User information.
Returns
  • 0 if successful; otherwise non-zero if an error occurred.
int (*get_touch_height)(void *packet, uint8_t digit_idx, uint32_t *touch_height, void *arg)
Retrieve the height information for the specified digit from packet.

This callback function is called for each of the touchpoints. The maximum number of touchpoints is max_touchpoints, as specified in mtouch_driver_params_t (mtouch_params.h).

Arguments
  • packet Data packet that contains information on the touch-related event. This data packet is the same packet that was passed into mtouch_driver_process_packet(). This data can be used to retrieve information about all digits, regardless of whether or not they are touching.
  • digit_idx Digit (finger) index that the Input Events library is requesting. It is a zero based index whose maximum is (max_touchpoints - 1). There is no requirement for any correlation between digit_idx and contact_id.
  • touch_height Pointer to the height of the touch-related event for the specified digit_idx. This function updates touch_height upon its successful execution.
  • arg User information.
Returns
  • 0 if successful; otherwise non-zero if an error occurred.
int (*get_touch_orientation)(void *packet, uint8_t digit_idx, uint32_t *touch_orientation, void *arg)
Retrieve the orientation information for the specified digit from packet.

This callback function is not yet implemented by the Input Events library. For the time being, simply set this callback function to NULL in your mtouch_driver_funcs_t assignment before you call mtouch_driver_attach().

Arguments
  • packet
  • digit_idx
  • touch_orientation
  • arg
Returns
  • 0 if successful; otherwise non-zero if an error occurred.
int (*get_touch_pressure)(void *packet, uint8_t digit_idx, uint32_t *touch_pressure, void *arg)
Retrieve the touch pressure information for the specified digit from packet.

For capacitive touchscreens, this callback function retrieves the signal strength, not the pressure. The signal strength information is directly proportional to the width and height retrieved from the (*get_touch_width)() and (*get_touch_height)() callback functions.

Arguments
  • packet Data packet that contains information on the touch-related event. This data packet is the same packet that was passed into mtouch_driver_process_packet(). This data can be used to retrieve information about all digits, regardless of whether or not they are touching.
  • digit_idx Digit (finger) index that the Input Events library is requesting. It is a zero based index whose maximum is (max_touchpoints - 1). There is no requirement for any correlation between digit_idx and contact_id.
  • touch_pressure Pointer to the pressure, or signal strength for capacitive touchscreens, of the touch-related event for the specified digit_idx. This function updates is touch_pressure upon its successful execution.
  • arg User information.
Returns
  • 0 if successful; otherwise non-zero if an error occurred.
void (*get_seq_id)(void *packet, uint32_t *seq_id, void *arg)
Retrieve the unique sequence ID of a touch-related event from packet.

This callback function is called for each of the touchpoints. The maximum number of touchpoints is max_touchpoints, as specified in mtouch_driver_params_t (mtouch_params.h). The sequence ID is used to track the touch-related event in the Input Events library. The sequence ID is commonly a value that is incremented continuously.

Arguments
  • packet Data packet that contains information on the touch-related event. This data packet is the same packet that was passed into mtouch_driver_process_packet(). This data can be used to retrieve information about all digits, regardless of whether or not they are touching.
  • seq_id Pointer to the unique sequence ID that Input Events library is requesting. This function updates seq_id upon its successful execution.
  • arg User information.
Returns
  • 0 if successful; otherwise non-zero if an error occurred.
int (*get_contact_type)(void *packet, uint8_t digit_idx, uint32_t *contact_type, void *arg)
Retrieve the contact type of a touch-related event from packet.

This callback function is called for each of the touchpoints. The maximum number of touchpoints is max_touchpoints, as specified in mtouch_driver_params_t (mtouch_params.h).

Arguments
  • packet Data packet that contains information on the touch-related event. This data packet is the same packet that was passed into mtouch_driver_process_packet(). This data can be used to retrieve information about all digits, regardless of whether or not they are touching.
  • digit_idx Digit (finger) index that is related to the contact type that is being retrived. It is a zero based index whose maximum is(max_touchpoints - 1).
  • contact_type Pointer to the contact type that Input Events library is requesting. Valid contact types are of type contact_type_e. This function updates contact_type upon its successful execution.
  • arg User information.
Returns
  • 0 if successful; otherwise non-zero if an error occurred.
int (*get_select)(void *packet, uint8_t digit_idx, uint32_t *select, void *arg)
Retrieve the select buttons of a touch-related event from packet.

This callback function is not yet implemented by the Input Events library. For the time being, simply set this callback function to NULL in your mtouch_driver_funcs_t assignment when attaching your driver.

Arguments
  • packet
  • digit_idx
  • select
  • arg
Returns
  • 0 if successful; otherwise non-zero if an error occurred.
int (*set_event_rate)(void *dev, uint32_t min_event_interval)
Retrieve the sampling period of a touch-related event from packet.

This callback function is called for each of the touchpoints. The maximum number of touchpoints is max_touchpoints, as specified in mtouch_driver_params_t (mtouch_params.h). This function is called with the device mutex held.

Arguments
  • dev Handle to the device driver.
  • min_event_interval Minimum sampling period, in microseconds, of the touch controller. Two touch-related events will not be received in a time less than this interval.
Returns
  • 0 if successful; otherwise non-zero if an error occurred.

Library:

libinputevents

Description:

These callback functions are called into by libinputevents to fetch the data required to transform the device (touch controller) data into mtouch events.

These functions must be implemented. Otherwise, the driver will not be able to connect to the Input Events framework.