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 |
Window | Struct representing a window. |