# 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).