touch_map.c File Reference

Turning frames of touch points into down/up events, and the coordinate maps before them. More...

#include "touch_map.h"
#include <string.h>

Functions
static int16_t	clamp16 (int v, int lo, int hi)
	v clamped into lo..hi.
void	touch_map_size (const touch_map_t *m, int16_t *w, int16_t *h)
	Size of the mapped coordinate space (rotation may swap the axes).
void	touch_map_apply (const touch_map_t *m, int16_t x, int16_t y, int16_t *out_x, int16_t *out_y)
	Map one raw controller coordinate into screen space. Inputs outside the native range are clamped, so callers never see an off-screen point.
void	touch_map_point (const touch_map_t *m, touch_point_t *p)
	Map a whole point in place (id and strength are untouched).
touch_map_t	touch_map_turned (const touch_map_t *m, bool turned)
	The map with a 180 degree turn on top (touch_map.h).
void	touch_map_points (const touch_map_t *m, touch_point_t *pts, int n)
	Map n points in place (touch_map.h).
int	touch_map_crop (touch_point_t *pts, int count, int16_t w, int16_t h)
	Keep the points inside w x h, in order (touch_map.h).
void	touch_tracker_reset (touch_tracker_t *t)
	Forget every contact (touch_map.h).
static const touch_point_t *	find_by_id (const touch_point_t *pts, int count, uint8_t id)
	The first of count points with track id id.
int	touch_tracker_update (touch_tracker_t *t, const touch_point_t *cur, int cur_count, touch_event_t *out, int max_out)
	Diff a frame against the last one (touch_map.h).

Detailed Description

Turning frames of touch points into down/up events, and the coordinate maps before them.

The controller reports which contacts are present each frame; a screen wants to know when one arrived and when one left. This diffs consecutive frames by track id to produce those edges, and the order it emits them in is a safety decision: releases first, so a caller that reads only the first event still sees a finger lift before any new press – the STOP-then-arm order can never invert. A duplicate id in one frame is the controller misbehaving, and keeping only the first copy stops one finger becoming two events.

SPDX-License-Identifier: MIT

Function Documentation

clamp16()

int16_t clamp16 ( int v, int lo, int hi )

static

v clamped into lo..hi.

Parameters

v	The value.
lo	The lowest.
hi	The highest.

Returns

The clamped value.

find_by_id()

const touch_point_t * find_by_id ( const touch_point_t * pts, int count, uint8_t id )

static

The first of count points with track id id.

Parameters

pts	The points.
count	How many.
id	The track id.

Returns

The point, or NULL for none.

touch_map_apply()

void touch_map_apply	(	const touch_map_t *	m,
		int16_t	x,
		int16_t	y,
		int16_t *	out_x,
		int16_t *	out_y )

Map one raw controller coordinate into screen space. Inputs outside the native range are clamped, so callers never see an off-screen point.

Parameters

m	The map; NULL writes nothing.
x	The raw x.
y	The raw y.
out_x	Where the mapped x goes, or NULL.
out_y	Where the mapped y goes, or NULL.

touch_map_crop()

int touch_map_crop	(	touch_point_t *	pts,
		int	count,
		int16_t	w,
		int16_t	h )

Keep the points inside w x h, in order (touch_map.h).

Keep the mapped points inside a w x h area at the origin and drop the rest, in place and in order. A panel whose UI (user interface) draws a smaller area than the glass reports drops the touches outside it.

Keep the points inside w x h, in order (touch_map.h).

A contact dragged out of the area leaves the next frame as a release; one dragged back in is a new press.

Parameters

pts	The mapped points; the kept ones move to the front.
count	How many there are.
w	The area's width in pixels.
h	The area's height in pixels.

Returns

the number of points kept; 0 for a NULL pts, a negative count or an empty area.

touch_map_point()

void touch_map_point	(	const touch_map_t *	m,
		touch_point_t *	p )

Map a whole point in place (id and strength are untouched).

Parameters

m	The map; NULL leaves the point.
p	The point; NULL maps nothing.

touch_map_points()

void touch_map_points	(	const touch_map_t *	m,
		touch_point_t *	pts,
		int	n )

Map n points in place (touch_map.h).

Map n points in place, each as touch_map_point() maps it.

Map n points in place (touch_map.h).

Each source is mapped with its own map before the sources are merged: the glass from the resolution it reports, with the board's mirrors; the touch injector as panel pixels of the UI's area, unmirrored.

Parameters

m	The map; NULL leaves the points as they are.
pts	The points.
n	How many; 0 or less maps nothing.

touch_map_size()

void touch_map_size	(	const touch_map_t *	m,
		int16_t *	w,
		int16_t *	h )

Size of the mapped coordinate space (rotation may swap the axes).

Parameters

m	The map; NULL writes nothing.
w	Where the width goes, or NULL.
h	Where the height goes, or NULL.

touch_map_turned()

touch_map_t touch_map_turned	(	const touch_map_t *	m,
		bool	turned )

The map with a 180 degree turn on top (touch_map.h).

The map m with the picture turned by 180 degrees on top of it: a point m maps to (x, y) maps to (w - 1 - x, h - 1 - y), with w x h touch_map_size()'s area.

The map with a 180 degree turn on top (touch_map.h).

The panel turns its picture by its scan direction (display.h), so the frame buffer, and every screen with it, keeps its logical pixels; the glass's map turns with it and the touch injector's does not, since the injector names logical pixels.

Parameters

m	The map; NULL gives a zeroed map.
turned	True for the turned map; false gives m as it is.

Returns

The map, rotation advanced by TOUCH_ROTATION_180 when turned.

touch_tracker_reset()

void touch_tracker_reset

(

touch_tracker_t *

t

)

Forget every contact (touch_map.h).

Forget every contact: the next frame's are all new.

Forget every contact (touch_map.h).

Parameters

t	The tracker; NULL does nothing.

touch_tracker_update()

int touch_tracker_update	(	touch_tracker_t *	t,
		const touch_point_t *	cur,
		int	cur_count,
		touch_event_t *	out,
		int	max_out )

Diff a frame against the last one (touch_map.h).

Diff the current contact set against the previous one and emit DOWN/MOVE/UP events.

Diff a frame against the last one (touch_map.h).

A MOVE is only produced when the contact actually changed position. The UP of a contact missing from the frame carries no flag: a lift and a contact the controller left out of one report look the same. The UP made for a jump carries TOUCH_FLAG_NO_TAP, and the DOWN that follows it TOUCH_FLAG_JUMP.

Parameters

t	The tracker; NULL gives 0.
cur	This frame's contacts; NULL for none.
cur_count	How many, at most TOUCH_MAX_POINTS taken.
out	Where the events go; NULL for none.
max_out	Its room.

Returns

number of events written to out (never more than max_out; events past the limit are dropped, but the tracker state still advances so nothing gets stuck "down").