Files
prometeu-runtime/docs/specs/runtime/07-touch-peripheral.md
T
bquarkz a2275932a5
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
Keep PBX at v0 and simplify Jenkins quality gate
2026-10-14 14:35:44 +01:00

176 lines
4.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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: **480×270**
- Origin: top-left corner `(0,0)`
- Ranges:
- `x ∈ [0, 479]`
- `y ∈ [0, 269]`
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:
down : bool
pressed : bool
released : bool
hold : Int64
x : Int64
y : Int64
```
### 3.2 Field Semantics
- **availability**
- is not a guest field or endpoint value
- a known query without a platform source raises `TRAP_UNAVAILABLE`
- **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
## Fixed query catalogue
Touch button queries occupy 0x2130–0x2133 (pressed/released/down/hold); x/y use 0x2134/0x2135. All have zero arguments and read the frame snapshot. Button states return Bool; hold and coordinates return Int64. See the [complete input contract](02c-program-registry-and-pbx-v0.md#input).