From 1f8a7e73358c4179b80a92fbb78394fb97e08372 Mon Sep 17 00:00:00 2001 From: Victor Brekenfeld Date: Mon, 3 Dec 2018 23:26:10 +0100 Subject: [PATCH] docs: add drm/gbm --- src/backend/drm/gbm/egl.rs | 17 ++++++++++++----- src/backend/drm/gbm/error.rs | 2 +- src/backend/drm/gbm/mod.rs | 15 +++++++++++++-- src/backend/drm/gbm/session.rs | 9 ++++++++- src/backend/drm/gbm/surface.rs | 19 ++++++++++++++++++- 5 files changed, 52 insertions(+), 10 deletions(-) diff --git a/src/backend/drm/gbm/egl.rs b/src/backend/drm/gbm/egl.rs index 696b400..6fdd0ff 100644 --- a/src/backend/drm/gbm/egl.rs +++ b/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 { _userdata: PhantomData, } @@ -68,7 +75,7 @@ unsafe impl NativeSurface for GbmSurface { } fn needs_recreation(&self) -> bool { - self.0.crtc.commit_pending() + self.needs_recreation() } fn recreate(&self) -> bool { diff --git a/src/backend/drm/gbm/error.rs b/src/backend/drm/gbm/error.rs index e654c2d..452e657 100644 --- a/src/backend/drm/gbm/error.rs +++ b/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"]; } } diff --git a/src/backend/drm/gbm/mod.rs b/src/backend/drm/gbm/mod.rs index 7b4f4bd..b45d2c1 100644 --- a/src/backend/drm/gbm/mod.rs +++ b/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 { pub(self) dev: Rc>>, backends: Rc>>>>, diff --git a/src/backend/drm/gbm/session.rs b/src/backend/drm/gbm/session.rs index 1894a5f..4d3bd82 100644 --- a/src/backend/drm/gbm/session.rs +++ b/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 + 'static, diff --git a/src/backend/drm/gbm/surface.rs b/src/backend/drm/gbm/surface.rs index 704ee64..9bcf2b9 100644 --- a/src/backend/drm/gbm/surface.rs +++ b/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 Drop for GbmSurfaceInternal { } } +/// Gbm surface for rendering pub struct GbmSurface(pub(super) Rc>); impl GbmSurface { + /// 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 Surface for GbmSurface {