vtimofei
/
smithay
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Replace documentation links with intra rustdoc links

This commit is contained in:
Victor Brekenfeld 2018-12-08 13:40:07 +01:00
parent d1d608ab2b
commit 04aee7cbc9
41 changed files with 529 additions and 477 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.travis.yml
View File

@ -108,7 +108,7 @@ deploy:
local_dir: "./target/doc" local_dir: "./target/doc"
on: on:
branch: master branch: master
rust: stable rust: nightly
condition: "$FEATURES = all" condition: "$FEATURES = all"
notifications: notifications:

3
src/backend/drm/egl/error.rs
View File

@ -1,5 +1,6 @@
//! //!
//! Errors thrown by the `DrmDevice` and `DrmBackend` //! Errors thrown by the [`EglDevice`](::backend::drm::egl::EglDevice)
//! and [`EglSurface`](::backend::drm::egl::EglSurface).
//! //!
use backend::egl::error as egl; use backend::egl::error as egl;

10
src/backend/drm/egl/mod.rs
View File

@ -1,9 +1,9 @@
//! //!
//! [`Device`](../trait.Device.html) and [`Surface`](../trait.Surface.html) //! [`Device`](Device) and [`Surface`](Surface)
//! implementations using egl contexts and surfaces for efficient rendering. //! implementations using egl contexts and surfaces for efficient rendering.
//! //!
//! Usually this implementation's [`EglSurface`](struct.EglSurface.html)s implementation //! Usually this implementation's [`EglSurface`](::backend::drm::egl::EglSurface)s implementation
//! of [`GlGraphicsBackend`](../../graphics/gl/trait.GlGraphicsBackend.html) will be used //! of [`GLGraphicsBackend`](::backend::graphics::gl::GLGraphicsBackend) will be used
//! to let your compositor render. //! to let your compositor render.
//! Take a look at `anvil`s source code for an example of this. //! Take a look at `anvil`s source code for an example of this.
//! //!
@ -59,7 +59,7 @@ where
D: Device + NativeDisplay<B, Arguments = crtc::Handle> + 'static, D: Device + NativeDisplay<B, Arguments = crtc::Handle> + 'static,
<D as Device>::Surface: NativeSurface, <D as Device>::Surface: NativeSurface,
{ {
/// Try to create a new `EglDevice` from an open device. /// Try to create a new [`EglDevice`] from an open device.
/// ///
/// Returns an error if the file is no valid device or context /// Returns an error if the file is no valid device or context
/// creation was not successful. /// creation was not successful.
@ -79,7 +79,7 @@ where
) )
} }
/// Create a new `EglDevice` from an open device and given `GlAttributes` /// Create a new [`EglDevice`] from an open device and given [`GlAttributes`]
/// ///
/// Returns an error if the file is no valid device or context /// Returns an error if the file is no valid device or context
/// creation was not successful. /// creation was not successful.

8
src/backend/drm/egl/session.rs
View File

@ -1,6 +1,6 @@
//! //!
//! Support to register an [`EglDevice`](../struct.EglDevice.html) //! Support to register an [`EglDevice`](EglDevice)
//! to an open [`Session`](../../session/trait.Session.html). //! to an open [`Session`](::backend::session::Session).
//! //!
use drm::control::crtc; use drm::control::crtc;
@ -11,8 +11,8 @@ use backend::drm::Device;
use backend::egl::native::{Backend, NativeDisplay, NativeSurface}; use backend::egl::native::{Backend, NativeDisplay, NativeSurface};
use backend::session::{AsSessionObserver, SessionObserver}; use backend::session::{AsSessionObserver, SessionObserver};
/// [`SessionObserver`](../../session/trait.SessionObserver.html) /// [`SessionObserver`](SessionObserver)
/// linked to the [`EglDevice`](../struct.EglDevice.html) it was /// linked to the [`EglDevice`](EglDevice) it was
/// created from. /// created from.
pub struct EglDeviceObserver<S: SessionObserver + 'static> { pub struct EglDeviceObserver<S: SessionObserver + 'static> {
observer: S, observer: S,

8
src/backend/drm/gbm/egl.rs
View File

@ -1,7 +1,7 @@
//! //!
//! Egl [`NativeDisplay`](../../egl/native/trait.NativeDisplay.html) and //! Egl [`NativeDisplay`](::backend::egl::native::NativeDisplay) and
//! [`NativeSurface`](../../egl/native/trait.NativeSurface.html) support for //! [`NativeSurface`](::backend::egl::native::NativeSurface) support for
//! [`GbmDevice`](../struct.GbmDevice.html) and [`GbmSurface`](../struct.GbmSurface.html). //! [`GbmDevice`](GbmDevice) and [`GbmSurface`](GbmSurface).
//! //!
use backend::drm::{Device, RawDevice}; use backend::drm::{Device, RawDevice};
@ -20,7 +20,7 @@ use std::ptr;
/// Egl Gbm backend type /// Egl Gbm backend type
/// ///
/// See [`Backend`](../../egl/native/trait.Backend.html). /// See [`Backend`](::backend::egl::native::Backend).
pub struct Gbm<D: RawDevice + 'static> { pub struct Gbm<D: RawDevice + 'static> {
_userdata: PhantomData<D>, _userdata: PhantomData<D>,
} }

3
src/backend/drm/gbm/error.rs
View File

