chip8_base/
lib.rs

1//!`chip8-base` provides everything you need to get started building your own CHIP-8 interpreter.
2//! See the documentation for the [`Interpreter`][Interpreter] trait to get started.
3
4mod interpreter;
5mod pixel;
6
7pub use interpreter::run;
8pub use pixel::Pixel;
9
10/// The Interpreter's representation of the CHIP-8 display.
11/// The display is 64x32 pixels, each pixel being either Black or White.
12pub type Display = [[Pixel; 64]; 32];
13
14/// This type is how keyboard input is presented to the Interpreter.
15/// Each of the 16 keys can either be down (`true`) or up (`false`).
16pub type Keys = [bool; 16];
17
18/// CHIP-8 interpreters can be built using this trait.
19/// [`step`][Interpreter::step] should be implemented on a type representing a CHIP-8 Interpreter to run the interpreter one clock cycle at a time, such that calling it in a loop runs the interpreter.
20pub trait Interpreter {
21    /// Executes the next CHIP-8 Instruction, modifying the state of the virtual machine/CPU accordingly.
22    /// This is the main driver function, running the interpreter one clock cycle at a time.
23    /// # Return
24    /// If the instruction modified the state of the display, then an updated [`Display`][Display] should be returned.
25    /// # Panics
26    /// Should panic if an unrecognised instruction is encountered
27    fn step(&mut self, keys: &Keys) -> Option<Display>;
28
29    /// Returns the duration of a single clock cycle, so the interpreter can keep the time steps uniform.
30    /// See [`std::time`][std::time] for more information on [`Duration`][std::time::Duration].
31    fn speed(&self) -> std::time::Duration;
32
33    /// Indicates if the sound buzzer is currently active, such that the interpreter can handle sound accordingly.
34    fn buzzer_active(&self) -> bool;
35}