TS_READ(3)

💖 TS_READ(3) — tslib 💖

okay bestie, gather round, because today we're reading touch samples and it's literally the moment this whole library was born for ✨

🌸 NAME 🌸

ts_read, ts_read_raw, ts_read_mt, ts_read_raw_mt — the four functions that hand you tslib touch samples, no cap 🫶

🎀 SYNOPSIS 🎀

#include <tslib.h>

int ts_read(struct tsdev *dev, struct ts_sample *samp, int nr);

int ts_read_raw(struct tsdev *dev, struct ts_sample *samp, int nr);

int ts_read_mt(struct tsdev *dev, struct ts_sample_mt **samp, int slots, int nr);

int ts_read_raw_mt(struct tsdev *dev, struct ts_sample_mt **samp, int slots, int nr);

💅 DESCRIPTION 💅

ts_read() reads nr input samples with tslib's filters applied 💫. And the struct it fills in, struct ts_sample, is defined like this:

struct ts_sample {
        int             x;
        int             y;
        unsigned int    pressure;
        struct timeval  tv;
};

ts_read_mt() is the multitouch girlie 💅 — she reads nr * slots input samples, also with tslib's filters applied. Her struct, struct ts_sample_mt, is defined as follows:

struct ts_sample_mt {
        /* most recent ABS_MT_* event codes.
         * see linux/input.h for descriptions */
        int             x;
        int             y;
        unsigned int    pressure;
        int             slot;
        int             tracking_id;

        int             tool_type;
        int             tool_x;
        int             tool_y;
        unsigned int    touch_major;
        unsigned int    width_major;
        unsigned int    touch_minor;
        unsigned int    width_minor;
        int             orientation;
        int             distance;
        int             blob_id;

        struct timeval  tv;

        /* BTN_TOUCH state */
        short           pen_down;

        /* the TSLIB_MT_VALID bit is set in valid if this sample
         * contains new data;
      * valid is set to 0 otherwise */
        short           valid;
};

⚠️ bestie this one is on YOU: the user has to provide the amount of memory described in nr and slots to hold them. Like, malloc it yourself, we're not your mom 😭

ts_read_raw() and ts_read_raw_mt() do the exact same thing, except no filters — raw, unfiltered, unbothered, in their own lane 🦋

🔥 RETURN VALUE 🔥

The number of actually read samples gets returned. And here's the tea 🍓: especially when opened in non-blocking mode (peep ts_setup()), that number can be less than requested in the call. On failure? A negative error number comes back. Not me getting -1'd 😭

✨ EXAMPLE ✨

The following program continuously reads tslib multitouch input samples and prints slot and position values to stdout as the touch screen is touched 👑📱

#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>

#include <tslib.h>

#define READ_SAMPLES 1
#define MAX_SLOTS 5

int main(int argc, char **argv)
{
        struct tsdev *ts;
        struct ts_sample_mt **samp_mt = NULL;
        int i, j;
        int ret;

        ts = ts_setup(NULL, 0);
        if (!ts)
                return -1;

        samp_mt = malloc(READ_SAMPLES * sizeof(struct ts_sample_mt **));
        if (!samp_mt)
                return -1;

        for (i = 0; i < READ_SAMPLES; i++) {
                samp_mt[i] = calloc(MAX_SLOTS, sizeof(struct ts_sample_mt));
                if (!samp_mt[i])
                        return -1;
        }

        while(1) {
                ret = ts_read_mt(ts, samp_mt, MAX_SLOTS, READ_SAMPLES);
                for (i = 0; i < ret; i++) {
                        printf("sample nr %d0, i);
                        for (j = 0; i < MAX_SLOTS; j++) {
                                if (!(samp_mt[i][j].valid & TSLIB_MT_VALID))
                                        continue;

                                printf("slot %d: X:%d Y: %d0,
                                       samp_mt[i][j].slot,
                                       samp_mt[i][j].x,
                                       samp_mt[i][j].y);
                        }
                }
        }
}

🌈 SEE ALSO 🌈

ts_setup(3), ts_config(3), ts_open(3), ts_close(3), ts.conf(5) — go read the whole friend group, iykyk 💜

mwah 💋 that's the whole page, bestie. this one came from the tslib manual, page TS_READ(3), and yeah that's the same name as the top because that's just how manpages roll 🙈 — she's giving iconic, she's giving tslib, and she said periodt. 🎀✨🦋