Hide the low-level features in the docs by using a re-export module

examples/headless/src/main.rs

@@ -14,7 +14,7 @@ use vello::wgpu::{
     self, BufferDescriptor, BufferUsages, CommandEncoderDescriptor, Extent3d, ImageCopyBuffer,
     TextureDescriptor, TextureFormat, TextureUsages,
 };
-use vello::{block_on_wgpu, RendererOptions, Scene};
+use vello::{util::block_on_wgpu, RendererOptions, Scene};
 
 fn main() -> Result<()> {
     #[cfg(not(target_arch = "wasm32"))]

examples/with_winit/src/lib.rs

@@ -10,6 +10,7 @@ use std::sync::Arc;
 
 #[cfg(not(target_arch = "wasm32"))]
 use std::time::Instant;
+use vello::low_level::DebugLayers;
 #[cfg(target_arch = "wasm32")]
 use web_time::Instant;
 use winit::application::ApplicationHandler;
@@ -26,7 +27,7 @@ use scenes::{ExampleScene, ImageCache, SceneParams, SceneSet, SimpleText};
 use vello::kurbo::{Affine, Vec2};
 use vello::peniko::Color;
 use vello::util::{RenderContext, RenderSurface};
-use vello::{AaConfig, BumpAllocators, Renderer, RendererOptions, Scene};
+use vello::{low_level::BumpAllocators, AaConfig, Renderer, RendererOptions, Scene};
 
 use winit::dpi::LogicalSize;
 use winit::event_loop::EventLoop;
@@ -162,7 +163,7 @@ struct VelloApp<'s> {
     prev_scene_ix: i32,
     modifiers: ModifiersState,
 
-    debug: vello::DebugLayers,
+    debug: DebugLayers,
 }
 
 impl<'s> ApplicationHandler<UserEvent> for VelloApp<'s> {
@@ -332,17 +333,16 @@ impl<'s> ApplicationHandler<UserEvent> for VelloApp<'s> {
                                 debug_layer @ ("1" | "2" | "3" | "4") => {
                                     match debug_layer {
                                         "1" => {
-                                            self.debug.toggle(vello::DebugLayers::BOUNDING_BOXES);
+                                            self.debug.toggle(DebugLayers::BOUNDING_BOXES);
                                         }
                                         "2" => {
-                                            self.debug
-                                                .toggle(vello::DebugLayers::LINESOUP_SEGMENTS);
+                                            self.debug.toggle(DebugLayers::LINESOUP_SEGMENTS);
                                         }
                                         "3" => {
-                                            self.debug.toggle(vello::DebugLayers::LINESOUP_POINTS);
+                                            self.debug.toggle(DebugLayers::LINESOUP_POINTS);
                                         }
                                         "4" => {
-                                            self.debug.toggle(vello::DebugLayers::VALIDATION);
+                                            self.debug.toggle(DebugLayers::VALIDATION);
                                         }
                                         _ => unreachable!(),
                                     }
@@ -549,7 +549,7 @@ impl<'s> ApplicationHandler<UserEvent> for VelloApp<'s> {
                 #[allow(deprecated)]
                 // #[expect(deprecated, reason = "This deprecation is not targeted at us.")] // Our MSRV is too low to use `expect`
                 if self.async_pipeline && cfg!(not(target_arch = "wasm32")) {
-                    self.scene_complexity = vello::block_on_wgpu(
+                    self.scene_complexity = vello::util::block_on_wgpu(
                         &device_handle.device,
                         self.renderers[surface.dev_id]
                             .as_mut()
@@ -699,7 +699,7 @@ fn run(
         Some(render_state)
     };
 
-    let debug = vello::DebugLayers::none();
+    let debug = DebugLayers::none();
 
     let mut app = VelloApp {
         context: render_cx,

examples/with_winit/src/stats.rs

@@ -5,7 +5,7 @@ use scenes::SimpleText;
 use std::collections::VecDeque;
 use vello::kurbo::{Affine, PathEl, Rect, Stroke};
 use vello::peniko::{Brush, Color, Fill};
-use vello::{AaConfig, BumpAllocators, Scene};
+use vello::{low_level::BumpAllocators, AaConfig, Scene};
 
 #[cfg(all(feature = "wgpu-profiler", not(target_arch = "wasm32")))]
 use std::time::Duration;

vello/src/lib.rs

@@ -86,50 +86,50 @@ mod recording;
 mod render;
 mod scene;
 mod shaders;
-#[cfg(feature = "wgpu")]
-mod wgpu_engine;
 
 #[cfg(feature = "wgpu")]
-use std::{
-    num::NonZeroUsize,
-    sync::{atomic::AtomicBool, Arc},
-};
+pub mod util;
+#[cfg(feature = "wgpu")]
+mod wgpu_engine;
 
+pub mod low_level {
+    //! Utilities which can be used to create an alternative Vello renderer to [`Renderer`][crate::Renderer].
+    //!
+    //! These APIs have not been carefully designed, and might not be powerful enough for this use case.
+
+    pub use crate::debug::DebugLayers;
+    pub use crate::recording::{
+        BindType, BufferProxy, Command, ImageFormat, ImageProxy, Recording, ResourceId,
+        ResourceProxy, ShaderId,
+    };
+    pub use crate::render::Render;
+    pub use crate::shaders::FullShaders;
+    /// Temporary export, used in `with_winit` for stats
+    pub use vello_encoding::BumpAllocators;
+}
 /// Styling and composition primitives.
 pub use peniko;
 /// 2D geometry, with a focus on curves.
 pub use peniko::kurbo;
-
 pub use skrifa;
-pub use vello_encoding::Glyph;
 
 #[cfg(feature = "wgpu")]
 pub use wgpu;
 
-#[cfg(feature = "wgpu")]
-pub mod util;
-
-pub use render::Render;
 pub use scene::{DrawGlyphs, Scene};
-use thiserror::Error;
-#[cfg(feature = "wgpu")]
-#[cfg_attr(docsrs, doc(hidden))]
-pub use util::block_on_wgpu;
+pub use vello_encoding::Glyph;
 
-pub use recording::{
-    BindType, BufferProxy, Command, ImageFormat, ImageProxy, Recording, ResourceId, ResourceProxy,
-    ShaderId,
-};
-pub use shaders::FullShaders;
+use debug::DebugLayers;
+use low_level::*;
+use thiserror::Error;
 
+#[cfg(feature = "wgpu")]
+use std::{num::NonZeroUsize, sync::Arc};
 #[cfg(feature = "wgpu")]
 use vello_encoding::Resolver;
 #[cfg(feature = "wgpu")]
 use wgpu_engine::{ExternalResource, WgpuEngine};
 
-pub use debug::DebugLayers;
-/// Temporary export, used in `with_winit` for stats
-pub use vello_encoding::BumpAllocators;
 #[cfg(feature = "wgpu")]
 use wgpu::{Device, Queue, SurfaceTexture, TextureFormat, TextureView};
 #[cfg(all(feature = "wgpu", feature = "wgpu-profiler"))]

vello/src/wgpu_engine.rs

@@ -16,8 +16,9 @@ use wgpu::{
 };
 
 use crate::{
-    recording::BindType, BufferProxy, Command, Error, ImageProxy, Recording, ResourceId,
-    ResourceProxy, Result, ShaderId,
+    low_level::{BufferProxy, Command, ImageProxy, Recording, ResourceId, ResourceProxy, ShaderId},
+    recording::BindType,
+    Error, Result,
 };
 
 #[cfg(not(target_arch = "wasm32"))]

vello_tests/src/lib.rs

@@ -16,7 +16,7 @@ use vello::wgpu::{
     self, BufferDescriptor, BufferUsages, CommandEncoderDescriptor, Extent3d, ImageCopyBuffer,
     TextureDescriptor, TextureFormat, TextureUsages,
 };
-use vello::{block_on_wgpu, util::RenderContext, AaConfig, RendererOptions, Scene};
+use vello::{util::block_on_wgpu, util::RenderContext, AaConfig, RendererOptions, Scene};
 
 mod compare;
 mod snapshot;