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

4.0 KiB
Raw Blame History

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
    • 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.