4.0 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: 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
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.