[−][src]Crate spectrusty
SPECTRUSTY
S P E C T R U S T Y is a library for building emulators based on various ZX Spectrum computer models and clones.
Components of the library can also be used to implement chiptune players, format converters, and more.
Because of its vast scope, SPECTRUSTY has been split into several dependent crates and one extra crate with complementary utilities. The additional crates can be used separately or through this library.
spectrusty- this library.- spectrusty-core - defines basic traits and structs.
- spectrusty-audio - tools for synthesizing and playing audio samples.
- spectrusty-formats - file formats and related utilities.
- spectrusty-peripherals - emulators of various peripheral devices.
- z80emu - Zilog's Z80 CPU family emulator, re-exported as
z80emu.
The separate crate spectrusty-utils, provides additional utilities, like TAPe organizers, tape ROM auto-loader, printer utilities, and keyboard helpers for various platforms.
Several features control which components will be included:
"audio"- includes spectrusty-audio which is re-exported as audio."formats"- includes spectrusty-formats which is re-exported as formats."peripherals"- includes spectrusty-peripherals which is re-exported as peripherals.
Additional features:
"snapshot"- enables serde serializers and deserializers, so custom snapshots can be created with ease in elastic formats."compression"- enables gzip compression/decompression of memory chunks stored in snapshots."boxed_frame_cache"- chipset implementations will have significantly reduced struct sizes by boxing their internal UlaFrameCache instances at the cost of a minimal performance penalty."sdl2"- enables audio implementation for SDL2 hardware abstraction layer."cpal"- enables audio implementation for cpal native audio library.
The default features are:
default = ["formats", "peripherals", "snapshot", "compression"]
Traits
Implemented by ZX Spectrum's core chipset emulators.
Responsible for code execution, keyboard input, video, and accessing peripheral devices:
| trait | function |
|---|---|
| UlaCommon | A grouping trait that includes all of the traits listed below in this table |
| ControlUnit | Code execution, reset/nmi, access to BusDevice peripherals |
| FrameState | Provides access to the frame and T-state counters |
| MemoryAccess | Provides access to onboard memory ZxMemory and memory extensions MemoryExtension |
| Video | Rendering video frame into pixel buffer, border-color control |
| KeyboardInterface | Keyboard input control |
| EarIn | EAR line input access |
| MicOut | MIC line output access |
| UlaControl | Accessors for specialized ULA functionality |
Audio output:
| trait | function |
|---|---|
| UlaAudioFrame | A grouping trait that includes all of the traits listed below in this table |
| AudioFrame | A helper trait for setting up Blep and ending audio frames |
| EarMicOutAudioFrame | Adds Blep steps from EAR/MIC output lines data |
| EarInAudioFrame | Adds Blep steps from EAR/MIC output lines data |
| AyAudioFrame | Renders Blep steps from AY-3-891x sound processor |
Emulated computer configurations:
| trait | function |
|---|---|
| HostConfig | Defines CPU clock frequency and a video frame duration |
Associated traits implemented by special unit structs for driving audio and video rendering and memory contention:
| trait | function |
|---|---|
| VideoFrame | Helps driving video rendering, provides arithmetic and conversion tools for VideoTs timestamps |
| MemoryContention | A trait that helps establish if an address is being contended |
| AmpLevels | Converts digital audio levels to sample amplitudes |
Implemented by other components:
| trait | implemented by | function |
|---|---|---|
| Cpu | Z80 CPU | Central processing unit |
| ZxMemory | System memory | An access to memory banks, pages, screens, attaching external ROM's |
| PagedMemory16k | Memory group | Groups memory implementations with 16k paging capability |
| PagedMemory8k | Memory group | Groups memory implementations with 8k paging capability |
| MemoryExtension | Memory extensions | Installs program counter traps to switch in and out external banks of memory |
| BusDevice | I/O peripheral devices | Establishes address and data BUS communication between CPU and peripherals |
| Blep | Bandwidth-Limited Pulse Buffer | An intermediate amplitude differences buffer for rendering square-waves |
Structs
These are the most commonly used:
| struct | function |
|---|---|
| VideoTs | A video T-state timestamp, that consist of two components: a scan line number and a horizontal T-state |
VFrameTs<V> | A VideoFrame aware video T-state timestamp, for timestamp calculations |
VFrameTsCounter<V, C> | Counts T-states and handles the CPU clock contention |
Ula<M, B, X, V> | A chipset for emulating ZX Spectrum 16/48k PAL/NTSC |
Ula128<B, X> | A chipset for emulating ZX Spectrum 128k/+2 |
Ula3<B, X> | A chipset for emulating ZX Spectrum +2A/+3 |
Scld<M, B, X, V> | A chipset for emulating TC2048 / TC2068 / TS2068 |
UlaPlus<U> | A wrapper chipset enhancer for emulating ULAplus graphic modes |
Generic parameters
M: A system memory that implements ZxMemory trait.B: A peripheral device that implements BusDevice.X: A memory extension that implements MemoryExtension.V: A unit struct that implements VideoFrame.C: A unit struct that implements MemoryContention.U: An underlying chipset implementing UlaPlusInner.
Re-exports
pub use spectrusty_core::z80emu; |
pub use spectrusty_formats as formats; |
Modules
| audio | Audio API. |
| bus | System bus device emulators to be used with ControlUnits. |
| chip | Chipset emulation building blocks and implementations. |
| clock | T-state timestamp types and counters. |
| memory | Memory API. |
| peripherals | Emulator components of various ZX Spectrum peripheral devices. |
| video | Video API. |