touch_map.h File Reference

Coordinate mapping and press/move/release tracking. Pure C; the unit tests are in test/host. More...

#include "touch_types.h"

Go to the source code of this file.

Data Structures
struct	touch_map_t
struct	touch_tracker_t
	The contacts of the last frame, to diff the next against. More...

Macros
#define	TOUCH_JUMP_PX   120
	A contact that moves further than this between two frames is treated as a lift and a new press rather than as one drag.

Functions
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 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.
void	touch_map_points (const touch_map_t *m, touch_point_t *pts, int n)
	Map n points in place, each as touch_map_point() maps it.
int	touch_map_crop (touch_point_t *pts, int count, int16_t w, int16_t 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.
void	touch_tracker_reset (touch_tracker_t *t)
	Forget every contact: the next frame's are all new.
int	touch_tracker_update (touch_tracker_t *t, const touch_point_t *cur, int cur_count, touch_event_t *out, int max_out)
	Diff the current contact set against the previous one and emit DOWN/MOVE/UP events.

Detailed Description

Coordinate mapping and press/move/release tracking. Pure C; the unit tests are in test/host.

SPDX-License-Identifier: MIT

Macro Definition Documentation

TOUCH_JUMP_PX

#define TOUCH_JUMP_PX   120

A contact that moves further than this between two frames is treated as a lift and a new press rather than as one drag.

The GT911 reuses track ids. When a release frame is missed (a poll that lands between the lift and the next press, or a failed I²C (Inter-Integrated Circuit) read), the reused id looks like the same finger moving across the panel, and the consumer gets a MOVE where it waits for an UP, which leaves a drag latched. A finger cannot cross 120px in one 10ms poll; a reused id can.

Function Documentation

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 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.

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.

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, 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.

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

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 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.

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.

touch_tracker_reset()

void touch_tracker_reset

(

touch_tracker_t *

t

)

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

Forget every contact (touch_map.h).

Parameters

t	The tracker; NULL does nothing.

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

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 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").

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