Don't document zero-initializing

src/backends/android.rs

@@ -114,7 +114,7 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> SurfaceInterface<D, W> for Android
         }
 
         let buffer =
-            vec![Pixel::default(); native_window_buffer.stride() * native_window_buffer.height()];
+            vec![Pixel::INIT; native_window_buffer.stride() * native_window_buffer.height()];
 
         Ok(BufferImpl {
             native_window_buffer,

src/backends/cg.rs

@@ -279,7 +279,7 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> SurfaceInterface<D, W> for CGImpl<
     fn next_buffer(&mut self, alpha_mode: AlphaMode) -> Result<BufferImpl<'_>, SoftBufferError> {
         let buffer_size = util::byte_stride(self.width as u32) as usize * self.height / 4;
         Ok(BufferImpl {
-            buffer: util::PixelBuffer(vec![Pixel::default(); buffer_size]),
+            buffer: util::PixelBuffer(vec![Pixel::INIT; buffer_size]),
             width: self.width,
             height: self.height,
             color_space: &self.color_space,

src/backends/orbital.rs

@@ -132,7 +132,7 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> SurfaceInterface<D, W> for Orbital
             )
         } else {
             Pixels::Buffer(util::PixelBuffer(vec![
-                Pixel::default();
+                Pixel::INIT;
                 self.width as usize
                     * self.height as usize
             ]))

src/backends/web.rs

@@ -182,7 +182,7 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> SurfaceInterface<D, W> for WebImpl
         if self.size != Some((width, height)) {
             self.buffer_presented = false;
             self.buffer
-                .resize(total_len(width.get(), height.get()), Pixel::default());
+                .resize(total_len(width.get(), height.get()), Pixel::INIT);
             self.canvas.set_width(width.get());
             self.canvas.set_height(height.get());
             self.size = Some((width, height));

src/backends/x11.rs

@@ -397,7 +397,7 @@ impl<D: HasDisplayHandle + ?Sized, W: HasWindowHandle> SurfaceInterface<D, W> fo
             .swbuf_err("Failed to fetch image from window")?;
 
         if reply.depth == self.depth && reply.visual == self.visual_id {
-            let mut out = vec![Pixel::default(); reply.data.len() / size_of::<Pixel>()];
+            let mut out = vec![Pixel::INIT; reply.data.len() / size_of::<Pixel>()];
             // SAFETY: `Pixel` can be re-interpreted as `[u8; 4]`.
             let out_u8s = unsafe {
                 slice::from_raw_parts_mut(
@@ -557,7 +557,7 @@ impl Buffer {
         match self {
             Buffer::Shm(ref mut shm) => shm.alloc_segment(conn, num_bytes),
             Buffer::Wire(wire) => {
-                wire.resize(num_bytes / size_of::<Pixel>(), Pixel::default());
+                wire.resize(num_bytes / size_of::<Pixel>(), Pixel::INIT);
                 Ok(())
             }
         }

src/lib.rs

@@ -197,7 +197,7 @@ impl<D: HasDisplayHandle, W: HasWindowHandle> Surface<D, W> {
     ///
     /// The size must be set with [`Surface::resize`] or [`Surface::configure`] first.
     ///
-    /// The contents of the buffer may be zeroed, or may contain a previous frame. Call
+    /// The contents of the buffer may be garbage, or may contain a previous frame. Call
     /// [`Buffer::age`] to determine this.
     ///
     /// ## Platform Dependent Behavior

src/pixel.rs

@@ -151,6 +151,20 @@ impl Pixel {
     pub const fn new_bgra(b: u8, g: u8, r: u8, a: u8) -> Self {
         Self { r, g, b, a }
     }
+
+    /// A reasonable value to initialize buffers with.
+    ///
+    /// Users should redraw the entire buffer when `buffer.age() == 0`, they shouldn't rely on this.
+    #[allow(unused)] // Only used on some backends.
+    pub(crate) const INIT: Self = if cfg!(debug_assertions) {
+        // Half-transparent mostly-red, this will panic in `Buffer::present` (unless the user
+        // chose a different alpha mode), which is desirable since we don't want this pixel to ever
+        // show up.
+        Self::new_rgba(0xff, 0x11, 0x22, 0x7f)
+    } else {
+        // Zero-initialization is often a lot faster.
+        Self::new_rgba(0x00, 0x00, 0x00, 0x00)
+    };
 }
 
 // TODO: Implement `Add`/`Mul`/similar `std::ops` like `rgb` does?