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.
4.6 KiB
Touch Peripheral (Absolute Pointer Input System)
Domain: virtual hardware: touch Function: normative
Didactic companion: ../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
truewhile the active pointer is pressed
- pressed
trueonly in the frame where the active pointer was captured
- released
trueonly 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
- If no pointer is active
- And a new physical touch occurs
- The first detected touch is captured
- This touch becomes the active pointer
This frame generates:
pressed = truedown = true
4.2 Capture Maintenance
While the active pointer is pressed:
- Only it is tracked
- All other physical touches are ignored
x, yfollow only the active pointer
4.3 Release
When the active pointer is released:
released = truedown = 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.