Piet 2D Graphics Abstraction

Piet is a cross-platform 2D graphics abstraction library. It consists of a core crate (piet) that defines the 2D graphics API and several backend crates that implement this API using the native 2D graphics systems of different platforms. This architecture allows developers to write drawing code once and run it on multiple platforms without bundling a heavy renderer.

Key relationships:

• piet: The core API crate.
• kurbo: A companion crate for Bézier path representation and geometry.
• Druid: A cross-platform GUI toolkit that uses Piet as its graphics foundation.

The piet-cairo backend currently uses the Cairo toy text API. This means text rendering is simplified and lacks advanced typographic features:

• No shaping: Complex scripts will not render correctly.
• No refinements: Latin text will lack kerning, ligatures, and other professional refinements.

For serious applications requiring high-quality text layout, this backend may not be sufficient until higher-level text support (such as Pango or HarfBuzz) is implemented.

The piet-common package provides automatic backend selection for the Piet 2D graphics API based on the target platform. When using Piet, the appropriate implementation is selected automatically as follows:

• Windows: piet-direct2d
• macOS: piet-coregraphics
• Linux, OpenBSD, FreeBSD, and NetBSD: piet-cairo
• wasm32 (Web): piet-web

Piet provides several backends for different platforms. For most cross-platform applications, you should use the piet-common crate, which automatically re-exports the most appropriate implementation for your current target platform.

Available backends:

• piet-cairo: Uses the Cairo library.
• piet-coregraphics: macOS only.
• piet-direct2d: Windows only.
• piet-svg: SVG output.
• piet-web: Web-based rendering.

Piet is verified to compile with Rust 1.92 and later.

Note that future versions may increase this requirement, even in patch releases, as dependencies may update their own MSRV requirements.

If you are running examples from the Piet repository, you must ensure that the submodules are checked out. Run the following command from the root directory:

git submodule update --init

To run the web-based examples for piet-web, you must have cargo and npm installed. You also need wasm-pack to build the WebAssembly components.

1. Install wasm-pack if you haven't already: cargo install wasm-pack
2. Navigate to the basic example directory and run the build script: cd examples/basic && ./build.sh
3. Open your browser to the local web server address provided by the script output.

$ cargo install wasm-pack
$ cd examples/basic && ./build.sh

Tests for piet-web are executed using wasm-pack against the Chrome browser in headless mode. Currently, Chrome is the only supported browser for testing.

1. Install wasm-pack: cargo install wasm-pack
2. Run the tests: wasm-pack test --chrome --headless

$ cargo install wasm-pack
$ wasm-pack test --chrome --headless

The cairo-rs crate used by piet-cairo expects the Cairo library to be provided on the system rather than building it from source. Follow these instructions based on your operating system:

• Windows: Use prebuilt binary releases from cairo-windows.
• macOS: Install via Homebrew using brew install cairo.
• OpenBSD: Install via official packages using pkg_add cairo.
• FreeBSD: Install via pkg using pkg install cairo.
• NetBSD: Install via pkgin using pkgin install cairo.

A pkg-config file is provided as usual, allowing cairo-rs to build correctly after installation.

The piet-direct2d crate provides convenience wrappers around Windows DirectWrite objects for text rendering. While many of these types are intended for internal system integration (e.g., DwriteFactory), they form the basis for text layout and formatting in the Direct2D backend.

Key types include:

• TextFormat: Defines font properties like size and weight.
• FontCollection: A collection of available fonts.
• TextLayout: Manages the layout of a specific string of text, including alignment, styling, and hit testing.
• Utf16Range: Represents a range within a Windows UTF-16 string using a start position and length.

The WebRenderContext provides the following concrete types for the RenderContext trait:

• Brush: Brush (supports Solid and Gradient)
• Text: WebText
• TextLayout: WebTextLayout
• Image: WebImage

Piet uses a builder pattern to separate the configuration of text from the actual layout process.

1. Text: The entry point. You use it to manage fonts and to call new_text_layout().
2. TextLayoutBuilder: The configuration stage. You use this to set fonts, sizes, alignments, and specific character attributes (like bolding a word). This stage is mutable and allows chaining calls.
3. TextLayout: The final product. Once you call .build() on the builder, you get a TextLayout, which is an immutable, drawable object used for rendering and hit-testing.

This separation allows the heavy lifting of text shaping and layout to be deferred until the configuration is complete.