sparse_strips: Document caveats more clearly

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,

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
 
 <!-- cargo-rdme start -->
 
@@ -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:
+
+- Some features are not yet supported and may panic, including filters during multi-threaded
+  rendering and complex filter graphs.
+- 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
 

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:
+//!
+//! - Some features are not yet supported and may panic, including filters during multi-threaded
+//!   rendering and complex filter graphs.
+//! - 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
 //!

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);
     }

sparse_strips/vello_hybrid/README.md

@@ -19,6 +19,9 @@ Full documentation at https://github.com/orium/cargo-rdme -->
 <!-- Intra-doc links used in lib.rs should be evaluated here.
 See https://linebender.org/blog/doc-include/ for related discussion. -->
 
+[`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
+
 <!-- cargo-rdme start -->
 
 A hybrid CPU/GPU renderer for 2D vector graphics.
@@ -57,6 +60,31 @@ 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:
+
+- Some features are not yet supported and may panic, including mask layers 
+  and complex filter graphs.
+- 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.
+
 <!-- cargo-rdme end -->
 
 ## Minimum supported Rust Version (MSRV)

sparse_strips/vello_hybrid/src/lib.rs

@@ -39,6 +39,31 @@
 //! - `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:
+//!
+//! - Some features are not yet supported and may panic, including mask layers 
+//!   and complex filter graphs.
+//! - 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]
 

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,

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);
     }