se.cherkasov
bdf23de8db
Some checks failed
CI / rust (push) Has been cancelled
Full NES emulation: CPU, PPU, APU, 47 mappers, iNES/NES 2.0 parsing. GTK4 desktop client with HeaderBar, pixel-perfect Cairo rendering, drag-and-drop ROM loading, and keyboard shortcuts. 187 tests covering core emulation, mappers, and runtime.
117 lines
3.1 KiB
Markdown
117 lines
3.1 KiB
Markdown
# API Contract
|
|
|
|
This document defines the supported external contract for `nesemu` `0.x`.
|
|
|
|
Use this file as the boundary of what external clients should rely on. For practical embedding examples, see `integration.md`. For internal structure, see `architecture.md`.
|
|
|
|
## Supported Surface
|
|
|
|
External users should prefer these entry points:
|
|
|
|
- Root crate re-exports from `src/lib.rs`
|
|
- `nesemu::runtime::*`
|
|
- `nesemu::prelude::*`
|
|
|
|
Optional adapter-facing API is available behind features:
|
|
|
|
- `adapter-api`
|
|
- `adapter-headless`
|
|
|
|
## Recommended Public Entry Points
|
|
|
|
The main public API is organized around these groups:
|
|
|
|
- ROM loading:
|
|
- `parse_header`
|
|
- `parse_rom`
|
|
- `InesHeader`
|
|
- `InesRom`
|
|
- `Mirroring`
|
|
- Cartridge mapping:
|
|
- `create_mapper`
|
|
- `Mapper`
|
|
- Low-level execution:
|
|
- `Cpu6502`
|
|
- `CpuBus`
|
|
- `CpuError`
|
|
- `NativeBus`
|
|
- High-level runtime:
|
|
- `NesRuntime`
|
|
- Host execution and lifecycle:
|
|
- `RuntimeHostLoop`
|
|
- `ClientRuntime`
|
|
- `HostConfig`
|
|
- `EmulationState`
|
|
- Host IO traits:
|
|
- `InputProvider`
|
|
- `VideoOutput`
|
|
- `AudioOutput`
|
|
- Timing and pacing:
|
|
- `FrameClock`
|
|
- `FramePacer`
|
|
- `PacingClock`
|
|
- `NoopClock`
|
|
- `VideoMode`
|
|
- Input helpers:
|
|
- `JoypadButton`
|
|
- `JoypadButtons`
|
|
- `JOYPAD_BUTTON_ORDER`
|
|
- `JOYPAD_BUTTONS_COUNT`
|
|
- `set_button_pressed`
|
|
- `button_pressed`
|
|
|
|
## Supported Client Flow
|
|
|
|
The expected integration flow is:
|
|
|
|
1. Load ROM bytes and parse them, or construct `NesRuntime` directly from ROM bytes.
|
|
2. Choose your integration level:
|
|
- use `Cpu6502` + `NativeBus` for low-level control
|
|
- use `NesRuntime` for a higher-level core wrapper
|
|
- use `RuntimeHostLoop` or `ClientRuntime` for host-facing frame execution
|
|
3. Provide input, video, and audio implementations through the public host traits.
|
|
4. Use save/load state through the runtime or bus APIs when snapshot behavior is needed.
|
|
|
|
## Stability Rules
|
|
|
|
The following are considered the primary supported surface for `0.x`:
|
|
|
|
- root re-exports
|
|
- `runtime`
|
|
- `prelude`
|
|
|
|
The following are available but less stable:
|
|
|
|
- `native_core::*` for advanced or experimental integrations
|
|
|
|
Lower-level modules may evolve faster than the root re-export surface.
|
|
|
|
## Compatibility Notes
|
|
|
|
- Types marked `#[non_exhaustive]` may gain fields or variants without a major version bump.
|
|
- Save-state compatibility is only guaranteed within the same crate version unless explicitly documented otherwise.
|
|
- Optional features may expose additional adapter-facing API, but they do not change the baseline contract of the main library.
|
|
|
|
## Extension Points
|
|
|
|
The intended extension points for hosts and frontends are:
|
|
|
|
- `InputProvider`
|
|
- `VideoOutput`
|
|
- `AudioOutput`
|
|
- `FrameClock`
|
|
- optional adapter bridge types when `adapter-api` is enabled:
|
|
- `InputAdapter`
|
|
- `VideoAdapter`
|
|
- `AudioAdapter`
|
|
- `ClockAdapter`
|
|
|
|
## Out Of Scope
|
|
|
|
This contract does not promise stability for:
|
|
|
|
- GTK frontend behavior in `nesemu-desktop`
|
|
- internal module layout under `native_core` and `runtime`
|
|
- concrete implementation details of mapper modules
|
|
- cross-version save-state compatibility unless explicitly documented
|