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"
on:
branch: master
rust: stable
rust: nightly
condition: "$FEATURES = all"
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;

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.
//!
//! Usually this implementation's [`EglSurface`](struct.EglSurface.html)s implementation
//! of [`GlGraphicsBackend`](../../graphics/gl/trait.GlGraphicsBackend.html) will be used
//! Usually this implementation's [`EglSurface`](::backend::drm::egl::EglSurface)s implementation
//! of [`GLGraphicsBackend`](::backend::graphics::gl::GLGraphicsBackend) will be used
//! to let your compositor render.
//! 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 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
/// 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
/// 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)
//! to an open [`Session`](../../session/trait.Session.html).
//! Support to register an [`EglDevice`](EglDevice)
//! to an open [`Session`](::backend::session::Session).
//!
use drm::control::crtc;
@ -11,8 +11,8 @@ use backend::drm::Device;
use backend::egl::native::{Backend, NativeDisplay, NativeSurface};
use backend::session::{AsSessionObserver, SessionObserver};
/// [`SessionObserver`](../../session/trait.SessionObserver.html)
/// linked to the [`EglDevice`](../struct.EglDevice.html) it was
/// [`SessionObserver`](SessionObserver)
/// linked to the [`EglDevice`](EglDevice) it was
/// created from.
pub struct EglDeviceObserver<S: SessionObserver + 'static> {
observer: S,

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

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

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.
//!
//! 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.
//!
//! 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};
@ -44,7 +44,7 @@ pub struct GbmDevice<D: RawDevice + ControlDevice + 'static> {
}
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
/// successful.

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

@ -1,6 +1,6 @@
//!
//! Support to register a [`GbmDevice`](../struct.GbmDevice.html)
//! to an open [`Session`](../../session/trait.Session.html).
//! Support to register a [`GbmDevice`](GbmDevice)
//! to an open [`Session`](::backend::session::Session).
//!
use drm::control::{crtc, Device as ControlDevice, ResourceInfo};
@ -14,8 +14,8 @@ use super::{GbmDevice, GbmSurfaceInternal};
use backend::drm::{RawDevice, RawSurface};
use backend::session::{AsSessionObserver, SessionObserver};
/// [`SessionObserver`](../../session/trait.SessionObserver.html)
/// linked to the [`GbmDevice`](../struct.GbmDevice.html) it was
/// [`SessionObserver`](SessionObserver)
/// linked to the [`GbmDevice`](GbmDevice) it was
/// created from.
pub struct GbmDeviceObserver<
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.
///
/// 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
/// `device_bind`.
/// [`device_bind`](::backend::drm::device_bind).
///
/// *Note*: This might trigger a full modeset on the underlying device,
/// potentially causing some flickering. In that case this operation is
@ -301,9 +301,9 @@ impl<D: RawDevice + 'static> GbmSurface<D> {
/// Recreate underlying gbm resources.
///
/// This recreates the gbm surfaces resources, which might be needed after e.g.
/// calling [`Surface::use_mode`](../trait.Surface.html#method.use_mode).
/// You may check if your `GbmSurface` needs recreation through
/// [`needs_recreation`](#method.needs_recreation).
/// calling [`Surface::use_mode`](Surface::use_mode).
/// You may check if your [`GbmSurface`] needs recreation through
/// [`needs_recreation`](GbmSurface::needs_recreation).
pub fn recreate(&self) -> Result<()> {
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};

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.
//!
//! 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.
//!
//! 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> {
/// 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
/// successful.

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

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

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

