Crate vello_cpu 

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

We also develop Vello, which makes use of the GPU for 2D rendering and has higher performance than Vello CPU. Vello CPU is being developed as part of work to address shortcomings in Vello.

Usage

To use Vello CPU, you need to:

• Create a RenderContext, a 2D drawing context for a fixed-size target area.
• For each object in your scene:
  • Set how the object will be painted, using set_paint.
  • Set the shape to be drawn for that object, using methods like fill_path, stroke_path, or glyph_run.
• Render it to an image using RenderContext::render_to_pixmap.

use vello_cpu::{RenderContext, Pixmap, RenderMode};
use vello_cpu::{color::{palette::css, PremulRgba8}, kurbo::Rect};
let width = 10;
let height = 5;
let mut context = RenderContext::new(width, height);
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_to_pixmap(&mut target);

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);

Feel free to take a look at some further examples to better understand how to interact with 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.

Caveats

Overall, Vello CPU is already very feature-rich and should be ready for production use cases. The main caveat at the moment is that the API is still likely to change and not stable yet. For example, we have known plans to change the API around how image resources are used.

Additionally, there are certain APIs that are still very much experimental, including for example support for filters. This will be reflected in the documentation of those APIs.

Another caveat is that multi-threading with large thread counts (more than 4) might give diminishing returns, especially when making heavy use of layers and clip paths.

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 vello_common::color;

pub use vello_common::kurbo;

pub use vello_common::peniko;

Structs

Glyphtext

Positioned glyph.

Mask

A mask.

Pixmap

A pixmap of premultiplied RGBA8 values backed by u8.

RenderContext

A render context for CPU-based 2D graphics rendering.

RenderSettings

Settings to apply to the render context.

Enums

ImageSource

Bitmap source used by Image.

Level

The level enum with the specific SIMD capabilities available.

Paint

A paint that is used internally by a rendering frontend to store how a wide tile command should be painted. There are only two types of paint:

RenderMode

The selected rendering mode. For using RenderMode::OptimizeQuality you also need to enable f32_pipeline feature.

Type Aliases

Image

An image.

PaintType

A kind of paint that can be used for filling and stroking shapes.