Skip to main content

Crate vello_cpu

Crate vello_cpu 

Source
Expand description

Vello CPU is a 2D graphics rendering engine written in Rust for devices with no or underpowered GPUs.

We also develop:

  1. Vello GPU, which shares Vello CPU’s architecture but moves rasterization and compositing to the GPU.
  2. Vello Research, an experimental, high-performance, compute-centric GPU renderer.

§Usage

To use Vello CPU, you need to:

use vello_cpu::{RenderContext, Resources, Pixmap};
use vello_cpu::{color::{palette::css, PremulRgba8}, kurbo::Rect};
let width = 10;
let height = 5;
let mut context = RenderContext::new(width, height);
let mut resources = Resources::new();
context.set_paint(css::MAGENTA);
context.fill_rect(&Rect::from_points((3., 1.), (7., 4.)));

let mut target = Pixmap::new(width, height);
// While calling `flush` is only strictly necessary if you are rendering using
// multiple threads, it is recommended to always do this.
context.flush();
context.render(&mut target, &mut resources);

let expected_render = b"\
    0000000000\
    0001111000\
    0001111000\
    0001111000\
    0000000000";
let magenta = css::MAGENTA.premultiply().to_rgba8();
let transparent = PremulRgba8 {r: 0, g: 0, b: 0, a: 0};
let mut result = Vec::new();
for pixel in target.data() {
    if *pixel == magenta {
        result.push(b'1');
    } else if *pixel == transparent {
        result.push(b'0');
    } else {
         panic!("Got unexpected pixel value {pixel:?}");
    }
}
assert_eq!(&result, expected_render);

See the examples for more complete demonstrations of Vello CPU’s API.

§Features

  • std (enabled by default): Get floating point functions from the standard library (likely using your target’s libc).
  • libm: Use floating point implementations from libm.
  • png(enabled by default): Allow loading Pixmaps from PNG images. Also required for rendering glyphs with an embedded PNG. Implies std.
  • multithreading: Enable multi-threaded rendering. Implies std.
  • text (enabled by default): Enables glyph rendering (glyph_run).
  • u8_pipeline (enabled by default): Enable the u8 pipeline, for speed focused rendering using u8 math. The u8 pipeline will be used for OptimizeSpeed, if both pipelines are enabled. If you’re using Vello CPU for application rendering, you should prefer this pipeline.
  • f32_pipeline: Enable the f32 pipeline, which is slower but has more accurate results. This is espectially useful for rendering test snapshots. The f32 pipeline will be used for OptimizeQuality, if both pipelines are enabled.

At least one of std and libm is required; std overrides libm. At least one of u8_pipeline and f32_pipeline must be enabled. You might choose to disable one of these pipelines if your application won’t use it, so as to reduce binary size.

§Current state

Vello CPU is a solid CPU-only 2D renderer with broad, reliable feature support. It provides excellent performance across a wide range of workloads, with optimized SIMD implementations for all major architectures. The renderer is still under active development, however, and a few limitations remain:

  • Complex filter graphs are currently not supported at all and will panic. In multi-threaded mode, even simple filters are currently unsupported.
  • Parts of the API and its documentation are still suboptimal, for example the Resources lifecycle.
  • Some exposed features remain experimental and are not recommended for use, including glyph caching. Experimental APIs are identified in their method documentation.
  • There is still more room for performance improvements, in particular on x86 systems and also for multi-threaded rendering.

With that said, we are continuously improving Vello CPU and will address these and other limitations in future releases.

§Performance

Performance benchmarks can be found here, As can be seen, Vello CPU achieves compelling performance on both, aarch64 and x86 platforms. We also have SIMD optimizations for WASM SIMD, meaning that you can expect good performance there as well.

§Implementation

If you want to gain a better understanding of Vello CPU and the sparse strips paradigm, you can take a look at the accompanying master’s thesis that was written on the topic. Note that parts of the descriptions might become outdated as the implementation changes, but it should give a good overview nevertheless.

Re-exports§

pub use text::GlyphRunBuilder;text

Modules§

filter_effects
Filter effects API based on the W3C Filter Effects specification.
geometry
Geometry utilities.
peniko
A Rust 2D graphics type library

Structs§

Glyphtext
Positioned glyph.
ImageId
Opaque image handle
Mask
A mask.
PixelMetadata
Metadata about the pixels of an image.
Pixmap
A pixmap of premultiplied RGBA8 values backed by u8.
PixmapMut
A mutable view into premultiplied RGBA8 pixmap data.
RasterizerSettings
Settings used when rasterizing a scene into a pixmap.
RenderContext
A render context for CPU-based 2D graphics rendering.
RenderSettings
Settings to apply to the render context.
RenderState
A render state which contains the style properties for path rendering.
Resources
Persistent resources required by Vello CPU for rendering.
Tint
A tint applied to image paints.
Transforms
Context for holding transforms for paths and paints.

Enums§

ImageSource
Bitmap source used by Image.
Level
The level enum with the specific SIMD capabilities available.
PixelFormat
The pixel format to assume for the destination pixmap.
Pixels
The result of attempting to extract RGB8 data from a Pixmap.
RenderMode
The selected rendering mode. For using RenderMode::OptimizeQuality you also need to enable f32_pipeline feature.
TintMode
How tint color is applied to an image.

Type Aliases§

GlyphRunBuildertext
A glyph run builder.
Image
An image.
PaintType
A kind of paint that can be used for filling and stroking shapes.
TargetInit
How the destination pixmap is initialized before rendering.