Fixup docs

examples/with_winit/src/lib.rs

@@ -677,7 +677,6 @@ fn run(
         let mut renderer = Renderer::new(
             &render_cx.devices[id].device,
             RendererOptions {
-                surface_format: Some(render_state.surface.format),
                 use_cpu: args.use_cpu,
                 antialiasing_support: AA_CONFIGS.iter().copied().collect(),
                 // We currently initialise on one thread on WASM, but mark this here

vello/src/lib.rs

@@ -273,7 +273,7 @@ pub enum Error {
     WgpuCreateSurfaceError(#[from] wgpu::CreateSurfaceError),
     /// Surface doesn't support the required texture formats.
     /// Make sure that you have a surface which provides one of
-    /// [`TextureFormat::Rgba8Unorm`] or [`TextureFormat::Bgra8Unorm`] as texture formats.
+    /// [`wgpu::TextureFormat::Rgba8Unorm`] or [`wgpu::TextureFormat::Bgra8Unorm`] as texture formats.
     #[cfg(feature = "wgpu")]
     #[error("Couldn't find `Rgba8Unorm` or `Bgra8Unorm` texture formats for surface")]
     UnsupportedSurfaceFormat,
@@ -355,7 +355,7 @@ static_assertions::assert_impl_all!(Renderer: Send);
 
 /// Parameters used in a single render that are configurable by the client.
 ///
-/// These are used in [`Renderer::render_to_surface`] and [`Renderer::render_to_texture`].
+/// These are used in [`Renderer::render_to_texture`].
 pub struct RenderParams {
     /// The background color applied to the target. This value is only applicable to the full
     /// pipeline.
@@ -433,6 +433,15 @@ impl Renderer {
     /// The texture is assumed to be of the specified dimensions and have been created with
     /// the [`wgpu::TextureFormat::Rgba8Unorm`] format and the [`wgpu::TextureUsages::STORAGE_BINDING`]
     /// flag set.
+    ///
+    /// If you want to render Vello content to a surface (such as in a UI toolkit), you have two options:
+    /// 1) Render to an intermediate texture, which is the same size as the surface.
+    ///    You would then use [`TextureBlitter`][wgpu::util::TextureBlitter] to blit the rendered result from
+    ///    that texture to the surface.
+    ///    This pattern is supported by the [`util`] module.
+    /// 2) Call `render_to_texture` directly on the [`SurfaceTexture`][wgpu::SurfaceTexture]'s texture, if
+    ///    it has the right usages. This should generally be avoided, as it's a potential performance pitfall
+    ///    on GPUs where the render pipeline method of writing to surfaces is assumed and optimised for.
     pub fn render_to_texture(
         &mut self,
         device: &Device,

vello/src/scene.rs

@@ -33,8 +33,7 @@ use vello_encoding::{Encoding, Glyph, GlyphRun, NormalizedCoord, Patch, Transfor
 /// A `Scene` stores a sequence of drawing commands, their context, and the
 /// associated resources, which can later be rendered.
 ///
-/// Most users will render this using [`Renderer::render_to_surface`][crate::Renderer::render_to_surface]
-/// or [`Renderer::render_to_texture`][crate::Renderer::render_to_texture].
+/// Most users will render this using [`Renderer::render_to_texture`][crate::Renderer::render_to_texture].
 ///
 /// Rendering from a `Scene` will *not* clear it, which should be done in a separate step, by calling [`Scene::reset`].
 ///