Struct Resources 

pub struct Resources { /* private fields */ }

Persistent resources required by Vello CPU for rendering.

You should create one such instance per renderer.

Implementations

impl Resources

pub fn new() -> Self

Create a new set of renderer resources.

Examples found in repository

examples/clipping.rs (line 129)

fn save_pixmap(ctx: &RenderContext, filename: &str) {
    let mut resources = Resources::new();
    let mut pixmap = Pixmap::new(ctx.width(), ctx.height());
    ctx.render(&mut pixmap, &mut resources);
    let png = pixmap.into_png().unwrap();
    std::fs::write(format!("{filename}.png"), png).unwrap();
}

examples/paints.rs (line 136)

fn save_pixmap(ctx: &RenderContext, filename: &str) {
    let mut resources = Resources::new();
    let mut pixmap = Pixmap::new(ctx.width(), ctx.height());
    ctx.render(&mut pixmap, &mut resources);
    let png = pixmap.into_png().unwrap();
    std::fs::write(format!("{filename}.png"), png).unwrap();
}

examples/masking.rs (line 22)

fn main() {
    // Vello CPU supports applying luminance and alpha masks to your drawings.

    // First, we need to create our actual mask. There are multiple ways how
    // you can get to it, in our case we are going to draw our own custom mask.
    let mask = {
        // In this case, we are drawing the mask ourselves. Note that the
        // dimensions of the final mask need to match the dimensions of our
        // original render context!
        let mut mask_ctx = RenderContext::new(SIZE, SIZE);
        let mut mask_resources = Resources::new();
        let mut pixmap = Pixmap::new(SIZE, SIZE);

        mask_ctx.set_paint(RED);
        mask_ctx.fill_rect(&Rect::new(30.0, 30.0, 170.0, 170.0));
        mask_ctx.flush();
        mask_ctx.render(&mut pixmap, &mut mask_resources);

        Mask::new_luminance(&pixmap)
    };

    // Create the main render context.
    let mut ctx = RenderContext::new(SIZE, SIZE);

    // Similarly to clip paths (see the clipping example), there are two
    // different ways of applying them:
    // The first method is by creating a new isolated layer where the mask
    // will be applied once the whole layer has been drawn and is composited
    // into the backdrop. The second method is by setting the mask in the
    // render context, in which case the mask will be applied to each shape
    // directly before being drawn. Which method you should use once again
    // depends on the imaging model you are reflecting.

    // Method 1: Non-isolated masking via `set_mask`.
    {
        ctx.set_paint(WHITE);
        ctx.fill_rect(&Rect::new(0.0, 0.0, SIZE as f64, SIZE as f64));

        // Once the mask is set, the mask will be applied to every path we
        // are drawing individually before compositing it into the background.
        ctx.set_mask(mask.clone());
        // We first apply the mask to the blue rectangle and then composite it.
        ctx.set_paint(BLUE);
        ctx.fill_rect(&Rect::new(20.0, 20.0, 130.0, 130.0));
        // Now, we yet again first apply the mask to the red rectangle only and
        // then composite the result.
        ctx.set_paint(RED);
        ctx.fill_rect(&Rect::new(70.0, 70.0, 180.0, 180.0));
        // Use this method if you want to reset the mask currently in place.
        ctx.reset_mask();

        ctx.flush();
        save_pixmap(&ctx, "example_masking1");
    }

    ctx.reset();
    // Method 2: Isolated masking via `push_mask_layer`.
    {
        ctx.set_paint(WHITE);
        ctx.fill_rect(&Rect::new(0.0, 0.0, SIZE as f64, SIZE as f64));

        // Using this method, we first push a new isolated layer. Apart from that,
        // nothing happens so far.
        ctx.push_mask_layer(mask);
        // Here, the blue rectangle will be drawn first. Then, the red one is drawn
        // and subsequently composited on top of the blue one,
        // without any special handling.
        ctx.set_paint(BLUE);
        ctx.fill_rect(&Rect::new(20.0, 20.0, 130.0, 130.0));
        ctx.set_paint(RED);
        ctx.fill_rect(&Rect::new(70.0, 70.0, 180.0, 180.0));
        // Now, the whole layer is taken, the mask is applied to all of it
        // and then composited into the background.
        ctx.pop_layer();

        ctx.flush();
        save_pixmap(&ctx, "example_masking2");
    }

    // As can be seen, the visual result of the two methods can be different!
}

