implements PLN-0022
This commit is contained in:
@@ -536,7 +536,12 @@ The system can measure:
|
||||
|
||||
## 19. Syscall Return and Fault Policy
|
||||
|
||||
`gfx` follows status-first policy for operations with operational failure modes.
|
||||
Graphics-related public ABI in v1 is split between:
|
||||
|
||||
- `gfx.*` for direct drawing/backend-oriented operations;
|
||||
- `composer.*` for frame orchestration operations.
|
||||
|
||||
Only operations with real operational rejection paths return explicit status values.
|
||||
|
||||
Fault boundary:
|
||||
|
||||
@@ -544,50 +549,50 @@ Fault boundary:
|
||||
- `status`: operational failure;
|
||||
- `Panic`: internal runtime invariant break only.
|
||||
|
||||
### 19.1 `gfx.set_sprite`
|
||||
### 19.1 Return-shape matrix in v1
|
||||
|
||||
Return-shape matrix in v1:
|
||||
| Syscall | Return | Policy basis |
|
||||
| ----------------------- | ------------- | --------------------------------------------------- |
|
||||
| `gfx.clear` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.fill_rect` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_line` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_circle` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_disc` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_square` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_text` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.clear_565` | `void` | no real operational failure path in v1 |
|
||||
| `composer.bind_scene` | `status:int` | explicit orchestration-domain operational result |
|
||||
| `composer.unbind_scene` | `status:int` | explicit orchestration-domain operational result |
|
||||
| `composer.set_camera` | `void` | no real operational failure path in v1 |
|
||||
| `composer.emit_sprite` | `status:int` | explicit orchestration-domain operational rejection |
|
||||
|
||||
| Syscall | Return | Policy basis |
|
||||
| ------------------ | ------------- | ---------------------------------------------------- |
|
||||
| `gfx.clear` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.fill_rect` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_line` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_circle` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_disc` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_square` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.set_sprite` | `status:int` | operational rejection must be explicit |
|
||||
| `gfx.draw_text` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.clear_565` | `void` | no real operational failure path in v1 |
|
||||
### 19.2 `composer.emit_sprite`
|
||||
|
||||
Only `gfx.set_sprite` is status-returning in v1.
|
||||
All other `gfx` syscalls remain `void` unless a future domain revision introduces a real operational failure path.
|
||||
|
||||
### 19.2 `gfx.set_sprite`
|
||||
|
||||
`gfx.set_sprite` returns `status:int`.
|
||||
`composer.emit_sprite` returns `status:int`.
|
||||
|
||||
ABI:
|
||||
1. `bank_id: int` — index of the tile bank
|
||||
2. `index: int` — sprite index (0..511)
|
||||
1. `glyph_id: int` — glyph index within the bank
|
||||
2. `palette_id: int` — palette index
|
||||
3. `x: int` — x coordinate
|
||||
4. `y: int` — y coordinate
|
||||
5. `tile_id: int` — tile index within the bank
|
||||
6. `palette_id: int` — palette index (0..63)
|
||||
7. `active: bool` — visibility toggle
|
||||
8. `flip_x: bool` — horizontal flip
|
||||
9. `flip_y: bool` — vertical flip
|
||||
10. `priority: int` — layer priority (0..4)
|
||||
5. `layer: int` — composition layer reference
|
||||
6. `bank_id: int` — glyph bank index
|
||||
7. `flip_x: bool` — horizontal flip
|
||||
8. `flip_y: bool` — vertical flip
|
||||
9. `priority: int` — within-layer ordering priority
|
||||
|
||||
Minimum status table:
|
||||
|
||||
- `0` = `OK`
|
||||
- `2` = `INVALID_SPRITE_INDEX`
|
||||
- `3` = `INVALID_ARG_RANGE`
|
||||
- `4` = `BANK_INVALID`
|
||||
- `1` = `SCENE_UNAVAILABLE`
|
||||
- `2` = `INVALID_ARG_RANGE`
|
||||
- `3` = `BANK_INVALID`
|
||||
- `4` = `LAYER_INVALID`
|
||||
- `5` = `SPRITE_OVERFLOW`
|
||||
|
||||
Operational notes:
|
||||
|
||||
- no fallback to default bank when the sprite bank id cannot be resolved;
|
||||
- no silent no-op for invalid index/range;
|
||||
- `palette_id` and `priority` must be validated against runtime-supported ranges.
|
||||
- the canonical public sprite contract is frame-emission based;
|
||||
- no caller-provided sprite index exists in the v1 canonical ABI;
|
||||
- no `active` flag exists in the v1 canonical ABI;
|
||||
- overflow remains non-fatal and must not escalate to trap in v1.
|
||||
|
||||
@@ -39,6 +39,7 @@ Example:
|
||||
```
|
||||
("gfx", "present", 1)
|
||||
("audio", "play", 2)
|
||||
("composer", "emit_sprite", 1)
|
||||
```
|
||||
|
||||
This identity is:
|
||||
@@ -198,6 +199,24 @@ For `asset.load`:
|
||||
- `slot` is the target slot index;
|
||||
- bank kind is resolved from `asset_table` by `asset_id`, not supplied by the caller.
|
||||
|
||||
### Composition surface (`composer`, v1)
|
||||
|
||||
The canonical frame-orchestration public ABI uses module `composer`.
|
||||
|
||||
Canonical operations in v1 are:
|
||||
|
||||
- `composer.bind_scene(bank_id) -> (status)`
|
||||
- `composer.unbind_scene() -> (status)`
|
||||
- `composer.set_camera(x, y) -> void`
|
||||
- `composer.emit_sprite(glyph_id, palette_id, x, y, layer, bank_id, flip_x, flip_y, priority) -> (status)`
|
||||
|
||||
For mutating composer operations:
|
||||
|
||||
- `status` is a `ComposerOpStatus` value;
|
||||
- `bind_scene`, `unbind_scene`, and `emit_sprite` are status-returning;
|
||||
- `set_camera` remains `void` in v1;
|
||||
- no caller-provided sprite index or `active` flag is part of the canonical contract.
|
||||
|
||||
## 7 Syscalls as Callable Entities (Not First-Class)
|
||||
|
||||
Syscalls behave like call sites, not like first-class guest values.
|
||||
|
||||
@@ -85,6 +85,9 @@ Example:
|
||||
- `asset.load` currently resolves with `arg_slots = 2` and `ret_slots = 2`.
|
||||
- The canonical stack contract is `asset_id, slot -> status, handle`.
|
||||
- Callers do not provide an explicit asset kind; the runtime derives it from `asset_table`.
|
||||
- `composer.bind_scene` resolves with `arg_slots = 1` and `ret_slots = 1`.
|
||||
- The canonical stack contract is `bank_id -> status`.
|
||||
- `composer.emit_sprite` resolves with `arg_slots = 9` and `ret_slots = 1`.
|
||||
|
||||
#### Canonical Intrinsic Registry Artifact
|
||||
|
||||
|
||||
Reference in New Issue
Block a user