Crate speedy2d[−][src]

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 OpenGL ES 2.0+
Very fast

Supports Windows, Mac, and Linux. Should also work on Android and iOS (for rendering only).

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

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 WindowHelper instance, which lets you perform window-related actions, like requesting that a new frame is drawn using WindowHelper::request_redraw().

Note: Unless you call 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:

use speedy2d::GLRenderer;

let mut renderer = unsafe {
    GLRenderer::new_for_current_context((640, 480))
}.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));

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.
window	Allows for the creation and management of windows.

Structs

GLRenderer	A graphics renderer using an OpenGL backend.
GLRendererCreationError	An error encountered during the creation of a GLRenderer.
Graphics2D	A `Graphics2D` object allows you to draw shapes, images, and text to the screen.
Window	Struct representing a window.