diff --git a/glifo/src/glyph.rs b/glifo/src/glyph.rs index ca1cc6aaf3..58ff63918b 100644 --- a/glifo/src/glyph.rs +++ b/glifo/src/glyph.rs @@ -301,6 +301,9 @@ impl AtlasCacher<'_> { /// A backend for glyph run builders. pub trait GlyphRunBackend<'a>: Sized { /// Enable or disable atlas-backed glyph caching for the glyph run. + /// + /// **Note: Atlas caching is currently highly experimental and not + /// recommended for external use.** fn atlas_cache(self, enabled: bool) -> Self; /// Fill the given glyph sequence using the configured builder state. @@ -936,6 +939,9 @@ where B: GlyphRunBackend<'a>, { /// Enable or disable the glyph atlas cache. + /// + /// **Note: Atlas caching is currently highly experimental and not + /// recommended for external use.** pub fn atlas_cache(self, enabled: bool) -> Self { Self { run: self.run, diff --git a/sparse_strips/vello_cpu/README.md b/sparse_strips/vello_cpu/README.md index 1b522e196c..a32a07f9a7 100644 --- a/sparse_strips/vello_cpu/README.md +++ b/sparse_strips/vello_cpu/README.md @@ -31,6 +31,7 @@ See https://linebender.org/blog/doc-include/ for related discussion. --> [RenderMode::OptimizeQuality]: https://docs.rs/vello_cpu/latest/vello_cpu/enum.RenderMode.html#variant.OptimizeQuality [`RenderContext::render`]: https://docs.rs/vello_cpu/latest/vello_cpu/struct.RenderContext.html#method.render [`Pixmap`]: https://docs.rs/vello_cpu/latest/vello_cpu/struct.Pixmap.html +[`Resources`]: https://docs.rs/vello_cpu/latest/vello_cpu/struct.Resources.html @@ -87,9 +88,9 @@ for pixel in target.data() { assert_eq!(&result, expected_render); ``` -Feel free to take a look at some further +See the [examples](https://github.com/linebender/vello/tree/main/sparse_strips/vello_cpu/examples) -to better understand how to interact with Vello CPU's API, +for more complete demonstrations of Vello CPU's API. ## Features @@ -112,20 +113,26 @@ 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. +## Current state + +Vello CPU is a solid CPU-only 2D renderer with broad, reliable feature +support. It provides excellent performance across a wide range of workloads, +with optimized SIMD implementations for all major architectures. The +renderer is still under active development, however, and a few limitations +remain: + +- Complex filter graphs are currently not supported at all and will panic. + In multi-threaded mode, even simple filters are currently unsupported. +- Parts of the API and its documentation are still suboptimal, for example + the [`Resources`][] lifecycle. +- Some exposed features remain experimental and are not recommended for use, + including glyph caching. Experimental APIs are identified in their method + documentation. +- There is still more room for performance improvements, in particular on + x86 systems and also for multi-threaded rendering. + +With that said, we are continuously improving Vello CPU and will address +these and other limitations in future releases. ## Performance diff --git a/sparse_strips/vello_cpu/src/lib.rs b/sparse_strips/vello_cpu/src/lib.rs index f4b772a0f7..a0cd312d88 100644 --- a/sparse_strips/vello_cpu/src/lib.rs +++ b/sparse_strips/vello_cpu/src/lib.rs @@ -57,9 +57,9 @@ //! assert_eq!(&result, expected_render); //! ``` //! -//! Feel free to take a look at some further +//! See the //! [examples](https://github.com/linebender/vello/tree/main/sparse_strips/vello_cpu/examples) -//! to better understand how to interact with Vello CPU's API, +//! for more complete demonstrations of Vello CPU's API. //! //! # Features //! @@ -82,20 +82,26 @@ //! 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. +//! # Current state +//! +//! Vello CPU is a solid CPU-only 2D renderer with broad, reliable feature +//! support. It provides excellent performance across a wide range of workloads, +//! with optimized SIMD implementations for all major architectures. The +//! renderer is still under active development, however, and a few limitations +//! remain: +//! +//! - Complex filter graphs are currently not supported at all and will panic. +//! In multi-threaded mode, even simple filters are currently unsupported. +//! - Parts of the API and its documentation are still suboptimal, for example +//! the [`Resources`][] lifecycle. +//! - Some exposed features remain experimental and are not recommended for use, +//! including glyph caching. Experimental APIs are identified in their method +//! documentation. +//! - There is still more room for performance improvements, in particular on +//! x86 systems and also for multi-threaded rendering. +//! +//! With that said, we are continuously improving Vello CPU and will address +//! these and other limitations in future releases. //! //! # Performance //! diff --git a/sparse_strips/vello_cpu/src/render.rs b/sparse_strips/vello_cpu/src/render.rs index 486aec8244..08365dc28f 100644 --- a/sparse_strips/vello_cpu/src/render.rs +++ b/sparse_strips/vello_cpu/src/render.rs @@ -57,6 +57,8 @@ pub(crate) const DEFAULT_GLYPH_ATLAS_SIZE: u16 = 4096; pub(crate) const ATLAS_IMAGE_ID_BASE: u32 = u32::MAX / 2; /// Persistent resources required by Vello CPU for rendering. +/// +/// You should create one such instance per renderer. #[derive(Debug, Default)] pub struct Resources { pub(crate) image_registry: ImageRegistry, @@ -459,6 +461,10 @@ impl RenderContext { /// Note that the mask, if provided, needs to have the same size as the render context. Otherwise, /// it will be ignored. In addition to that, the mask will not be affected by the current /// transformation matrix in place. + /// + /// # Panics + /// + /// Panics if `filter` is provided when this context uses multi-threaded rendering. pub fn push_layer( &mut self, clip_path: Option<&BezPath>, @@ -539,6 +545,10 @@ impl RenderContext { /// WARNING: Note that filters are currently incomplete and experimental. In /// particular, they will lead to a panic when used in combination with /// multi-threaded rendering. + /// + /// # Panics + /// + /// Panics when this context uses multi-threaded rendering. pub fn push_filter_layer(&mut self, filter: Filter) { self.push_layer(None, None, None, None, Some(filter)); } @@ -677,6 +687,9 @@ impl RenderContext { /// /// This sets a filter that will be applied to the next drawn element. /// To apply a filter to multiple elements, use `push_filter_layer` instead. + /// # Panics + /// + /// When this context uses multi-threaded rendering. pub fn set_filter_effect(&mut self, filter: Filter) { self.filter = Some(filter); } diff --git a/sparse_strips/vello_hybrid/README.md b/sparse_strips/vello_hybrid/README.md index f46e6ffaef..b9a29f6b59 100644 --- a/sparse_strips/vello_hybrid/README.md +++ b/sparse_strips/vello_hybrid/README.md @@ -19,6 +19,9 @@ Full documentation at https://github.com/orium/cargo-rdme --> +[`Resources`]: https://docs.rs/vello_hybrid/latest/vello_hybrid/struct.Resources.html +[`Scene::glyph_run`]: https://docs.rs/vello_hybrid/latest/vello_hybrid/struct.Scene.html#method.glyph_run + A hybrid CPU/GPU renderer for 2D vector graphics. @@ -57,6 +60,32 @@ The renderer is split into several key components: See the individual module documentation for more details on usage and implementation. +## Current state + +Vello Hybrid is a solid GPU-accelerated 2D renderer with broad, reliable +feature support. Although it does not match Vello Classic's raw performance +on dynamic and vector-heavy workloads, it provides excellent performance +on workloads that benefit from GPU acceleration, such as images, +gradients, and filters. Overall, we still consider it to be slightly less +mature than its CPU-only counterpart Vello CPU. + +Vello Hybrid remains under active development. Known limitations include: + +- The following features are not yet supported and will panic: Mask layers, + complex filter graphs as well as certain blend modes for non-isolated + blending. +- Parts of the API and its documentation are still suboptimal, for example + the lifecycle and ownership of external resources through [`Resources`][]. +- Some exposed features remain experimental and are not recommended for use, + including glyph caching. Experimental APIs are identified in their method + documentation. +- Parts of the rendering pipeline are not yet fully optimized, particularly + the wgpu backend, but also other aspects. +- Some failures panic instead of being reported through a user-facing error. + +With that said, we are continuously improving Vello Hybrid and will address +these and other limitations in future releases. + ## Minimum supported Rust Version (MSRV) diff --git a/sparse_strips/vello_hybrid/src/lib.rs b/sparse_strips/vello_hybrid/src/lib.rs index c7543629f6..0bbce6c3bc 100644 --- a/sparse_strips/vello_hybrid/src/lib.rs +++ b/sparse_strips/vello_hybrid/src/lib.rs @@ -39,6 +39,32 @@ //! - `Renderer` or `WebGlRenderer`: Handles GPU resource management and executes draw operations //! //! See the individual module documentation for more details on usage and implementation. +//! +//! # Current state +//! +//! Vello Hybrid is a solid GPU-accelerated 2D renderer with broad, reliable +//! feature support. Although it does not match Vello Classic's raw performance +//! on dynamic and vector-heavy workloads, it provides excellent performance +//! on workloads that benefit from GPU acceleration, such as images, +//! gradients, and filters. Overall, we still consider it to be slightly less +//! mature than its CPU-only counterpart Vello CPU. +//! +//! Vello Hybrid remains under active development. Known limitations include: +//! +//! - The following features are not yet supported and will panic: Mask layers, +//! complex filter graphs as well as certain blend modes for non-isolated +//! blending. +//! - Parts of the API and its documentation are still suboptimal, for example +//! the lifecycle and ownership of external resources through [`Resources`][]. +//! - Some exposed features remain experimental and are not recommended for use, +//! including glyph caching. Experimental APIs are identified in their method +//! documentation. +//! - Parts of the rendering pipeline are not yet fully optimized, particularly +//! the wgpu backend, but also other aspects. +//! - Some failures panic instead of being reported through a user-facing error. +//! +//! With that said, we are continuously improving Vello Hybrid and will address +//! these and other limitations in future releases. #![no_std] diff --git a/sparse_strips/vello_hybrid/src/resources.rs b/sparse_strips/vello_hybrid/src/resources.rs index d04e64f558..9a01e403aa 100644 --- a/sparse_strips/vello_hybrid/src/resources.rs +++ b/sparse_strips/vello_hybrid/src/resources.rs @@ -11,6 +11,8 @@ use vello_common::image_cache::ImageCache; use vello_common::multi_atlas::AtlasConfig; /// Persistent resources required by Vello Hybrid for rendering. +/// +/// You should create one such instance per renderer. #[derive(Debug)] pub struct Resources { pub(crate) image_cache: ImageCache, diff --git a/sparse_strips/vello_hybrid/src/scene.rs b/sparse_strips/vello_hybrid/src/scene.rs index a977055d01..792347d1a2 100644 --- a/sparse_strips/vello_hybrid/src/scene.rs +++ b/sparse_strips/vello_hybrid/src/scene.rs @@ -498,6 +498,8 @@ impl Scene { /// [source regions][`SampleRect::source_region`] must be within bounds of that texture. The /// texture is treated as premultiplied alpha in the render target's color space. See the /// backend's binding type for more information on texture requirements. + /// + /// This operation is currently only supported for the wgpu backend. pub fn draw_texture_rects( &mut self, texture_id: TextureId, @@ -716,6 +718,10 @@ impl Scene { } /// Push a new layer with the given properties. + /// + /// # Panics + /// + /// Panics if `mask` is provided because mask layers are not yet supported. pub fn push_layer( &mut self, clip_path: Option<&BezPath>, @@ -798,7 +804,9 @@ impl Scene { /// Push a new mask layer. /// - /// Note that masks are not yet supported in `vello_hybrid`. + /// # Panics + /// + /// This method currently always panics since masks are not supported yet. pub fn push_mask_layer(&mut self, mask: Mask) { self.push_layer(None, None, None, Some(mask), None); }