From 566be2965e4452c87f467ce6284bb7bf4a40e624 Mon Sep 17 00:00:00 2001 From: Daniel McNab <36049421+DJMcNab@users.noreply.github.com> Date: Thu, 22 Jan 2026 15:02:14 +0000 Subject: [PATCH 1/4] Drive-by: Remove a duplicate TODO --- sparse_strips/vello_api/src/painter.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/sparse_strips/vello_api/src/painter.rs b/sparse_strips/vello_api/src/painter.rs index 9d693b6a1..6c515e9fc 100644 --- a/sparse_strips/vello_api/src/painter.rs +++ b/sparse_strips/vello_api/src/painter.rs @@ -57,7 +57,6 @@ pub type StandardBrush = Brush>; /// [`append`]: PaintScene::append /// [`Renderer`]: todo pub trait PaintScene: Any { - // TODO: This also "clobbers" the brush; we need to document that. /// Insert the contents of `Scene` into the drawing sequence at this point, with the 2d affine /// `transform` applied to its contents. /// From 5718eec3c910cd59c6fc7d0a2a0eb5dc7e585206 Mon Sep 17 00:00:00 2001 From: Daniel McNab <36049421+DJMcNab@users.noreply.github.com> Date: Thu, 22 Jan 2026 16:04:43 +0000 Subject: [PATCH 2/4] Add experimental and preview warnings to Vello API --- sparse_strips/vello_api/README.md | 25 ++++++++++++++----------- sparse_strips/vello_api/src/lib.rs | 5 ++++- sparse_strips/vello_cpu/src/api.rs | 9 ++++++++- sparse_strips/vello_hybrid/src/api.rs | 9 ++++++++- 4 files changed, 34 insertions(+), 14 deletions(-) diff --git a/sparse_strips/vello_api/README.md b/sparse_strips/vello_api/README.md index 5d52449a4..9a1c06eda 100644 --- a/sparse_strips/vello_api/README.md +++ b/sparse_strips/vello_api/README.md @@ -2,7 +2,7 @@ # Vello API -**Public API types** +**Experimental public API for Vello Renderers** [![Latest published version.](https://img.shields.io/crates/v/vello_api.svg)](https://crates.io/crates/vello_api) [![Documentation build status.](https://img.shields.io/docsrs/vello_api.svg)](https://docs.rs/vello_api) @@ -26,18 +26,21 @@ See https://linebender.org/blog/doc-include/ for related discussion. --> -Vello API is the rendering API of the 2D renderers in the Vello project. +Vello API is the **experimental** rendering API of the 2D renderers in the Vello project. + +Warning: Vello API is currently only released as a preview, and is not ready for usage beyond short-term experiments. +We know of several design decisions which will change before its use can be recommended. There are currently two [supported Vello renderers](#renderers), each with different tradeoffs. This crate allows you to write the majority of your application logic to support either of those renderers. These renderers are [Vello CPU](todo) and [Vello Hybrid](todo). -# Usage +## Usage TODO: Mention Renderer trait when it exists. Otherwise, this code isn't really usable yet. TODO: This is a stub just to have an outline to push. -# Renderers +## Renderers The Vello renderers which support this API are: @@ -65,7 +68,7 @@ Vello API guarantees identical rendering between renderers which implement it, b This doesn't apply to renderer-specific features. -# Abstraction Boundaries +## Abstraction Boundaries The abstractions in this crate are focused on 2D rendering, and the resources required to perform that. In particular, this does not abstract over strategies for: @@ -78,7 +81,7 @@ These functionalities are however catered for where applicable by APIs on the sp The renderer API supports downcasting to the specific renderer, so that these extensions can be called. Each supported renderer will/does have examples showing how to achieve this yourself. -# Text +## Text Vello API does not handle text/glyph rendering itself. This allows for improved resource sharing of intermediate text layout data, for hinting and ink splitting underlines. @@ -88,7 +91,7 @@ Note that this crate is not currently implemented; design work is ongoing. We also support rendering using using traditional glyph atlases, which may be preferred by some consumers. This is especially useful to achieve subpixel rendering, such as ClearType, which Vello doesn't currently support directly. -# Unimplemented Features +## Unimplemented Features NOTE: This section is not complete; in particular, we have only pushed a half-version of this API to make review more scoped. @@ -96,7 +99,7 @@ The current version of Vello API is a minimal viable product for exploration and As such, there are several features which we expect to be included in this API, but which are not yet exposed in this crate. These are categorised as follows: -## Out of scope/Renderer specific +### Out of scope/Renderer specific As discussed above, some features are out-of-scope, as they have concerns which need to be handled individually by each renderer. @@ -105,7 +108,7 @@ This includes: - Rendering directly to a surface. - Importing "external" textures (e.g. from a `wgpu::Texture`) -## Excluded for expedience +### Excluded for expedience - Renderer specific painting commands (i.e. using downcasting). This is intended to be an immediate follow-up to the MVP landing. @@ -122,7 +125,7 @@ This includes: - "Unsetting" the brush; this is mostly useful for append style operations, which may unexpectedly change the brush. - Dynamic version of `PaintScene`, allowing `dyn PaintScene` for cases where that would be relevant. -## Not cross-renderer +### Not cross-renderer There are some features which are only implemented in one of our target renderers, so cannot yet be included in the generalised API. As an interim solution, we intend to expose these features as renderer specific extensions (see the "excluded for expedience section"). @@ -136,7 +139,7 @@ For Vello CPU, these are (i.e. Vello Hybrid does not implement these): There are currently no such features the other way around (i.e. which only Vello Hybrid supports). -## Not implemented +### Not implemented - Path caching. This feature is intended to allow re-using paths efficiently, primarily for glyphs. - Blurred rounded rectangle paints in custom shapes (e.g. to exclude the unblurred parts). diff --git a/sparse_strips/vello_api/src/lib.rs b/sparse_strips/vello_api/src/lib.rs index 9be3ebcf1..b2cf584bd 100644 --- a/sparse_strips/vello_api/src/lib.rs +++ b/sparse_strips/vello_api/src/lib.rs @@ -6,7 +6,10 @@ // These docs are written for a more complete version of Vello API. -//! Vello API is the rendering API of the 2D renderers in the Vello project. +//! Vello API is the **experimental** rendering API of the 2D renderers in the Vello project. +//! +//! Warning: Vello API is currently only released as a preview, and is not ready for usage beyond short-term experiments. +//! We know of several design decisions which will change before its use can be recommended. //! //! There are currently two [supported Vello renderers](#renderers), each with different tradeoffs. //! This crate allows you to write the majority of your application logic to support either of those renderers. diff --git a/sparse_strips/vello_cpu/src/api.rs b/sparse_strips/vello_cpu/src/api.rs index b92839a8c..ec577a62a 100644 --- a/sparse_strips/vello_cpu/src/api.rs +++ b/sparse_strips/vello_cpu/src/api.rs @@ -1,7 +1,14 @@ // Copyright 2025 the Vello Authors // SPDX-License-Identifier: Apache-2.0 OR MIT -//! Integration of Vello API into Vello CPU. +//! Integration of the experimental Vello API preview into Vello CPU. +//! +//!
+//! +//! Vello API is currently in an experimental phase, released only as a preview, and has no stability guarantees. +//! See [its documentation](vello_api) for more details. +//! +//!
use vello_api::{ PaintScene, Scene, diff --git a/sparse_strips/vello_hybrid/src/api.rs b/sparse_strips/vello_hybrid/src/api.rs index 4f4abb2f1..9d2cda775 100644 --- a/sparse_strips/vello_hybrid/src/api.rs +++ b/sparse_strips/vello_hybrid/src/api.rs @@ -1,7 +1,14 @@ // Copyright 2025 the Vello Authors // SPDX-License-Identifier: Apache-2.0 OR MIT -//! Integration of Vello API into Vello Hybrid. +//! Integration of the experimental Vello API preview into Vello Hybrid. +//! +//!
+//! +//! Vello API is currently in an experimental phase, released only as a preview, and has no stability guarantees. +//! See [its documentation](vello_api) for more details. +//! +//!
use vello_api::{ PaintScene, Scene, From 87f10c46140d732dae0c93f1835c77fce826b60f Mon Sep 17 00:00:00 2001 From: Daniel McNab <36049421+DJMcNab@users.noreply.github.com> Date: Thu, 22 Jan 2026 16:18:12 +0000 Subject: [PATCH 3/4] Removing the wrong base level --- .github/workflows/ci.yml | 2 +- sparse_strips/vello_api/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4cc9231a4..c3a4a13a4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -113,7 +113,7 @@ jobs: run: cargo rdme --check --workspace-project=vello_common - name: Run cargo rdme (vello_api) - run: cargo rdme --check --heading-base-level=0 --workspace-project=vello_api + run: cargo rdme --check --workspace-project=vello_api - name: Run cargo rdme (vello_hybrid) run: cargo rdme --check --workspace-project=vello_hybrid diff --git a/sparse_strips/vello_api/README.md b/sparse_strips/vello_api/README.md index 9a1c06eda..518c1edcd 100644 --- a/sparse_strips/vello_api/README.md +++ b/sparse_strips/vello_api/README.md @@ -16,7 +16,7 @@