Lib.rs

wilhelm_renderer is a minimalist 2D graphics engine written in Rust with native OpenGL bindings. Its goal is to provide a robust foundation for rendering 2D shapes and visualizing 2D data and animations in real time.

Status

APIs are still evolving — always use the latest release.

Features

Shapes: Point, MultiPoint, Line, Polyline, Arc, Triangle, Rectangle, RoundedRectangle, Circle, Ellipse, Polygon, Image, Text

Rendering:

• Instanced rendering for high-performance scenes (10,000+ shapes)
• Per-shape rotation, scale, and position
• Fill, stroke, and fill+stroke styles
• Alpha/opacity support
• MSAA 4x multisampling

Text: FreeType-based rendering with font atlas caching and on-demand glyph loading

Projection: Camera2D with world/screen coordinate conversion, pan, zoom, and WGS84/Mercator support

Bundled dependencies: GLFW 3.4 and FreeType 2.13.2 are included — no external setup required

Crate structure

This crate provides the safe Rust API — shapes, camera, text, and the rendering loop. The companion wilhelm_renderer_sys crate contains the raw extern "C" bindings and the bundled GLFW 3.4 / FreeType 2.13.2 sources; Cargo pulls it in automatically as a transitive dependency.

Quick Start

use wilhelm_renderer::core::{App, Color, Window};
use wilhelm_renderer::graphics2d::shapes::{
    Circle, Rectangle, ShapeKind, ShapeRenderable, ShapeStyle, Text,
};

fn main() {
    let window = Window::new("Shapes", 800, 800, Color::from_rgb(0.07, 0.13, 0.17));
    let mut app = App::new(window);

    let shape = |pos: (f32, f32), kind: ShapeKind, style: ShapeStyle| {
        let mut s = ShapeRenderable::from_shape(kind, style);
        s.set_position(pos.0, pos.1);
        s
    };

    app.add_shapes(vec![
        shape((160.0, 280.0),
            ShapeKind::Text(Text::new("Hello!", "fonts/DejaVuSans.ttf", 48)),
            ShapeStyle::fill(Color::from_rgb(0.94, 0.91, 0.78)),
        ),
        shape((50.0, 50.0),
            ShapeKind::Rectangle(Rectangle::new(200.0, 80.0)),
            ShapeStyle::fill(Color::from_rgb(0.2, 0.5, 0.9)),
        ),
        shape((400.0, 400.0),
            ShapeKind::Circle(Circle::new(50.0)),
            ShapeStyle::fill(Color::from_rgb(0.0, 0.0, 1.0)),
        ),
    ]);

    app.run();
}

Examples

All examples are standalone Cargo projects in the examples/ directory. Run any example with:

cd examples/<example> && cargo run

Build all examples at once to verify API compatibility:

cargo build --workspace

	Example	Description
	triangle	Low-level: custom shaders and geometry
	transforms	Low-level: matrix transforms and animation
	shapes	All supported shape types
	text	Text rendering with FreeType
	rotations	Per-shape rotation and animation
	shapes_scaled	Shapes with scroll-to-zoom scaling
	bouncing_balls	200 animated balls with per-shape rendering
	instancing	1,750 instanced circles with per-instance color
	bouncing_balls_instanced	10,000 animated balls with instanced rendering
	alpha_transparency	Alpha blending and opacity control
	style_mutation	Dynamic color changes and HSL cycling
	z_order	Shape z-ordering independent of insertion order
	waypoints	WGS84 coordinates with Camera2D projection
	waypoints_instanced	Instanced waypoint markers with Camera2D

Installation

Linux

sudo apt-get install libgl1-mesa-dev
sudo apt install libwayland-dev libxkbcommon-dev xorg-dev

Windows

Ensure that Visual C++ Build Tools and CMake 3.5 or later are installed.

macOS

Ensure that the Xcode command-line tools and CMake 3.5 or later are installed.

Then add to your Cargo.toml:

[dependencies]
wilhelm_renderer = "0.10"

IDE Setup (C++ Language Server)

The C++ component uses CMake and lives in wilhelm_renderer_sys/cpp/. To enable clangd support, generate a compile_commands.json:

cmake -S wilhelm_renderer_sys/cpp -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

The build/ directory is gitignored. Re-run only when wilhelm_renderer_sys/cpp/CMakeLists.txt changes.

Issues

Report issues on GitHub.