Files
prometeu-runtime/docs/specs/runtime/07-touch-peripheral.md
T
bquarkz a32f834b2b
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
feat(graphics): migrate native target to 640x360
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.
2026-11-20 10:34:45 +00:00

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