implemented intrinsecs de input and specs adjustment
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# Input Peripheral (Input System)
|
||||
# Input Peripheral (VM-Owned Snapshot Input)
|
||||
|
||||
Domain: virtual hardware: input
|
||||
Domain: virtual hardware: input
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/input-mental-model.md`](../learn/input-mental-model.md)
|
||||
@@ -11,154 +11,99 @@ This chapter defines the runtime-facing input contract of PROMETEU.
|
||||
|
||||
Core contract:
|
||||
|
||||
- input is exposed as state, not asynchronous callback flow;
|
||||
- sampling occurs at a defined moment in the logical frame;
|
||||
- queries are deterministic during the frame;
|
||||
- logical identifiers are stable across host devices.
|
||||
- input is exposed as VM-owned snapshot state;
|
||||
- sampling happens at a deterministic point of each logical frame;
|
||||
- queries are deterministic inside the same frame;
|
||||
- input access uses VM-owned intrinsics (not host syscalls in v1).
|
||||
|
||||
## 2 Input Devices
|
||||
## 2 Devices and Surface
|
||||
|
||||
PROMETEU abstracts different devices into a common interface.
|
||||
For v1, the input domain includes:
|
||||
|
||||
Typical devices:
|
||||
- `pad`
|
||||
- `touch`
|
||||
- `button` (as a nested state surface used by `pad` and `touch`)
|
||||
|
||||
- digital control (D-Pad + botões)
|
||||
- keyboard (mapped to buttons)
|
||||
- gamepad
|
||||
- touch (mobile, mapped)
|
||||
No analog axis is part of the v1 input contract.
|
||||
|
||||
Regardless of source, PROMETEU exposes the same logical model.
|
||||
## 3 Frame Sampling Model
|
||||
|
||||
## 3 State Model
|
||||
|
||||
### 3.1 Per-Frame State
|
||||
|
||||
For each frame, the system maintains:
|
||||
|
||||
- current state of buttons
|
||||
- state from the previous frame
|
||||
|
||||
This allows querying:
|
||||
|
||||
- button pressed
|
||||
- button released
|
||||
- button held down
|
||||
|
||||
### 3.2 Query Types
|
||||
|
||||
Typical operations:
|
||||
|
||||
```
|
||||
input.btn(id)// button is pressed
|
||||
input.btnp(id)// button was pressed this frame
|
||||
input.btnr(id)// button was released this frame
|
||||
```
|
||||
|
||||
These functions:
|
||||
|
||||
- are purely advisory
|
||||
- do not change state
|
||||
- have an explicit cost
|
||||
|
||||
## 4 Sampling Moment
|
||||
|
||||
The input state is captured **at the beginning of each frame**, before the `UPDATE` phase.
|
||||
Input state is captured at the beginning of each logical frame, before update logic runs.
|
||||
|
||||
Conceptual flow:
|
||||
|
||||
```
|
||||
```text
|
||||
FRAME N:
|
||||
SAMPLEINPUT
|
||||
SAMPLE_INPUT
|
||||
UPDATE
|
||||
DRAW
|
||||
AUDIO
|
||||
SYNC
|
||||
```
|
||||
|
||||
Throughout the entire frame:
|
||||
Within the same frame:
|
||||
|
||||
- the input state is immutable
|
||||
- repeated calls return the same value
|
||||
- input state is immutable;
|
||||
- repeated reads return the same values.
|
||||
|
||||
## 5 Determinism and Reproducibility
|
||||
## 4 State Semantics
|
||||
|
||||
The PROMETEU input model guarantees:
|
||||
`button` exposes:
|
||||
|
||||
- same sequence of inputs
|
||||
- same frames
|
||||
- same results
|
||||
- `pressed: bool` (true only on transition up -> down in this frame)
|
||||
- `released: bool` (true only on transition down -> up in this frame)
|
||||
- `down: bool` (true while physically pressed in this frame snapshot)
|
||||
- `hold: int` (count of consecutive pressed frames)
|
||||
|
||||
This allows:
|
||||
`pad` is a fixed set of buttons:
|
||||
|
||||
- execution playback
|
||||
- deterministic replays
|
||||
- reliable certification
|
||||
- `up`, `down`, `left`, `right`
|
||||
- `a`, `b`, `x`, `y`
|
||||
- `l`, `r`, `start`, `select`
|
||||
|
||||
Input can be:
|
||||
`touch` exposes:
|
||||
|
||||
- recorded
|
||||
- played back
|
||||
- artificially injected
|
||||
- `x: int`
|
||||
- `y: int`
|
||||
- `button` with the same `pressed/released/down/hold` semantics
|
||||
|
||||
## 6 Input and CAP
|
||||
PROMETEU handheld v1 uses single-touch active pointer semantics.
|
||||
|
||||
Input operations:
|
||||
## 5 Access Model
|
||||
|
||||
- consume few cycles
|
||||
- participate in the per-frame budget
|
||||
- appear in certification reports
|
||||
Input is VM-owned in v1:
|
||||
|
||||
Example:
|
||||
- frontend surfaces may be ergonomic and language-specific;
|
||||
- lowering maps to VM-owned `INTRINSIC <id_final>`;
|
||||
- no input syscall is required in the host ABI path.
|
||||
|
||||
```
|
||||
Frame 18231:
|
||||
input.btn():12cycles
|
||||
Illustrative (language-level) shape:
|
||||
|
||||
```text
|
||||
Input.pad().up().hold()
|
||||
Input.touch().x()
|
||||
```
|
||||
|
||||
Although cheap, input **is not free**.
|
||||
The normative contract is intrinsic identity/version and semantics, not source syntax.
|
||||
|
||||
## 7 Button Mapping
|
||||
## 6 Determinism and Replay
|
||||
|
||||
### 7.1 Logical Identifiers
|
||||
Given the same per-frame input snapshots, execution must produce the same observable results.
|
||||
|
||||
PROMETEU defines logical button identifiers:
|
||||
This enables:
|
||||
|
||||
- `UP`, `DOWN`, `LEFT`, `RIGHT`
|
||||
- `A`, `B`, `X`, `Y`
|
||||
- `START`, `SELECT`
|
||||
- deterministic replay;
|
||||
- deterministic certification analysis;
|
||||
- controlled input injection in tests/tooling.
|
||||
|
||||
The physical mapping:
|
||||
## 7 Capability and Certification
|
||||
|
||||
- depends on the platform
|
||||
- is resolved outside the VM
|
||||
- is transparent to the program
|
||||
Input reads are not capability-gated by syscall capability policy in v1.
|
||||
|
||||
### 7.2 Portability
|
||||
Input access is VM-owned and should not be reported as host syscall consumption.
|
||||
|
||||
The same PROMETEU cartridge:
|
||||
## 8 Portability
|
||||
|
||||
- runs on a keyboard
|
||||
- runs on a gamepad
|
||||
- runs on touch
|
||||
All platforms must provide the mandatory input elements (`pad`, `touch`, `button`) to the runtime.
|
||||
|
||||
Without any code changes.
|
||||
|
||||
## 8 Analog Input (Optional)
|
||||
|
||||
PROMETEU can expose analog axes explicitly:
|
||||
|
||||
```
|
||||
input.axis(id)
|
||||
```
|
||||
|
||||
Characteristics:
|
||||
|
||||
- normalized value (e.g.: -1.0 to 1.0)
|
||||
- explicit cost
|
||||
- per-frame update
|
||||
|
||||
Analog input:
|
||||
|
||||
- is not mandatory
|
||||
- does not replace digital input
|
||||
- must be used consciously
|
||||
Platform differences in physical device mapping are resolved outside VM semantics.
|
||||
|
||||
@@ -37,7 +37,6 @@ Example:
|
||||
|
||||
```
|
||||
("gfx", "present", 1)
|
||||
("input", "state", 1)
|
||||
("audio", "play", 2)
|
||||
```
|
||||
|
||||
@@ -47,6 +46,8 @@ This identity is:
|
||||
- toolchain-stable;
|
||||
- used for linking and capability gating.
|
||||
|
||||
Input queries are VM-owned intrinsic calls in v1 and are outside the syscall identity space.
|
||||
|
||||
## 3 Syscall Resolution
|
||||
|
||||
The host maintains a registry:
|
||||
|
||||
@@ -41,12 +41,13 @@ Example groups:
|
||||
|
||||
- `gfx`
|
||||
- `audio`
|
||||
- `input`
|
||||
- `asset`
|
||||
- `memcard`
|
||||
|
||||
Capability checks exist to constrain which host-managed surfaces a cartridge may use.
|
||||
|
||||
Input in v1 is VM-owned intrinsic surface and is not capability-gated through syscall policy.
|
||||
|
||||
## 3 Interaction with the Garbage Collector
|
||||
|
||||
The VM heap and host-managed memory are separate.
|
||||
|
||||
Reference in New Issue
Block a user