![Build Status] ![Latest Version] ![Doc Status] ![Downloads] ![License]
pix_engine is a cross-platform graphics & UI library for simple games,
visualizations, digital art, and graphics applications written in Rust,
supporting SDL2 (and soon Web-Assembly!) renderers.
The primary goal of this library is to be simple to setup and use for graphics or algorithm exploration and is not meant to be as fully-featured as other, larger graphics libraries.
It is intended to be more than just a toy library, however, and can be used to
drive real applications. The Tetanes NES emulator, for example uses
pix_engine for rendering, window and event handling.
The current minimum Rust version is 1.56.1.
Creating an application is as simple as implementing the only required method of
the AppState trait for your application:
AppState::on_update which gets executed as often as
possible by default. Within that function you'll have access to a mutable
PixState object which provides several methods for modifying
settings and drawing to the screen.
AppState has several additional methods that can be implemented to
respond to user and system events.
Here's an example application:
```rust norun use pixengine::prelude::*;
struct MyApp;
impl AppState for MyApp {
fn onstart(&mut self, s: &mut PixState) -> PixResult<()> {
// Setup App state. PixState contains engine specific state and
// utility functions for things like getting mouse coordinates,
// drawing shapes, etc.
s.background(Color::GRAY);
s.fontfamily(Font::NOTO)?;
s.font_size(16);
Ok(())
}
fn on_update(&mut self, s: &mut PixState) -> PixResult<()> {
// Main render loop. Called as often as possible, or based on `target frame rate`.
if s.mouse_pressed() {
s.fill(0); // Set fill color to a minimum grayscale of 0 (or black, #000).
} else {
s.fill(255); // Set fill color to a minimum grayscale of 255 (or white, #fff).
}
let m = s.mouse_pos();
// Draw circle with fill color at mouse position with radius 80.
s.circle([m.x(), m.y(), 80])?;
Ok(())
}
fn on_stop(&mut self, s: &mut PixState) -> PixResult<()> {
// Teardown any state or resources before exiting such as deleting temporary files.
Ok(())
}
}
fn main() -> PixResult<()> { let mut engine = PixEngine::builder() .withdimensions(800, 600) .withtitle("MyApp") .withframerate() .resizable() .build()?; let mut app = MyApp; engine.run(&mut app) } ```
When using the default target for macOS, Linux, or Windows, SDL2 libraries
are a required dependency. You can either install them manually using one of the
methods outlined in the rust-sdl2 crate, or you can use the use-vcpkg
feature flag to statically link them.
This library uses the log crate. To leverage
logging in your application, choose one of the supported logger implementations
and initialize it in your main function.
Example using env_logger:
```rust ignore fn main() -> PixResult<()> { env_logger::init();
let mut engine = PixEngine::builder()
.with_dimensions(800, 600)
.with_title("MyApp")
.build()?;
let mut app = MyApp;
engine.run(&mut app)
} ```
serde -
Adds serde Serialize/Deserialize implementations for all
enums/structs.
backtrace -
Enables the backtrace feature for anyhow, which allows printing
backtraces based on environment variables outlined in
std::backtrace. Useful for debugging.
use-vcpkg -
Enables static linking of the SDL2 libraries which are dependencies for
macOS, Linux, and Windows targets. Using this feature is the easiest way to
get up and running unless you already have SDL2 installed on your system.
sdl2 to use opengl as its renderer. This feature is disabled by
default, allowing sdl2 to use whichever renderer it defaults to on the
target system. For example, macOS defaults to metal.See the github issue tracker.
Licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
For issue reporting, please use the github issue tracker. You can also contact me directly at https://lukeworks.tech/contact/.
This has been a true passion project for several years and I can't thank the open source community enough for the all the amazing content and support.
A special shout out to the following projects which heavily inspired the implementation and evolution of this crate: