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 5d52449a4..518c1edcd 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) @@ -16,7 +16,7 @@ -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_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. /// diff --git a/sparse_strips/vello_common/README.md b/sparse_strips/vello_common/README.md index 683b9729f..85c34ff93 100644 --- a/sparse_strips/vello_common/README.md +++ b/sparse_strips/vello_common/README.md @@ -16,7 +16,7 @@