se.cherkasov
ea0c5b1894
Some checks failed
CI / rust (push) Has been cancelled
Fix 9 clippy warnings across mmc5 mapper and desktop frontend. Sync api_contract.md and architecture.md with actual public surface.
135 lines
3.4 KiB
Markdown
135 lines
3.4 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`
|
|
- `Ppu`
|
|
- `Apu`
|
|
- `ApuStateTail`
|
|
- `ChannelOutputs`
|
|
- High-level runtime:
|
|
- `NesRuntime`
|
|
- `RuntimeError`
|
|
- Host execution and lifecycle:
|
|
- `RuntimeHostLoop`
|
|
- `ClientRuntime`
|
|
- `HostConfig`
|
|
- `EmulationState`
|
|
- Host IO traits:
|
|
- `InputProvider`
|
|
- `VideoOutput`
|
|
- `AudioOutput`
|
|
- Null/stub implementations:
|
|
- `NullInput`
|
|
- `NullVideo`
|
|
- `NullAudio`
|
|
- Audio helpers:
|
|
- `AudioMixer`
|
|
- `RingBuffer`
|
|
- Timing and pacing:
|
|
- `FrameClock`
|
|
- `FramePacer`
|
|
- `PacingClock`
|
|
- `NoopClock`
|
|
- `VideoMode`
|
|
- Video constants:
|
|
- `FRAME_WIDTH`
|
|
- `FRAME_HEIGHT`
|
|
- `FRAME_RGBA_BYTES`
|
|
- Input helpers:
|
|
- `JoypadButton`
|
|
- `JoypadButtons`
|
|
- `JOYPAD_BUTTON_ORDER`
|
|
- `JOYPAD_BUTTONS_COUNT`
|
|
- `set_button_pressed`
|
|
- `button_pressed`
|
|
- State versioning:
|
|
- `SAVE_STATE_VERSION`
|
|
|
|
## 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
|