Crate pix_engine[−][src]

Expand description

PixEngine

License

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

Asteroids Fluid Simulation 2D Raycasting UI Widgets Maze Generation & A* Search Matrix Rain

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 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.