Crate speedy2d

source ·
Expand description

Hardware-accelerated drawing of shapes, images, and text, with an easy to use API.

Speedy2D aims to be:

  • The simplest Rust API for creating a window, rendering graphics/text, and handling input
  • Compatible with any device supporting OpenGL 2.0+ or WebGL 2.0. Support for OpenGL ES 2.0+ is planned.
  • Very fast

Supports Windows, Mac, Linux, and WebGL. Support for Android and iOS is in development.

By default, Speedy2D contains support for setting up a window with an OpenGL context. If you’d like to handle this yourself, and use Speedy2D only for rendering, you can disable the windowing feature.

§Getting Started (Windows/Mac/Linux)

§Create a window

After adding Speedy2D to your Cargo.toml dependencies, create a window as follows:

use speedy2d::Window;

let window = Window::new_centered("Title", (640, 480)).unwrap();

You may also use Window::new_fullscreen_borderless(), Window::new_with_options(), or Window::new_with_user_events().

§Implement the callbacks

Create a struct implementing the WindowHandler trait. Override whichever callbacks you’re interested in, for example on_draw(), on_mouse_move(), or on_key_down().

use speedy2d::window::{WindowHandler, WindowHelper};
use speedy2d::Graphics2D;

struct MyWindowHandler {}

impl WindowHandler for MyWindowHandler
{
    fn on_draw(&mut self, helper: &mut WindowHelper, graphics: &mut Graphics2D)
    {
        // Draw things here using `graphics`
    }
}

The full list of possible callbacks is currently as follows. See WindowHandler for full documentation.

It’s only necessary to implement the callbacks you actually want to use. The default implementation will do nothing and continue the event loop.

fn on_start()
fn on_user_event()
fn on_resize()
fn on_scale_factor_changed()
fn on_draw()
fn on_mouse_move()
fn on_mouse_button_down()
fn on_mouse_button_up()
fn on_key_down()
fn on_key_up()
fn on_keyboard_char()
fn on_keyboard_modifiers_changed()

Each callback gives you a window::WindowHelper instance, which lets you perform window-related actions, like requesting that a new frame is drawn using window::WindowHelper::request_redraw().

Note: Unless you call window::WindowHelper::request_redraw(), frames will only be drawn when necessary, for example when resizing the window.

§Render some graphics

The WindowHandler::on_draw() callback gives you a Graphics2D instance, which lets you draw shapes, text, and images.

    fn on_draw(&mut self, helper: &mut WindowHelper, graphics: &mut Graphics2D)
    {
        graphics.clear_screen(Color::from_rgb(0.8, 0.9, 1.0));
        graphics.draw_circle((100.0, 100.0), 75.0, Color::BLUE);

        // Request that we draw another frame once this one has finished
        helper.request_redraw();
    }

§Start it running!

Once you’ve implemented the callbacks you’re interested in, start the event loop running with Window::run_loop():

let window = Window::<()>::new_centered("Title", (640, 480)).unwrap();

window.run_loop(MyWindowHandler{});

§Alternative: Managing the GL context yourself

If you’d rather handle the window creation and OpenGL context management yourself, simply disable Speedy2D’s windowing feature in your Cargo.toml file, and create a context as follows. You will need to specify a loader function to allow Speedy2D to obtain the OpenGL function pointers.

use speedy2d::GLRenderer;

let mut renderer = unsafe {
    GLRenderer::new_for_gl_context((640, 480), |fn_name| {
        window_context.get_proc_address(fn_name) as *const _
    })
}.unwrap();

Then, draw a frame using GLRenderer::draw_frame():

renderer.draw_frame(|graphics| {
    graphics.clear_screen(Color::WHITE);
    graphics.draw_circle((100.0, 100.0), 75.0, Color::BLUE);
});

§Laying out text

To render text, a font must be created. Call font::Font::new() with the bytes from the TTF or OTF font file.

(note: OTF support may be limited)

use speedy2d::font::Font;

let bytes = include_bytes!("../assets/fonts/NotoSans-Regular.ttf");
let font = Font::new(bytes).unwrap();

Then, invoke font.layout_text() (part of the font::TextLayout trait) to calculate the necessary line breaks and spacing. This will give you a font::FormattedTextBlock.

use speedy2d::font::TextLayout;

let block = font.layout_text("Hello World", 32.0, TextOptions::new());

Finally, call Graphics2D::draw_text() to draw the text block!

graphics.draw_text((100.0, 100.0), Color::BLUE, &block);

§Word wrap

To wrap lines of text to a certain width, use font::TextOptions::with_wrap_to_width():

use speedy2d::font::{TextLayout, TextAlignment};

let block = font.layout_text(
    "The quick brown fox jumps over the lazy dog.",
    32.0,
    TextOptions::new().with_wrap_to_width(300.0, TextAlignment::Left));

§Loading images

Image files (in formats such as PNG, JPG, and BMP) can be loaded using the following APIs, available in both Graphics2D and GLRenderer.

Alternatively, you can create an image from raw pixel data, using:

§Getting Started (WebGL)

To use Speedy2D with WebGL, your app must be compiled for WebAssembly. Speedy2D can attach itself to a canvas on the page using an ID you specify.

As with Windows/Mac/Linux targets, it’s possible to use Speedy2D either in a full rendering and event handling configuation, or for rendering only.

For rendering only, use the following API:

For full keyboard/mouse/etc event handling in addition to rendering, use:

After initialization, the usual WindowHandler callbacks and window::WindowHelper/Graphics2D APIs should operate as on other platforms.

For an example, see the examples/webgl directory. To build this, first install the prerequisites:

cargo install wasm-bindgen-cli just

Then use the following command to run the build:

just build-example-webgl

Modules§

  • color
    Types representing colors.
  • dimen
    Types representing sizes and positions.
  • error
    Error types.
  • font
    Components for loading fonts and laying out text.
  • image
    Types relating to images.
  • numeric
    Utilities and traits for numeric values.
  • shape
    Types representing shapes.
  • time
    Utilities for accessing the system clock on all platforms.
  • window
    Allows for the creation and management of windows.

Structs§