Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Centralize the fixed 640x360 RGBA8888/60 Hz contract in the existing HAL. Preserve 8/16/32 tiles and composition, cover partial edges and mixed-size camera movement, and adapt firmware, fixtures, hosts and native tests. Share nearest-neighbor presentation geometry with pointer input. Measure actual framebuffer publications and successful host presentations separately from VM ticks, with bounded opt-in diagnostics and release harnesses. Validated with the complete tooling verify gate, native rendering tests, GPU readback, headless/process integration, formatting and strict clippy. The existing synchronous session path is documented; no worker/session architecture replacement or format compatibility layer is introduced. Work: WRK-0016 / DEC-0001 / PLN-0001 Commit and push explicitly authorized by the user after completion.
185 lines
4.6 KiB
Markdown
185 lines
4.6 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: **640×360**
|
||
- Origin: top-left corner `(0,0)`
|
||
- Ranges:
|
||
- `x ∈ [0, 639]`
|
||
- `y ∈ [0, 359]`
|
||
|
||
TOUCH is **absolute**:
|
||
|
||
- `(x, y)` represents the current contact position after normalization;
|
||
- the runtime does not apply dynamic transformation to that coordinate pair.
|
||
|
||
The host MUST apply the inverse of the actual presentation rectangle and scale,
|
||
including bars, proportional reduction, resize and HiDPI. A press outside that
|
||
rectangle MUST NOT capture a pointer. An active pointer leaving the image MUST
|
||
release, with `released` exposed for one logical frame under the existing button
|
||
contract. Returning while the physical button remains held MUST NOT recapture;
|
||
a new press inside is required. Releasing or losing focus must neutralize the
|
||
active pointer. Coordinates while `down == false` retain their existing invalid
|
||
status; no new guest-visible sentinel is introduced.
|
||
|
||
## 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).
|