Crate pix_engine
source · [−]Expand description
PixEngine
Table of Contents
- Summary
- Minimum Supported Rust Version
- Screenshots
- Getting Started
- Crate Features
- Known Issues
- License
- Contribution
- Contact
- Credits
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.
Some examples of things you can create with pix-engine
:
- 2D ray casting of scenes or objects.
- 2D games like Asteroids, Tetris, Pong, or platformers including sound effects, music and UI elements.
- User interfaces for basic applications or configuration.
- Algorithm visualizations for sorting, searching, or particle simulations.
- Image viewing and editing.
- Visual art.
Minimum Supported Rust Version (MSRV)
The current minimum Rust version is 1.59.0
.
Screenshots
Getting Started
Installing Dependencies
First and foremost you’ll need Rust installed! Follow the latest directions at https://www.rust-lang.org/learn/get-started.
When building or running applications for a desktop target such as macOS
,
Linux
, or Windows
and not a Web-Assembly target, you must install
SDL2 libraries. Note for windows: You may need to install
Visual Studio C++ Build Tools.
There are several options for installing SDL2
, but these are the most common:
- Install via homebrew for
macOS
, a package management tool likeapt
forLinux
orMSVC
forWindows
.
For more details and installation options see the rust-sdl2 documentation.
macOS, Linux, or Windows 10 Subsystem for Linux (homebrew)
brew install sdl2 sdl2_gfx sdl2_image sdl2_mixer sdl2_ttf
Linux (package manager)
Note: The minimum SDL2
version is 2.0.20
. Some package managers may not have
the latest versions available.
Ubuntu:
sudo apt-get install libsdl2-dev libsdl2-gfx-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
Fedora:
sudo dnf install SDL2-devel SDL2_gfx-devel SDL2_image-devel SDL2_mixer-devel SDL2_ttf-devel
Arch:
sudo pacman -S sdl2 sdl2_gfx sdl2_image sdl2_mixer sdl2_ttf
Windows (MSVC)
- Download the latest
SDL2
MSVC
development libraries from https://www.libsdl.org/download-2.0.php e.g. (SDL2-devel-2.0.20-VC.zip
). - Download the latest
SDL2_image
,SDL2_mixer
, andSDL2_ttf
MSVC
development libraries from https://www.libsdl.org/projects/. e.g. (SDL2_image-devel-2.0.5-VC.zip
). - Unzip each
.zip
file into a folder. - Copy library files:
- from:
lib\x64\
- to:
C:\Users\{Username}\.rustup\toolchains\{current toolchain}\lib\rustlib\{current toolchain}\lib
where{current toolchain}
is likelystable-x86_64-pc-windows-msvc
.
- Note: If you don’t use
rustup
, See rust-sdl2 for more info on Windows installation.
- from:
- Copy all
dll
files:- from:
lib\x64\
- to: your
cargo
project next toCargo.toml
.
- from:
MSVC binaries for SDL2 are also present in this repository under the lib
folder.
Creating Your Application
Creating a visual or interactive application using pix-engine
requires
implementing only a single method of the AppState
trait for your
application: AppState::on_update
which gets executed as
often as possible. 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
provides additional methods that can be implemented to
respond to user events and handle application startup and teardown.
Here’s an example application which simply draws a circle following the mouse and renders it white or black depending if the mouse is held down or not:
use pix_engine::prelude::*;
struct MyApp;
impl AppState for MyApp {
// Set up application state and initial settings. `PixState` contains
// engine specific state and utility methods for actions like getting mouse
// coordinates, drawing shapes, etc. (Optional)
fn on_start(&mut self, s: &mut PixState) -> PixResult<()> {
// Set the background to GRAY and clear the screen.
s.background(Color::GRAY);
// Change the font family to NOTO and size to 16 instead of using the
// defaults.
s.font_family(Font::NOTO)?;
s.font_size(16);
// Returning `Err` instead of `Ok` would indicate initialization failed,
// and that the application should terminate immediately.
Ok(())
}
// Main update/render loop. Called as often as possible unless
// `target_frame_rate` was set with a value. (Required)
fn on_update(&mut self, s: &mut PixState) -> PixResult<()> {
// Set fill color to black if mouse is pressed, otherwise wite.
if s.mouse_pressed() {
s.fill(color!(0));
} else {
s.fill(color!(255));
}
// Draw a circle with fill color at the mouse position with a radius of
// 80.
let m = s.mouse_pos();
s.circle([m.x(), m.y(), 80])?;
Ok(())
}
// Clean up any state or resources before exiting such as deleting temporary
// files or saving game state. (Optional)
fn on_stop(&mut self, s: &mut PixState) -> PixResult<()> {
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)
}
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.
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
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.