docs: add drm/gbm

src/backend/drm/gbm/egl.rs

@@ -1,4 +1,10 @@
-use backend::drm::{connector, Device, RawDevice, RawSurface, Surface};
+//!
+//! Egl [`NativeDisplay`](../../egl/native/trait.NativeDisplay.html) and
+//! [`NativeSurface`](../../egl/native/trait.NativeSurface.html) support for
+//! [`GbmDevice`](../struct.GbmDevice.html) and [`GbmSurface`](../struct.GbmSurface.html).
+//!
+
+use backend::drm::{Device, RawDevice};
 use backend::egl::error::Result as EglResult;
 use backend::egl::ffi;
 use backend::egl::native::{Backend, NativeDisplay, NativeSurface};
@@ -7,13 +13,14 @@ use backend::graphics::SwapBuffersError;
 use super::error::{Error, Result};
 use super::{GbmDevice, GbmSurface};
 
-use drm::control::{crtc, Device as ControlDevice, Mode};
+use drm::control::{crtc, Device as ControlDevice};
 use gbm::AsRaw;
-use std::iter::{FromIterator, IntoIterator};
 use std::marker::PhantomData;
 use std::ptr;
 
-/// Gbm backend type
+/// Egl Gbm backend type
+///
+/// See [`Backend`](../../egl/native/trait.Backend.html).
 pub struct Gbm<D: RawDevice + 'static> {
     _userdata: PhantomData<D>,
 }
@@ -68,7 +75,7 @@ unsafe impl<D: RawDevice + 'static> NativeSurface for GbmSurface<D> {
     }
 
     fn needs_recreation(&self) -> bool {
-        self.0.crtc.commit_pending()
+        self.needs_recreation()
     }
 
     fn recreate(&self) -> bool {

src/backend/drm/gbm/error.rs

@@ -48,6 +48,6 @@ error_chain! {
     }
 
     foreign_links {
-        FailedToSwap(::backend::graphics::SwapBuffersError);
+        FailedToSwap(::backend::graphics::SwapBuffersError) #[doc = "Swapping front buffers failed"];
     }
 }

src/backend/drm/gbm/mod.rs

@@ -1,6 +1,17 @@
+//!
+//! [`Device`](../trait.Device.html) and [`Surface`](../trait.Surface.html)
+//! implementations using gbm buffers for efficient rendering.
+//!
+//! Usually this implementation will be wrapped into a [`EglDevice`](../egl/struct.EglDevice.html).
+//! Take a look at `anvil`s source code for an example of this.
+//!
+//! To use these types standalone, you will need to consider the special requirements
+//! of [`GbmSurface::page_flip`](struct.GbmSurface.html#method.page_flip).
+//!
+
 use super::{Device, DeviceHandler, RawDevice, ResourceHandles, ResourceInfo, Surface};
 
-use drm::control::{connector, crtc, Device as ControlDevice, Mode};
+use drm::control::{crtc, Device as ControlDevice};
 use gbm::{self, BufferObjectFlags, Format as GbmFormat};
 use nix::libc::dev_t;
 
@@ -25,7 +36,7 @@ pub mod session;
 
 static LOAD: Once = ONCE_INIT;
 
-/// Representation of an open gbm device to create rendering backends
+/// Representation of an open gbm device to create rendering surfaces
 pub struct GbmDevice<D: RawDevice + ControlDevice + 'static> {
     pub(self) dev: Rc<RefCell<gbm::Device<D>>>,
     backends: Rc<RefCell<HashMap<crtc::Handle, Weak<GbmSurfaceInternal<D>>>>>,

src/backend/drm/gbm/session.rs

@@ -1,3 +1,8 @@
+//!
+//! Support to register a [`GbmDevice`](../struct.GbmDevice.html)
+//! to an open [`Session`](../../session/trait.Session.html).
+//!
+
 use drm::control::{crtc, Device as ControlDevice, ResourceInfo};
 use gbm::BufferObject;
 use std::cell::RefCell;
@@ -9,7 +14,9 @@ use super::{GbmDevice, GbmSurfaceInternal};
 use backend::drm::{RawDevice, RawSurface};
 use backend::session::{AsSessionObserver, SessionObserver};
 
-/// `SessionObserver` linked to the `DrmDevice` it was created from.
+/// [`SessionObserver`](../../session/trait.SessionObserver.html)
+/// linked to the [`GbmDevice`](../struct.GbmDevice.html) it was
+/// created from.
 pub struct GbmDeviceObserver<
     S: SessionObserver + 'static,
     D: RawDevice + ControlDevice + AsSessionObserver<S> + 'static,

src/backend/drm/gbm/surface.rs

@@ -1,7 +1,7 @@
 use super::super::{Device, RawDevice, RawSurface, Surface};
 use super::error::*;
 
-use drm::control::{connector, crtc, framebuffer, Mode, ResourceHandles, ResourceInfo};
+use drm::control::{connector, crtc, framebuffer, Mode, ResourceInfo};
 use gbm::{self, BufferObject, BufferObjectFlags, Format as GbmFormat, SurfaceBufferHandle};
 use image::{ImageBuffer, Rgba};
 
@@ -278,16 +278,33 @@ impl<D: RawDevice + 'static> Drop for GbmSurfaceInternal<D> {
     }
 }
 
+/// Gbm surface for rendering
 pub struct GbmSurface<D: RawDevice + 'static>(pub(super) Rc<GbmSurfaceInternal<D>>);
 
 impl<D: RawDevice + 'static> GbmSurface<D> {
+    /// Flips the underlying buffers.
+    ///
+    /// *Note*: This might trigger a full modeset on the underlying device,
+    /// potentially causing some flickering. In that case this operation is
+    /// blocking until the crtc is in the desired state.
     pub fn page_flip(&self) -> ::std::result::Result<(), SwapBuffersError> {
         self.0.page_flip()
     }
 
+    /// Recreate underlying gbm resources.
+    ///
+    /// This recreates the gbm surfaces resources, which might be needed after e.g.
+    /// calling [`Surface::use_mode`](../trait.Surface.html#method.use_mode).
+    /// You may check if your `GbmSurface` needs recreation through
+    /// [`needs_recreation`](#method.needs_recreation).
     pub fn recreate(&self) -> Result<()> {
         self.0.recreate()
     }
+
+    /// Check if underlying gbm resources need to be recreated.
+    pub fn needs_recreation(&self) -> bool {
+        self.0.crtc.commit_pending()
+    }
 }
 
 impl<D: RawDevice + 'static> Surface for GbmSurface<D> {