@ -1,5 +1,6 @@
//! //!
//! Errors thrown by the `DrmDevice` and `DrmBackend` //! Errors thrown by the [`GbmDevice`](::backend::drm::gbm::GbmDevice)
//! and [`GbmSurface`](::backend::drm::gbm::GbmSurface).
//! //!
error_chain! { error_chain! {

8
src/backend/drm/gbm/mod.rs
View File

@ -1,12 +1,12 @@
//! //!
//! [`Device`](../trait.Device.html) and [`Surface`](../trait.Surface.html) //! [`Device`](Device) and [`Surface`](Surface)
//! implementations using gbm buffers for efficient rendering. //! implementations using gbm buffers for efficient rendering.
//! //!
//! Usually this implementation will be wrapped into a [`EglDevice`](../egl/struct.EglDevice.html). //! Usually this implementation will be wrapped into a [`EglDevice`](::backend::drm::egl::EglDevice).
//! Take a look at `anvil`s source code for an example of this. //! 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 //! To use these types standalone, you will need to consider the special requirements
//! of [`GbmSurface::page_flip`](struct.GbmSurface.html#method.page_flip). //! of [`GbmSurface::page_flip`](::backend::drm::gbm::GbmSurface::page_flip).
//! //!
use super::{Device, DeviceHandler, RawDevice, ResourceHandles, ResourceInfo, Surface}; use super::{Device, DeviceHandler, RawDevice, ResourceHandles, ResourceInfo, Surface};
@ -44,7 +44,7 @@ pub struct GbmDevice<D: RawDevice + ControlDevice + 'static> {
} }
impl<D: RawDevice + ControlDevice + 'static> GbmDevice<D> { impl<D: RawDevice + ControlDevice + 'static> GbmDevice<D> {
/// Create a new `GbmDevice` from an open drm node /// Create a new [`GbmDevice`] from an open drm node
/// ///
/// Returns an error if the file is no valid drm node or context creation was not /// Returns an error if the file is no valid drm node or context creation was not
/// successful. /// successful.

8
src/backend/drm/gbm/session.rs
View File

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

10
src/backend/drm/gbm/surface.rs
View File

@ -287,9 +287,9 @@ impl<D: RawDevice + 'static> GbmSurface<D> {
/// Flips the underlying buffers. /// Flips the underlying buffers.
/// ///
/// The surface will report being already flipped until the matching event /// The surface will report being already flipped until the matching event
/// was processed either by calling `GbmDevice::process_events` manually after the flip /// was processed either by calling [`Device::process_events`] manually after the flip
/// (bad idea performance-wise) or by binding the device to an event-loop by using /// (bad idea performance-wise) or by binding the device to an event-loop by using
/// `device_bind`. /// [`device_bind`](::backend::drm::device_bind).
/// ///
/// *Note*: This might trigger a full modeset on the underlying device, /// *Note*: This might trigger a full modeset on the underlying device,
/// potentially causing some flickering. In that case this operation is /// potentially causing some flickering. In that case this operation is
@ -301,9 +301,9 @@ impl<D: RawDevice + 'static> GbmSurface<D> {
/// Recreate underlying gbm resources. /// Recreate underlying gbm resources.
/// ///
/// This recreates the gbm surfaces resources, which might be needed after e.g. /// This recreates the gbm surfaces resources, which might be needed after e.g.
/// calling [`Surface::use_mode`](../trait.Surface.html#method.use_mode). /// calling [`Surface::use_mode`](Surface::use_mode).
/// You may check if your `GbmSurface` needs recreation through /// You may check if your [`GbmSurface`] needs recreation through
/// [`needs_recreation`](#method.needs_recreation). /// [`needs_recreation`](GbmSurface::needs_recreation).
pub fn recreate(&self) -> Result<()> { pub fn recreate(&self) -> Result<()> {
self.0.recreate() self.0.recreate()
} }

3
src/backend/drm/legacy/error.rs
View File

@ -1,5 +1,6 @@
//! //!
//! Errors thrown by the `LegacyDrmDevice` and `LegacyDrmSurface` //! Errors thrown by the [`LegacyDrmDevice`](::backend::drm::legacy::LegacyDrmDevice)
//! and [`LegacyDrmSurface`](::backend::drm::legacy::LegacyDrmSurface).
//! //!
use drm::control::{connector, crtc, Mode}; use drm::control::{connector, crtc, Mode};

6
src/backend/drm/legacy/mod.rs
View File

@ -1,8 +1,8 @@
//! //!
//! [`RawDevice`](../trait.RawDevice.html) and [`RawSurface`](../trait.RawSurface.html) //! [`RawDevice`](RawDevice) and [`RawSurface`](RawSurface)
//! implementations using the legacy mode-setting infrastructure. //! implementations using the legacy mode-setting infrastructure.
//! //!
//! Usually this implementation will be wrapped into a [`GbmDevice`](../gbm/struct.GbmDevice.html). //! Usually this implementation will be wrapped into a [`GbmDevice`](::backend::drm::gbm::GbmDevice).
//! Take a look at `anvil`s source code for an example of this. //! Take a look at `anvil`s source code for an example of this.
//! //!
//! For an example how to use this standalone, take a look at the `raw_drm` example. //! For an example how to use this standalone, take a look at the `raw_drm` example.
@ -86,7 +86,7 @@ impl<A: AsRawFd + 'static> Drop for Dev<A> {
} }
impl<A: AsRawFd + 'static> LegacyDrmDevice<A> { impl<A: AsRawFd + 'static> LegacyDrmDevice<A> {
/// Create a new `LegacyDrmDevice` from an open drm node /// Create a new [`LegacyDrmDevice`] from an open drm node
/// ///
/// Returns an error if the file is no valid drm node or context creation was not /// Returns an error if the file is no valid drm node or context creation was not
/// successful. /// successful.

8
src/backend/drm/legacy/session.rs
View File

@ -1,6 +1,6 @@
//! //!
//! Support to register an open [`LegacyDrmDevice`](../struct.LegacyDrmDevice.html) //! Support to register an open [`LegacyDrmDevice`](LegacyDrmDevice)
//! to an open [`Session`](../../session/trait.Session.html). //! to an open [`Session`](::backend::session::Session).
//! //!
use drm::control::crtc; use drm::control::crtc;
@ -17,8 +17,8 @@ use std::sync::Arc;
use super::{Dev, LegacyDrmDevice, LegacyDrmSurfaceInternal}; use super::{Dev, LegacyDrmDevice, LegacyDrmSurfaceInternal};
use backend::session::{AsSessionObserver, SessionObserver}; use backend::session::{AsSessionObserver, SessionObserver};
/// [`SessionObserver`](../../session/trait.SessionObserver.html) /// [`SessionObserver`](SessionObserver)
/// linked to the [`LegacyDrmDevice`](../struct.LegacyDrmDevice.html) /// linked to the [`LegacyDrmDevice`](LegacyDrmDevice)
/// it was created from. /// it was created from.
pub struct LegacyDrmDeviceObserver<A: AsRawFd + 'static> { pub struct LegacyDrmDeviceObserver<A: AsRawFd + 'static> {
dev: Weak<Dev<A>>, dev: Weak<Dev<A>>,

54
src/backend/drm/mod.rs
View File

@ -63,11 +63,11 @@ pub mod gbm;
#[cfg(feature = "backend_drm_legacy")] #[cfg(feature = "backend_drm_legacy")]
pub mod legacy; pub mod legacy;
/// Trait to receive events of a bound [`Device`](trait.Device.html) /// Trait to receive events of a bound [`Device`]
/// ///
/// See [`device_bind`](fn.device_bind.html) /// See [`device_bind`]
pub trait DeviceHandler { pub trait DeviceHandler {
/// The [`Device`](trait.Device.html) type this handler can handle /// The [`Device`] type this handler can handle
type Device: Device + ?Sized; type Device: Device + ?Sized;
/// A vblank blank event on the provided crtc has happend /// A vblank blank event on the provided crtc has happend
@ -78,15 +78,15 @@ pub trait DeviceHandler {
/// An open drm device /// An open drm device
pub trait Device: AsRawFd + DevPath { pub trait Device: AsRawFd + DevPath {
/// Associated [`Surface`](trait.Surface.html) of this `Device` type /// Associated [`Surface`] of this [`Device`] type
type Surface: Surface; type Surface: Surface;
/// Returns the `id` of this device node. /// Returns the id of this device node.
fn device_id(&self) -> dev_t; fn device_id(&self) -> dev_t;
/// Assigns a `DeviceHandler` called during event processing. /// Assigns a [`DeviceHandler`] called during event processing.
/// ///
/// See [`device_bind`](fn.device_bind.html) and [`DeviceHandler`](trait.DeviceHandler.html) /// See [`device_bind`] and [`DeviceHandler`]
fn set_handler(&mut self, handler: impl DeviceHandler<Device = Self> + 'static); fn set_handler(&mut self, handler: impl DeviceHandler<Device = Self> + 'static);
/// Clear a set [`DeviceHandler`](trait.DeviceHandler.html), if any /// Clear a set [`DeviceHandler`](trait.DeviceHandler.html), if any
fn clear_handler(&mut self); fn clear_handler(&mut self);
@ -108,26 +108,26 @@ pub trait Device: AsRawFd + DevPath {
/// Processes any open events of the underlying file descriptor. /// Processes any open events of the underlying file descriptor.
/// ///
/// You should not call this function manually, but rather use /// You should not call this function manually, but rather use
/// [`device_bind`](fn.device_bind.html) to register the device /// [`device_bind`] to register the device
/// to an [`EventLoop`](https://docs.rs/calloop/0.4.2/calloop/struct.EventLoop.html) /// to an [`EventLoop`](https://docs.rs/calloop/0.4.2/calloop/struct.EventLoop.html)
/// to synchronize your rendering to the vblank events of the open crtc's /// to synchronize your rendering to the vblank events of the open crtc's
fn process_events(&mut self); fn process_events(&mut self);
/// Load the resource from a `Device` given its /// Load the resource from a [`Device`] given its
/// [`ResourceHandle`](https://docs.rs/drm/0.3.4/drm/control/trait.ResourceHandle.html) /// [`ResourceHandle`](https://docs.rs/drm/0.3.4/drm/control/trait.ResourceHandle.html)
fn resource_info<T: ResourceInfo>( fn resource_info<T: ResourceInfo>(
&self, &self,
handle: T::Handle, handle: T::Handle,
) -> Result<T, <Self::Surface as Surface>::Error>; ) -> Result<T, <Self::Surface as Surface>::Error>;
/// Attempts to acquire a copy of the `Device`'s /// Attempts to acquire a copy of the [`Device`]'s
/// [`ResourceHandles`](https://docs.rs/drm/0.3.4/drm/control/struct.ResourceHandles.html) /// [`ResourceHandles`](https://docs.rs/drm/0.3.4/drm/control/struct.ResourceHandles.html)
fn resource_handles(&self) -> Result<ResourceHandles, <Self::Surface as Surface>::Error>; fn resource_handles(&self) -> Result<ResourceHandles, <Self::Surface as Surface>::Error>;
} }
/// Marker trait for `Device`s able to provide [`RawSurface`](trait.RawSurface.html)s /// Marker trait for [`Device`]s able to provide [`RawSurface`]s
pub trait RawDevice: Device<Surface = <Self as RawDevice>::Surface> { pub trait RawDevice: Device<Surface = <Self as RawDevice>::Surface> {
/// Associated [`RawSurface`](trait.RawSurface.html) of this `RawDevice` type /// Associated [`RawSurface`] of this [`RawDevice`] type
type Surface: RawSurface; type Surface: RawSurface;
} }
@ -135,8 +135,8 @@ pub trait RawDevice: Device<Surface = <Self as RawDevice>::Surface> {
pub trait Surface { pub trait Surface {
/// Type repesenting a collection of /// Type repesenting a collection of
/// [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s /// [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s
/// returned by [`current_connectors`](#method.current_connectors) and /// returned by [`current_connectors`](Surface::current_connectors) and
/// [`pending_connectors`](#method.pending_connectors) /// [`pending_connectors`](Surface::pending_connectors)
type Connectors: IntoIterator<Item = connector::Handle>; type Connectors: IntoIterator<Item = connector::Handle>;
/// Error type returned by methods of this trait /// Error type returned by methods of this trait
type Error: Error + Send; type Error: Error + Send;
@ -146,10 +146,10 @@ pub trait Surface {
/// Currently used [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s of this `Surface` /// Currently used [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s of this `Surface`
fn current_connectors(&self) -> Self::Connectors; fn current_connectors(&self) -> Self::Connectors;
/// Returns the pending [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s /// Returns the pending [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s
/// used after the next `commit` of this `Surface` /// used after the next [`commit`](RawSurface::commit) of this [`Surface`]
/// ///
/// *Note*: Only on a [`RawSurface`](trait.RawSurface.html) you may directly trigger /// *Note*: Only on a [`RawSurface`] you may directly trigger
/// a [`commit`](trait.RawSurface.html#method.commit). Other `Surface`s provide their /// a [`commit`](RawSurface::commit). Other `Surface`s provide their
/// own methods that *may* trigger a commit, you will need to read their docs. /// own methods that *may* trigger a commit, you will need to read their docs.
fn pending_connectors(&self) -> Self::Connectors; fn pending_connectors(&self) -> Self::Connectors;
/// Tries to add a new [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html) /// Tries to add a new [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)
@ -177,8 +177,8 @@ pub trait Surface {
/// [`crtc`](https://docs.rs/drm/0.3.4/drm/control/crtc/index.html) or any of the /// [`crtc`](https://docs.rs/drm/0.3.4/drm/control/crtc/index.html) or any of the
/// pending [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s. /// pending [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s.
/// ///
/// *Note*: Only on a [`RawSurface`](trait.RawSurface.html) you may directly trigger /// *Note*: Only on a [`RawSurface`] you may directly trigger
/// a [`commit`](trait.RawSurface.html#method.commit). Other `Surface`s provide their /// a [`commit`](RawSurface::commit). Other [`Surface`]s provide their
/// own methods that *may* trigger a commit, you will need to read their docs. /// own methods that *may* trigger a commit, you will need to read their docs.
fn use_mode(&self, mode: Option<Mode>) -> Result<(), Self::Error>; fn use_mode(&self, mode: Option<Mode>) -> Result<(), Self::Error>;
} }
@ -188,15 +188,15 @@ pub trait RawSurface: Surface + ControlDevice + BasicDevice {
/// Returns true whenever any state changes are pending to be commited /// Returns true whenever any state changes are pending to be commited
/// ///
/// The following functions may trigger a pending commit: /// The following functions may trigger a pending commit:
/// - [`add_connector`](trait.Surface.html#method.add_connector) /// - [`add_connector`](Surface::add_connector)
/// - [`remove_connector`](trait.Surface.html#method.remove_connector) /// - [`remove_connector`](Surface::remove_connector)
/// - [`use_mode`](trait.Surface.html#method.use_mode) /// - [`use_mode`](Surface::use_mode)
fn commit_pending(&self) -> bool; fn commit_pending(&self) -> bool;
/// Commit the pending state rendering a given framebuffer. /// Commit the pending state rendering a given framebuffer.
/// ///
/// *Note*: This will trigger a full modeset on the underlying device, /// *Note*: This will trigger a full modeset on the underlying device,
/// potentially causing some flickering. Check before performing this /// potentially causing some flickering. Check before performing this
/// operation if a commit really is necessary using [`commit_pending`](#method.commit_pending). /// operation if a commit really is necessary using [`commit_pending`](RawSurface::commit_pending).
/// ///
/// This operation is blocking until the crtc is in the desired state. /// This operation is blocking until the crtc is in the desired state.
fn commit(&self, framebuffer: framebuffer::Handle) -> Result<(), <Self as Surface>::Error>; fn commit(&self, framebuffer: framebuffer::Handle) -> Result<(), <Self as Surface>::Error>;
@ -206,8 +206,8 @@ pub trait RawSurface: Surface + ControlDevice + BasicDevice {
/// This will not cause the crtc to modeset. /// This will not cause the crtc to modeset.
/// ///
/// This operation is not blocking and will produce a `vblank` event once swapping is done. /// This operation is not blocking and will produce a `vblank` event once swapping is done.
/// Make sure to [set a `DeviceHandler`](trait.Device.html#method.set_handler) and /// Make sure to [set a `DeviceHandler`](Device::set_handler) and
/// [register the belonging `Device`](fn.device_bind.html) before to receive the event in time. /// [register the belonging `Device`](device_bind) before to receive the event in time.
fn page_flip(&self, framebuffer: framebuffer::Handle) -> Result<(), SwapBuffersError>; fn page_flip(&self, framebuffer: framebuffer::Handle) -> Result<(), SwapBuffersError>;
} }
@ -225,10 +225,10 @@ impl<A: AsRawFd> DevPath for A {
} }
} }
/// Bind a `Device` to an `EventLoop`, /// Bind a `Device` to an [`EventLoop`](wayland_server::calloop::EventLoop),
/// ///
/// This will cause it to recieve events and feed them into a previously /// This will cause it to recieve events and feed them into a previously
/// set [`DeviceHandler`](trait.DeviceHandler.html). /// set [`DeviceHandler`](DeviceHandler).
pub fn device_bind<D: Device + 'static, Data>( pub fn device_bind<D: Device + 'static, Data>(
handle: &LoopHandle<Data>, handle: &LoopHandle<Data>,
device: D, device: D,

6
src/backend/egl/context.rs
View File

@ -26,7 +26,7 @@ pub struct EGLContext<B: native::Backend, N: native::NativeDisplay<B>> {
} }
impl<B: native::Backend, N: native::NativeDisplay<B>> EGLContext<B, N> { impl<B: native::Backend, N: native::NativeDisplay<B>> EGLContext<B, N> {
/// Create a new `EGLContext` from a given `NativeDisplay` /// Create a new [`EGLContext`] from a given [`NativeDisplay`](native::NativeDisplay)
pub fn new<L>( pub fn new<L>(
native: N, native: N,
attributes: GlAttributes, attributes: GlAttributes,
@ -449,7 +449,7 @@ impl<B: native::Backend, N: native::NativeDisplay<B>> EGLContext<B, N> {
/// Borrow the underlying native display. /// Borrow the underlying native display.
/// ///
/// This follows the same semantics as `std::cell:RefCell`. /// This follows the same semantics as [`std::cell:RefCell`](std::cell::RefCell).
/// Multiple read-only borrows are possible. Borrowing the /// Multiple read-only borrows are possible. Borrowing the
/// backend while there is a mutable reference will panic. /// backend while there is a mutable reference will panic.
pub fn borrow(&self) -> Ref<N> { pub fn borrow(&self) -> Ref<N> {
@ -458,7 +458,7 @@ impl<B: native::Backend, N: native::NativeDisplay<B>> EGLContext<B, N> {
/// Borrow the underlying native display mutably. /// Borrow the underlying native display mutably.
/// ///
/// This follows the same semantics as `std::cell:RefCell`. /// This follows the same semantics as [`std::cell:RefCell`](std::cell::RefCell).
/// Holding any other borrow while trying to borrow the backend /// Holding any other borrow while trying to borrow the backend
/// mutably will panic. Note that EGL will borrow the display /// mutably will panic. Note that EGL will borrow the display
/// mutably during surface creation. /// mutably during surface creation.

48
src/backend/egl/mod.rs
View File

@ -1,21 +1,22 @@
//! Common traits and types for egl rendering //! Common traits and types for egl rendering
//! //!
//! Large parts of this module are taken from //! Large parts of this module are taken from
//! https://github.com/tomaka/glutin/tree/044e651edf67a2029eecc650dd42546af1501414/src/api/egl/ //! [glutin src/api/egl](https://github.com/tomaka/glutin/tree/044e651edf67a2029eecc650dd42546af1501414/src/api/egl/)
//! //!
//! It therefore falls under glutin's Apache 2.0 license //! It therefore falls under
//! (see https://github.com/tomaka/glutin/tree/044e651edf67a2029eecc650dd42546af1501414/LICENSE) //! [glutin's Apache 2.0 license](https://github.com/tomaka/glutin/tree/044e651edf67a2029eecc650dd42546af1501414/LICENSE)
//! Wayland specific EGL functionality - EGL based `WlBuffer`s. //!
//! Wayland specific EGL functionality - EGL based [`WlBuffer`](wayland_server::protocol::wl_buffer::WlBuffer)s.
//! //!
//! The types of this module can be used to initialize hardware acceleration rendering //! The types of this module can be used to initialize hardware acceleration rendering
//! based on EGL for clients as it may enabled usage of `EGLImage` based `WlBuffer`s. //! based on EGL for clients as it may enabled usage of `EGLImage` based [`WlBuffer`](wayland_server::protocol::wl_buffer::WlBuffer)s.
//! //!
//! To use it bind any backend implementing the `EGLWaylandExtensions` trait, that shall do the //! To use it bind any backend implementing the [`EGLGraphicsBackend`](::backend::egl::EGLGraphicsBackend) trait, that shall do the
//! rendering (so pick a fast one), to the `wayland_server::Display` of your compositor. //! rendering (so pick a fast one), to the [`wayland_server::Display`] of your compositor.
//! Note only one backend may be bound to any `Display` at any time. //! Note only one backend may be bound to any [`Display`](wayland_server::Display) at any time.
//! //!
//! You may then use the resulting `EGLDisplay` to receive `EGLImages` of an EGL-based `WlBuffer` //! You may then use the resulting [`EGLDisplay`](::backend::egl::EGLDisplay) to receive [`EGLImages`](::backend::egl::EGLImages)
//! for rendering. //! of an EGL-based [`WlBuffer`](wayland_server::protocol::wl_buffer::WlBuffer) for rendering.
#[cfg(feature = "renderer_gl")] #[cfg(feature = "renderer_gl")]
use backend::graphics::gl::ffi as gl_ffi; use backend::graphics::gl::ffi as gl_ffi;
@ -219,7 +220,7 @@ impl Format {
} }
} }
/// Images of the EGL-based `WlBuffer`. /// Images of the EGL-based [`WlBuffer`].
pub struct EGLImages { pub struct EGLImages {
display: Weak<ffi::egl::types::EGLDisplay>, display: Weak<ffi::egl::types::EGLDisplay>,
/// Width in pixels /// Width in pixels
@ -297,29 +298,28 @@ impl Drop for EGLImages {
} }
} }
/// Trait any backend type may implement that allows binding a `wayland_server::Display` /// Trait any backend type may implement that allows binding a [`Display`](wayland_server::Display)
/// to create an `EGLDisplay` for EGL-based `WlBuffer`s. /// to create an [`EGLDisplay`] for EGL-based [`WlBuffer`]s.
#[cfg(feature = "native_lib")] #[cfg(feature = "native_lib")]
pub trait EGLGraphicsBackend { pub trait EGLGraphicsBackend {
/// Binds this EGL context to the given Wayland display. /// Binds this EGL context to the given Wayland display.
/// ///
/// This will allow clients to utilize EGL to create hardware-accelerated /// This will allow clients to utilize EGL to create hardware-accelerated
/// surfaces. The server will need to be able to handle EGL-`wl_buffers`. /// surfaces. The server will need to be able to handle EGL-[`WlBuffer`]s.
/// See the `wayland::drm` module.
/// ///
/// ## Errors /// ## Errors
/// ///
/// This might return `WlExtensionNotSupported` if binding is not supported /// This might return [`EglExtensionNotSupported`](ErrorKind::EglExtensionNotSupported)
/// by the EGL implementation. /// if binding is not supported by the EGL implementation.
/// ///
/// This might return `OtherEGLDisplayAlreadyBound` if called for the same /// This might return [`OtherEGLDisplayAlreadyBound`](ErrorKind::OtherEGLDisplayAlreadyBound)
/// `Display` multiple times, as only one context may be bound at any given time. /// if called for the same [`Display`] multiple times, as only one context may be bound at any given time.
fn bind_wl_display(&self, display: &Display) -> Result<EGLDisplay>; fn bind_wl_display(&self, display: &Display) -> Result<EGLDisplay>;
} }
/// Type to receive `EGLImages` for EGL-based `WlBuffer`s. /// Type to receive [`EGLImages`] for EGL-based [`WlBuffer`]s.
/// ///
/// Can be created by using `EGLGraphicsBackend::bind_wl_display`. /// Can be created by using [`EGLGraphicsBackend::bind_wl_display`].
#[cfg(feature = "native_lib")] #[cfg(feature = "native_lib")]
pub struct EGLDisplay { pub struct EGLDisplay {
egl: Weak<ffi::egl::types::EGLDisplay>, egl: Weak<ffi::egl::types::EGLDisplay>,
@ -357,10 +357,10 @@ impl EGLDisplay {
} }
} }
/// Try to receive `EGLImages` from a given `WlBuffer`. /// Try to receive [`EGLImages`] from a given [`WlBuffer`].
/// ///
/// In case the buffer is not managed by EGL (but e.g. the `wayland::shm` module) /// In case the buffer is not managed by EGL (but e.g. the [`wayland::shm` module](::wayland::shm))
/// a `BufferAccessError::NotManaged(WlBuffer)` is returned with the original buffer /// a [`BufferAccessError::NotManaged`](::backend::egl::BufferAccessError::NotManaged) is returned with the original buffer
/// to render it another way. /// to render it another way.
pub fn egl_buffer_contents( pub fn egl_buffer_contents(
&self, &self,

18
src/backend/egl/native.rs
View File

@ -18,11 +18,11 @@ pub trait Backend {
/// Surface type created by this backend /// Surface type created by this backend
type Surface: NativeSurface; type Surface: NativeSurface;
/// Return an `EGLDisplay` based on this backend /// Return an [`EGLDisplay`](ffi::egl::types::EGLDisplay) based on this backend
/// ///
/// # Unsafety /// # Unsafety
/// ///
/// The returned `EGLDisplay` needs to be a valid pointer for EGL, /// The returned [`EGLDisplay`](ffi::egl::types::EGLDisplay) needs to be a valid pointer for EGL,
/// but there is no way to test that. /// but there is no way to test that.
unsafe fn get_display<F: Fn(&str) -> bool>( unsafe fn get_display<F: Fn(&str) -> bool>(
display: ffi::NativeDisplayType, display: ffi::NativeDisplayType,
@ -91,18 +91,18 @@ impl Backend for X11 {
} }
} }
/// Trait for types returning Surfaces which can be used to initialize `EGLSurface`s /// Trait for types returning Surfaces which can be used to initialize [`EGLSurface`](super::EGLSurface)s
/// ///
/// ## Unsafety /// ## Unsafety
/// ///
/// The returned `NativeDisplayType` must be valid for EGL and there is no way to test that. /// The returned [`NativeDisplayType`](super::ffi::NativeDisplayType) must be valid for EGL and there is no way to test that.
pub unsafe trait NativeDisplay<B: Backend> { pub unsafe trait NativeDisplay<B: Backend> {
/// Arguments used to surface creation. /// Arguments used to surface creation.
type Arguments; type Arguments;
/// Error type thrown by the surface creation in case of failure. /// Error type thrown by the surface creation in case of failure.
type Error: ::std::error::Error + Send + 'static; type Error: ::std::error::Error + Send + 'static;
/// Because one type might implement multiple `Backend`s this function must be called to check /// Because one type might implement multiple [`Backend`]s this function must be called to check
/// if the expected `Backend` is used at runtime. /// if the expected [`Backend`] is used at runtime.
fn is_backend(&self) -> bool; fn is_backend(&self) -> bool;
/// Return a raw pointer EGL will accept for context creation. /// Return a raw pointer EGL will accept for context creation.
fn ptr(&self) -> Result<ffi::NativeDisplayType>; fn ptr(&self) -> Result<ffi::NativeDisplayType>;
@ -163,7 +163,8 @@ unsafe impl NativeDisplay<Wayland> for WinitWindow {
/// ///
/// ## Unsafety /// ## Unsafety
/// ///
/// The returned `NativeWindowType` must be valid for EGL and there is no way to test that. /// The returned [`NativeWindowType`](ffi::NativeWindowType) must be valid for EGL
/// and there is no way to test that.
pub unsafe trait NativeSurface { pub unsafe trait NativeSurface {
/// Return a raw pointer egl will accept for surface creation. /// Return a raw pointer egl will accept for surface creation.
fn ptr(&self) -> ffi::NativeWindowType; fn ptr(&self) -> ffi::NativeWindowType;
@ -187,7 +188,8 @@ pub unsafe trait NativeSurface {
true true
} }
/// Adds additional semantics when calling EGLSurface::swap_buffers /// Adds additional semantics when calling
/// [EGLSurface::swap_buffers](::backend::egl::surface::EGLSurface::swap_buffers)
/// ///
/// Only implement if required by the backend. /// Only implement if required by the backend.
fn swap_buffers(&self) -> ::std::result::Result<(), SwapBuffersError> { fn swap_buffers(&self) -> ::std::result::Result<(), SwapBuffersError> {

9
src/backend/graphics/cursor.rs
View File

@ -1,4 +1,9 @@
/// Functions to render cursors on any graphics backend independently from it's rendering techique. /// Functions to render cursors on graphics backend independently from it's rendering techique.
///
/// In the most cases this will be the fastest available implementation utilizing hardware composing
/// where possible. This may however be quite restrictive in terms of supported formats.
///
/// For those reasons you may always choose to render your cursor(s) (partially) in software instead.
pub trait CursorBackend<'a> { pub trait CursorBackend<'a> {
/// Format representing the image drawn for the cursor. /// Format representing the image drawn for the cursor.
type CursorFormat: 'a; type CursorFormat: 'a;
@ -19,7 +24,7 @@ pub trait CursorBackend<'a> {
/// ///
fn set_cursor_position(&self, x: u32, y: u32) -> Result<(), Self::Error>; fn set_cursor_position(&self, x: u32, y: u32) -> Result<(), Self::Error>;
/// Set the cursor drawn on the `CursorBackend`. /// Set the cursor drawn on the [`CursorBackend`].
/// ///
/// The format is entirely dictated by the concrete implementation and might range /// The format is entirely dictated by the concrete implementation and might range
/// from raw image buffers over a fixed list of possible cursor types to simply the /// from raw image buffers over a fixed list of possible cursor types to simply the

8
src/backend/graphics/gl.rs
View File

@ -1,4 +1,4 @@
//! Gl rendering types //! OpenGL rendering types
use nix::libc::c_void; use nix::libc::c_void;
@ -45,11 +45,11 @@ pub trait GLGraphicsBackend {
fn get_pixel_format(&self) -> PixelFormat; fn get_pixel_format(&self) -> PixelFormat;
} }
/// Loads a Raw GLES Interface for a given `GLGraphicsBackend` /// Loads a Raw GLES Interface for a given [`GLGraphicsBackend`]
/// ///
/// This remains valid as long as the underlying `GLGraphicsBackend` is alive /// This remains valid as long as the underlying [`GLGraphicsBackend`] is alive
/// and may only be used in combination with the backend. Using this with any /// and may only be used in combination with the backend. Using this with any
/// other gl context *may* cause undefined behavior. /// other gl context or after the backend was dropped *may* cause undefined behavior.
pub fn load_raw_gl<B: GLGraphicsBackend>(backend: &B) -> Gles2 { pub fn load_raw_gl<B: GLGraphicsBackend>(backend: &B) -> Gles2 {
Gles2::load_with(|s| unsafe { backend.get_proc_address(s) as *const _ }) Gles2::load_with(|s| unsafe { backend.get_proc_address(s) as *const _ })
} }

10
src/backend/graphics/glium.rs
View File

@ -45,10 +45,10 @@ impl<T: GLGraphicsBackend + 'static> GliumGraphicsBackend<T> {
/// Start drawing on the backbuffer. /// Start drawing on the backbuffer.
/// ///
/// This function returns a `Frame`, which can be used to draw on it. When the `Frame` is /// This function returns a [`Frame`], which can be used to draw on it.
/// destroyed, the buffers are swapped. /// When the [`Frame`] is destroyed, the buffers are swapped.
/// ///
/// Note that destroying a `Frame` is immediate, even if vsync is enabled. /// Note that destroying a [`Frame`] is immediate, even if vsync is enabled.
#[inline] #[inline]
pub fn draw(&self) -> Frame { pub fn draw(&self) -> Frame {
Frame::new(self.context.clone(), self.backend.get_framebuffer_dimensions()) Frame::new(self.context.clone(), self.backend.get_framebuffer_dimensions())
@ -56,7 +56,7 @@ impl<T: GLGraphicsBackend + 'static> GliumGraphicsBackend<T> {
/// Borrow the underlying backend. /// Borrow the underlying backend.
/// ///
/// This follows the same semantics as `std::cell:RefCell`. /// This follows the same semantics as [`std::cell::RefCell`](RefCell::borrow).
/// Multiple read-only borrows are possible. Borrowing the /// Multiple read-only borrows are possible. Borrowing the
/// backend while there is a mutable reference will panic. /// backend while there is a mutable reference will panic.
pub fn borrow(&self) -> Ref<T> { pub fn borrow(&self) -> Ref<T> {
@ -65,7 +65,7 @@ impl<T: GLGraphicsBackend + 'static> GliumGraphicsBackend<T> {
/// Borrow the underlying backend mutably. /// Borrow the underlying backend mutably.
/// ///
/// This follows the same semantics as `std::cell:RefCell`. /// This follows the same semantics as [`std::cell::RefCell`](RefCell::borrow_mut).
/// Holding any other borrow while trying to borrow the backend /// Holding any other borrow while trying to borrow the backend
/// mutably will panic. Note that Glium will borrow the backend /// mutably will panic. Note that Glium will borrow the backend
/// (not mutably) during rendering. /// (not mutably) during rendering.

74
src/backend/input.rs
View File

@ -10,8 +10,8 @@ use std::{error::Error, string::ToString};
/// separated users, all with their own focus, input and cursor available. /// separated users, all with their own focus, input and cursor available.
/// ///
/// Seats referring to the same internal id will always be equal and result in the same /// Seats referring to the same internal id will always be equal and result in the same
/// hash, but capabilities of cloned and copied `Seat`s will not be updated by smithay. /// hash, but capabilities of cloned and copied [`Seat`]s will not be updated by smithay.
/// Always refer to the `Seat` given by a callback for up-to-date information. You may /// Always refer to the [`Seat`] given by a callback for up-to-date information. You may
/// use this to calculate the differences since the last callback. /// use this to calculate the differences since the last callback.
#[derive(Debug, Clone, Eq)] #[derive(Debug, Clone, Eq)]
pub struct Seat { pub struct Seat {
@ -33,12 +33,12 @@ impl Seat {
&mut self.capabilities &mut self.capabilities
} }
/// Get the currently capabilities of this `Seat` /// Get the currently capabilities of this [`Seat`]
pub fn capabilities(&self) -> &SeatCapabilities { pub fn capabilities(&self) -> &SeatCapabilities {
&self.capabilities &self.capabilities
} }
/// Get the name of this `Seat` /// Get the name of this [`Seat`]
pub fn name(&self) -> &str { pub fn name(&self) -> &str {
&*self.name &*self.name
} }
@ -59,14 +59,14 @@ impl ::std::hash::Hash for Seat {
} }
} }
/// Describes capabilities a `Seat` has. /// Describes capabilities a [`Seat`] has.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct SeatCapabilities { pub struct SeatCapabilities {
/// `Seat` has a pointer /// [`Seat`] has a pointer
pub pointer: bool, pub pointer: bool,
/// `Seat` has a keyboard /// [`Seat`] has a keyboard
pub keyboard: bool, pub keyboard: bool,
/// `Seat` has a touchscreen /// [`Seat`] has a touchscreen
pub touch: bool, pub touch: bool,
} }
@ -81,10 +81,10 @@ pub trait Event {
fn time(&self) -> u32; fn time(&self) -> u32;
} }
/// Used to mark events never emitted by an `InputBackend` implementation. /// Used to mark events never emitted by an [`InputBackend`] implementation.
/// ///
/// Implements all event types and can be used in place for any `Event` type, /// Implements all event types and can be used in place for any [`Event`] type,
/// that is not used by an `InputBackend` implementation. Initialization is not /// that is not used by an [`InputBackend`] implementation. Initialization is not
/// possible, making accidental use impossible and enabling a lot of possible /// possible, making accidental use impossible and enabling a lot of possible
/// compiler optimizations. /// compiler optimizations.
pub enum UnusedEvent {} pub enum UnusedEvent {}
@ -110,7 +110,7 @@ pub trait KeyboardKeyEvent: Event {
fn key_code(&self) -> u32; fn key_code(&self) -> u32;
/// State of the key /// State of the key
fn state(&self) -> KeyState; fn state(&self) -> KeyState;
/// Total number of keys pressed on all devices on the associated `Seat` /// Total number of keys pressed on all devices on the associated [`Seat`]
fn count(&self) -> u32; fn count(&self) -> u32;
} }
@ -190,7 +190,7 @@ pub enum AxisSource {
/// cursor movement, i.e. a scroll value of 1 represents the equivalent relative /// cursor movement, i.e. a scroll value of 1 represents the equivalent relative
/// motion of 1. /// motion of 1.
Finger, Finger,
/// Continuous scrolling device. Almost identical to `Finger` /// Continuous scrolling device. Almost identical to [`Finger`](AxisSource::Finger)
/// ///
/// No terminating event is guaranteed (though it may happen). /// No terminating event is guaranteed (though it may happen).
/// ///
@ -212,14 +212,14 @@ pub enum AxisSource {
/// Trait for pointer events generated by scrolling on an axis. /// Trait for pointer events generated by scrolling on an axis.
pub trait PointerAxisEvent: Event { pub trait PointerAxisEvent: Event {
/// Amount of scrolling in pixels on the given `Axis`. /// Amount of scrolling in pixels on the given [`Axis`].
/// ///
/// Guaranteed to be `Some` when source returns either `AxisSource::Finger` or `AxisSource::Continuous`. /// Guaranteed to be `Some` when source returns either [`AxisSource::Finger`] or [`AxisSource::Continuous`].
fn amount(&self, axis: &Axis) -> Option<f64>; fn amount(&self, axis: &Axis) -> Option<f64>;
/// Amount of scrolling in discrete steps on the given `Axis`. /// Amount of scrolling in discrete steps on the given [`Axis`].
/// ///
/// Guaranteed to be `Some` when source returns either `AxisSource::Wheel` or `AxisSource::WheelTilt`. /// Guaranteed to be `Some` when source returns either [`AxisSource::Wheel`] or [`AxisSource::WheelTilt`].
fn amount_discrete(&self, axis: &Axis) -> Option<f64>; fn amount_discrete(&self, axis: &Axis) -> Option<f64>;
/// Source of the scroll event. /// Source of the scroll event.
@ -336,7 +336,7 @@ impl TouchSlot {
/// Trait for touch events starting at a given position. /// Trait for touch events starting at a given position.
pub trait TouchDownEvent: Event { pub trait TouchDownEvent: Event {
/// `TouchSlot`, if the device has multi-touch capabilities /// [`TouchSlot`], if the device has multi-touch capabilities
fn slot(&self) -> Option<TouchSlot>; fn slot(&self) -> Option<TouchSlot>;
/// Touch position in the device's native coordinate space /// Touch position in the device's native coordinate space
@ -398,7 +398,7 @@ impl TouchDownEvent for UnusedEvent {
/// Trait for touch events regarding movement on the screen /// Trait for touch events regarding movement on the screen
pub trait TouchMotionEvent: Event { pub trait TouchMotionEvent: Event {
/// `TouchSlot`, if the device has multi-touch capabilities /// [`TouchSlot`], if the device has multi-touch capabilities
fn slot(&self) -> Option<TouchSlot>; fn slot(&self) -> Option<TouchSlot>;
/// Touch position in the device's native coordinate space /// Touch position in the device's native coordinate space
@ -460,7 +460,7 @@ impl TouchMotionEvent for UnusedEvent {
/// Trait for touch events finishing. /// Trait for touch events finishing.
pub trait TouchUpEvent: Event { pub trait TouchUpEvent: Event {
/// `TouchSlot`, if the device has multi-touch capabilities /// [`TouchSlot`], if the device has multi-touch capabilities
fn slot(&self) -> Option<TouchSlot>; fn slot(&self) -> Option<TouchSlot>;
} }
@ -472,7 +472,7 @@ impl TouchUpEvent for UnusedEvent {
/// Trait for touch events cancelling the chain /// Trait for touch events cancelling the chain
pub trait TouchCancelEvent: Event { pub trait TouchCancelEvent: Event {
/// `TouchSlot`, if the device has multi-touch capabilities /// [`TouchSlot`], if the device has multi-touch capabilities
fn slot(&self) -> Option<TouchSlot>; fn slot(&self) -> Option<TouchSlot>;
} }
@ -518,7 +518,7 @@ pub trait InputBackend: Sized {
/// Type representing touch frame events /// Type representing touch frame events
type TouchFrameEvent: TouchFrameEvent; type TouchFrameEvent: TouchFrameEvent;
/// Sets a new handler for this `InputBackend` /// Sets a new handler for this [`InputBackend`]
fn set_handler<H: InputHandler<Self> + 'static>(&mut self, handler: H); fn set_handler<H: InputHandler<Self> + 'static>(&mut self, handler: H);
/// Get a reference to the currently set handler, if any /// Get a reference to the currently set handler, if any
fn get_handler(&mut self) -> Option<&mut InputHandler<Self>>; fn get_handler(&mut self) -> Option<&mut InputHandler<Self>>;
@ -528,17 +528,17 @@ pub trait InputBackend: Sized {
/// Get current `InputConfig` /// Get current `InputConfig`
fn input_config(&mut self) -> &mut Self::InputConfig; fn input_config(&mut self) -> &mut Self::InputConfig;
/// Processes new events of the underlying backend and drives the `InputHandler`. /// Processes new events of the underlying backend and drives the [`InputHandler`].
fn dispatch_new_events(&mut self) -> Result<(), Self::EventError>; fn dispatch_new_events(&mut self) -> Result<(), Self::EventError>;
} }
/// Implement to receive input events from any `InputBackend`. /// Implement to receive input events from any [`InputBackend`].
pub trait InputHandler<B: InputBackend> { pub trait InputHandler<B: InputBackend> {
/// Called when a new `Seat` has been created /// Called when a new [`Seat`] has been created
fn on_seat_created(&mut self, seat: &Seat); fn on_seat_created(&mut self, seat: &Seat);
/// Called when an existing `Seat` has been destroyed. /// Called when an existing [`Seat`] has been destroyed.
fn on_seat_destroyed(&mut self, seat: &Seat); fn on_seat_destroyed(&mut self, seat: &Seat);
/// Called when a `Seat`'s properties have changed. /// Called when a [`Seat`]'s properties have changed.
/// ///
/// ## Note: /// ## Note:
/// ///
@ -549,7 +549,7 @@ pub trait InputHandler<B: InputBackend> {
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `seat` - The `Seat` the event belongs to /// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The keyboard event /// - `event` - The keyboard event
/// ///
fn on_keyboard_key(&mut self, seat: &Seat, event: B::KeyboardKeyEvent); fn on_keyboard_key(&mut self, seat: &Seat, event: B::KeyboardKeyEvent);
@ -558,28 +558,28 @@ pub trait InputHandler<B: InputBackend> {
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `seat` - The `Seat` the event belongs to /// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The pointer movement event /// - `event` - The pointer movement event
fn on_pointer_move(&mut self, seat: &Seat, event: B::PointerMotionEvent); fn on_pointer_move(&mut self, seat: &Seat, event: B::PointerMotionEvent);
/// Called when a new pointer absolute movement event was received. /// Called when a new pointer absolute movement event was received.
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `seat` - The `Seat` the event belongs to /// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The pointer absolute movement event /// - `event` - The pointer absolute movement event
fn on_pointer_move_absolute(&mut self, seat: &Seat, event: B::PointerMotionAbsoluteEvent); fn on_pointer_move_absolute(&mut self, seat: &Seat, event: B::PointerMotionAbsoluteEvent);
/// Called when a new pointer button event was received. /// Called when a new pointer button event was received.
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `seat` - The `Seat` the event belongs to /// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The pointer button event /// - `event` - The pointer button event
fn on_pointer_button(&mut self, seat: &Seat, event: B::PointerButtonEvent); fn on_pointer_button(&mut self, seat: &Seat, event: B::PointerButtonEvent);
/// Called when a new pointer scroll event was received. /// Called when a new pointer scroll event was received.
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `seat` - The `Seat` the event belongs to /// - `seat` - The [`Seat`] the event belongs to
/// - `event` - A upward counting variable useful for event ordering. Makes no guarantees about actual time passed between events. /// - `event` - A upward counting variable useful for event ordering. Makes no guarantees about actual time passed between events.
fn on_pointer_axis(&mut self, seat: &Seat, event: B::PointerAxisEvent); fn on_pointer_axis(&mut self, seat: &Seat, event: B::PointerAxisEvent);
@ -587,35 +587,35 @@ pub trait InputHandler<B: InputBackend> {
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `seat` - The `Seat` the event belongs to /// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The touch down event /// - `event` - The touch down event
fn on_touch_down(&mut self, seat: &Seat, event: B::TouchDownEvent); fn on_touch_down(&mut self, seat: &Seat, event: B::TouchDownEvent);
/// Called when a new touch motion event was received. /// Called when a new touch motion event was received.
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `seat` - The `Seat` the event belongs to /// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The touch motion event. /// - `event` - The touch motion event.
fn on_touch_motion(&mut self, seat: &Seat, event: B::TouchMotionEvent); fn on_touch_motion(&mut self, seat: &Seat, event: B::TouchMotionEvent);
/// Called when a new touch up event was received. /// Called when a new touch up event was received.
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `seat` - The `Seat` the event belongs to /// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The touch up event. /// - `event` - The touch up event.
fn on_touch_up(&mut self, seat: &Seat, event: B::TouchUpEvent); fn on_touch_up(&mut self, seat: &Seat, event: B::TouchUpEvent);
/// Called when a new touch cancel event was received. /// Called when a new touch cancel event was received.
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `seat` - The `Seat` the event belongs to /// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The touch cancel event. /// - `event` - The touch cancel event.
fn on_touch_cancel(&mut self, seat: &Seat, event: B::TouchCancelEvent); fn on_touch_cancel(&mut self, seat: &Seat, event: B::TouchCancelEvent);
/// Called when a new touch frame event was received. /// Called when a new touch frame event was received.
/// ///
/// # Arguments /// # Arguments
/// ///
/// - `seat` - The `Seat` the event belongs to /// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The touch frame event. /// - `event` - The touch frame event.
fn on_touch_frame(&mut self, seat: &Seat, event: B::TouchFrameEvent); fn on_touch_frame(&mut self, seat: &Seat, event: B::TouchFrameEvent);

18
src/backend/libinput.rs
View File

@ -1,8 +1,8 @@
//! Implementation of input backend trait for types provided by `libinput` //! Implementation of input backend trait for types provided by `libinput`
use backend::input::{self as backend, Axis, InputBackend};
#[cfg(feature = "backend_session")] #[cfg(feature = "backend_session")]
use backend::session::{AsErrno, Session, SessionObserver}; use backend::session::{AsErrno, Session, SessionObserver};
use backend::{input as backend, input::Axis};
use input as libinput; use input as libinput;
use input::event; use input::event;
@ -27,7 +27,7 @@ use wayland_server::calloop::{
#[cfg(all(any(target_os = "linux", target_os = "android"), feature = "backend_session"))] #[cfg(all(any(target_os = "linux", target_os = "android"), feature = "backend_session"))]
const INPUT_MAJOR: u32 = 13; const INPUT_MAJOR: u32 = 13;
/// Libinput based `InputBackend`. /// Libinput based [`InputBackend`].
/// ///
/// Tracks input of all devices given manually or via a udev seat to a provided libinput /// Tracks input of all devices given manually or via a udev seat to a provided libinput
/// context. /// context.
@ -40,8 +40,8 @@ pub struct LibinputInputBackend {
} }
impl LibinputInputBackend { impl LibinputInputBackend {
/// Initialize a new `LibinputInputBackend` from a given already initialized libinput /// Initialize a new [`LibinputInputBackend`] from a given already initialized
/// context. /// [libinput context](libinput::Libinput).
pub fn new<L>(context: libinput::Libinput, logger: L) -> Self pub fn new<L>(context: libinput::Libinput, logger: L) -> Self
where where
L: Into<Option<::slog::Logger>>, L: Into<Option<::slog::Logger>>,
@ -248,7 +248,7 @@ impl backend::Event for event::touch::TouchFrameEvent {
impl backend::TouchFrameEvent for event::touch::TouchFrameEvent {} impl backend::TouchFrameEvent for event::touch::TouchFrameEvent {}
impl backend::InputBackend for LibinputInputBackend { impl InputBackend for LibinputInputBackend {
type InputConfig = [libinput::Device]; type InputConfig = [libinput::Device];
type EventError = IoError; type EventError = IoError;
@ -565,8 +565,8 @@ impl SessionObserver for libinput::Libinput {
} }
} }
/// Wrapper for types implementing the `Session` trait to provide /// Wrapper for types implementing the [`Session`] trait to provide
/// a `LibinputInterface` implementation. /// a [`libinput::LibinputInterface`] implementation.
#[cfg(feature = "backend_session")] #[cfg(feature = "backend_session")]
pub struct LibinputSessionInterface<S: Session>(S); pub struct LibinputSessionInterface<S: Session>(S);
@ -597,10 +597,10 @@ impl AsRawFd for LibinputInputBackend {
} }
} }
/// Binds a `LibinputInputBackend` to a given `EventLoop`. /// Binds a [`LibinputInputBackend`] to a given [`LoopHandle`].
/// ///
/// Automatically feeds the backend with incoming events without any manual calls to /// Automatically feeds the backend with incoming events without any manual calls to
/// `dispatch_new_events`. Should be used to achieve the smallest possible latency. /// [`dispatch_new_events`](InputBackend::dispatch_new_events). Should be used to achieve the smallest possible latency.
pub fn libinput_bind<Data: 'static>( pub fn libinput_bind<Data: 'static>(
backend: LibinputInputBackend, backend: LibinputInputBackend,
handle: LoopHandle<Data>, handle: LoopHandle<Data>,

64
src/backend/session/auto.rs
View File

@ -1,31 +1,32 @@
//! Implementation of the `Session` trait through various implementations //! Implementation of the [`Session`] trait through various implementations
//! automatically choosing the best available interface. //! automatically choosing the best available interface.
//! //!
//! ## How to use it //! ## How to use it
//! //!
//! ### Initialization //! ### Initialization
//! //!
//! To initialize a session just call `AutoSession::new`. A new session will be opened, if the //! To initialize a session just call [`AutoSession::new`](::backend::session::auto::AutoSession::new).
//! any available interface is successful and will be closed once the `AutoSessionNotifier` is dropped. //! A new session will be opened, if the any available interface is successful and will be closed once the
//! [`AutoSessionNotifier`](::backend::session::auto::AutoSessionNotifier) is dropped.
//! //!
//! ### Usage of the session //! ### Usage of the session
//! //!
//! The session may be used to open devices manually through the `Session` interface //! The session may be used to open devices manually through the [`Session`] interface
//! or be passed to other objects that need it to open devices themselves. //! or be passed to other objects that need it to open devices themselves.
//! The `AutoSession` is clonable and may be passed to multiple devices easily. //! The [`AutoSession`](::backend::session::auto::AutoSession) is clonable
//! and may be passed to multiple devices easily.
//! //!
//! Examples for those are e.g. the `LibinputInputBackend` (its context might be initialized through a //! Examples for those are e.g. the [`LibinputInputBackend`](::backend::libinput::LibinputInputBackend)
//! `Session` via the `LibinputSessionInterface`) or the `UdevBackend`. //! (its context might be initialized through a [`Session`] via the [`LibinputSessionInterface`](::backend::libinput::LibinputSessionInterface)).
//! //!
//! ### Usage of the session notifier //! ### Usage of the session notifier
//! //!
//! The notifier might be used to pause device access, when the session gets paused (e.g. by //! The notifier might be used to pause device access, when the session gets paused (e.g. by
//! switching the tty via `AutoSession::change_vt`) and to automatically enable it again, //! switching the tty via [`AutoSession::change_vt`](::backend::session::Session::change_vt))
//! when the session becomes active again. //! and to automatically enable it again, when the session becomes active again.
//! //!
//! It is crucial to avoid errors during that state. Examples for object that might be registered //! It is crucial to avoid errors during that state. Examples for object that might be registered
//! for notifications are the `Libinput` context, the `UdevBackend` or a `DrmDevice` (handled //! for notifications are the [`Libinput`](input::Libinput) context or the [`Device`](::backend::drm::Device).
//! automatically by the `UdevBackend`, if not done manually).
#[cfg(feature = "backend_session_logind")] #[cfg(feature = "backend_session_logind")]
use super::logind::{self, logind_session_bind, BoundLogindSession, LogindSession, LogindSessionNotifier}; use super::logind::{self, logind_session_bind, BoundLogindSession, LogindSession, LogindSessionNotifier};
@ -38,7 +39,7 @@ use std::{cell::RefCell, io::Error as IoError, os::unix::io::RawFd, path::Path,
use wayland_server::calloop::LoopHandle; use wayland_server::calloop::LoopHandle;
/// `Session` using the best available interface /// [`Session`] using the best available interface
#[derive(Clone)] #[derive(Clone)]
pub enum AutoSession { pub enum AutoSession {
/// Logind session /// Logind session
@ -48,7 +49,7 @@ pub enum AutoSession {
Direct(Rc<RefCell<DirectSession>>), Direct(Rc<RefCell<DirectSession>>),
} }
/// `SessionNotifier` using the best available interface /// [`SessionNotifier`] using the best available interface
pub enum AutoSessionNotifier { pub enum AutoSessionNotifier {
/// Logind session notifier /// Logind session notifier
#[cfg(feature = "backend_session_logind")] #[cfg(feature = "backend_session_logind")]
@ -57,11 +58,11 @@ pub enum AutoSessionNotifier {
Direct(DirectSessionNotifier), Direct(DirectSessionNotifier),
} }
/// Bound session that is driven by the `calloop::EventLoop`. /// Bound session that is driven by a [`EventLoop`](wayland_server::calloop::EventLoop).
/// ///
/// See `auto_session_bind` for details. /// See [`auto_session_bind`] for details.
/// ///
/// Dropping this object will close the session just like the `AutoSessionNotifier`. /// Dropping this object will close the session just like the [`AutoSessionNotifier`].
pub enum BoundAutoSession { pub enum BoundAutoSession {
/// Bound logind session /// Bound logind session
#[cfg(feature = "backend_session_logind")] #[cfg(feature = "backend_session_logind")]
@ -70,7 +71,7 @@ pub enum BoundAutoSession {
Direct(BoundDirectSession), Direct(BoundDirectSession),
} }
/// Id's used by the `AutoSessionNotifier` internally. /// Id's used by the [`AutoSessionNotifier`] internally.
#[derive(Debug, PartialEq, Eq, Clone, Copy)] #[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub struct AutoId(AutoIdInternal); pub struct AutoId(AutoIdInternal);
#[derive(Debug, PartialEq, Eq, Clone, Copy)] #[derive(Debug, PartialEq, Eq, Clone, Copy)]
@ -138,11 +139,11 @@ impl AutoSession {
} }
} }
/// Bind an `AutoSessionNotifier` to an `EventLoop`. /// Bind an [`AutoSessionNotifier`] to an [`EventLoop`](wayland_server::calloop::EventLoop).
/// ///
/// Allows the `AutoSessionNotifier` to listen for incoming signals signalling the session state. /// Allows the [`AutoSessionNotifier`] to listen for incoming signals signalling the session state.
/// If you don't use this function `AutoSessionNotifier` will not correctly tell you the /// If you don't use this function [`AutoSessionNotifier`] will not correctly tell you the
/// session state and call its `SessionObservers`. /// session state and call its [`SessionObserver`]s.
pub fn auto_session_bind<Data: 'static>( pub fn auto_session_bind<Data: 'static>(
notifier: AutoSessionNotifier, notifier: AutoSessionNotifier,
handle: &LoopHandle<Data>, handle: &LoopHandle<Data>,
@ -232,7 +233,7 @@ impl SessionNotifier for AutoSessionNotifier {
} }
impl BoundAutoSession { impl BoundAutoSession {
/// Unbind the session from the `EventLoop` again /// Unbind the session from the [`EventLoop`](wayland_server::calloop::EventLoop) again
pub fn unbind(self) -> AutoSessionNotifier { pub fn unbind(self) -> AutoSessionNotifier {
match self { match self {
#[cfg(feature = "backend_session_logind")] #[cfg(feature = "backend_session_logind")]
@ -242,15 +243,22 @@ impl BoundAutoSession {
} }
} }
error_chain! { /// Errors related to auto sessions
links { pub mod errors {
Logind(logind::Error, logind::ErrorKind) #[cfg(feature = "backend_session_logind")] #[doc = "Underlying logind session error"]; #[cfg(feature = "backend_session_logind")]
} use super::logind::errors as logind;
foreign_links { error_chain! {
Direct(::nix::Error) #[doc = "Underlying direct tty session error"]; links {
Logind(logind::Error, logind::ErrorKind) #[cfg(feature = "backend_session_logind")] #[doc = "Underlying logind session error"];
}
foreign_links {
Direct(::nix::Error) #[doc = "Underlying direct tty session error"];
}
} }
} }
use self::errors::*;
impl AsErrno for Error { impl AsErrno for Error {
fn as_errno(&self) -> Option<i32> { fn as_errno(&self) -> Option<i32> {

141
src/backend/session/dbus/logind.rs
View File

@ -1,5 +1,5 @@
//! //!
//! Implementation of the `Session` trait through the logind dbus interface. //! Implementation of the [`Session`](::backend::session::Session) trait through the logind dbus interface.
//! //!
//! This requires systemd and dbus to be available and started on the system. //! This requires systemd and dbus to be available and started on the system.
//! //!
@ -7,28 +7,29 @@
//! //!
//! ### Initialization //! ### Initialization
//! //!
//! To initialize a session just call `LogindSession::new`. A new session will be opened, if the //! To initialize a session just call [`LogindSession::new`](::backend::session::dbus::logind::LogindSession::new).
//! call is successful and will be closed once the `LogindSessionNotifier` is dropped. //! A new session will be opened, if the call is successful and will be closed once the
//! [`LogindSessionNotifier`](::backend::session::dbus::logind::LogindSessionNotifier) is dropped.
//! //!
//! ### Usage of the session //! ### Usage of the session
//! //!
//! The session may be used to open devices manually through the `Session` interface //! The session may be used to open devices manually through the [`Session`](::backend::session::Session) interface
//! or be passed to other objects that need it to open devices themselves. //! or be passed to other objects that need it to open devices themselves.
//! The `LogindSession` is clonable and may be passed to multiple devices easily. //! The [`LogindSession`](::backend::session::dbus::logind::LogindSession) is clonable
//! and may be passed to multiple devices easily.
//! //!
//! Examples for those are e.g. the `LibinputInputBackend` (its context might be initialized through a //! Examples for those are e.g. the [`LibinputInputBackend`](::backend::libinput::LibinputInputBackend)
//! `Session` via the `LibinputSessionInterface`) or the `UdevBackend`. //! (its context might be initialized through a [`Session`](::backend::session::Session) via the
//! [`LibinputSessionInterface`](::backend::libinput::LibinputSessionInterface)).
//! //!
//! ### Usage of the session notifier //! ### Usage of the session notifier
//! //!
//! The notifier might be used to pause device access, when the session gets paused (e.g. by //! The notifier might be used to pause device access, when the session gets paused (e.g. by
//! switching the tty via `LogindSession::change_vt`) and to automatically enable it again, //! switching the tty via [`LogindSession::change_vt`](::backend::session::Session::change_vt))
//! when the session becomes active again. //! and to automatically enable it again, when the session becomes active again.
//! //!
//! It is crucial to avoid errors during that state. Examples for object that might be registered //! It is crucial to avoid errors during that state. Examples for object that might be registered
//! for notifications are the `Libinput` context, the `UdevBackend` or a `DrmDevice` (handled //! for notifications are the [`Libinput`](input::Libinput) context or the [`Device`](::backend::drm::Device).
//! automatically by the `UdevBackend`, if not done manually).
//! ```
use backend::session::{AsErrno, Session, SessionNotifier, SessionObserver}; use backend::session::{AsErrno, Session, SessionNotifier, SessionObserver};
use dbus::{ use dbus::{
@ -64,14 +65,14 @@ struct LogindSessionImpl {
logger: ::slog::Logger, logger: ::slog::Logger,
} }
/// `Session` via the logind dbus interface /// [`Session`] via the logind dbus interface
#[derive(Clone)] #[derive(Clone)]
pub struct LogindSession { pub struct LogindSession {
internal: Weak<LogindSessionImpl>, internal: Weak<LogindSessionImpl>,
seat: String, seat: String,
} }
/// `SessionNotifier` via the logind dbus interface /// [`SessionNotifier`] via the logind dbus interface
#[derive(Clone)] #[derive(Clone)]
pub struct LogindSessionNotifier { pub struct LogindSessionNotifier {
internal: Rc<LogindSessionImpl>, internal: Rc<LogindSessionImpl>,
@ -401,7 +402,7 @@ impl Session for LogindSession {
} }
} }
/// Ids of registered `SessionObserver`s of the `LogindSessionNotifier` /// Ids of registered [`SessionObserver`]s of the [`LogindSessionNotifier`]
#[derive(Debug, PartialEq, Eq, Clone, Copy)] #[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub struct Id(usize); pub struct Id(usize);
@ -417,22 +418,22 @@ impl SessionNotifier for LogindSessionNotifier {
} }
} }
/// Bound logind session that is driven by the `wayland_server::EventLoop`. /// Bound logind session that is driven by the [`EventLoop`](wayland_server::calloop::EventLoop).
/// ///
/// See `logind_session_bind` for details. /// See [`logind_session_bind`] for details.
/// ///
/// Dropping this object will close the logind session just like the `LogindSessionNotifier`. /// Dropping this object will close the logind session just like the [`LogindSessionNotifier`].
pub struct BoundLogindSession { pub struct BoundLogindSession {
notifier: LogindSessionNotifier, notifier: LogindSessionNotifier,
_watches: Vec<Watch>, _watches: Vec<Watch>,
sources: Vec<Source<Generic<EventedRawFd>>>, sources: Vec<Source<Generic<EventedRawFd>>>,
} }
/// Bind a `LogindSessionNotifier` to an `EventLoop`. /// Bind a [`LogindSessionNotifier`] to an [`EventLoop`](wayland_server::calloop::EventLoop).
/// ///
/// Allows the `LogindSessionNotifier` to listen for incoming signals signalling the session state. /// Allows the [`LogindSessionNotifier`] to listen for incoming signals signalling the session state.
/// If you don't use this function `LogindSessionNotifier` will not correctly tell you the logind /// If you don't use this function [`LogindSessionNotifier`] will not correctly tell you the logind
/// session state and call it's `SessionObservers`. /// session state and call it's [`SessionObserver`]s.
pub fn logind_session_bind<Data: 'static>( pub fn logind_session_bind<Data: 'static>(
notifier: LogindSessionNotifier, notifier: LogindSessionNotifier,
handle: &LoopHandle<Data>, handle: &LoopHandle<Data>,
@ -471,7 +472,7 @@ pub fn logind_session_bind<Data: 'static>(
} }
impl BoundLogindSession { impl BoundLogindSession {
/// Unbind the logind session from the `EventLoop` /// Unbind the logind session from the [`EventLoop`](wayland_server::calloop::EventLoop)
pub fn unbind(self) -> LogindSessionNotifier { pub fn unbind(self) -> LogindSessionNotifier {
for source in self.sources { for source in self.sources {
source.remove(); source.remove();
@ -518,62 +519,68 @@ impl LogindSessionNotifier {
} }
} }
error_chain! { /// Errors related to logind sessions
errors { pub mod errors {
#[doc = "Failed to connect to dbus system socket"] use dbus::{BusName, Interface, Member, Path as DbusPath};
FailedDbusConnection {
description("Failed to connect to dbus system socket"),
}
#[doc = "Failed to get session from logind"] error_chain! {
FailedToGetSession { errors {
description("Failed to get session from logind") #[doc = "Failed to connect to dbus system socket"]
} FailedDbusConnection {
description("Failed to connect to dbus system socket"),
}
#[doc = "Failed to get seat from logind"] #[doc = "Failed to get session from logind"]
FailedToGetSeat { FailedToGetSession {
description("Failed to get seat from logind") description("Failed to get session from logind")
} }
#[doc = "Failed to get vt from logind"] #[doc = "Failed to get seat from logind"]
FailedToGetVT { FailedToGetSeat {
description("Failed to get vt from logind") description("Failed to get seat from logind")
} }
#[doc = "Failed to call dbus method"] #[doc = "Failed to get vt from logind"]
FailedToSendDbusCall(bus: BusName<'static>, path: DbusPath<'static>, interface: Interface<'static>, member: Member<'static>) { FailedToGetVT {
description("Failed to call dbus method") description("Failed to get vt from logind")
display("Failed to call dbus method for service: {:?}, path: {:?}, interface: {:?}, member: {:?}", bus, path, interface, member), }
}
#[doc = "Dbus method call failed"] #[doc = "Failed to call dbus method"]
DbusCallFailed(bus: BusName<'static>, path: DbusPath<'static>, interface: Interface<'static>, member: Member<'static>) { FailedToSendDbusCall(bus: BusName<'static>, path: DbusPath<'static>, interface: Interface<'static>, member: Member<'static>) {
description("Dbus method call failed") description("Failed to call dbus method")
display("Dbus message call failed for service: {:?}, path: {:?}, interface: {:?}, member: {:?}", bus, path, interface, member), display("Failed to call dbus method for service: {:?}, path: {:?}, interface: {:?}, member: {:?}", bus, path, interface, member),
} }
#[doc = "Dbus method return had unexpected format"] #[doc = "Dbus method call failed"]
UnexpectedMethodReturn { DbusCallFailed(bus: BusName<'static>, path: DbusPath<'static>, interface: Interface<'static>, member: Member<'static>) {
description("Dbus method return returned unexpected format") description("Dbus method call failed")
} display("Dbus message call failed for service: {:?}, path: {:?}, interface: {:?}, member: {:?}", bus, path, interface, member),
}
#[doc = "Failed to setup dbus match rule"] #[doc = "Dbus method return had unexpected format"]
DbusMatchFailed(rule: String) { UnexpectedMethodReturn {
description("Failed to setup dbus match rule"), description("Dbus method return returned unexpected format")
display("Failed to setup dbus match rule {}", rule), }
}
#[doc = "Failed to stat device"] #[doc = "Failed to setup dbus match rule"]
FailedToStatDevice { DbusMatchFailed(rule: String) {
description("Failed to stat device") description("Failed to setup dbus match rule"),
} display("Failed to setup dbus match rule {}", rule),
}
#[doc = "Session is already closed"] #[doc = "Failed to stat device"]
SessionLost { FailedToStatDevice {
description("Session is already closed") description("Failed to stat device")
}
#[doc = "Session is already closed"]
SessionLost {
description("Session is already closed")
}
} }
} }
} }
use self::errors::*;
impl AsErrno for Error { impl AsErrno for Error {
fn as_errno(&self) -> Option<i32> { fn as_errno(&self) -> Option<i32> {

133
src/backend/session/direct.rs
View File

@ -1,5 +1,5 @@
//! //!
//! Implementation of the `Session` trait through the legacy vt kernel interface. //! Implementation of the [`Session`](Session) trait through the legacy vt kernel interface.
//! //!
//! This requires write permissions for the given tty device and any devices opened through this //! This requires write permissions for the given tty device and any devices opened through this
//! interface. This means it will almost certainly require root permissions and not allow to run //! interface. This means it will almost certainly require root permissions and not allow to run
@ -26,24 +26,23 @@
//! //!
//! ### Usage of the session //! ### Usage of the session
//! //!
//! The session may be used to open devices manually through the `Session` interface //! The session may be used to open devices manually through the [`Session`] interface
//! or be passed to other objects that need it to open devices themselves. //! or be passed to other objects that need it to open devices themselves.
//! //!
//! Examples for those are e.g. the `LibinputInputBackend` (its context might be initialized through a //! Examples for those are e.g. the [`LibinputInputBackend`](::backend::libinput::LibinputInputBackend)
//! `Session` via the `LibinputSessionInterface`) or the `UdevBackend`. //! (its context might be initialized through a [`Session`] via the [`LibinputSessionInterface`](::backend::libinput::LibinputSessionInterface)).
//! //!
//! In case you want to pass the same `Session` to multiple objects, `Session` is implement for //! In case you want to pass the same [`Session`] to multiple objects, [`Session`] is implement for
//! every `Rc<RefCell<Session>>` or `Arc<Mutex<Session>>`. //! every `Rc<RefCell<Session>>` or `Arc<Mutex<Session>>`.
//! //!
//! ### Usage of the session notifier //! ### Usage of the session notifier
//! //!
//! The notifier might be used to pause device access, when the session gets paused (e.g. by //! The notifier might be used to pause device access, when the session gets paused (e.g. by
//! switching the tty via `DirectSession::change_vt`) and to automatically enable it again, //! switching the tty via [`DirectSession::change_vt`](::backend::session::Session::change_vt))
//! when the session becomes active again. //! and to automatically enable it again, when the session becomes active again.
//! //!
//! It is crucial to avoid errors during that state. Examples for object that might be registered //! It is crucial to avoid errors during that state. Examples for object that might be registered
//! for notifications are the `Libinput` context, the `UdevBackend` or a `DrmDevice` (handled //! for notifications are the [`Libinput`](input::Libinput) context or the [`Device`](::backend::drm::Device).
//! automatically by the `UdevBackend`, if not done manually).
use super::{AsErrno, Session, SessionNotifier, SessionObserver}; use super::{AsErrno, Session, SessionNotifier, SessionObserver};
use nix::{ use nix::{
@ -150,7 +149,7 @@ fn is_tty_device(dev: dev_t, path: Option<&Path>) -> bool {
} }
} }
/// `Session` via the virtual terminal direct kernel interface /// [`Session`] via the virtual terminal direct kernel interface
pub struct DirectSession { pub struct DirectSession {
tty: RawFd, tty: RawFd,
active: Arc<AtomicBool>, active: Arc<AtomicBool>,
@ -159,7 +158,7 @@ pub struct DirectSession {
logger: ::slog::Logger, logger: ::slog::Logger,
} }
/// `SessionNotifier` via the virtual terminal direct kernel interface /// [`SessionNotifier`] via the virtual terminal direct kernel interface
pub struct DirectSessionNotifier { pub struct DirectSessionNotifier {
tty: RawFd, tty: RawFd,
active: Arc<AtomicBool>, active: Arc<AtomicBool>,
@ -253,7 +252,7 @@ impl DirectSession {
// https://github.com/nix-rust/nix/issues/495 // https://github.com/nix-rust/nix/issues/495
/* /*
let signal = if tty::__libc_current_sigrtmin() > tty::__libc_current_sigrtmax() { let signal = if tty::__libc_current_sigrtmin() > tty::__libc_current_sigrtmax() {
warn!(logger, "Not enough real-time signals available, falling back to USR1"); warn!(logger, "Not enough real-time signals available, falling back to USR2");
nix::sys::signal::SIGUSR2 as i32 nix::sys::signal::SIGUSR2 as i32
} else { } else {
tty::__libc_current_sigrtmin() tty::__libc_current_sigrtmin()
@ -345,7 +344,7 @@ impl Drop for DirectSession {
} }
} }
/// Ids of registered `SessionObserver`s of the `DirectSessionNotifier` /// Ids of registered [`SessionObserver`]s of the [`DirectSessionNotifier`]
#[derive(Debug, PartialEq, Eq, Clone, Copy)] #[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub struct Id(usize); pub struct Id(usize);
@ -391,16 +390,16 @@ impl DirectSessionNotifier {
} }
} }
/// Bound logind session that is driven by the `wayland_server::EventLoop`. /// Bound logind session that is driven by the [`EventLoop`](wayland_server::calloop::EventLoop).
/// ///
/// See `direct_session_bind` for details. /// See [`direct_session_bind`] for details.
pub struct BoundDirectSession { pub struct BoundDirectSession {
source: Source<Signals>, source: Source<Signals>,
notifier: Rc<RefCell<DirectSessionNotifier>>, notifier: Rc<RefCell<DirectSessionNotifier>>,
} }
impl BoundDirectSession { impl BoundDirectSession {
/// Unbind the direct session from the `EventLoop` /// Unbind the direct session from the [`EventLoop`](wayland_server::calloop::EventLoop)
pub fn unbind(self) -> DirectSessionNotifier { pub fn unbind(self) -> DirectSessionNotifier {
let BoundDirectSession { source, notifier } = self; let BoundDirectSession { source, notifier } = self;
source.remove(); source.remove();
@ -411,11 +410,11 @@ impl BoundDirectSession {
} }
} }
/// Bind a `DirectSessionNotifier` to an `EventLoop`. /// Bind a [`DirectSessionNotifier`] to an [`EventLoop`](wayland_server::calloop::EventLoop).
/// ///
/// Allows the `DirectSessionNotifier` to listen for incoming signals signalling the session state. /// Allows the [`DirectSessionNotifier`] to listen for incoming signals signalling the session state.
/// If you don't use this function `DirectSessionNotifier` will not correctly tell you the current /// If you don't use this function [`DirectSessionNotifier`] will not correctly tell you the current
/// session state and call it's `SessionObservers`. /// session state and call it's [`SessionObserver`]s.
pub fn direct_session_bind<Data: 'static>( pub fn direct_session_bind<Data: 'static>(
notifier: DirectSessionNotifier, notifier: DirectSessionNotifier,
handle: &LoopHandle<Data>, handle: &LoopHandle<Data>,
@ -442,59 +441,63 @@ pub fn direct_session_bind<Data: 'static>(
Ok(BoundDirectSession { source, notifier }) Ok(BoundDirectSession { source, notifier })
} }
error_chain! { /// Errors related to direct/tty sessions
errors { pub mod errors {
#[doc = "Failed to open tty"] error_chain! {
FailedToOpenTTY(path: String) { errors {
description("Failed to open tty"), #[doc = "Failed to open tty"]
display("Failed to open tty ({:?})", path), FailedToOpenTTY(path: String) {
} description("Failed to open tty"),
display("Failed to open tty ({:?})", path),
}
#[doc = "Not running from a tty"] #[doc = "Not running from a tty"]
NotRunningFromTTY { NotRunningFromTTY {
description("Not running from a tty"), description("Not running from a tty"),
} }
#[doc = "tty is already in KB_GRAPHICS mode"] #[doc = "tty is already in KB_GRAPHICS mode"]
TTYAlreadyInGraphicsMode { TTYAlreadyInGraphicsMode {
description("The tty is already in KB_GRAPHICS mode"), description("The tty is already in KB_GRAPHICS mode"),
display("The tty is already in graphics mode, is already a compositor running?"), display("The tty is already in graphics mode, is already a compositor running?"),
} }
#[doc = "Failed to activate open tty"] #[doc = "Failed to activate open tty"]
FailedToActivateTTY(num: i32) { FailedToActivateTTY(num: i32) {
description("Failed to activate open tty"), description("Failed to activate open tty"),
display("Failed to activate open tty ({:?})", num), display("Failed to activate open tty ({:?})", num),
} }
#[doc = "Failed to wait for tty to become active"] #[doc = "Failed to wait for tty to become active"]
FailedToWaitForTTY(num: i32) { FailedToWaitForTTY(num: i32) {
description("Failed to wait for tty to become active"), description("Failed to wait for tty to become active"),
display("Failed to wait for tty ({:?}) to become active", num), display("Failed to wait for tty ({:?}) to become active", num),
} }
#[doc = "Failed to save old tty state"] #[doc = "Failed to save old tty state"]
FailedToSaveTTYState(num: i32) { FailedToSaveTTYState(num: i32) {
description("Failed to save old tty state"), description("Failed to save old tty state"),
display("Failed to save old tty ({:?}) state", num), display("Failed to save old tty ({:?}) state", num),
} }
#[doc = "Failed to set tty kb mode"] #[doc = "Failed to set tty kb mode"]
FailedToSetTTYKbMode(num: i32) { FailedToSetTTYKbMode(num: i32) {
description("Failed to set tty kb mode to K_OFF"), description("Failed to set tty kb mode to K_OFF"),
display("Failed to set tty ({:?}) kb mode to K_OFF", num), display("Failed to set tty ({:?}) kb mode to K_OFF", num),
} }
#[doc = "Failed to set tty mode"] #[doc = "Failed to set tty mode"]
FailedToSetTTYMode(num: i32) { FailedToSetTTYMode(num: i32) {
description("Failed to set tty mode to KD_GRAPHICS"), description("Failed to set tty mode to KD_GRAPHICS"),
display("Failed to set tty ({:?}) mode into graphics mode", num), display("Failed to set tty ({:?}) mode into graphics mode", num),
} }
#[doc = "Failed to set tty in process mode"] #[doc = "Failed to set tty in process mode"]
FailedToTakeControlOfTTY(num: i32) { FailedToTakeControlOfTTY(num: i32) {
description("Failed to set tty mode to VT_PROCESS"), description("Failed to set tty mode to VT_PROCESS"),
display("Failed to take control of tty ({:?})", num), display("Failed to take control of tty ({:?})", num),
}
} }
} }
} }
use self::errors::*;

15
src/backend/session/mod.rs
View File

@ -45,25 +45,26 @@ pub trait Session {
/// Interface for registering for notifications for a given session. /// Interface for registering for notifications for a given session.
/// ///
/// Part of the session API which allows to get notified, when the given session /// Part of the session API which allows to get notified, when the given session
/// gets paused or becomes active again. Any object implementing the `SessionObserver` trait /// gets paused or becomes active again. Any object implementing the [`SessionObserver`]
/// may be registered. /// trait may be registered.
pub trait SessionNotifier { pub trait SessionNotifier {
/// Id type of registered observers /// Id type of registered observers
type Id: PartialEq + Eq; type Id: PartialEq + Eq;
/// Registers a given `SessionObserver`. /// Registers a given [`SessionObserver`].
/// ///
/// Returns an id of the inserted observer, can be used to remove it again. /// Returns an id of the inserted observer, can be used to remove it again.
fn register<S: SessionObserver + 'static>(&mut self, signal: S) -> Self::Id; fn register<S: SessionObserver + 'static>(&mut self, signal: S) -> Self::Id;
/// Removes an observer by its given id from `SessionNotifier::register`. /// Removes an observer by its given id from [`SessionNotifier::register`].
fn unregister(&mut self, signal: Self::Id); fn unregister(&mut self, signal: Self::Id);
} }
/// Trait describing the ability to return a `SessionObserver` related to Self. /// Trait describing the ability to return a [`SessionObserver`] related to Self.
/// ///
/// The returned `SessionObserver` is responsible to handle the `pause` and `activate` signals. /// The returned [`SessionObserver`] is responsible to handle the [`pause`](SessionObserver::pause)
/// and [`activate`](SessionObserver::activate) signals.
pub trait AsSessionObserver<S: SessionObserver + 'static> { pub trait AsSessionObserver<S: SessionObserver + 'static> {
/// Create a `SessionObserver` linked to this object /// Create a [`SessionObserver`] linked to this object
fn observer(&mut self) -> S; fn observer(&mut self) -> S;
} }

6
src/backend/session/multi.rs
View File

@ -11,7 +11,7 @@ use super::{SessionNotifier, SessionObserver};
static ID_COUNTER: AtomicUsize = AtomicUsize::new(0); static ID_COUNTER: AtomicUsize = AtomicUsize::new(0);
/// Ids of registered `SessionObserver`s of the `DirectSessionNotifier` /// Ids of registered [`SessionObserver`](SessionObserver)s
#[derive(Debug, PartialEq, Eq, Clone, Copy, Hash)] #[derive(Debug, PartialEq, Eq, Clone, Copy, Hash)]
pub struct Id(usize); pub struct Id(usize);
@ -52,8 +52,8 @@ impl SessionNotifier for MultiNotifier {
} }
} }
/// Create a pair of a linked [`SessionObserver`](../trait.SessionObserver.html) and a /// Create a pair of a linked [`SessionObserver`] and a
/// [`SessionNotifier`](../trait.SessionNotifier.html). /// [`SessionNotifier`](SessionNotifier).
/// ///
/// Observers added to the returned notifier are notified, /// Observers added to the returned notifier are notified,
/// when the returned observer is notified. /// when the returned observer is notified.

24
src/backend/udev.rs
View File

@ -1,12 +1,12 @@
//! //!
//! Provides `udev` related functionality for automated device scanning. //! Provides `udev` related functionality for automated device scanning.
//! //!
//! This module mainly provides the `UdevBackend`, which constantly monitors available DRM devices //! This module mainly provides the [`UdevBackend`](::backend::udev::UdevBackend), which constantly monitors available DRM devices
//! and notifies a user supplied `UdevHandler` of any changes. //! and notifies a user supplied [`UdevHandler`](::backend::udev::UdevHandler) of any changes.
//! //!
//! Additionally this contains some utility functions related to scanning. //! Additionally this contains some utility functions related to scanning.
//! //!
//! See also `examples/udev.rs` for pure hardware backed example of a compositor utilizing this //! See also `anvil/src/udev.rs` for pure hardware backed example of a compositor utilizing this
//! backend. //! backend.
use nix::sys::stat::{dev_t, stat}; use nix::sys::stat::{dev_t, stat};
@ -43,7 +43,7 @@ impl<T: UdevHandler + 'static> AsRawFd for UdevBackend<T> {
} }
impl<T: UdevHandler + 'static> UdevBackend<T> { impl<T: UdevHandler + 'static> UdevBackend<T> {
/// Creates a new `UdevBackend` and adds it to the given `EventLoop`'s state. /// Creates a new [`UdevBackend`]
/// ///
/// ## Arguments /// ## Arguments
/// `context` - An initialized udev context /// `context` - An initialized udev context
@ -97,9 +97,9 @@ impl<T: UdevHandler + 'static> Drop for UdevBackend<T> {
} }
} }
/// Binds a `UdevBackend` to a given `EventLoop`. /// Binds a [`UdevBackend`] to a given [`EventLoop`](wayland_server::calloop::EventLoop).
/// ///
/// Allows the backend to receive kernel events and thus to drive the `UdevHandler`. /// Allows the backend to receive kernel events and thus to drive the [`UdevHandler`].
/// No runtime functionality can be provided without using this function. /// No runtime functionality can be provided without using this function.
pub fn udev_backend_bind<T: UdevHandler + 'static, Data: 'static>( pub fn udev_backend_bind<T: UdevHandler + 'static, Data: 'static>(
udev: UdevBackend<T>, udev: UdevBackend<T>,
@ -156,7 +156,7 @@ impl<T: UdevHandler + 'static> UdevBackend<T> {
} }
} }
/// Handler for the `UdevBackend`, allows to open, close and update drm devices as they change during runtime. /// Handler for the [`UdevBackend`], allows to open, close and update drm devices as they change during runtime.
pub trait UdevHandler { pub trait UdevHandler {
/// Called when a new device is detected. /// Called when a new device is detected.
fn device_added(&mut self, device: dev_t, path: PathBuf); fn device_added(&mut self, device: dev_t, path: PathBuf);
@ -166,16 +166,13 @@ pub trait UdevHandler {
/// should scan again for connected monitors and mode switch accordingly. /// should scan again for connected monitors and mode switch accordingly.
fn device_changed(&mut self, device: dev_t); fn device_changed(&mut self, device: dev_t);
/// Called when a device was removed. /// Called when a device was removed.
///
/// The corresponding `UdevRawFd` will never return a valid `RawFd` anymore
/// and its file descriptor will be closed once this function returns,
/// any open references/tokens to this device need to be released.
fn device_removed(&mut self, device: dev_t); fn device_removed(&mut self, device: dev_t);
} }
/// Returns the path of the primary GPU device if any /// Returns the path of the primary GPU device if any
/// ///
/// Might be used for filtering in `UdevHandler::device_added` or for manual `DrmDevice` initialization /// Might be used for filtering in [`UdevHandler::device_added`] or for manual
/// [`LegacyDrmDevice`](::backend::drm::legacy::LegacyDrmDevice) initialization.
pub fn primary_gpu<S: AsRef<str>>(context: &Context, seat: S) -> UdevResult<Option<PathBuf>> { pub fn primary_gpu<S: AsRef<str>>(context: &Context, seat: S) -> UdevResult<Option<PathBuf>> {
let mut enumerator = Enumerator::new(context)?; let mut enumerator = Enumerator::new(context)?;
enumerator.match_subsystem("drm")?; enumerator.match_subsystem("drm")?;
@ -205,7 +202,8 @@ pub fn primary_gpu<S: AsRef<str>>(context: &Context, seat: S) -> UdevResult<Opti
/// Returns the paths of all available GPU devices /// Returns the paths of all available GPU devices
/// ///
/// Might be used for manual `DrmDevice` initialization /// Might be used for manual [`LegacyDrmDevice`](::backend::drm::legacy::LegacyDrmDevice)
/// initialization.
pub fn all_gpus<S: AsRef<str>>(context: &Context, seat: S) -> UdevResult<Vec<PathBuf>> { pub fn all_gpus<S: AsRef<str>>(context: &Context, seat: S) -> UdevResult<Vec<PathBuf>> {
let mut enumerator = Enumerator::new(context)?; let mut enumerator = Enumerator::new(context)?;
enumerator.match_subsystem("drm")?; enumerator.match_subsystem("drm")?;

101
src/backend/winit.rs
View File

@ -2,8 +2,8 @@
use backend::{ use backend::{
egl::{ egl::{
context::GlAttributes, error as egl_error, error::Result as EGLResult, native, EGLContext, context::GlAttributes, error::Result as EGLResult, native, EGLContext, EGLDisplay,
EGLDisplay, EGLGraphicsBackend, EGLSurface, EGLGraphicsBackend, EGLSurface,
}, },
graphics::{gl::GLGraphicsBackend, CursorBackend, PixelFormat, SwapBuffersError}, graphics::{gl::GLGraphicsBackend, CursorBackend, PixelFormat, SwapBuffersError},
input::{ input::{
@ -16,7 +16,7 @@ use backend::{
use nix::libc::c_void; use nix::libc::c_void;
use std::{ use std::{
cell::{Ref, RefCell}, cell::{Ref, RefCell},
cmp, error, fmt, cmp, fmt,
rc::Rc, rc::Rc,
time::Instant, time::Instant,
}; };
@ -28,23 +28,29 @@ use winit::{
MouseScrollDelta, Touch, TouchPhase, Window as WinitWindow, WindowBuilder, WindowEvent, MouseScrollDelta, Touch, TouchPhase, Window as WinitWindow, WindowBuilder, WindowEvent,
}; };
error_chain! { /// Errors thrown by the `winit` backends
errors { pub mod errors {
#[doc = "Failed to initialize a window"] use backend::egl::error as egl_error;
InitFailed {
description("Failed to initialize a window") error_chain! {
errors {
#[doc = "Failed to initialize a window"]
InitFailed {
description("Failed to initialize a window")
}
#[doc = "Context creation is not supported on the current window system"]
NotSupported {
description("Context creation is not supported on the current window system.")
}
} }
#[doc = "Context creation is not supported on the current window system"] links {
NotSupported { EGL(egl_error::Error, egl_error::ErrorKind) #[doc = "EGL error"];
description("Context creation is not supported on the current window system.")
} }
} }
links {
EGL(egl_error::Error, egl_error::ErrorKind) #[doc = "EGL error"];
}
} }
use self::errors::*;
enum Window { enum Window {
Wayland { Wayland {
@ -72,16 +78,17 @@ struct WindowSize {
} }
/// Window with an active EGL Context created by `winit`. Implements the /// Window with an active EGL Context created by `winit`. Implements the
/// `EGLGraphicsBackend` graphics backend trait /// [`EGLGraphicsBackend`] and [`GLGraphicsBackend`] graphics backend trait
pub struct WinitGraphicsBackend { pub struct WinitGraphicsBackend {
window: Rc<Window>, window: Rc<Window>,
size: Rc<RefCell<WindowSize>>, size: Rc<RefCell<WindowSize>>,
logger: ::slog::Logger, logger: ::slog::Logger,
} }
/// Abstracted event loop of a `winit` `Window` implementing the `InputBackend` trait /// Abstracted event loop of a [`WinitWindow`] implementing the [`InputBackend`] trait
/// ///
/// You need to call `dispatch_new_events` periodically to receive any events. /// You need to call [`dispatch_new_events`](InputBackend::dispatch_new_events)
/// periodically to receive any events.
pub struct WinitInputBackend { pub struct WinitInputBackend {
events_loop: EventsLoop, events_loop: EventsLoop,
events_handler: Option<Box<WinitEventsHandler>>, events_handler: Option<Box<WinitEventsHandler>>,
@ -95,9 +102,9 @@ pub struct WinitInputBackend {
size: Rc<RefCell<WindowSize>>, size: Rc<RefCell<WindowSize>>,
} }
/// Create a new `WinitGraphicsBackend`, which implements the `EGLGraphicsBackend` /// Create a new [`WinitGraphicsBackend`], which implements the [`EGLGraphicsBackend`]
/// graphics backend trait and a corresponding `WinitInputBackend`, which implements /// and [`GLGraphicsBackend`] graphics backend trait and a corresponding [`WinitInputBackend`],
/// the `InputBackend` trait /// which implements the [`InputBackend`] trait
pub fn init<L>(logger: L) -> Result<(WinitGraphicsBackend, WinitInputBackend)> pub fn init<L>(logger: L) -> Result<(WinitGraphicsBackend, WinitInputBackend)>
where where
L: Into<Option<::slog::Logger>>, L: Into<Option<::slog::Logger>>,
@ -111,9 +118,9 @@ where
) )
} }
/// Create a new `WinitGraphicsBackend`, which implements the `EGLGraphicsBackend` /// Create a new [`WinitGraphicsBackend`], which implements the [`EGLGraphicsBackend`]
/// graphics backend trait, from a given `WindowBuilder` struct and a corresponding /// and [`GLGraphicsBackend`] graphics backend trait, from a given [`WindowBuilder`]
/// `WinitInputBackend`, which implements the `InputBackend` trait /// struct and a corresponding [`WinitInputBackend`], which implements the [`InputBackend`] trait
pub fn init_from_builder<L>( pub fn init_from_builder<L>(
builder: WindowBuilder, builder: WindowBuilder,
logger: L, logger: L,
@ -133,10 +140,10 @@ where
) )
} }
/// Create a new `WinitGraphicsBackend`, which implements the `EGLGraphicsBackend` /// Create a new [`WinitGraphicsBackend`], which implements the [`EGLGraphicsBackend`]
/// graphics backend trait, from a given `WindowBuilder` struct, as well as given /// and [`GLGraphicsBackend`] graphics backend trait, from a given [`WindowBuilder`]
/// `GlAttributes` for further customization of the rendering pipeline and a /// struct, as well as given [`GlAttributes`] for further customization of the rendering pipeline and a
/// corresponding `WinitInputBackend`, which implements the `InputBackend` trait. /// corresponding [`WinitInputBackend`], which implements the [`InputBackend`] trait.
pub fn init_from_builder_with_gl_attr<L>( pub fn init_from_builder_with_gl_attr<L>(
builder: WindowBuilder, builder: WindowBuilder,
attributes: GlAttributes, attributes: GlAttributes,
@ -208,7 +215,7 @@ where
/// Handler trait to receive window-related events to provide a better *nested* experience. /// Handler trait to receive window-related events to provide a better *nested* experience.
pub trait WinitEventsHandler { pub trait WinitEventsHandler {
/// The window was resized, can be used to adjust the associated `wayland::output::Output`s mode. /// The window was resized, can be used to adjust the associated [`Output`](::wayland::output::Output)s mode.
/// ///
/// Here are provided the new size (in physical pixels) and the new scale factor provided by `winit`. /// Here are provided the new size (in physical pixels) and the new scale factor provided by `winit`.
fn resized(&mut self, size: (f64, f64), scale: f64); fn resized(&mut self, size: (f64, f64), scale: f64);
@ -219,7 +226,7 @@ pub trait WinitEventsHandler {
} }
impl WinitGraphicsBackend { impl WinitGraphicsBackend {
/// Get a reference to the internally used `winit::Window` /// Get a reference to the internally used [`WinitWindow`]
pub fn winit_window(&self) -> Ref<WinitWindow> { pub fn winit_window(&self) -> Ref<WinitWindow> {
self.window.window() self.window.window()
} }
@ -314,16 +321,16 @@ impl EGLGraphicsBackend for WinitGraphicsBackend {
} }
} }
/// Errors that may happen when driving the event loop of `WinitInputBackend` /// Errors that may happen when driving the event loop of [`WinitInputBackend`]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum WinitInputError { pub enum WinitInputError {
/// The underlying `winit` `Window` was closed. No further events can be processed. /// The underlying [`WinitWindow`] was closed. No further events can be processed.
/// ///
/// See `WinitInputBackend::dispatch_new_events`. /// See `dispatch_new_events`.
WindowClosed, WindowClosed,
} }
impl error::Error for WinitInputError { impl ::std::error::Error for WinitInputError {
fn description(&self) -> &str { fn description(&self) -> &str {
match *self { match *self {
WinitInputError::WindowClosed => "Glutin Window was closed", WinitInputError::WindowClosed => "Glutin Window was closed",
@ -338,7 +345,7 @@ impl fmt::Display for WinitInputError {
} }
} }
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
/// Winit-Backend internal event wrapping `winit`'s types into a `KeyboardKeyEvent` /// Winit-Backend internal event wrapping `winit`'s types into a [`KeyboardKeyEvent`]
pub struct WinitKeyboardInputEvent { pub struct WinitKeyboardInputEvent {
time: u32, time: u32,
key: u32, key: u32,
@ -367,7 +374,7 @@ impl KeyboardKeyEvent for WinitKeyboardInputEvent {
} }
#[derive(Clone)] #[derive(Clone)]
/// Winit-Backend internal event wrapping `winit`'s types into a `PointerMotionAbsoluteEvent` /// Winit-Backend internal event wrapping `winit`'s types into a [`PointerMotionAbsoluteEvent`]
pub struct WinitMouseMovedEvent { pub struct WinitMouseMovedEvent {
size: Rc<RefCell<WindowSize>>, size: Rc<RefCell<WindowSize>>,
time: u32, time: u32,
@ -404,7 +411,7 @@ impl PointerMotionAbsoluteEvent for WinitMouseMovedEvent {
} }
#[derive(Debug, Clone, Copy, PartialEq)] #[derive(Debug, Clone, Copy, PartialEq)]
/// Winit-Backend internal event wrapping `winit`'s types into a `PointerAxisEvent` /// Winit-Backend internal event wrapping `winit`'s types into a [`PointerAxisEvent`]
pub struct WinitMouseWheelEvent { pub struct WinitMouseWheelEvent {
time: u32, time: u32,
delta: MouseScrollDelta, delta: MouseScrollDelta,
@ -442,7 +449,7 @@ impl PointerAxisEvent for WinitMouseWheelEvent {
} }
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
/// Winit-Backend internal event wrapping `winit`'s types into a `PointerButtonEvent` /// Winit-Backend internal event wrapping `winit`'s types into a [`PointerButtonEvent`]
pub struct WinitMouseInputEvent { pub struct WinitMouseInputEvent {
time: u32, time: u32,
button: WinitMouseButton, button: WinitMouseButton,
@ -466,7 +473,7 @@ impl PointerButtonEvent for WinitMouseInputEvent {
} }
#[derive(Clone)] #[derive(Clone)]
/// Winit-Backend internal event wrapping `winit`'s types into a `TouchDownEvent` /// Winit-Backend internal event wrapping `winit`'s types into a [`TouchDownEvent`]
pub struct WinitTouchStartedEvent { pub struct WinitTouchStartedEvent {
size: Rc<RefCell<WindowSize>>, size: Rc<RefCell<WindowSize>>,
time: u32, time: u32,
@ -513,7 +520,7 @@ impl TouchDownEvent for WinitTouchStartedEvent {
} }
#[derive(Clone)] #[derive(Clone)]
/// Winit-Backend internal event wrapping `winit`'s types into a `TouchMotionEvent` /// Winit-Backend internal event wrapping `winit`'s types into a [`TouchMotionEvent`]
pub struct WinitTouchMovedEvent { pub struct WinitTouchMovedEvent {
size: Rc<RefCell<WindowSize>>, size: Rc<RefCell<WindowSize>>,
time: u32, time: u32,
@ -573,7 +580,7 @@ impl TouchUpEvent for WinitTouchEndedEvent {
} }
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
/// Winit-Backend internal event wrapping `winit`'s types into a `TouchCancelEvent` /// Winit-Backend internal event wrapping `winit`'s types into a [`TouchCancelEvent`]
pub struct WinitTouchCancelledEvent { pub struct WinitTouchCancelledEvent {
time: u32, time: u32,
id: u64, id: u64,
@ -655,17 +662,17 @@ impl InputBackend for WinitInputBackend {
&mut self.input_config &mut self.input_config
} }
/// Processes new events of the underlying event loop to drive the set `InputHandler`. /// Processes new events of the underlying event loop to drive the set [`InputHandler`].
/// ///
/// You need to periodically call this function to keep the underlying event loop and /// You need to periodically call this function to keep the underlying event loop and
/// `Window` active. Otherwise the window may no respond to user interaction and no /// [`WinitWindow`] active. Otherwise the window may no respond to user interaction and no
/// input events will be received by a set `InputHandler`. /// input events will be received by a set [`InputHandler`].
/// ///
/// Returns an error if the `Window` the window has been closed. Calling /// Returns an error if the [`WinitWindow`] the window has been closed. Calling
/// `dispatch_new_events` again after the `Window` has been closed is considered an /// `dispatch_new_events` again after the [`WinitWindow`] has been closed is considered an
/// application error and unspecified behaviour may occur. /// application error and unspecified behaviour may occur.
/// ///
/// The linked `WinitGraphicsBackend` will error with a lost `Context` and should /// The linked [`WinitGraphicsBackend`] will error with a lost context and should
/// not be used anymore as well. /// not be used anymore as well.
fn dispatch_new_events(&mut self) -> ::std::result::Result<(), WinitInputError> { fn dispatch_new_events(&mut self) -> ::std::result::Result<(), WinitInputError> {
let mut closed = false; let mut closed = false;

2
src/lib.rs
View File

@ -1,7 +1,7 @@
#![warn(missing_docs)] #![warn(missing_docs)]
//! **Smithay: the Wayland compositor smithy** //! **Smithay: the Wayland compositor smithy**
//! //!
//! Most entry points in the modules can take an optional `slog::Logger` as argument //! Most entry points in the modules can take an optional [`slog::Logger`](::slog::Logger) as argument
//! that will be used as a drain for logging. If `None` is provided, they'll log to `slog-stdlog`. //! that will be used as a drain for logging. If `None` is provided, they'll log to `slog-stdlog`.
// `error_chain!` can recurse deeply // `error_chain!` can recurse deeply

46
src/wayland/compositor/mod.rs
View File

@ -2,7 +2,8 @@
//! //!
//! This module provides automatic handling of surfaces, subsurfaces //! This module provides automatic handling of surfaces, subsurfaces
//! and region Wayland objects, by registering an implementation for //! and region Wayland objects, by registering an implementation for
//! for the `wl_compositor` and `wl_subcompositor` globals. //! for the [`wl_compositor`](wayland_server::protocol::wl_compositor)
//! and [`wl_subcompositor`](wayland_server::protocol::wl_subcompositor) globals.
//! //!
//! ## Why use this implementation //! ## Why use this implementation
//! //!
@ -22,8 +23,8 @@
//! //!
//! ### Initialization //! ### Initialization
//! //!
//! To initialize this implementation, use the `compositor_init` method provided //! To initialize this implementation, use the [`compositor_init`](::wayland::compositor::compositor_init)
//! by this module. It'll require you to first define as few things, as shown in //! method provided by this module. It'll require you to first define as few things, as shown in
//! this example: //! this example:
//! //!
//! ``` //! ```
@ -66,15 +67,17 @@
//! //!
//! As you can see in the previous example, in the end we are retrieving a token from //! As you can see in the previous example, in the end we are retrieving a token from
//! the `init` function. This token is necessary to retrieve the metadata associated with //! the `init` function. This token is necessary to retrieve the metadata associated with
//! a surface. It can be cloned. See `CompositorToken` for the details of what it enables you. //! a surface. It can be cloned. See [`CompositorToken`](::wayland::compositor::CompositorToken)
//! for the details of what it enables you.
//! //!
//! The surface metadata is held in the `SurfaceAttributes` struct. In contains double-buffered //! The surface metadata is held in the [`SurfaceAttributes`](::wayland::compositor::SurfaceAttributes)
//! state pending from the client as defined by the protocol for `wl_surface`, as well as your //! struct. In contains double-buffered state pending from the client as defined by the protocol for
//! user-defined type holding any data you need to have associated with a struct. See its //! [`wl_surface`](wayland_server::protocol::wl_surface), as well as your user-defined type holding
//! documentation for details. //! any data you need to have associated with a struct. See its documentation for details.
//! //!
//! This `CompositorToken` also provides access to the metadata associated with the role of the //! This [`CompositorToken`](::wayland::compositor::CompositorToken) also provides access to the metadata associated with the role of the
//! surfaces. See the documentation of the `roles` submodule for a detailed explanation. //! surfaces. See the documentation of the [`roles`](::wayland::compositor::roles) submodule
//! for a detailed explanation.
use std::{cell::RefCell, rc::Rc, sync::Mutex}; use std::{cell::RefCell, rc::Rc, sync::Mutex};
@ -117,7 +120,8 @@ struct Marker<U, R> {
/// Data associated with a surface, aggregated by the handlers /// Data associated with a surface, aggregated by the handlers
/// ///
/// Most of the fields of this struct represent a double-buffered state, which /// Most of the fields of this struct represent a double-buffered state, which
/// should only be applied once a `commit` request is received from the surface. /// should only be applied once a [`commit`](::wayland::compositor::SurfaceEvent::Commit)
/// request is received from the surface.
/// ///
/// You are responsible for setting those values as you see fit to avoid /// You are responsible for setting those values as you see fit to avoid
/// processing them two times. /// processing them two times.
@ -232,7 +236,8 @@ impl Default for RegionAttributes {
/// A Compositor global token /// A Compositor global token
/// ///
/// This token can be cloned at will, and is the entry-point to /// This token can be cloned at will, and is the entry-point to
/// access data associated with the `wl_surface` and `wl_region` managed /// access data associated with the [`wl_surface`](wayland_server::protocol::wl_surface)
/// and [`wl_region`](wayland_server::protocol::wl_region) managed
/// by the `CompositorGlobal` that provided it. /// by the `CompositorGlobal` that provided it.
pub struct CompositorToken<U, R> { pub struct CompositorToken<U, R> {
_data: ::std::marker::PhantomData<*mut U>, _data: ::std::marker::PhantomData<*mut U>,
@ -292,7 +297,7 @@ where
/// - a mutable reference to its surface attribute data /// - a mutable reference to its surface attribute data
/// - a mutable reference to its role data, /// - a mutable reference to its role data,
/// - a custom value that is passed in a fold-like manner, but only from the output of a parent /// - a custom value that is passed in a fold-like manner, but only from the output of a parent
/// to its children. See `TraversalAction` for details. /// to its children. See [`TraversalAction`] for details.
/// ///
/// If the surface not managed by the `CompositorGlobal` that provided this token, this /// If the surface not managed by the `CompositorGlobal` that provided this token, this
/// will panic (having more than one compositor is not supported). /// will panic (having more than one compositor is not supported).
@ -315,7 +320,7 @@ where
/// in a depth-first order. This matches the reverse of the order in which the surfaces are /// in a depth-first order. This matches the reverse of the order in which the surfaces are
/// supposed to be drawn: top-most first. /// supposed to be drawn: top-most first.
/// ///
/// Behavior is the same as `with_surface_tree_upward`. /// Behavior is the same as [`with_surface_tree_upward`](CompositorToken::with_surface_tree_upward).
pub fn with_surface_tree_downward<F, T>( pub fn with_surface_tree_downward<F, T>(
&self, &self,
surface: &Resource<WlSurface>, surface: &Resource<WlSurface>,
@ -438,11 +443,12 @@ impl<U: 'static, R: RoleType + 'static> CompositorToken<U, R> {
} }
} }
/// Create new `wl_compositor` and `wl_subcompositor` globals. /// Create new [`wl_compositor`](wayland_server::protocol::wl_compositor)
/// and [`wl_subcompositor`](wayland_server::protocol::wl_subcompositor) globals.
/// ///
/// The globals are directly registered into the event loop, and this function /// The globals are directly registered into the event loop, and this function
/// returns a `CompositorToken` which you'll need access the data associated to /// returns a [`CompositorToken`] which you'll need access the data associated to
/// the `wl_surface`s. /// the [`wl_surface`](wayland_server::protocol::wl_surface)s.
/// ///
/// It also returns the two global handles, in case you wish to remove these /// It also returns the two global handles, in case you wish to remove these
/// globals from the event loop in the future. /// globals from the event loop in the future.
@ -491,7 +497,7 @@ where
pub enum SurfaceEvent { pub enum SurfaceEvent {
/// The double-buffered state has been validated by the client /// The double-buffered state has been validated by the client
/// ///
/// At this point, the pending state that has been accumulated in the `SurfaceAttributes` associated /// At this point, the pending state that has been accumulated in the [`SurfaceAttributes`] associated
/// to this surface should be integrated into the current state of the surface. /// to this surface should be integrated into the current state of the surface.
/// ///
/// See [`wayland_server::protocol::wl_surface::Implementation::commit`](https://docs.rs/wayland-server/0.10.1/wayland_server/protocol/wl_surface/struct.Implementation.html#structfield.commit) /// See [`wayland_server::protocol::wl_surface::Implementation::commit`](https://docs.rs/wayland-server/0.10.1/wayland_server/protocol/wl_surface/struct.Implementation.html#structfield.commit)
@ -499,8 +505,8 @@ pub enum SurfaceEvent {
Commit, Commit,
/// The client asks to be notified when would be a good time to update the contents of this surface /// The client asks to be notified when would be a good time to update the contents of this surface
/// ///
/// You must keep the provided `WlCallback` and trigger it at the appropriate time by calling /// You must keep the provided [`WlCallback`](wayland_server::protocol::wl_callback::WlCallback)
/// its `done()` method. /// and trigger it at the appropriate time by calling its `done()` method.
/// ///
/// See [`wayland_server::protocol::wl_surface::Implementation::frame`](https://docs.rs/wayland-server/0.10.1/wayland_server/protocol/wl_surface/struct.Implementation.html#structfield.frame) /// See [`wayland_server::protocol::wl_surface::Implementation::frame`](https://docs.rs/wayland-server/0.10.1/wayland_server/protocol/wl_surface/struct.Implementation.html#structfield.frame)
/// for more details /// for more details

19
src/wayland/compositor/roles.rs
View File

@ -76,12 +76,14 @@
//! as well as implement a few trait for it, allowing it to be used by //! as well as implement a few trait for it, allowing it to be used by
//! all smithay handlers: //! all smithay handlers:
//! //!
//! - The trait `RoleType`, which defines it as a type handling roles //! - The trait [`RoleType`](::wayland::compositor::roles::RoleType),
//! - For each of your roles, the trait `Role<Token>` (where `Token` is your //! which defines it as a type handling roles
//! token type), marking its ability to handle this given role. //! - For each of your roles, the trait [`Role<Token>`](::wayland::compositor::roles::Role)
//! (where `Token` is your token type), marking its ability to handle this given role.
//! //!
//! All handlers that handle a specific role will require you to provide //! All handlers that handle a specific role will require you to provide
//! them with a `CompositorToken<U, R, H>` where `R: Role<TheToken>`. //! them with a [`CompositorToken<U, R, H>`](::wayland::compositor::CompositorToken)
//! where `R: Role<TheToken>`.
//! //!
//! See the documentation of these traits for their specific definition and //! See the documentation of these traits for their specific definition and
//! capabilities. //! capabilities.
@ -98,13 +100,13 @@ pub trait RoleType {
/// Check if the associated surface has a role /// Check if the associated surface has a role
/// ///
/// Only reports if the surface has any role or no role. /// Only reports if the surface has any role or no role.
/// To check for a role in particular, see `Role::has`. /// To check for a role in particular, see [`Role::has`].
fn has_role(&self) -> bool; fn has_role(&self) -> bool;
} }
/// A trait representing the capability of a `RoleType` to handle a given role /// A trait representing the capability of a [`RoleType`] to handle a given role
/// ///
/// This trait allows to interact with the different roles a `RoleType` can /// This trait allows to interact with the different roles a [`RoleType`] can
/// handle. /// handle.
/// ///
/// This trait is meant to be used generically, for example, to retrieve the /// This trait is meant to be used generically, for example, to retrieve the
@ -115,7 +117,8 @@ pub trait RoleType {
/// .expect("The surface does not have this role."); /// .expect("The surface does not have this role.");
/// ``` /// ```
/// ///
/// The methods of this trait are mirrored on `CompositorToken` for easy /// The methods of this trait are mirrored on
/// [`CompositorToken`](::wayland::compositor::CompositorToken) for easy
/// access to the role data of the surfaces. /// access to the role data of the surfaces.
/// ///
/// Note that if a role is automatically handled for you by a Handler provided /// Note that if a role is automatically handled for you by a Handler provided

30
src/wayland/data_device/mod.rs
View File

@ -6,11 +6,11 @@
//! //!
//! This module provides 2 main freestanding functions: //! This module provides 2 main freestanding functions:
//! //!
//! - `init_data_device`: this function must be called during the compositor startup to initialize //! - [`init_data_device`](::wayland::data_device::init_data_device): this function must be called
//! the data device logic //! during the compositor startup to initialize the data device logic
//! - `set_data_device_focus`: this function sets the data device focus for a given seat; you'd //! - [`set_data_device_focus`](::wayland::data_device::set_data_device_focus): this function sets
//! typically call it whenever the keyboard focus changes, to follow it (for example in the focus //! the data device focus for a given seat; you'd typically call it whenever the keyboard focus
//! hook of your keyboards) //! changes, to follow it (for example in the focus hook of your keyboards)
//! //!
//! Using these two functions is enough for your clients to be able to interact with each other using //! Using these two functions is enough for your clients to be able to interact with each other using
//! the data devices. //! the data devices.
@ -18,10 +18,11 @@
//! The module also provides additionnal mechanisms allowing your compositor to see and interact with //! The module also provides additionnal mechanisms allowing your compositor to see and interact with
//! the contents of the data device: //! the contents of the data device:
//! //!
//! - You can provide a callback closure to `init_data_device` to peek into the the actions of your clients //! - You can provide a callback closure to [`init_data_device`](::wayland::data_device::init_data_device)
//! - the freestanding function `set_data_device_selection` allows you to set the contents of the selection //! to peek into the the actions of your clients
//! for your clients //! - the freestanding function [`set_data_device_selection`](::wayland::data_device::set_data_device_selection)
//! - the freestanding function `start_dnd` allows you to initiate a drag'n'drop event from the compositor //! allows you to set the contents of the selection for your clients
//! - the freestanding function [`start_dnd`](::wayland::data_device::start_dnd) allows you to initiate a drag'n'drop event from the compositor
//! itself and receive interactions of clients with it via an other dedicated callback. //! itself and receive interactions of clients with it via an other dedicated callback.
//! //!
//! The module also defines the `DnDIconRole` that you need to insert into your compositor roles enum, to //! The module also defines the `DnDIconRole` that you need to insert into your compositor roles enum, to
@ -269,15 +270,16 @@ impl SeatData {
/// ///
/// You can provide a callback to peek into the actions of your clients over the data devices /// You can provide a callback to peek into the actions of your clients over the data devices
/// (allowing you to retrieve the current selection buffer, or intercept DnD data). See the /// (allowing you to retrieve the current selection buffer, or intercept DnD data). See the
/// `DataDeviceEvent` type for details about what notifications you can receive. Note that this /// [`DataDeviceEvent`] type for details about what notifications you can receive. Note that this
/// closure will not receive notifications about dnd actions the compositor initiated, see /// closure will not receive notifications about dnd actions the compositor initiated, see
/// `start_dnd` for details about that. /// [`start_dnd`] for details about that.
/// ///
/// You also need to provide a `(DndAction, DndAction) -> DndAction` closure that will arbitrate /// You also need to provide a `(DndAction, DndAction) -> DndAction` closure that will arbitrate
/// the choice of action resulting from a drag'n'drop session. Its first argument is the set of /// the choice of action resulting from a drag'n'drop session. Its first argument is the set of
/// available actions (which is the intersection of the actions supported by the source and targets) /// available actions (which is the intersection of the actions supported by the source and targets)
/// and the second argument is the preferred action reported by the target. If no action should be /// and the second argument is the preferred action reported by the target. If no action should be
/// chosen (and thus the drag'n'drop should abort on drop), return `DndAction::empty()`. /// chosen (and thus the drag'n'drop should abort on drop), return
/// [`DndAction::empty()`](wayland_server::protocol::wl_data_device_manager::DndAction::empty).
pub fn init_data_device<F, C, U, R, L>( pub fn init_data_device<F, C, U, R, L>(
display: &mut Display, display: &mut Display,
callback: C, callback: C,
@ -329,7 +331,7 @@ pub fn set_data_device_focus(seat: &Seat, client: Option<Client>) {
/// You need to provide the available mime types for this selection. /// You need to provide the available mime types for this selection.
/// ///
/// Whenever a client requests to read the selection, your callback will /// Whenever a client requests to read the selection, your callback will
/// receive a `DataDeviceEvent::SendSelection` event. /// receive a [`DataDeviceEvent::SendSelection`] event.
pub fn set_data_device_selection(seat: &Seat, mime_types: Vec<String>) { pub fn set_data_device_selection(seat: &Seat, mime_types: Vec<String>) {
// TODO: same question as in set_data_device_focus // TODO: same question as in set_data_device_focus
seat.user_data().insert_if_missing(|| { seat.user_data().insert_if_missing(|| {
@ -350,7 +352,7 @@ pub fn set_data_device_selection(seat: &Seat, mime_types: Vec<String>) {
/// Start a drag'n'drop from a ressource controlled by the compositor /// Start a drag'n'drop from a ressource controlled by the compositor
/// ///
/// You'll receive events generated by the interaction of clients with your /// You'll receive events generated by the interaction of clients with your
/// drag'n'drop in the provided callback. See `SeverDndEvent` for details about /// drag'n'drop in the provided callback. See [`ServerDndEvent`] for details about
/// which events can be generated and what response is expected from you to them. /// which events can be generated and what response is expected from you to them.
pub fn start_dnd<C>(seat: &Seat, serial: u32, metadata: SourceMetadata, callback: C) pub fn start_dnd<C>(seat: &Seat, serial: u32, metadata: SourceMetadata, callback: C)
where where

2
src/wayland/data_device/server_dnd_grab.rs
View File

@ -10,7 +10,7 @@ use wayland::seat::{AxisFrame, PointerGrab, PointerInnerHandle, Seat};
use super::{DataDeviceData, SeatData}; use super::{DataDeviceData, SeatData};
/// Event generated by the interactions of clients with a server innitiated drag'n'drop /// Event generated by the interactions of clients with a server initiated drag'n'drop
pub enum ServerDndEvent { pub enum ServerDndEvent {
/// The client chose an action /// The client chose an action
Action(DndAction), Action(DndAction),

2
src/wayland/mod.rs
View File

@ -21,7 +21,7 @@ pub mod seat;
pub mod shell; pub mod shell;
pub mod shm; pub mod shm;
/// A global `SerialCounter` for use in your compositor. /// A global [`SerialCounter`] for use in your compositor.
/// ///
/// Is is also used internally by some parts of Smithay. /// Is is also used internally by some parts of Smithay.
pub static SERIAL_COUNTER: SerialCounter = SerialCounter { pub static SERIAL_COUNTER: SerialCounter = SerialCounter {

12
src/wayland/output/mod.rs
View File

@ -7,12 +7,12 @@
//! //!
//! # How to use it //! # How to use it
//! //!
//! You need to instantiate an `Output` for each output global you want //! You need to instantiate an [`Output`](::wayland::output::Output)
//! to advertise to clients. //! for each output global you want to advertise to clients.
//! //!
//! Just add it to your Display using the `Output::new(..)` method. //! Just add it to your Display using the [`Output::new(..)`](::wayland::output::Output::new)
//! You can use the returned `Output` to change the properties of your //! method. You can use the returned [`Output`](::wayland::output::Output) to change
//! output (if the current resolution mode changes for example), //! the properties of your output (if the current resolution mode changes for example),
//! it'll automatically forward any changes to the clients. //! it'll automatically forward any changes to the clients.
//! //!
//! ``` //! ```
@ -306,7 +306,7 @@ impl Output {
} }
} }
/// Check is given `wl_output` instance is managed by this `Output`. /// Check is given [`wl_output`](WlOutput) instance is managed by this [`Output`].
pub fn owns(&self, output: &Resource<WlOutput>) -> bool { pub fn owns(&self, output: &Resource<WlOutput>) -> bool {
self.inner self.inner
.lock() .lock()

11
src/wayland/seat/keyboard.rs
View File

@ -275,9 +275,9 @@ struct KbdArc {
/// This handle gives you 2 main ways to interact with the keyboard handling: /// This handle gives you 2 main ways to interact with the keyboard handling:
/// ///
/// - set the current focus for this keyboard: designing the surface that will receive the key inputs /// - set the current focus for this keyboard: designing the surface that will receive the key inputs
/// using the `KeyboardHandle::set_focus` method. /// using the [`KeyboardHandle::set_focus`] method.
/// - process key inputs from the input backend, allowing them to be caught at the compositor-level /// - process key inputs from the input backend, allowing them to be caught at the compositor-level
/// or forwarded to the client. See the documentation of the `KeyboardHandle::input` method for /// or forwarded to the client. See the documentation of the [`KeyboardHandle::input`] method for
/// details. /// details.
#[derive(Clone)] #[derive(Clone)]
pub struct KeyboardHandle { pub struct KeyboardHandle {
@ -295,7 +295,7 @@ impl KeyboardHandle {
/// returns false, the input will not be sent to the client. This mechanism can be used to /// returns false, the input will not be sent to the client. This mechanism can be used to
/// implement compositor-level key bindings for example. /// implement compositor-level key bindings for example.
/// ///
/// The module `smithay::keyboard::keysyms` exposes definitions of all possible keysyms /// The module [`wayland::seat::keysyms`](::wayland::seat::keysyms) exposes definitions of all possible keysyms
/// to be compared against. This includes non-character keysyms, such as XF86 special keys. /// to be compared against. This includes non-character keysyms, such as XF86 special keys.
pub fn input<F>(&self, keycode: u32, state: KeyState, serial: u32, time: u32, filter: F) pub fn input<F>(&self, keycode: u32, state: KeyState, serial: u32, time: u32, filter: F)
where where
@ -357,8 +357,9 @@ impl KeyboardHandle {
/// Set the current focus of this keyboard /// Set the current focus of this keyboard
/// ///
/// If the new focus is different from the previous one, any previous focus /// If the new focus is different from the previous one, any previous focus
/// will be sent a `wl_keyboard::leave` event, and if the new focus is not `None`, /// will be sent a [`wl_keyboard::Event::Leave`](wayland_server::protocol::wl_keyboard::Event::Leave)
/// a `wl_keyboard::enter` event will be sent. /// event, and if the new focus is not `None`,
/// a [`wl_keyboard::Event::Enter`](wayland_server::protocol::wl_keyboard::Event::Enter) event will be sent.
pub fn set_focus(&self, focus: Option<&Resource<WlSurface>>, serial: u32) { pub fn set_focus(&self, focus: Option<&Resource<WlSurface>>, serial: u32) {
let mut guard = self.arc.internal.lock().unwrap(); let mut guard = self.arc.internal.lock().unwrap();

15
src/wayland/seat/mod.rs
View File

@ -38,7 +38,8 @@
//! Currently, only pointer and keyboard capabilities are supported by //! Currently, only pointer and keyboard capabilities are supported by
//! smithay. //! smithay.
//! //!
//! You can add these capabilities via methods of the `Seat` struct: `add_keyboard`, `add_pointer`. //! You can add these capabilities via methods of the [`Seat`](::wayland::seat::Seat) struct:
//! [`add_keyboard`](::wayland::seat::Seat::add_keyboard), [`add_pointer`](::wayland::seat::Seat::add_pointer).
//! These methods return handles that can be cloned and sent across thread, so you can keep one around //! These methods return handles that can be cloned and sent across thread, so you can keep one around
//! in your event-handling code to forward inputs to your clients. //! in your event-handling code to forward inputs to your clients.
@ -101,7 +102,7 @@ impl Inner {
/// This struct gives you access to the control of the /// This struct gives you access to the control of the
/// capabilities of the associated seat. /// capabilities of the associated seat.
/// ///
/// It is directly inserted in the event loop by its `new` method. /// It is directly inserted in the event loop by its [`new`](Seat::new) method.
/// ///
/// This is an handle to the inner logic, it can be cloned and shared accross /// This is an handle to the inner logic, it can be cloned and shared accross
/// threads. /// threads.
@ -160,7 +161,7 @@ impl Seat {
(seat, global) (seat, global)
} }
/// Attempt to retrieve a `Seat` from an existing resource /// Attempt to retrieve a [`Seat`] from an existing resource
pub fn from_resource(seat: &Resource<wl_seat::WlSeat>) -> Option<Seat> { pub fn from_resource(seat: &Resource<wl_seat::WlSeat>) -> Option<Seat> {
seat.user_data::<Arc<SeatArc>>().cloned().map(|arc| Seat { arc }) seat.user_data::<Arc<SeatArc>>().cloned().map(|arc| Seat { arc })
} }
@ -172,8 +173,8 @@ impl Seat {
/// Adds the pointer capability to this seat /// Adds the pointer capability to this seat
/// ///
/// You are provided a `PointerHandle`, which allows you to send input events /// You are provided a [`PointerHandle`], which allows you to send input events
/// to this keyboard. This handle can be cloned and sent across threads. /// to this pointer. This handle can be cloned and sent across threads.
/// ///
/// Calling this method on a seat that already has a pointer capability /// Calling this method on a seat that already has a pointer capability
/// will overwrite it, and will be seen by the clients as if the /// will overwrite it, and will be seen by the clients as if the
@ -245,7 +246,7 @@ impl Seat {
/// Adds the keyboard capability to this seat /// Adds the keyboard capability to this seat
/// ///
/// You are provided a `KbdHandle`, which allows you to send input events /// You are provided a [`KeyboardHandle`], which allows you to send input events
/// to this keyboard. This handle can be cloned and sent across threads. /// to this keyboard. This handle can be cloned and sent across threads.
/// ///
/// You also provide a Model/Layout/Variant/Options specification of the /// You also provide a Model/Layout/Variant/Options specification of the
@ -324,7 +325,7 @@ impl Seat {
} }
} }
/// Checks whether a given `WlSeat` is associated with this `Seat` /// Checks whether a given [`WlSeat`](wl_seat::WlSeat) is associated with this [`Seat`]
pub fn owns(&self, seat: &Resource<wl_seat::WlSeat>) -> bool { pub fn owns(&self, seat: &Resource<wl_seat::WlSeat>) -> bool {
let inner = self.arc.inner.lock().unwrap(); let inner = self.arc.inner.lock().unwrap();
inner.known_seats.iter().any(|s| s.equals(seat)) inner.known_seats.iter().any(|s| s.equals(seat))

11
src/wayland/seat/pointer.rs
View File

@ -124,7 +124,7 @@ impl PointerInternal {
/// clients. /// clients.
/// ///
/// When sending events using this handle, they will be intercepted by a pointer /// When sending events using this handle, they will be intercepted by a pointer
/// grab if any is active. See the `PointerGrab` trait for details. /// grab if any is active. See the [`PointerGrab`] trait for details.
#[derive(Clone)] #[derive(Clone)]
pub struct PointerHandle { pub struct PointerHandle {
inner: Arc<Mutex<PointerInternal>>, inner: Arc<Mutex<PointerInternal>>,
@ -213,7 +213,6 @@ impl PointerHandle {
/// Start an axis frame /// Start an axis frame
/// ///
/// A single frame will group multiple scroll events as if they happened in the same instance. /// A single frame will group multiple scroll events as if they happened in the same instance.
/// Dropping the returned `PointerAxisHandle` will group the events together.
pub fn axis(&self, details: AxisFrame) { pub fn axis(&self, details: AxisFrame) {
self.inner.lock().unwrap().with_grab(|mut handle, grab| { self.inner.lock().unwrap().with_grab(|mut handle, grab| {
grab.axis(&mut handle, details); grab.axis(&mut handle, details);
@ -228,9 +227,9 @@ impl PointerHandle {
/// the underlying surfaces will no longer receive classic pointer event, but rather special events. /// the underlying surfaces will no longer receive classic pointer event, but rather special events.
/// ///
/// This trait is the interface to intercept regular pointer events and change them as needed, its /// This trait is the interface to intercept regular pointer events and change them as needed, its
/// interface mimics the `PointerHandle` interface. /// interface mimics the [`PointerHandle`] interface.
/// ///
/// If your logic decides that the grab should end, both `PointerInnerHandle` and `PointerHandle` have /// If your logic decides that the grab should end, both [`PointerInnerHandle`] and [`PointerHandle`] have
/// a method to change it. /// a method to change it.
/// ///
/// When your grab ends (either as you requested it or if it was forcefully cancelled by the server), /// When your grab ends (either as you requested it or if it was forcefully cancelled by the server),
@ -492,7 +491,7 @@ impl AxisFrame {
/// This event is optional, if no source is known, you can ignore this call. /// This event is optional, if no source is known, you can ignore this call.
/// Only one source event is allowed per frame. /// Only one source event is allowed per frame.
/// ///
/// Using the `AxisSource::Finger` requires a stop event to be send, /// Using the [`AxisSource::Finger`] requires a stop event to be send,
/// when the user lifts off the finger (not necessarily in the same frame). /// when the user lifts off the finger (not necessarily in the same frame).
pub fn source(mut self, source: AxisSource) -> Self { pub fn source(mut self, source: AxisSource) -> Self {
self.source = Some(source); self.source = Some(source);
@ -532,7 +531,7 @@ impl AxisFrame {
/// Notification of stop of scrolling on an axis. /// Notification of stop of scrolling on an axis.
/// ///
/// This event is required for sources of the `AxisSource::Finger` type /// This event is required for sources of the [`AxisSource::Finger`] type
/// and otherwise optional. /// and otherwise optional.
pub fn stop(mut self, axis: Axis) -> Self { pub fn stop(mut self, axis: Axis) -> Self {
match axis { match axis {

10
src/wayland/shell/legacy/mod.rs
View File

@ -23,9 +23,9 @@
//! //!
//! ### Initialization //! ### Initialization
//! //!
//! To initialize this handler, simple use the `wl_shell_init` function provided in this //! To initialize this handler, simple use the [`wl_shell_init`](::wayland::shell::legacy::wl_shell_init)
//! module. You will need to provide it the `CompositorToken` you retrieved from an //! function provided in this module. You will need to provide it the [`CompositorToken`](::wayland::compositor::CompositorToken)
//! instantiation of the compositor handler provided by smithay. //! you retrieved from an instantiation of the compositor handler provided by smithay.
//! //!
//! ```no_run //! ```no_run
//! # extern crate wayland_server; //! # extern crate wayland_server;
@ -85,7 +85,7 @@ use wayland_server::{
mod wl_handlers; mod wl_handlers;
/// Metadata associated with the `xdg_surface` role /// Metadata associated with the `wl_surface` role
pub struct ShellSurfaceRole<D: 'static> { pub struct ShellSurfaceRole<D: 'static> {
/// Title of the surface /// Title of the surface
pub title: String, pub title: String,
@ -133,7 +133,7 @@ where
/// Send a ping request to this shell surface /// Send a ping request to this shell surface
/// ///
/// You'll receive the reply as a `ShellRequest::Pong` request /// You'll receive the reply as a [`ShellRequest::Pong`] request
/// ///
/// A typical use is to start a timer at the same time you send this ping /// A typical use is to start a timer at the same time you send this ping
/// request, and cancel it when you receive the pong. If the timer runs /// request, and cancel it when you receive the pong. If the timer runs

31
src/wayland/shell/xdg/mod.rs
View File

@ -21,9 +21,9 @@
//! //!
//! ### Initialization //! ### Initialization
//! //!
//! To initialize this handler, simple use the `xdg_shell_init` function provided in this //! To initialize this handler, simple use the [`xdg_shell_init`](::wayland::shell::xdg::xdg_shell_init) function provided in this
//! module. You will need to provide it the `CompositorToken` you retrieved from an //! module. You will need to provide it the [`CompositorToken`](::wayland::compositor::CompositorToken)
//! instantiation of the compositor global provided by smithay. //! you retrieved from an instantiation of the compositor global provided by smithay.
//! //!
//! ```no_run //! ```no_run
//! # extern crate wayland_server; //! # extern crate wayland_server;
@ -73,17 +73,22 @@
//! //!
//! There are mainly 3 kind of objects that you'll manipulate from this implementation: //! There are mainly 3 kind of objects that you'll manipulate from this implementation:
//! //!
//! - `ShellClient`: This is a handle representing an instantiation of a shell global //! - [`ShellClient`](::wayland::shell::xdg::ShellClient):
//! This is a handle representing an instantiation of a shell global
//! you can associate client-wise metadata to it (this is the `MyShellData` type in //! you can associate client-wise metadata to it (this is the `MyShellData` type in
//! the example above). //! the example above).
//! - `ToplevelSurface`: This is a handle representing a toplevel surface, you can //! - [`ToplevelSurface`](::wayland::shell::xdg::ToplevelSurface):
//! retrieve a list of all currently alive toplevel surface from the `ShellState`. //! This is a handle representing a toplevel surface, you can
//! - `PopupSurface`: This is a handle representing a popup/tooltip surface. Similarly, //! retrieve a list of all currently alive toplevel surface from the
//! you can get a list of all currently alive popup surface from the `ShellState`. //! [`ShellState`](::wayland::shell::xdg::ShellState).
//! - [`PopupSurface`](::wayland::shell::xdg::PopupSurface):
//! This is a handle representing a popup/tooltip surface. Similarly,
//! you can get a list of all currently alive popup surface from the
//! [`ShellState`](::wayland::shell::xdg::ShellState).
//! //!
//! You'll obtain these objects though two means: either via the callback methods of //! You'll obtain these objects though two means: either via the callback methods of
//! the subhandler you provided, or via methods on the `ShellState` that you are given //! the subhandler you provided, or via methods on the [`ShellState`](::wayland::shell::xdg::ShellState)
//! (in an `Arc<Mutex<_>>`) as return value of the `init` function. //! that you are given (in an `Arc<Mutex<_>>`) as return value of the `init` function.
use std::{ use std::{
cell::RefCell, cell::RefCell,
@ -408,7 +413,7 @@ where
/// Send a ping request to this shell client /// Send a ping request to this shell client
/// ///
/// You'll receive the reply as a `XdgRequest::ClientPong` request. /// You'll receive the reply as a [`XdgRequest::ClientPong`] request.
/// ///
/// A typical use is to start a timer at the same time you send this ping /// A typical use is to start a timer at the same time you send this ping
/// request, and cancel it when you receive the pong. If the timer runs /// request, and cancel it when you receive the pong. If the timer runs
@ -843,7 +848,7 @@ pub enum XdgRequest<U, R, SD> {
}, },
/// A new toplevel surface was created /// A new toplevel surface was created
/// ///
/// You likely need to send a `ToplevelConfigure` to the surface, to hint the /// You likely need to send a [`ToplevelConfigure`] to the surface, to hint the
/// client as to how its window should be /// client as to how its window should be
NewToplevel { NewToplevel {
/// the surface /// the surface
@ -851,7 +856,7 @@ pub enum XdgRequest<U, R, SD> {
}, },
/// A new popup surface was created /// A new popup surface was created
/// ///
/// You likely need to send a `PopupConfigure` to the surface, to hint the /// You likely need to send a [`PopupConfigure`] to the surface, to hint the
/// client as to how its popup should be /// client as to how its popup should be
NewPopup { NewPopup {
/// the surface /// the surface

9
src/wayland/shm/mod.rs
View File

@ -36,8 +36,9 @@
//! # } //! # }
//! ``` //! ```
//! //!
//! Then, when you have a `WlBuffer` and need to retrieve its contents, use the //! Then, when you have a [`WlBuffer`](wayland_server::protocol::wl_buffer::WlBuffer)
//! `with_buffer_contents` function to do it: //! and need to retrieve its contents, use the
//! [`with_buffer_contents`](::wayland::shm::with_buffer_contents) function to do it:
//! //!
//! ``` //! ```
//! # extern crate wayland_server; //! # extern crate wayland_server;
@ -103,8 +104,8 @@ pub struct ShmGlobalData {
/// as they are required by the protocol. Formats given as argument /// as they are required by the protocol. Formats given as argument
/// as additionally advertized. /// as additionally advertized.
/// ///
/// The global is directly created on the provided `Display`, and this function /// The global is directly created on the provided [`Display`](wayland_server::Display),
/// returns the global handle, in case you wish to remove this global in /// and this function returns the global handle, in case you wish to remove this global in
/// the future. /// the future.
pub fn init_shm_global<L>( pub fn init_shm_global<L>(
display: &mut Display, display: &mut Display,