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

linebender · Oct 3, 2024 · d74d3d4 · d74d3d4
1 parent b57d930
commit d74d3d4
Show file tree

Hide file tree

Showing 7 changed files with 36 additions and 23 deletions.
diff --git a/examples/headless/src/main.rs b/examples/headless/src/main.rs
@@ -139,7 +139,7 @@ async fn render(mut scenes: SceneSet, index: usize, args: &Args) -> Result<()> {
         width,
         height,
         antialiasing_method: vello::AaConfig::Area,
-        debug: vello::DebugLayers::none(),
+        debug: vello::low_level::DebugLayers::none(),
     };
     let mut scene = Scene::new();
     scene.append(&fragment, Some(transform));

diff --git a/examples/simple/src/main.rs b/examples/simple/src/main.rs
@@ -7,7 +7,7 @@ use std::sync::Arc;
 use vello::kurbo::{Affine, Circle, Ellipse, Line, RoundedRect, Stroke};
 use vello::peniko::Color;
 use vello::util::{RenderContext, RenderSurface};
-use vello::{AaConfig, DebugLayers, Renderer, RendererOptions, Scene};
+use vello::{low_level::DebugLayers, AaConfig, Renderer, RendererOptions, Scene};
 use winit::application::ApplicationHandler;
 use winit::dpi::LogicalSize;
 use winit::event::*;

diff --git a/examples/with_winit/src/lib.rs b/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!(),
                                     }
@@ -697,7 +697,7 @@ fn run(
         Some(render_state)
     };
 
-    let debug = vello::DebugLayers::none();
+    let debug = DebugLayers::none();
 
     let mut app = VelloApp {
         context: render_cx,

diff --git a/examples/with_winit/src/stats.rs b/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;

diff --git a/vello/src/lib.rs b/vello/src/lib.rs
@@ -92,12 +92,17 @@ mod wgpu_engine;
 #[cfg(feature = "wgpu")]
 use std::{num::NonZeroUsize, sync::Arc};
 
+use debug::DebugLayers;
 /// Styling and composition primitives.
 pub use peniko;
 /// 2D geometry, with a focus on curves.
 pub use peniko::kurbo;
 
+use recording::{BindType, ImageFormat, ImageProxy, Recording, ResourceProxy, ShaderId};
+use render::Render;
+use shaders::FullShaders;
 pub use skrifa;
+use vello_encoding::BumpAllocators;
 pub use vello_encoding::Glyph;
 
 #[cfg(feature = "wgpu")]
@@ -106,26 +111,32 @@ pub use wgpu;
 #[cfg(feature = "wgpu")]
 pub mod util;
 
-pub use render::Render;
 pub use scene::{DrawGlyphs, Scene};
 use thiserror::Error;
 #[cfg(feature = "wgpu")]
 pub use util::block_on_wgpu;
 
-pub use recording::{
-    BindType, BufferProxy, Command, ImageFormat, ImageProxy, Recording, ResourceId, ResourceProxy,
-    ShaderId,
-};
-pub use shaders::FullShaders;
+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;
+}
 
 #[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"))]

diff --git a/vello/src/wgpu_engine.rs b/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"))]

diff --git a/vello_tests/src/lib.rs b/vello_tests/src/lib.rs
@@ -11,6 +11,7 @@ use std::sync::Arc;
 use anyhow::{anyhow, bail, Result};
 use scenes::{ExampleScene, ImageCache, SceneParams, SimpleText};
 use vello::kurbo::{Affine, Vec2};
+use vello::low_level::DebugLayers;
 use vello::peniko::{Blob, Color, Format, Image};
 use vello::wgpu::{
     self, BufferDescriptor, BufferUsages, CommandEncoderDescriptor, Extent3d, ImageCopyBuffer,
@@ -100,7 +101,7 @@ pub async fn get_scene_image(params: &TestParams, scene: &Scene) -> Result<Image
         width,
         height,
         antialiasing_method: params.anti_aliasing,
-        debug: vello::DebugLayers::none(),
+        debug: DebugLayers::none(),
     };
     let size = Extent3d {
         width,