Crate pix_engine[−][src]
Expand description
PixEngine
Summary
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.
Minimum Supported Rust Version
The current minimum Rust version is 1.56.1
.
Getting Started
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:
use pix_engine::prelude::*;
struct MyApp;
impl AppState for MyApp {
fn on_start(&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.font_family(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()
.with_dimensions(800, 600)
.with_title("MyApp")
.with_frame_rate()
.resizable()
.build()?;
let mut app = MyApp;
engine.run(&mut app)
}
Screenshots
Dependencies
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.
Crate features
Logging
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:
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)
}
Utility features
-
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.
Renderer features
- opengl -
Forces
sdl2
to useopengl
as its renderer. This feature is disabled by default, allowingsdl2
to use whichever renderer it defaults to on the target system. For example, macOS defaults tometal
.
Known Issues
See the github issue tracker.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.
Contribution
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.
Contact
For issue reporting, please use the github issue tracker. You can also contact me directly at https://lukeworks.tech/contact/.
Credits
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:
- OneLoneCoder and the olcPixelGameEngine.
- The Coding Train and p5js.
- Dear ImGui
Modules
Audio
functions.
Drawing methods.
Errors that this crate can return.
3D Graphics functions.
Graphical User Interface methods.
Image and PixelFormat
functions.
Math functions and constants.
Exports most commonly used types, traits, and functions.
Graphics renderer functions.
Serialization/Deserialization modules.
Shape methods for drawing.
Texture
methods.
Transformation functions and types.
Window
functions.
Macros
Returns the Perlin noise value at specified coordinates.
Returns a random number within a range.