# Touch Peripheral (Absolute Pointer Input System)

Domain: virtual hardware: touch
Function: normative

Didactic companion: [`../learn/touch-mental-model.md`](../learn/touch-mental-model.md)

## 1 Scope

This chapter defines the runtime-facing TOUCH contract of PROMETEU.

Core contract:

- one absolute pointer at a time;
- framebuffer-aligned coordinates;
- per-frame state exposure;
- no gesture semantics;
- no acceleration or smoothing semantics.

## 2 Coordinate Space

- TOUCH coordinates use **the same space as the framebuffer**
- Resolution: **320×180**
- Origin: top-left corner `(0,0)`
- Ranges:
    - `x ∈ [0, 319]`
    - `y ∈ [0, 179]`

TOUCH is **absolute**:

- `(x, y)` represents the current contact position after normalization;
- the runtime does not apply dynamic transformation to that coordinate pair.

## 3 TOUCH Peripheral API

### 3.1 Exposed Structure

```
TOUCH:
  present   : bool
  down      : bool
  pressed   : bool
  released  : bool
  x         : int
  y         : int

```
### 3.2 Field Semantics

- **present**
    - `true` if the TOUCH peripheral is available
    - `false` if there is no physical touch (desktop, hardware without touch)
- **down**
    - `true` while the active pointer is pressed
- **pressed**
    - `true` only in the frame where the active pointer was captured
- **released**
    - `true` only in the frame where the active pointer was released
- **x, y**
    - current position of the active pointer
    - valid only when `down == true`

## 4 Pointer Selection Policy

### *Single Pointer Capture Policy*

When multiple physical touches occur, PROMETEU applies the following policy:

### 4.1 Initial Capture

1. If **no pointer is active**
2. And a **new physical touch** occurs
3. The **first detected touch** is captured
4. This touch becomes the **active pointer**

This frame generates:

- `pressed = true`
- `down = true`

### 4.2 Capture Maintenance

While the active pointer is pressed:

- Only it is tracked
- All other physical touches are ignored
- `x, y` follow only the active pointer

### 4.3 Release

When the active pointer is released:

- `released = true`
- `down = false`
- The system enters a **no active pointer** state

### 4.4 Recapture

After release:

- Touches that **were already present** are ignored
- A new pointer is only captured with a **new touch event**

## 5 Deliberately Unsupported Behaviors

The TOUCH peripheral **does not implement**:

❌ Multitouch

❌ Gestures (swipe, pinch, rotate, long-press)

❌ Acceleration or smoothing

❌ Dynamic sensitivity

❌ Implicit history

❌ Intent interpretation

If a game wants any of these behaviors, it must:

- implement them explicitly
- using only per-frame state
- without implicit hardware support

## 6 “No Gesture” — Formal Definition

PROMETEU **does not interpret temporal patterns**.

The TOUCH peripheral **does not classify actions** as:

- swipe
- drag
- long press
- double tap

It only reports:

- current position
- contact state

All semantics are the game's responsibility.

## 7 “No Acceleration” — Formal Definition

PROMETEU **does not modify** the TOUCH input.

- No sensitivity curves
- No speed-based amplification
- No smoothing

The relationship between the physical touch and `(x, y)` is **1:1** after normalization.

## 8 Integration with Other Input Forms

- Desktop:
    - mouse can emulate TOUCH
- Mobile:
    - direct physical touch
- Steam Deck:
    - physical touchscreen
- PROMETEU Hardware:
    - optional touch, but supported

## 9 Portability Guarantees

Every PROMETEU game that uses TOUCH:

- behaves identically on all platforms
- does not depend on host-specific capabilities
- does not suffer semantic variation between desktop, mobile, and dedicated hardware