AgentSkillsCN

vello-svg-api

精通 Eiffel 编程，熟悉契约式设计、工作帽模式、OOSC2 原则、梅耶尔的验证流程，以及 simple_* 生态系统的相关知识。当您处理 Eiffel 代码、.e 文件、.ecf 配置文件，或当用户提及“工作帽”“DBC”“契约”“Eiffel”“simple_*”“规格说明”“契约式开发”时，可选用此方案。

SKILL.md
--- frontmatter
name: vello-svg-api
description: Use when rendering SVG content with vello_svg crate, converting SVG strings or usvg trees to vello Scenes, or handling unsupported SVG features

vello_svg API Reference

Overview

vello_svg converts SVG content into vello Scene objects for GPU-accelerated rendering. Simple API: string in, Scene out.

Quick Reference

FunctionInputOutputError Handler
render(svg)&strResult<Scene, Error>Default (red boxes)
append(scene, svg)&mut Scene, &strResult<(), Error>Default
append_with(scene, svg, handler)&mut Scene, &str, FnMutResult<(), Error>Custom
render_tree(tree)&usvg::TreeSceneDefault
append_tree(scene, tree)&mut Scene, &usvg::Tree()Default
append_tree_with(scene, tree, handler)&mut Scene, &usvg::Tree, FnMut()Custom

Re-exports

rust
// Use these for version compatibility
use vello_svg::vello;  // vello crate (0.7.0)
use vello_svg::usvg;   // usvg crate (0.46.0)
use vello_svg::Error;  // wraps usvg::Error

Common Patterns

Basic rendering

rust
let scene = vello_svg::render(svg_string)?;

Append to existing scene

rust
let mut scene = vello_svg::vello::Scene::new();
vello_svg::append(&mut scene, svg_string)?;

Pre-parsed tree (custom usvg options)

rust
use vello_svg::usvg;
let tree = usvg::Tree::from_str(svg_string, &usvg::Options::default())?;
let scene = vello_svg::render_tree(&tree);

Custom error handling

rust
// Handler signature: FnMut(&mut Scene, &usvg::Node)
// Node variants: Group, Path, Image, Text
// bounding_box() returns usvg::Rect with left(), top(), right(), bottom(), width(), height()
vello_svg::append_with(&mut scene, svg_string, &mut |_scene, node| {
    let bb = node.bounding_box();
    eprintln!("Unsupported at ({}, {}) size {}x{}",
        bb.left(), bb.top(), bb.width(), bb.height());
});

Unsupported SVG Features

Default handler draws semi-transparent red boxes. Unsupported:

  • •Filter effects
  • •Masking
  • •Patterns
  • •Group opacity
  • •Mix-blend-modes
  • •Complex clipping (single-path clips work)
  • •Group background
  • •Path shape-rendering

Note: Text elements ARE rendered - usvg flattens them to paths automatically via text.flattened().

Utility Functions (vello_svg::util)

  • •to_affine(&usvg::Transform) -> Affine
  • •to_stroke(&usvg::Stroke) -> Stroke
  • •to_bez_path(&usvg::Path) -> BezPath
  • •to_brush(&usvg::Paint, Opacity) -> Option<(Brush, Affine)>
  • •default_error_handler(&mut Scene, &usvg::Node)
  • •into_image(image::RgbaImage) -> ImageBrush (requires image feature)
  • •decode_raw_raster_image(&usvg::ImageKind) -> Result<RgbaImage, ImageError> (requires image feature)

Feature Flags

toml
[dependencies]
vello_svg = { version = "0.9", features = ["wgpu"] }

# Image formats enabled by default: png, gif, jpeg, webp
# Optional: image (for decode_raw_raster_image)

Common Mistakes

MistakeFix
Import vello/usvg separatelyUse vello_svg::vello and vello_svg::usvg re-exports
Look for RenderOptions typeNo options struct - use usvg::Options for parsing
Call render::render_svg_string()Use vello_svg::render() directly
Use node.tag() in error handlerNode is an enum - use bounding_box() which returns Rect
Access bb.x0, bb.y0 on bounding boxUse bb.left(), bb.top(), bb.width(), bb.height()
Manually convert text to pathsNot needed - usvg auto-flattens text via text.flattened()