@ -63,11 +63,11 @@ pub mod gbm;
#[cfg(feature = "backend_drm_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 {
/// The [`Device`](trait.Device.html) type this handler can handle
/// The [`Device`] type this handler can handle
type Device: Device + ?Sized;
/// A vblank blank event on the provided crtc has happend
@ -78,15 +78,15 @@ pub trait DeviceHandler {
/// An open drm device
pub trait Device: AsRawFd + DevPath {
/// Associated [`Surface`](trait.Surface.html) of this `Device` type
/// Associated [`Surface`] of this [`Device`] type
type Surface: Surface;
/// Returns the `id` of this device node.
/// Returns the id of this device node.
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);
/// Clear a set [`DeviceHandler`](trait.DeviceHandler.html), if any
fn clear_handler(&mut self);
@ -108,26 +108,26 @@ pub trait Device: AsRawFd + DevPath {
/// Processes any open events of the underlying file descriptor.
///
/// 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 synchronize your rendering to the vblank events of the open crtc's
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)
fn resource_info<T: ResourceInfo>(
&self,
handle: T::Handle,
) -> 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)
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> {
/// Associated [`RawSurface`](trait.RawSurface.html) of this `RawDevice` type
/// Associated [`RawSurface`] of this [`RawDevice`] type
type Surface: RawSurface;
}
@ -135,8 +135,8 @@ pub trait RawDevice: Device<Surface = <Self as RawDevice>::Surface> {
pub trait Surface {
/// Type repesenting a collection of
/// [`connector`](https://docs.rs/drm/0.3.4/drm/control/connector/index.html)s
/// returned by [`current_connectors`](#method.current_connectors) and
/// [`pending_connectors`](#method.pending_connectors)
/// returned by [`current_connectors`](Surface::current_connectors) and
/// [`pending_connectors`](Surface::pending_connectors)
type Connectors: IntoIterator<Item = connector::Handle>;
/// Error type returned by methods of this trait
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`
fn current_connectors(&self) -> Self::Connectors;
/// 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
/// a [`commit`](trait.RawSurface.html#method.commit). Other `Surface`s provide their
/// *Note*: Only on a [`RawSurface`] you may directly trigger
/// a [`commit`](RawSurface::commit). Other `Surface`s provide their
/// own methods that *may* trigger a commit, you will need to read their docs.
fn pending_connectors(&self) -> Self::Connectors;
/// 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
/// 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
/// a [`commit`](trait.RawSurface.html#method.commit). Other `Surface`s provide their
/// *Note*: Only on a [`RawSurface`] you may directly trigger
/// a [`commit`](RawSurface::commit). Other [`Surface`]s provide their
/// own methods that *may* trigger a commit, you will need to read their docs.
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
///
/// The following functions may trigger a pending commit:
/// - [`add_connector`](trait.Surface.html#method.add_connector)
/// - [`remove_connector`](trait.Surface.html#method.remove_connector)
/// - [`use_mode`](trait.Surface.html#method.use_mode)
/// - [`add_connector`](Surface::add_connector)
/// - [`remove_connector`](Surface::remove_connector)
/// - [`use_mode`](Surface::use_mode)
fn commit_pending(&self) -> bool;
/// Commit the pending state rendering a given framebuffer.
///
/// *Note*: This will trigger a full modeset on the underlying device,
/// 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.
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 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
/// [register the belonging `Device`](fn.device_bind.html) before to receive the event in time.
/// Make sure to [set a `DeviceHandler`](Device::set_handler) and
/// [register the belonging `Device`](device_bind) before to receive the event in time.
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
/// set [`DeviceHandler`](trait.DeviceHandler.html).
/// set [`DeviceHandler`](DeviceHandler).
pub fn device_bind<D: Device + 'static, Data>(
handle: &LoopHandle<Data>,
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> {
/// Create a new `EGLContext` from a given `NativeDisplay`
/// Create a new [`EGLContext`] from a given [`NativeDisplay`](native::NativeDisplay)
pub fn new<L>(
native: N,
attributes: GlAttributes,
@ -449,7 +449,7 @@ impl<B: native::Backend, N: native::NativeDisplay<B>> EGLContext<B, N> {
/// 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
/// backend while there is a mutable reference will panic.
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.
///
/// 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
/// mutably will panic. Note that EGL will borrow the display
/// mutably during surface creation.

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

@ -1,21 +1,22 @@
//! Common traits and types for egl rendering
//!
//! 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
//! (see https://github.com/tomaka/glutin/tree/044e651edf67a2029eecc650dd42546af1501414/LICENSE)
//! Wayland specific EGL functionality - EGL based `WlBuffer`s.
//! It therefore falls under
//! [glutin's Apache 2.0 license](https://github.com/tomaka/glutin/tree/044e651edf67a2029eecc650dd42546af1501414/LICENSE)
//!
//! 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
//! 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
//! 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.
//! 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.
//! 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`
//! for rendering.
//! You may then use the resulting [`EGLDisplay`](::backend::egl::EGLDisplay) to receive [`EGLImages`](::backend::egl::EGLImages)
//! of an EGL-based [`WlBuffer`](wayland_server::protocol::wl_buffer::WlBuffer) for rendering.
#[cfg(feature = "renderer_gl")]
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 {
display: Weak<ffi::egl::types::EGLDisplay>,
/// Width in pixels
@ -297,29 +298,28 @@ impl Drop for EGLImages {
}
}
/// Trait any backend type may implement that allows binding a `wayland_server::Display`
/// to create an `EGLDisplay` for EGL-based `WlBuffer`s.
/// Trait any backend type may implement that allows binding a [`Display`](wayland_server::Display)
/// to create an [`EGLDisplay`] for EGL-based [`WlBuffer`]s.
#[cfg(feature = "native_lib")]
pub trait EGLGraphicsBackend {
/// Binds this EGL context to the given Wayland display.
///
/// This will allow clients to utilize EGL to create hardware-accelerated
/// surfaces. The server will need to be able to handle EGL-`wl_buffers`.
/// See the `wayland::drm` module.
/// surfaces. The server will need to be able to handle EGL-[`WlBuffer`]s.
///
/// ## Errors
///
/// This might return `WlExtensionNotSupported` if binding is not supported
/// by the EGL implementation.
/// This might return [`EglExtensionNotSupported`](ErrorKind::EglExtensionNotSupported)
/// if binding is not supported by the EGL implementation.
///
/// This might return `OtherEGLDisplayAlreadyBound` if called for the same
/// `Display` multiple times, as only one context may be bound at any given time.
/// This might return [`OtherEGLDisplayAlreadyBound`](ErrorKind::OtherEGLDisplayAlreadyBound)
/// 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>;
}
/// 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")]
pub struct 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)
/// a `BufferAccessError::NotManaged(WlBuffer)` is returned with the original buffer
/// In case the buffer is not managed by EGL (but e.g. the [`wayland::shm` module](::wayland::shm))
/// a [`BufferAccessError::NotManaged`](::backend::egl::BufferAccessError::NotManaged) is returned with the original buffer
/// to render it another way.
pub fn egl_buffer_contents(
&self,

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

@ -18,11 +18,11 @@ pub trait Backend {
/// Surface type created by this backend
type Surface: NativeSurface;
/// Return an `EGLDisplay` based on this backend
/// Return an [`EGLDisplay`](ffi::egl::types::EGLDisplay) based on this backend
///
/// # 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.
unsafe fn get_display<F: Fn(&str) -> bool>(
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
///
/// 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> {
/// Arguments used to surface creation.
type Arguments;
/// Error type thrown by the surface creation in case of failure.
type Error: ::std::error::Error + Send + 'static;
/// Because one type might implement multiple `Backend`s this function must be called to check
/// if the expected `Backend` is used at runtime.
/// Because one type might implement multiple [`Backend`]s this function must be called to check
/// if the expected [`Backend`] is used at runtime.
fn is_backend(&self) -> bool;
/// Return a raw pointer EGL will accept for context creation.
fn ptr(&self) -> Result<ffi::NativeDisplayType>;
@ -163,7 +163,8 @@ unsafe impl NativeDisplay<Wayland> for WinitWindow {
///
/// ## 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 {
/// Return a raw pointer egl will accept for surface creation.
fn ptr(&self) -> ffi::NativeWindowType;
@ -187,7 +188,8 @@ pub unsafe trait NativeSurface {
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.
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> {
/// Format representing the image drawn for the cursor.
type CursorFormat: 'a;
@ -19,7 +24,7 @@ pub trait CursorBackend<'a> {
///
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
/// 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;
@ -45,11 +45,11 @@ pub trait GLGraphicsBackend {
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
/// 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 {
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.
///
/// This function returns a `Frame`, which can be used to draw on it. When the `Frame` is
/// destroyed, the buffers are swapped.
/// This function returns a [`Frame`], which can be used to draw on it.
/// 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]
pub fn draw(&self) -> Frame {
Frame::new(self.context.clone(), self.backend.get_framebuffer_dimensions())
@ -56,7 +56,7 @@ impl<T: GLGraphicsBackend + 'static> GliumGraphicsBackend<T> {
/// 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
/// backend while there is a mutable reference will panic.
pub fn borrow(&self) -> Ref<T> {
@ -65,7 +65,7 @@ impl<T: GLGraphicsBackend + 'static> GliumGraphicsBackend<T> {
/// 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
/// mutably will panic. Note that Glium will borrow the backend
/// (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.
///
/// 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.
/// Always refer to the `Seat` given by a callback for up-to-date information. You may
/// 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
/// use this to calculate the differences since the last callback.
#[derive(Debug, Clone, Eq)]
pub struct Seat {
@ -33,12 +33,12 @@ impl Seat {
&mut self.capabilities
}
/// Get the currently capabilities of this `Seat`
/// Get the currently capabilities of this [`Seat`]
pub fn capabilities(&self) -> &SeatCapabilities {
&self.capabilities
}
/// Get the name of this `Seat`
/// Get the name of this [`Seat`]
pub fn name(&self) -> &str {
&*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)]
pub struct SeatCapabilities {
/// `Seat` has a pointer
/// [`Seat`] has a pointer
pub pointer: bool,
/// `Seat` has a keyboard
/// [`Seat`] has a keyboard
pub keyboard: bool,
/// `Seat` has a touchscreen
/// [`Seat`] has a touchscreen
pub touch: bool,
}
@ -81,10 +81,10 @@ pub trait Event {
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,
/// that is not used by an `InputBackend` implementation. Initialization is not
/// 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
/// possible, making accidental use impossible and enabling a lot of possible
/// compiler optimizations.
pub enum UnusedEvent {}
@ -110,7 +110,7 @@ pub trait KeyboardKeyEvent: Event {
fn key_code(&self) -> u32;
/// State of the key
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;
}
@ -190,7 +190,7 @@ pub enum AxisSource {
/// cursor movement, i.e. a scroll value of 1 represents the equivalent relative
/// motion of 1.
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).
///
@ -212,14 +212,14 @@ pub enum AxisSource {
/// Trait for pointer events generated by scrolling on an axis.
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>;
/// 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>;
/// Source of the scroll event.
@ -336,7 +336,7 @@ impl TouchSlot {
/// Trait for touch events starting at a given position.
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>;
/// 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
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>;
/// Touch position in the device's native coordinate space
@ -460,7 +460,7 @@ impl TouchMotionEvent for UnusedEvent {
/// Trait for touch events finishing.
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>;
}
@ -472,7 +472,7 @@ impl TouchUpEvent for UnusedEvent {
/// Trait for touch events cancelling the chain
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>;
}
@ -518,7 +518,7 @@ pub trait InputBackend: Sized {
/// Type representing touch frame events
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);
/// Get a reference to the currently set handler, if any
fn get_handler(&mut self) -> Option<&mut InputHandler<Self>>;
@ -528,17 +528,17 @@ pub trait InputBackend: Sized {
/// Get current `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>;
}
/// Implement to receive input events from any `InputBackend`.
/// Implement to receive input events from any [`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);
/// Called when an existing `Seat` has been destroyed.
/// Called when an existing [`Seat`] has been destroyed.
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:
///
@ -549,7 +549,7 @@ pub trait InputHandler<B: InputBackend> {
///
/// # Arguments
///
/// - `seat` - The `Seat` the event belongs to
/// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The keyboard event
///
fn on_keyboard_key(&mut self, seat: &Seat, event: B::KeyboardKeyEvent);
@ -558,28 +558,28 @@ pub trait InputHandler<B: InputBackend> {
///
/// # Arguments
///
/// - `seat` - The `Seat` the event belongs to
/// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The pointer movement event
fn on_pointer_move(&mut self, seat: &Seat, event: B::PointerMotionEvent);
/// Called when a new pointer absolute movement event was received.
///
/// # Arguments
///
/// - `seat` - The `Seat` the event belongs to
/// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The pointer absolute movement event
fn on_pointer_move_absolute(&mut self, seat: &Seat, event: B::PointerMotionAbsoluteEvent);
/// Called when a new pointer button event was received.
///
/// # Arguments
///
/// - `seat` - The `Seat` the event belongs to
/// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The pointer button event
fn on_pointer_button(&mut self, seat: &Seat, event: B::PointerButtonEvent);
/// Called when a new pointer scroll event was received.
///
/// # 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.
fn on_pointer_axis(&mut self, seat: &Seat, event: B::PointerAxisEvent);
@ -587,35 +587,35 @@ pub trait InputHandler<B: InputBackend> {
///
/// # Arguments
///
/// - `seat` - The `Seat` the event belongs to
/// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The touch down event
fn on_touch_down(&mut self, seat: &Seat, event: B::TouchDownEvent);
/// Called when a new touch motion event was received.
///
/// # Arguments
///
/// - `seat` - The `Seat` the event belongs to
/// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The touch motion event.
fn on_touch_motion(&mut self, seat: &Seat, event: B::TouchMotionEvent);
/// Called when a new touch up event was received.
///
/// # Arguments
///
/// - `seat` - The `Seat` the event belongs to
/// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The touch up event.
fn on_touch_up(&mut self, seat: &Seat, event: B::TouchUpEvent);
/// Called when a new touch cancel event was received.
///
/// # Arguments
///
/// - `seat` - The `Seat` the event belongs to
/// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The touch cancel event.
fn on_touch_cancel(&mut self, seat: &Seat, event: B::TouchCancelEvent);
/// Called when a new touch frame event was received.
///
/// # Arguments
///
/// - `seat` - The `Seat` the event belongs to
/// - `seat` - The [`Seat`] the event belongs to
/// - `event` - The touch frame event.
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`
use backend::input::{self as backend, Axis, InputBackend};
#[cfg(feature = "backend_session")]
use backend::session::{AsErrno, Session, SessionObserver};
use backend::{input as backend, input::Axis};
use input as libinput;
use input::event;
@ -27,7 +27,7 @@ use wayland_server::calloop::{
#[cfg(all(any(target_os = "linux", target_os = "android"), feature = "backend_session"))]
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
/// context.
@ -40,8 +40,8 @@ pub struct LibinputInputBackend {
}
impl LibinputInputBackend {
/// Initialize a new `LibinputInputBackend` from a given already initialized libinput
/// context.
/// Initialize a new [`LibinputInputBackend`] from a given already initialized
/// [libinput context](libinput::Libinput).
pub fn new<L>(context: libinput::Libinput, logger: L) -> Self
where
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::InputBackend for LibinputInputBackend {
impl InputBackend for LibinputInputBackend {
type InputConfig = [libinput::Device];
type EventError = IoError;
@ -565,8 +565,8 @@ impl SessionObserver for libinput::Libinput {
}
}
/// Wrapper for types implementing the `Session` trait to provide
/// a `LibinputInterface` implementation.
/// Wrapper for types implementing the [`Session`] trait to provide
/// a [`libinput::LibinputInterface`] implementation.
#[cfg(feature = "backend_session")]
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
/// `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>(
backend: LibinputInputBackend,
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.
//!
//! ## How to use it
//!
//! ### Initialization
//!
//! To initialize a session just call `AutoSession::new`. A new session will be opened, if the
//! any available interface is successful and will be closed once the `AutoSessionNotifier` is dropped.
//! To initialize a session just call [`AutoSession::new`](::backend::session::auto::AutoSession::new).
//! 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
//!
//! 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.
//! 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
//! `Session` via the `LibinputSessionInterface`) or the `UdevBackend`.
//! Examples for those are e.g. the [`LibinputInputBackend`](::backend::libinput::LibinputInputBackend)
//! (its context might be initialized through a [`Session`] via the [`LibinputSessionInterface`](::backend::libinput::LibinputSessionInterface)).
//!
//! ### Usage of the session notifier
//!
//! 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,
//! when the session becomes active again.
//! switching the tty via [`AutoSession::change_vt`](::backend::session::Session::change_vt))
//! 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
//! for notifications are the `Libinput` context, the `UdevBackend` or a `DrmDevice` (handled
//! automatically by the `UdevBackend`, if not done manually).
//! for notifications are the [`Libinput`](input::Libinput) context or the [`Device`](::backend::drm::Device).
#[cfg(feature = "backend_session_logind")]
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;
/// `Session` using the best available interface
/// [`Session`] using the best available interface
#[derive(Clone)]
pub enum AutoSession {
/// Logind session
@ -48,7 +49,7 @@ pub enum AutoSession {
Direct(Rc<RefCell<DirectSession>>),
}
/// `SessionNotifier` using the best available interface
/// [`SessionNotifier`] using the best available interface
pub enum AutoSessionNotifier {
/// Logind session notifier
#[cfg(feature = "backend_session_logind")]
@ -57,11 +58,11 @@ pub enum AutoSessionNotifier {
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 {
/// Bound logind session
#[cfg(feature = "backend_session_logind")]
@ -70,7 +71,7 @@ pub enum BoundAutoSession {
Direct(BoundDirectSession),
}
/// Id's used by the `AutoSessionNotifier` internally.
/// Id's used by the [`AutoSessionNotifier`] internally.
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub struct AutoId(AutoIdInternal);
#[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.
/// If you don't use this function `AutoSessionNotifier` will not correctly tell you the
/// session state and call its `SessionObservers`.
/// 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
/// session state and call its [`SessionObserver`]s.
pub fn auto_session_bind<Data: 'static>(
notifier: AutoSessionNotifier,
handle: &LoopHandle<Data>,
@ -232,7 +233,7 @@ impl SessionNotifier for AutoSessionNotifier {
}
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 {
match self {
#[cfg(feature = "backend_session_logind")]
@ -242,15 +243,22 @@ impl BoundAutoSession {
}
}
error_chain! {
links {
Logind(logind::Error, logind::ErrorKind) #[cfg(feature = "backend_session_logind")] #[doc = "Underlying logind session error"];
}
/// Errors related to auto sessions
pub mod errors {
#[cfg(feature = "backend_session_logind")]
use super::logind::errors as logind;
foreign_links {
Direct(::nix::Error) #[doc = "Underlying direct tty session error"];
error_chain! {
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 {
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.
//!
@ -7,28 +7,29 @@
//!
//! ### Initialization
//!
//! To initialize a session just call `LogindSession::new`. A new session will be opened, if the
//! call is successful and will be closed once the `LogindSessionNotifier` is dropped.
//! To initialize a session just call [`LogindSession::new`](::backend::session::dbus::logind::LogindSession::new).
//! 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
//!
//! 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.
//! 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
//! `Session` via the `LibinputSessionInterface`) or the `UdevBackend`.
//! Examples for those are e.g. the [`LibinputInputBackend`](::backend::libinput::LibinputInputBackend)
//! (its context might be initialized through a [`Session`](::backend::session::Session) via the
//! [`LibinputSessionInterface`](::backend::libinput::LibinputSessionInterface)).
//!
//! ### Usage of the session notifier
//!
//! 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,
//! when the session becomes active again.
//! switching the tty via [`LogindSession::change_vt`](::backend::session::Session::change_vt))
//! 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
//! for notifications are the `Libinput` context, the `UdevBackend` or a `DrmDevice` (handled
//! automatically by the `UdevBackend`, if not done manually).
//! ```
//! for notifications are the [`Libinput`](input::Libinput) context or the [`Device`](::backend::drm::Device).
use backend::session::{AsErrno, Session, SessionNotifier, SessionObserver};
use dbus::{
@ -64,14 +65,14 @@ struct LogindSessionImpl {
logger: ::slog::Logger,
}
/// `Session` via the logind dbus interface
/// [`Session`] via the logind dbus interface
#[derive(Clone)]
pub struct LogindSession {
internal: Weak<LogindSessionImpl>,
seat: String,
}
/// `SessionNotifier` via the logind dbus interface
/// [`SessionNotifier`] via the logind dbus interface
#[derive(Clone)]
pub struct LogindSessionNotifier {
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)]
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 {
notifier: LogindSessionNotifier,
_watches: Vec<Watch>,
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.
/// If you don't use this function `LogindSessionNotifier` will not correctly tell you the logind
/// session state and call it's `SessionObservers`.
/// 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
/// session state and call it's [`SessionObserver`]s.
pub fn logind_session_bind<Data: 'static>(
notifier: LogindSessionNotifier,
handle: &LoopHandle<Data>,
@ -471,7 +472,7 @@ pub fn logind_session_bind<Data: 'static>(
}
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 {
for source in self.sources {
source.remove();
@ -518,62 +519,68 @@ impl LogindSessionNotifier {
}
}
error_chain! {
errors {
#[doc = "Failed to connect to dbus system socket"]
FailedDbusConnection {
description("Failed to connect to dbus system socket"),
}
/// Errors related to logind sessions
pub mod errors {
use dbus::{BusName, Interface, Member, Path as DbusPath};
#[doc = "Failed to get session from logind"]
FailedToGetSession {
description("Failed to get session from logind")
}
error_chain! {
errors {
#[doc = "Failed to connect to dbus system socket"]
FailedDbusConnection {
description("Failed to connect to dbus system socket"),
}
#[doc = "Failed to get seat from logind"]
FailedToGetSeat {
description("Failed to get seat from logind")
}
#[doc = "Failed to get session from logind"]
FailedToGetSession {
description("Failed to get session from logind")
}
#[doc = "Failed to get vt from logind"]
FailedToGetVT {
description("Failed to get vt from logind")
}
#[doc = "Failed to get seat from logind"]
FailedToGetSeat {
description("Failed to get seat from logind")
}
#[doc = "Failed to call dbus method"]
FailedToSendDbusCall(bus: BusName<'static>, path: DbusPath<'static>, interface: Interface<'static>, member: Member<'static>) {
description("Failed to call dbus method")
display("Failed to call dbus method for service: {:?}, path: {:?}, interface: {:?}, member: {:?}", bus, path, interface, member),
}
#[doc = "Failed to get vt from logind"]
FailedToGetVT {
description("Failed to get vt from logind")
}
#[doc = "Dbus method call failed"]
DbusCallFailed(bus: BusName<'static>, path: DbusPath<'static>, interface: Interface<'static>, member: Member<'static>) {
description("Dbus method call failed")
display("Dbus message call failed for service: {:?}, path: {:?}, interface: {:?}, member: {:?}", bus, path, interface, member),
}
#[doc = "Failed to call dbus method"]
FailedToSendDbusCall(bus: BusName<'static>, path: DbusPath<'static>, interface: Interface<'static>, member: Member<'static>) {
description("Failed to call dbus method")
display("Failed to call dbus method for service: {:?}, path: {:?}, interface: {:?}, member: {:?}", bus, path, interface, member),
}
#[doc = "Dbus method return had unexpected format"]
UnexpectedMethodReturn {
description("Dbus method return returned unexpected format")
}
#[doc = "Dbus method call failed"]
DbusCallFailed(bus: BusName<'static>, path: DbusPath<'static>, interface: Interface<'static>, member: Member<'static>) {
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"]
DbusMatchFailed(rule: String) {
description("Failed to setup dbus match rule"),
display("Failed to setup dbus match rule {}", rule),
}
#[doc = "Dbus method return had unexpected format"]
UnexpectedMethodReturn {
description("Dbus method return returned unexpected format")
}
#[doc = "Failed to stat device"]
FailedToStatDevice {
description("Failed to stat device")
}
#[doc = "Failed to setup dbus match rule"]
DbusMatchFailed(rule: String) {
description("Failed to setup dbus match rule"),
display("Failed to setup dbus match rule {}", rule),
}
#[doc = "Session is already closed"]
SessionLost {
description("Session is already closed")
#[doc = "Failed to stat device"]
FailedToStatDevice {
description("Failed to stat device")
}
#[doc = "Session is already closed"]
SessionLost {
description("Session is already closed")
}
}
}
}
use self::errors::*;
impl AsErrno for Error {
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
//! interface. This means it will almost certainly require root permissions and not allow to run
@ -26,24 +26,23 @@
//!
//! ### 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.
//!
//! Examples for those are e.g. the `LibinputInputBackend` (its context might be initialized through a
//! `Session` via the `LibinputSessionInterface`) or the `UdevBackend`.
//! Examples for those are e.g. the [`LibinputInputBackend`](::backend::libinput::LibinputInputBackend)
//! (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>>`.
//!
//! ### Usage of the session notifier
//!
//! 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,
//! when the session becomes active again.
//! switching the tty via [`DirectSession::change_vt`](::backend::session::Session::change_vt))
//! 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
//! for notifications are the `Libinput` context, the `UdevBackend` or a `DrmDevice` (handled
//! automatically by the `UdevBackend`, if not done manually).
//! for notifications are the [`Libinput`](input::Libinput) context or the [`Device`](::backend::drm::Device).
use super::{AsErrno, Session, SessionNotifier, SessionObserver};
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 {
tty: RawFd,
active: Arc<AtomicBool>,
@ -159,7 +158,7 @@ pub struct DirectSession {
logger: ::slog::Logger,
}
/// `SessionNotifier` via the virtual terminal direct kernel interface
/// [`SessionNotifier`] via the virtual terminal direct kernel interface
pub struct DirectSessionNotifier {
tty: RawFd,
active: Arc<AtomicBool>,
@ -253,7 +252,7 @@ impl DirectSession {
// https://github.com/nix-rust/nix/issues/495
/*
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
} else {
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)]
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 {
source: Source<Signals>,
notifier: Rc<RefCell<DirectSessionNotifier>>,
}
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 {
let BoundDirectSession { source, notifier } = self;
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.
/// If you don't use this function `DirectSessionNotifier` will not correctly tell you the current
/// session state and call it's `SessionObservers`.
/// 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
/// session state and call it's [`SessionObserver`]s.
pub fn direct_session_bind<Data: 'static>(
notifier: DirectSessionNotifier,
handle: &LoopHandle<Data>,
@ -442,59 +441,63 @@ pub fn direct_session_bind<Data: 'static>(
Ok(BoundDirectSession { source, notifier })
}
error_chain! {
errors {
#[doc = "Failed to open tty"]
FailedToOpenTTY(path: String) {
description("Failed to open tty"),
display("Failed to open tty ({:?})", path),
}
/// Errors related to direct/tty sessions
pub mod errors {
error_chain! {
errors {
#[doc = "Failed to open tty"]
FailedToOpenTTY(path: String) {
description("Failed to open tty"),
display("Failed to open tty ({:?})", path),
}
#[doc = "Not running from a tty"]
NotRunningFromTTY {
description("Not running from a tty"),
}
#[doc = "Not running from a tty"]
NotRunningFromTTY {
description("Not running from a tty"),
}
#[doc = "tty is already in KB_GRAPHICS mode"]
TTYAlreadyInGraphicsMode {
description("The tty is already in KB_GRAPHICS mode"),
display("The tty is already in graphics mode, is already a compositor running?"),
}
#[doc = "tty is already in KB_GRAPHICS mode"]
TTYAlreadyInGraphicsMode {
description("The tty is already in KB_GRAPHICS mode"),
display("The tty is already in graphics mode, is already a compositor running?"),
}
#[doc = "Failed to activate open tty"]
FailedToActivateTTY(num: i32) {
description("Failed to activate open tty"),
display("Failed to activate open tty ({:?})", num),
}
#[doc = "Failed to activate open tty"]
FailedToActivateTTY(num: i32) {
description("Failed to activate open tty"),
display("Failed to activate open tty ({:?})", num),
}
#[doc = "Failed to wait for tty to become active"]
FailedToWaitForTTY(num: i32) {
description("Failed to wait for tty to become active"),
display("Failed to wait for tty ({:?}) to become active", num),
}
#[doc = "Failed to wait for tty to become active"]
FailedToWaitForTTY(num: i32) {
description("Failed to wait for tty to become active"),
display("Failed to wait for tty ({:?}) to become active", num),
}
#[doc = "Failed to save old tty state"]
FailedToSaveTTYState(num: i32) {
description("Failed to save old tty state"),
display("Failed to save old tty ({:?}) state", num),
}
#[doc = "Failed to save old tty state"]
FailedToSaveTTYState(num: i32) {
description("Failed to save old tty state"),
display("Failed to save old tty ({:?}) state", num),
}
#[doc = "Failed to set tty kb mode"]
FailedToSetTTYKbMode(num: i32) {
description("Failed to set tty kb mode to K_OFF"),
display("Failed to set tty ({:?}) kb mode to K_OFF", num),
}
#[doc = "Failed to set tty kb mode"]
FailedToSetTTYKbMode(num: i32) {
description("Failed to set tty kb mode to K_OFF"),
display("Failed to set tty ({:?}) kb mode to K_OFF", num),
}
#[doc = "Failed to set tty mode"]
FailedToSetTTYMode(num: i32) {
description("Failed to set tty mode to KD_GRAPHICS"),
display("Failed to set tty ({:?}) mode into graphics mode", num),
}
#[doc = "Failed to set tty mode"]
FailedToSetTTYMode(num: i32) {
description("Failed to set tty mode to KD_GRAPHICS"),
display("Failed to set tty ({:?}) mode into graphics mode", num),
}
#[doc = "Failed to set tty in process mode"]
FailedToTakeControlOfTTY(num: i32) {
description("Failed to set tty mode to VT_PROCESS"),
display("Failed to take control of tty ({:?})", num),
#[doc = "Failed to set tty in process mode"]
FailedToTakeControlOfTTY(num: i32) {
description("Failed to set tty mode to VT_PROCESS"),
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.
///
/// 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
/// may be registered.
/// gets paused or becomes active again. Any object implementing the [`SessionObserver`]
/// trait may be registered.
pub trait SessionNotifier {
/// Id type of registered observers
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.
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);
}
/// 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> {
/// Create a `SessionObserver` linked to this object
/// Create a [`SessionObserver`] linked to this object
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);
/// Ids of registered `SessionObserver`s of the `DirectSessionNotifier`
/// Ids of registered [`SessionObserver`](SessionObserver)s
#[derive(Debug, PartialEq, Eq, Clone, Copy, Hash)]
pub struct Id(usize);
@ -52,8 +52,8 @@ impl SessionNotifier for MultiNotifier {
}
}
/// Create a pair of a linked [`SessionObserver`](../trait.SessionObserver.html) and a
/// [`SessionNotifier`](../trait.SessionNotifier.html).
/// Create a pair of a linked [`SessionObserver`] and a
/// [`SessionNotifier`](SessionNotifier).
///
/// Observers added to the returned notifier are 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.
//!
//! This module mainly provides the `UdevBackend`, which constantly monitors available DRM devices
//! and notifies a user supplied `UdevHandler` of any changes.
//! This module mainly provides the [`UdevBackend`](::backend::udev::UdevBackend), which constantly monitors available DRM devices
//! and notifies a user supplied [`UdevHandler`](::backend::udev::UdevHandler) of any changes.
//!
//! 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.
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> {
/// Creates a new `UdevBackend` and adds it to the given `EventLoop`'s state.
/// Creates a new [`UdevBackend`]
///
/// ## Arguments
/// `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.
pub fn udev_backend_bind<T: UdevHandler + 'static, Data: 'static>(
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 {
/// Called when a new device is detected.
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.
fn device_changed(&mut self, device: dev_t);
/// 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);
}
/// 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>> {
let mut enumerator = Enumerator::new(context)?;
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
///
/// 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>> {
let mut enumerator = Enumerator::new(context)?;
enumerator.match_subsystem("drm")?;

101
src/backend/winit.rs
View File

@ -2,8 +2,8 @@
use backend::{
egl::{
context::GlAttributes, error as egl_error, error::Result as EGLResult, native, EGLContext,
EGLDisplay, EGLGraphicsBackend, EGLSurface,
context::GlAttributes, error::Result as EGLResult, native, EGLContext, EGLDisplay,
EGLGraphicsBackend, EGLSurface,
},
graphics::{gl::GLGraphicsBackend, CursorBackend, PixelFormat, SwapBuffersError},
input::{
@ -16,7 +16,7 @@ use backend::{
use nix::libc::c_void;
use std::{
cell::{Ref, RefCell},
cmp, error, fmt,
cmp, fmt,
rc::Rc,
time::Instant,
};
@ -28,23 +28,29 @@ use winit::{
MouseScrollDelta, Touch, TouchPhase, Window as WinitWindow, WindowBuilder, WindowEvent,
};
error_chain! {
errors {
#[doc = "Failed to initialize a window"]
InitFailed {
description("Failed to initialize a window")
/// Errors thrown by the `winit` backends
pub mod errors {
use backend::egl::error as egl_error;
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"]
NotSupported {
description("Context creation is not supported on the current window system.")
links {
EGL(egl_error::Error, egl_error::ErrorKind) #[doc = "EGL error"];
}
}
links {
EGL(egl_error::Error, egl_error::ErrorKind) #[doc = "EGL error"];
}
}
use self::errors::*;
enum Window {
Wayland {
@ -72,16 +78,17 @@ struct WindowSize {
}
/// Window with an active EGL Context created by `winit`. Implements the
/// `EGLGraphicsBackend` graphics backend trait
/// [`EGLGraphicsBackend`] and [`GLGraphicsBackend`] graphics backend trait
pub struct WinitGraphicsBackend {
window: Rc<Window>,
size: Rc<RefCell<WindowSize>>,
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 {
events_loop: EventsLoop,
events_handler: Option<Box<WinitEventsHandler>>,
@ -95,9 +102,9 @@ pub struct WinitInputBackend {
size: Rc<RefCell<WindowSize>>,
}
/// Create a new `WinitGraphicsBackend`, which implements the `EGLGraphicsBackend`
/// graphics backend trait and a corresponding `WinitInputBackend`, which implements
/// the `InputBackend` trait
/// Create a new [`WinitGraphicsBackend`], which implements the [`EGLGraphicsBackend`]
/// and [`GLGraphicsBackend`] graphics backend trait and a corresponding [`WinitInputBackend`],
/// which implements the [`InputBackend`] trait
pub fn init<L>(logger: L) -> Result<(WinitGraphicsBackend, WinitInputBackend)>
where
L: Into<Option<::slog::Logger>>,
@ -111,9 +118,9 @@ where
)
}
/// Create a new `WinitGraphicsBackend`, which implements the `EGLGraphicsBackend`
/// graphics backend trait, from a given `WindowBuilder` struct and a corresponding
/// `WinitInputBackend`, which implements the `InputBackend` trait
/// Create a new [`WinitGraphicsBackend`], which implements the [`EGLGraphicsBackend`]
/// and [`GLGraphicsBackend`] graphics backend trait, from a given [`WindowBuilder`]
/// struct and a corresponding [`WinitInputBackend`], which implements the [`InputBackend`] trait
pub fn init_from_builder<L>(
builder: WindowBuilder,
logger: L,
@ -133,10 +140,10 @@ where
)
}
/// Create a new `WinitGraphicsBackend`, which implements the `EGLGraphicsBackend`
/// graphics backend trait, from a given `WindowBuilder` struct, as well as given
/// `GlAttributes` for further customization of the rendering pipeline and a
/// corresponding `WinitInputBackend`, which implements the `InputBackend` trait.
/// Create a new [`WinitGraphicsBackend`], which implements the [`EGLGraphicsBackend`]
/// and [`GLGraphicsBackend`] graphics backend trait, from a given [`WindowBuilder`]
/// struct, as well as given [`GlAttributes`] for further customization of the rendering pipeline and a
/// corresponding [`WinitInputBackend`], which implements the [`InputBackend`] trait.
pub fn init_from_builder_with_gl_attr<L>(
builder: WindowBuilder,
attributes: GlAttributes,
@ -208,7 +215,7 @@ where
/// Handler trait to receive window-related events to provide a better *nested* experience.
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`.
fn resized(&mut self, size: (f64, f64), scale: f64);
@ -219,7 +226,7 @@ pub trait WinitEventsHandler {
}
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> {
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)]
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,
}
impl error::Error for WinitInputError {
impl ::std::error::Error for WinitInputError {
fn description(&self) -> &str {
match *self {
WinitInputError::WindowClosed => "Glutin Window was closed",
@ -338,7 +345,7 @@ impl fmt::Display for WinitInputError {
}
}
#[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 {
time: u32,
key: u32,
@ -367,7 +374,7 @@ impl KeyboardKeyEvent for WinitKeyboardInputEvent {
}
#[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 {
size: Rc<RefCell<WindowSize>>,
time: u32,
@ -404,7 +411,7 @@ impl PointerMotionAbsoluteEvent for WinitMouseMovedEvent {
}
#[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 {
time: u32,
delta: MouseScrollDelta,
@ -442,7 +449,7 @@ impl PointerAxisEvent for WinitMouseWheelEvent {
}
#[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 {
time: u32,
button: WinitMouseButton,
@ -466,7 +473,7 @@ impl PointerButtonEvent for WinitMouseInputEvent {
}
#[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 {
size: Rc<RefCell<WindowSize>>,
time: u32,
@ -513,7 +520,7 @@ impl TouchDownEvent for WinitTouchStartedEvent {
}
#[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 {
size: Rc<RefCell<WindowSize>>,
time: u32,
@ -573,7 +580,7 @@ impl TouchUpEvent for WinitTouchEndedEvent {
}
#[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 {
time: u32,
id: u64,
@ -655,17 +662,17 @@ impl InputBackend for WinitInputBackend {
&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
/// `Window` active. Otherwise the window may no respond to user interaction and no
/// input events will be received by a set `InputHandler`.
/// [`WinitWindow`] active. Otherwise the window may no respond to user interaction and no
/// input events will be received by a set [`InputHandler`].
///
/// Returns an error if the `Window` the window has been closed. Calling
/// `dispatch_new_events` again after the `Window` has been closed is considered an
/// Returns an error if the [`WinitWindow`] the window has been closed. Calling
/// `dispatch_new_events` again after the [`WinitWindow`] has been closed is considered an
/// 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.
fn dispatch_new_events(&mut self) -> ::std::result::Result<(), WinitInputError> {
let mut closed = false;

2
src/lib.rs
View File

@ -1,7 +1,7 @@
#![warn(missing_docs)]
//! **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`.
// `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
//! 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
//!
@ -22,8 +23,8 @@
//!
//! ### Initialization
//!
//! To initialize this implementation, use the `compositor_init` method provided
//! by this module. It'll require you to first define as few things, as shown in
//! To initialize this implementation, use the [`compositor_init`](::wayland::compositor::compositor_init)
//! method provided by this module. It'll require you to first define as few things, as shown in
//! this example:
//!
//! ```
@ -66,15 +67,17 @@
//!
//! 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
//! 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
//! state pending from the client as defined by the protocol for `wl_surface`, as well as your
//! user-defined type holding any data you need to have associated with a struct. See its
//! documentation for details.
//! The surface metadata is held in the [`SurfaceAttributes`](::wayland::compositor::SurfaceAttributes)
//! struct. In contains double-buffered state pending from the client as defined by the protocol for
//! [`wl_surface`](wayland_server::protocol::wl_surface), as well as your user-defined type holding
//! 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
//! surfaces. See the documentation of the `roles` submodule for a detailed explanation.
//! This [`CompositorToken`](::wayland::compositor::CompositorToken) also provides access to the metadata associated with the role of the
//! surfaces. See the documentation of the [`roles`](::wayland::compositor::roles) submodule
//! for a detailed explanation.
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
///
/// 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
/// processing them two times.
@ -232,7 +236,8 @@ impl Default for RegionAttributes {
/// A Compositor global token
///
/// 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.
pub struct CompositorToken<U, R> {
_data: ::std::marker::PhantomData<*mut U>,
@ -292,7 +297,7 @@ where
/// - a mutable reference to its surface attribute 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
/// 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
/// 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
/// 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>(
&self,
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
/// returns a `CompositorToken` which you'll need access the data associated to
/// the `wl_surface`s.
/// returns a [`CompositorToken`] which you'll need access the data associated to
/// the [`wl_surface`](wayland_server::protocol::wl_surface)s.
///
/// It also returns the two global handles, in case you wish to remove these
/// globals from the event loop in the future.
@ -491,7 +497,7 @@ where
pub enum SurfaceEvent {
/// 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.
///
/// 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,
/// 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
/// its `done()` method.
/// You must keep the provided [`WlCallback`](wayland_server::protocol::wl_callback::WlCallback)
/// 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)
/// 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
//! all smithay handlers:
//!
//! - The trait `RoleType`, which defines it as a type handling roles
//! - For each of your roles, the trait `Role<Token>` (where `Token` is your
//! token type), marking its ability to handle this given role.
//! - The trait [`RoleType`](::wayland::compositor::roles::RoleType),
//! which defines it as a type handling roles
//! - 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
//! 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
//! capabilities.
@ -98,13 +100,13 @@ pub trait RoleType {
/// Check if the associated surface has a 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;
}
/// 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.
///
/// 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.");
/// ```
///
/// 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.
///
/// 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:
//!
//! - `init_data_device`: this function must be called 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
//! typically call it whenever the keyboard focus changes, to follow it (for example in the focus
//! hook of your keyboards)
//! - [`init_data_device`](::wayland::data_device::init_data_device): this function must be called
//! during the compositor startup to initialize the data device logic
//! - [`set_data_device_focus`](::wayland::data_device::set_data_device_focus): this function sets
//! the data device focus for a given seat; you'd typically call it whenever the keyboard focus
//! 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
//! the data devices.
@ -18,10 +18,11 @@
//! The module also provides additionnal mechanisms allowing your compositor to see and interact with
//! 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
//! - the freestanding function `set_data_device_selection` allows you to set the contents of the selection
//! for your clients
//! - the freestanding function `start_dnd` allows you to initiate a drag'n'drop event from the compositor
//! - You can provide a callback closure to [`init_data_device`](::wayland::data_device::init_data_device)
//! to peek into the the actions of your clients
//! - the freestanding function [`set_data_device_selection`](::wayland::data_device::set_data_device_selection)
//! 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.
//!
//! 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
/// (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
/// `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
/// 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)
/// 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>(
display: &mut Display,
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.
///
/// 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>) {
// TODO: same question as in set_data_device_focus
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
///
/// 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.
pub fn start_dnd<C>(seat: &Seat, serial: u32, metadata: SourceMetadata, callback: C)
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};
/// 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 {
/// The client chose an action
Action(DndAction),

2
src/wayland/mod.rs
View File

@ -21,7 +21,7 @@ pub mod seat;
pub mod shell;
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.
pub static SERIAL_COUNTER: SerialCounter = SerialCounter {

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

@ -7,12 +7,12 @@
//!
//! # How to use it
//!
//! You need to instantiate an `Output` for each output global you want
//! to advertise to clients.
//! You need to instantiate an [`Output`](::wayland::output::Output)
//! for each output global you want to advertise to clients.
//!
//! Just add it to your Display using the `Output::new(..)` method.
//! You can use the returned `Output` to change the properties of your
//! output (if the current resolution mode changes for example),
//! Just add it to your Display using the [`Output::new(..)`](::wayland::output::Output::new)
//! method. You can use the returned [`Output`](::wayland::output::Output) to change
//! the properties of your output (if the current resolution mode changes for example),
//! 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 {
self.inner
.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:
///
/// - 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
/// 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.
#[derive(Clone)]
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
/// 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.
pub fn input<F>(&self, keycode: u32, state: KeyState, serial: u32, time: u32, filter: F)
where
@ -357,8 +357,9 @@ impl KeyboardHandle {
/// Set the current focus of this keyboard
///
/// 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`,
/// a `wl_keyboard::enter` event will be sent.
/// will be sent a [`wl_keyboard::Event::Leave`](wayland_server::protocol::wl_keyboard::Event::Leave)
/// 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) {
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
//! 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
//! 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
/// 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
/// threads.
@ -160,7 +161,7 @@ impl Seat {
(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> {
seat.user_data::<Arc<SeatArc>>().cloned().map(|arc| Seat { arc })
}
@ -172,8 +173,8 @@ impl Seat {
/// Adds the pointer capability to this seat
///
/// You are provided a `PointerHandle`, which allows you to send input events
/// to this keyboard. This handle can be cloned and sent across threads.
/// You are provided a [`PointerHandle`], which allows you to send input events
/// to this pointer. This handle can be cloned and sent across threads.
///
/// 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
@ -245,7 +246,7 @@ impl 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.
///
/// 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 {
let inner = self.arc.inner.lock().unwrap();
inner.known_seats.iter().any(|s| s.equals(seat))

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

@ -124,7 +124,7 @@ impl PointerInternal {
/// clients.
///
/// 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)]
pub struct PointerHandle {
inner: Arc<Mutex<PointerInternal>>,
@ -213,7 +213,6 @@ impl PointerHandle {
/// Start an axis frame
///
/// 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) {
self.inner.lock().unwrap().with_grab(|mut handle, grab| {
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.
///
/// 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.
///
/// 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.
/// 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).
pub fn source(mut self, source: AxisSource) -> Self {
self.source = Some(source);
@ -532,7 +531,7 @@ impl AxisFrame {
/// 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.
pub fn stop(mut self, axis: Axis) -> Self {
match axis {

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

@ -23,9 +23,9 @@
//!
//! ### Initialization
//!
//! To initialize this handler, simple use the `wl_shell_init` function provided in this
//! module. You will need to provide it the `CompositorToken` you retrieved from an
//! instantiation of the compositor handler provided by smithay.
//! To initialize this handler, simple use the [`wl_shell_init`](::wayland::shell::legacy::wl_shell_init)
//! function provided in this module. You will need to provide it the [`CompositorToken`](::wayland::compositor::CompositorToken)
//! you retrieved from an instantiation of the compositor handler provided by smithay.
//!
//! ```no_run
//! # extern crate wayland_server;
@ -85,7 +85,7 @@ use wayland_server::{
mod wl_handlers;
/// Metadata associated with the `xdg_surface` role
/// Metadata associated with the `wl_surface` role
pub struct ShellSurfaceRole<D: 'static> {
/// Title of the surface
pub title: String,
@ -133,7 +133,7 @@ where
/// 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
/// 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
//!
//! To initialize this handler, simple use the `xdg_shell_init` function provided in this
//! module. You will need to provide it the `CompositorToken` you retrieved from an
//! instantiation of the compositor global provided by smithay.
//! 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`](::wayland::compositor::CompositorToken)
//! you retrieved from an instantiation of the compositor global provided by smithay.
//!
//! ```no_run
//! # extern crate wayland_server;
@ -73,17 +73,22 @@
//!
//! 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
//! the example above).
//! - `ToplevelSurface`: This is a handle representing a toplevel surface, you can
//! retrieve a list of all currently alive toplevel surface from the `ShellState`.
//! - `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`.
//! - [`ToplevelSurface`](::wayland::shell::xdg::ToplevelSurface):
//! This is a handle representing a toplevel surface, you can
//! retrieve a list of all currently alive toplevel surface from the
//! [`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
//! the subhandler you provided, or via methods on the `ShellState` that you are given
//! (in an `Arc<Mutex<_>>`) as return value of the `init` function.
//! the subhandler you provided, or via methods on the [`ShellState`](::wayland::shell::xdg::ShellState)
//! that you are given (in an `Arc<Mutex<_>>`) as return value of the `init` function.
use std::{
cell::RefCell,
@ -408,7 +413,7 @@ where
/// 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
/// 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
///
/// 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
NewToplevel {
/// the surface
@ -851,7 +856,7 @@ pub enum XdgRequest<U, R, SD> {
},
/// 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
NewPopup {
/// 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
//! `with_buffer_contents` function to do it:
//! Then, when you have a [`WlBuffer`](wayland_server::protocol::wl_buffer::WlBuffer)
//! and need to retrieve its contents, use the
//! [`with_buffer_contents`](::wayland::shm::with_buffer_contents) function to do it:
//!
//! ```
//! # extern crate wayland_server;
@ -103,8 +104,8 @@ pub struct ShmGlobalData {
/// as they are required by the protocol. Formats given as argument
/// as additionally advertized.
///
/// The global is directly created on the provided `Display`, and this function
/// returns the global handle, in case you wish to remove this global in
/// The global is directly created on the provided [`Display`](wayland_server::Display),
/// and this function returns the global handle, in case you wish to remove this global in
/// the future.
pub fn init_shm_global<L>(
display: &mut Display,