fn save_pixmap(ctx: &RenderContext, filename: &str) {
    let mut resources = Resources::new();
    let mut pixmap = Pixmap::new(ctx.width(), ctx.height());
    ctx.render(&mut pixmap, &mut resources);
    let png = pixmap.into_png().unwrap();
    std::fs::write(format!("{filename}.png"), png).unwrap();
}

examples/basic.rs (line 91)

fn main() {
    // Vello CPU is a CPU-based 2D renderer. It takes drawing commands like
    // "fill a rectangle" or "stroke a triangle" as input and rasterizes
    // them into a bitmap with premultiplied RGBA pixels, which can then
    // be further processed (for example by converting to PNG or displaying
    // the result in a window).

    // We first need to define some basic render settings.
    let settings = RenderSettings {
        // The `level` field indicates what SIMD level should be used. In
        // the vast majority of cases, you should just use `Level::new` so that
        // Vello CPU automatically uses an appropriate level that is
        // available on the host system.
        //
        // There are very few reasons to override that value. One instance where
        // it might be useful to override is for example when using Vello CPU
        // to create reference images for test suites. In that case, you could
        // pass `Level::fallback`, which indicates to Vello CPU that no
        // platform-specific SIMD intrinsics should be used. This might be useful
        // because it reduces the possibility of slight pixel differences when
        // running on different platforms.
        level: Level::new(),
        // The number of additional threads that should be used for rendering.
        // This setting only has an effect when the `multi-threading` feature
        // is enabled. More threads _usually_ translates to better performance,
        // but also higher CPU usage. Multi-threading can be very effective
        // in situations where you need to continually redraw scenes (for example
        // when rendering GUIs), but is usually less useful for one-time
        // rendering operations. It should also be noted that the current
        // implementation of multi-threading is still not fully optimized and
        // might not work as well in certain workloads, so it's worth trying
        // yourself whether it actually leads to any speedups before using it.
        //
        // If you enabled the multi-threading feature and leave this as 0,
        // it has the exact same effect as rendering in single-threaded mode.
        // According to our experiments, 2-4 threads give the best results,
        // using 4+ threads might result in diminishing results, depending on
        // the workload.
        num_threads: 0,
    };
    let rasterizer_settings = RasterizerSettings {
        // Define whether the renderer should prioritize speed or quality
        // during rendering. Currently, the only difference is that
        // `OptimizeSpeed` will use u8/u16 for the rasterization
        // while `OptimizeQuality` uses f32. The former is much faster, but
        // has the disadvantage that the overall color accuracy might be slightly
        // worse due to quantization. Unless you really care about that, it is
        // highly recommended to use the `OptimizeSpeed` rendering mode.
        render_mode: RenderMode::OptimizeSpeed,
        ..Default::default()
    };

    // Vello CPU embraces a slightly different paradigm than a lot of other 2D
    // renderers. Many 2D renderers use _immediate mode rendering_, where
    // you create a single `Pixmap` and then dispatch rendering commands into
    // it. In Vello CPU, there are two components instead.
    //
    // The first component is the `RenderContext`, which can be thought of as
    // a reusable buffer for dispatching rendering commands. The `reusable`
    // part is important: In situations where you are executing multiple
    // rendering passes at the same resolution, you should reset the context
    // and reuse it instead of always creating a new one, as will be shown below.
    // This is important because it allows Vello CPU to reuse existing memory
    // allocations, leading to better performance.
    //
    // The second component is then the `Pixmap`, which simply acts as a storage
    // for the raw RGBA pixels from the render context.

    // Let's start by creating a new render context with a certain
    // width and height in pixels, as well as our render settings.
    let mut ctx = RenderContext::new_with(100, 100, settings);
    // Vello CPU needs this to track certain resources (e.g. for glyph caching)
    // across multiple frames. You need to make sure that you create on such struct
    // for each render context you create, and then only use it in combination with that
    // specific render context.
    let mut resources = Resources::new();

    // Vello CPU uses a Postscript-like API, where you can use methods like
    // `set_paint` or `set_stroke` to update an internal state, and then
    // dispatch commands to fill or stroke paths, using the current state.

    // Using the `set_paint` method, we can change what color our shapes should
    // be drawn with. You can use any RGBA color for that. Apart from that, you
    // can also paint your shapes using gradients or patterns (see the `paints`
    // example). In this case, we are setting the color to blue.
    ctx.set_paint(BLUE);
    // Now, we can dispatch a commands, for example to fill a rectangle with
    // the given dimensions.
    ctx.fill_path(&Rect::new(25.0, 25.0, 75.0, 75.0).to_path(0.1));

    // We can then update the color to a red with 50% opacity...
    ctx.set_paint(RED.with_alpha(0.5));
    // ...and draw a different rectangle that overlaps the previous one. You
    // can also use the `fill_rect` convenience method for that.
    ctx.fill_rect(&Rect::new(50.0, 50.0, 85.0, 85.0));

    ctx.set_paint(GREEN);
    // As mentioned, stroking is also supported. You can update the stroke
    // properties using the `set_stroke` method.
    ctx.stroke_path(&Circle::new((50.0, 50.0), 30.0).to_path(0.1));

    // Let's say that we have drawn everything we wanted to now. Next, it is
    // recommended that you call the `flush` method. In theory, this call
    // is only necessary when using multi-threaded rendering, to signal that
    // no more operations will be dispatched and the render context should be
    // synchronized. If you forget to call this during multi-threaded rendering,
    // the application will panic. In single-threaded rendering, nothing happens.
    //
    // However, it is highly recommended that you always call this.
    // This way, downstream consumers of your crate that might have externally
    // enabled Vello CPU's multi-threading feature won't run into panics when
    // running your code.
    ctx.flush();

    // Now the second step is to copy the results of the render context into the
    // pixmap. We do this by creating a new pixmap (or reusing an existing one).
    // The pixmap and render context can have different dimensions. See the documentation
    // of the `render_with` method for more information.
    let mut pixmap_1 = Pixmap::new(100, 100);
    // Now, simply extract the results from the render context into the
    // pixmap.
    ctx.render_with(&mut pixmap_1, &mut resources, rasterizer_settings);

    // Now you can do whatever you want with the pixmap, which provides raw
    // access to the premultiplied RGBA pixels of the image. If you have enabled
    // the `png` feature, you can convert it into a PNG image very easily and
    // then save it to disk.
    let png_1 = pixmap_1.into_png().unwrap();
    std::fs::write("example_basic1.png", png_1).unwrap();

    // If you have another scene you want to draw at the same resolution,
    // you can simply reuse the existing render context instead of creating
    // a new one.
    ctx.reset();

    // Vello CPU supports arbitrary affine transformations.
    ctx.set_transform(Affine::scale(3.0));
    ctx.set_paint(YELLOW);
    // The rectangle will now actually have the dimensions 60x60 since we
    // applied an affine transform that scales everything by 3x to the context.
    ctx.fill_rect(&Rect::new(0.0, 0.0, 20.0, 20.0));
    ctx.flush();

    // Once again, we render the results into a pixmap again. If you can,
    // you can just reuse existing pixmaps (assuming they have the correct
    // dimension), since all previous pixels in the pixmap will be cleared by
    // the default replace mode. In our case, we need to create a new one since
    // our call to `into_png` consumed the pixmap.
    let mut pixmap_2 = Pixmap::new(100, 100);
    ctx.render_with(&mut pixmap_2, &mut resources, rasterizer_settings);
    let png_2 = pixmap_2.into_png().unwrap();
    std::fs::write("example_basic2.png", png_2).unwrap();
}

impl Resources

Image registry implementation.

pub fn register_image(&mut self, pixmap: Arc<Pixmap>) -> ImageId

Register a pixmap in the image registry and return its ImageId.

pub fn destroy_image(&mut self, id: ImageId) -> bool

Remove an image from the registry.

pub fn resolve_image(&self, id: ImageId) -> Option<Arc<Pixmap>>

Resolve an ImageId to its pixmap data.

pub fn clear_images(&mut self)

Clear the image registry.

Trait Implementations

impl Debug for Resources

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Resources

fn default() -> Resources

Returns the “default value” for a type.