Crate vello 

Vello is a 2d graphics rendering engine written in Rust, using wgpu. It efficiently draws large 2d scenes with interactive or near-interactive performance.

Motivation

Vello is meant to fill the same place in the graphics stack as other vector graphics renderers like Skia, Cairo, and its predecessor project Piet. On a basic level, that means it provides tools to render shapes, images, gradients, texts, etc, using a PostScript-inspired API, the same that powers SVG files and the browser <canvas> element.

Vello’s selling point is that it gets better performance than other renderers by better leveraging the GPU. In traditional PostScript-style renderers, some steps of the render process like sorting and clipping either need to be handled in the CPU or done through the use of intermediary textures. Vello avoids this by using prefix-scan algorithms to parallelize work that usually needs to happen in sequence, so that work can be offloaded to the GPU with minimal use of temporary buffers.

This means that Vello needs a GPU with support for compute shaders to run.

Getting started

Vello is meant to be integrated deep in UI render stacks. While drawing in a Vello Scene is easy, actually rendering that scene to a surface setting up a wgpu context, which is a non-trivial task.

To use Vello as the renderer for your PDF reader / GUI toolkit / etc, your code will have to look roughly like this:

// Initialize wgpu and get handles
let (width, height) = ...;
let device: wgpu::Device = ...;
let queue: wgpu::Queue = ...;
let mut renderer = Renderer::new(
   &device,
   RendererOptions {
      use_cpu: false,
      antialiasing_support: vello::AaSupport::all(),
      num_init_threads: NonZeroUsize::new(1),
   },
).expect("Failed to create renderer");

// Create scene and draw stuff in it
let mut scene = vello::Scene::new();
scene.fill(
   vello::peniko::Fill::NonZero,
   vello::Affine::IDENTITY,
   vello::Color::from_rgb8(242, 140, 168),
   None,
   &vello::Circle::new((420.0, 200.0), 120.0),
);

// Draw more stuff
scene.push_layer(...);
scene.fill(...);
scene.stroke(...);
scene.pop_layer(...);

let texture = device.create_texture(&...);
// Render to a wgpu Texture
renderer
   .render_to_texture(
      &device,
      &queue,
      &scene,
      &texture,
      &vello::RenderParams {
         base_color: palette::css::BLACK, // Background color
         width,
         height,
         antialiasing_method: AaConfig::Msaa16,
      },
   )
   .expect("Failed to render to a texture");
// Do things with surface texture, such as blitting it to the Surface using
// wgpu::util::TextureBlitter.

See the examples/ folder to see how that code integrates with frameworks like winit.

Modules

low_level

Utilities which can be used to create an alternative Vello renderer to Renderer.

peniko

A Rust 2D graphics type library

util

Simple helpers for managing wgpu state and surfaces.

wgpu

wgpu is a cross-platform, safe, pure-Rust graphics API. It runs natively on Vulkan, Metal, D3D12, and OpenGL; and on top of WebGL2 and WebGPU on wasm.

Structs

AaSupport

Represents the set of anti-aliasing configurations to enable during pipeline creation.

DeferredPipelines

Renderer::deferred_pipelines: what a deferring renderer has not built.

DrawGlyphs

Builder for encoding a glyph run.

FontEmbolden

Synthetic embolden settings for a glyph run.

Glyph

Positioned glyph.

ImageCacheStats

What the image cache holds, for memory diagnostics.

ImageSource

A texture an image’s pixels are drawn from, through a render pass.

RenderParams

Parameters used in a single render that are configurable by the client.

Renderer

Renders a scene into a texture or surface.

RendererMemoryStats

GPU allocations whose sizes Vello can account for directly. Driver, pipeline-cache, and swapchain memory are intentionally excluded.

RendererOptions

Options which are set at renderer creation time, used in Renderer::new.

Scene

The main datatype for rendering graphics.

Enums

AaConfig

Represents the anti-aliasing method to use during a render pass.

BumpBudgetError

A counter readback could not establish whether the render fit its budget.

BumpBudgetPoll

State of the outstanding adaptive bump-counter readbacks.

Error

Errors that can occur in Vello.

PipelineDeferral

Which of its pipelines Renderer::new_deferring builds before it returns (Tilo patch). A deferred pipeline is built by Renderer::start_deferred_pipelines’ background thread, or by the first render that dispatches it; no dispatch ever runs without its pipeline.

Constants

SHADER_FINGERPRINT

A stable identity of every shader’s name and WGSL text in this build.

Functions

set_external_image_source

Install the process’s ExternalImageSource. The first one installed stays.

Type Aliases

ExternalImageSource

Supplies the pixels of an image drawn with an empty blob — one whose pixels live in a texture overridden on another renderer (see Renderer::override_image) — to a renderer that has no override for it. Given the blob id, it returns the image’s tightly packed pixels.

NormalizedCoord

A normalized variation coordinate (for variable fonts) in 2.14 fixed point format.