172 lines
3.7 KiB
Markdown
172 lines
3.7 KiB
Markdown
# Touch Peripheral (Absolute Pointer Input System)
|
||
|
||
Domain: virtual hardware: touch
|
||
Function: normative
|
||
|
||
Didactic companion: [`../learn/mental-model-touch.md`](../runtime/learn/mental-model-touch.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
|